DEFOLD
Home Features Showcase Learn Asset Portal Community Support API Free Download Donate  

Defold Learn logo

Defold Learn logo

Http

HTTP service and request functions.

Include: #include <dmsdk/dlib/http.h>
TYPES
HttpRequest HTTP request object
HttpRequestHandle HTTP request handle
HttpResponseCallback HTTP response callback
HttpResponseInfo HTTP response information
HttpService HTTP service object
CONSTANTS
HTTP_REQUEST_HANDLE_INVALID invalid HTTP request handle
HTTP_SERVICE_CONTEXT_NAME HTTP service extension context name
ENUMS
HttpCallbackResult HTTP callback result
HttpResponseEvent HTTP response event
HttpResult HTTP result values
FUNCTIONS
HttpResult HttpAddHeader (HttpRequest* request, const char* header) add a request header
HttpResult HttpCancelRequest (HttpService* service, HttpRequestHandle request_handle) request cancellation
void HttpDeleteRequest (HttpRequest* request) delete an HTTP request
HttpResult HttpNewRequest (HttpRequest** request) create a new HTTP request
HttpResult HttpPushRequest (HttpService* service, HttpRequest* request, HttpRequestHandle* request_handle) push a request to an HTTP service
uint32_t HttpResponseGetBytesReceived (const HttpResponseInfo* response) get progress bytes received
uint32_t HttpResponseGetBytesSent (const HttpResponseInfo* response) get progress bytes sent
int32_t HttpResponseGetBytesTotal (const HttpResponseInfo* response) get progress byte total
const void* HttpResponseGetData (const HttpResponseInfo* response) get response data
uint32_t HttpResponseGetDataSize (const HttpResponseInfo* response) get response data size
uint32_t HttpResponseGetDocumentSize (const HttpResponseInfo* response) get response document size
HttpResponseEvent HttpResponseGetEvent (const HttpResponseInfo* response) get response event
const char* HttpResponseGetHeader (const HttpResponseInfo* response) get response header
uint32_t HttpResponseGetHeaderSize (const HttpResponseInfo* response) get response header size
const char* HttpResponseGetPath (const HttpResponseInfo* response) get response path
uint32_t HttpResponseGetRangeEnd (const HttpResponseInfo* response) get response range end
uint32_t HttpResponseGetRangeStart (const HttpResponseInfo* response) get response range start
HttpResult HttpResponseGetResult (const HttpResponseInfo* response) get response result
int HttpResponseGetStatusCode (const HttpResponseInfo* response) get response status code
const char* HttpResponseGetURL (const HttpResponseInfo* response) get response URL
HttpResult HttpSetBasicAuth (HttpRequest* request, const char* username, const char* password) set basic authentication credentials
HttpResult HttpSetBearerAuth (HttpRequest* request, const char* token) set bearer authentication token
HttpResult HttpSetChunkedTransfer (HttpRequest* request, int chunked_transfer) set chunked transfer
HttpResult HttpSetIgnoreCache (HttpRequest* request, int ignore_cache) set ignore cache
HttpResult HttpSetMethod (HttpRequest* request, const char* method) set request method
HttpResult HttpSetProxy (HttpRequest* request, const char* proxy) set proxy URL
HttpResult HttpSetReportProgress (HttpRequest* request, int report_progress) set progress reporting
HttpResult HttpSetRequestBody (HttpRequest* request, const void* body, uint32_t body_size) set request body
HttpResult HttpSetResponseCallback (HttpRequest* request, HttpResponseCallback callback, void* user_data) set response callback
HttpResult HttpSetResponsePath (HttpRequest* request, const char* path) set response path
HttpResult HttpSetTimeout (HttpRequest* request, uint32_t timeout_us) set request timeout
HttpResult HttpSetURL (HttpRequest* request, const char* url) set request URL

Functions

HttpAddHeader

HttpResult HttpAddHeader(HttpRequest* request, const char* header)

add a request header

PARAMETERS

HttpRequest* request Request object.
const char* header Raw request header, eg "Accept: application/json".

RETURNS

HttpResult HTTP_RESULT_OK on success.

HttpCancelRequest

HttpResult HttpCancelRequest(HttpService* service, HttpRequestHandle request_handle)

Marks a queued or running request as canceled. Cancellation is best effort.

PARAMETERS

HttpService* service HTTP service object.
HttpRequestHandle request_handle Request handle returned by HttpPushRequest().

RETURNS

HttpResult HTTP_RESULT_OK on success.

HttpDeleteRequest

void HttpDeleteRequest(HttpRequest* request)

Only valid before HttpPushRequest() succeeds.

PARAMETERS

HttpRequest* request Request object.

HttpNewRequest

HttpResult HttpNewRequest(HttpRequest** request)

create a new HTTP request

PARAMETERS

HttpRequest** request Request object on success.

RETURNS

HttpResult HTTP_RESULT_OK on success.

HttpPushRequest

HttpResult HttpPushRequest(HttpService* service, HttpRequest* request, HttpRequestHandle* request_handle)

On success, ownership of request is transferred to the service and the caller must not modify or delete it.

PARAMETERS

HttpService* service HTTP service object.
HttpRequest* request Request object.
HttpRequestHandle* request_handle Request handle on success.

RETURNS

HttpResult HTTP_RESULT_OK on success.

HttpResponseGetBytesReceived

uint32_t HttpResponseGetBytesReceived(const HttpResponseInfo* response)

Valid for HTTP_RESPONSE_EVENT_PROGRESS.

PARAMETERS

const HttpResponseInfo* response Response data.

RETURNS

uint32_t Received byte count.

HttpResponseGetBytesSent

uint32_t HttpResponseGetBytesSent(const HttpResponseInfo* response)

Valid for HTTP_RESPONSE_EVENT_PROGRESS.

PARAMETERS

const HttpResponseInfo* response Response data.

RETURNS

uint32_t Sent byte count.

HttpResponseGetBytesTotal

int32_t HttpResponseGetBytesTotal(const HttpResponseInfo* response)

Valid for HTTP_RESPONSE_EVENT_PROGRESS.

PARAMETERS

const HttpResponseInfo* response Response data.

RETURNS

int32_t Total byte count, or -1 if unknown.

HttpResponseGetData

const void* HttpResponseGetData(const HttpResponseInfo* response)

Valid for HTTP_RESPONSE_EVENT_DATA.

PARAMETERS

const HttpResponseInfo* response Response data.

RETURNS

const void* Response body chunk data.

HttpResponseGetDataSize

uint32_t HttpResponseGetDataSize(const HttpResponseInfo* response)

Valid for HTTP_RESPONSE_EVENT_DATA.

PARAMETERS

const HttpResponseInfo* response Response data.

RETURNS

uint32_t Response body chunk size.

HttpResponseGetDocumentSize

uint32_t HttpResponseGetDocumentSize(const HttpResponseInfo* response)

get response document size

PARAMETERS

const HttpResponseInfo* response Response data.

RETURNS

uint32_t Full size of the requested file, when known.

HttpResponseGetEvent

HttpResponseEvent HttpResponseGetEvent(const HttpResponseInfo* response)

get response event

PARAMETERS

const HttpResponseInfo* response Response data.

RETURNS

HttpResponseEvent Event type.

HttpResponseGetHeader

const char* HttpResponseGetHeader(const HttpResponseInfo* response)

Valid for HTTP_RESPONSE_EVENT_HEADER. Returns the raw response header line as "Name:Value", without a trailing newline. The returned pointer is valid only for the duration of the callback. Use HttpResponseGetHeaderSize() for the number of bytes in the header line.

PARAMETERS

const HttpResponseInfo* response Response data.

RETURNS

const char* Raw header line in "Name:Value" form.

HttpResponseGetHeaderSize

uint32_t HttpResponseGetHeaderSize(const HttpResponseInfo* response)

Valid for HTTP_RESPONSE_EVENT_HEADER.

PARAMETERS

const HttpResponseInfo* response Response data.

RETURNS

uint32_t Number of bytes returned by HttpResponseGetHeader(), excluding any null terminator.

HttpResponseGetPath

const char* HttpResponseGetPath(const HttpResponseInfo* response)

get response path

PARAMETERS

const HttpResponseInfo* response Response data.

RETURNS

const char* User supplied response path.

HttpResponseGetRangeEnd

uint32_t HttpResponseGetRangeEnd(const HttpResponseInfo* response)

get response range end

PARAMETERS

const HttpResponseInfo* response Response data.

RETURNS

uint32_t End offset into the requested file, when known.

HttpResponseGetRangeStart

uint32_t HttpResponseGetRangeStart(const HttpResponseInfo* response)

get response range start

PARAMETERS

const HttpResponseInfo* response Response data.

RETURNS

uint32_t Start offset into the requested file, when known.

HttpResponseGetResult

HttpResult HttpResponseGetResult(const HttpResponseInfo* response)

Valid for HTTP_RESPONSE_EVENT_COMPLETE.

PARAMETERS

const HttpResponseInfo* response Response data.

RETURNS

HttpResult Transfer result.

HttpResponseGetStatusCode

int HttpResponseGetStatusCode(const HttpResponseInfo* response)

get response status code

PARAMETERS

const HttpResponseInfo* response Response data.

RETURNS

int HTTP status code, eg 200.

HttpResponseGetURL

const char* HttpResponseGetURL(const HttpResponseInfo* response)

get response URL

PARAMETERS

const HttpResponseInfo* response Response data.

RETURNS

const char* Request URL.

HttpSetBasicAuth

HttpResult HttpSetBasicAuth(HttpRequest* request, const char* username, const char* password)

set basic authentication credentials

PARAMETERS

HttpRequest* request Request object.
const char* username User name.
const char* password Password.

RETURNS

HttpResult HTTP_RESULT_OK on success.

HttpSetBearerAuth

HttpResult HttpSetBearerAuth(HttpRequest* request, const char* token)

set bearer authentication token

PARAMETERS

HttpRequest* request Request object.
const char* token Bearer token.

RETURNS

HttpResult HTTP_RESULT_OK on success.

HttpSetChunkedTransfer

HttpResult HttpSetChunkedTransfer(HttpRequest* request, int chunked_transfer)

set chunked transfer

PARAMETERS

HttpRequest* request Request object.
int chunked_transfer Non-zero to allow chunked transfer encoding.

RETURNS

HttpResult HTTP_RESULT_OK on success.

HttpSetIgnoreCache

HttpResult HttpSetIgnoreCache(HttpRequest* request, int ignore_cache)

set ignore cache

PARAMETERS

HttpRequest* request Request object.
int ignore_cache Non-zero to ignore the HTTP cache.

RETURNS

HttpResult HTTP_RESULT_OK on success.

HttpSetMethod

HttpResult HttpSetMethod(HttpRequest* request, const char* method)

set request method

PARAMETERS

HttpRequest* request Request object.
const char* method HTTP method, eg "GET".

RETURNS

HttpResult HTTP_RESULT_OK on success.

HttpSetProxy

HttpResult HttpSetProxy(HttpRequest* request, const char* proxy)

set proxy URL

PARAMETERS

HttpRequest* request Request object.
const char* proxy Full proxy URL, or 0 to clear.

RETURNS

HttpResult HTTP_RESULT_OK on success.

HttpSetReportProgress

HttpResult HttpSetReportProgress(HttpRequest* request, int report_progress)

set progress reporting

PARAMETERS

HttpRequest* request Request object.
int report_progress Non-zero to receive HTTP_RESPONSE_EVENT_PROGRESS callbacks.

RETURNS

HttpResult HTTP_RESULT_OK on success.

HttpSetRequestBody

HttpResult HttpSetRequestBody(HttpRequest* request, const void* body, uint32_t body_size)

Copies request body data into the request. Passing a zero size clears the body. The current HTTP client sends request bodies for POST, PUT, and PATCH.

PARAMETERS

HttpRequest* request Request object.
const void* body Request body data.
uint32_t body_size Request body size.

RETURNS

HttpResult HTTP_RESULT_OK on success.

HttpSetResponseCallback

HttpResult HttpSetResponseCallback(HttpRequest* request, HttpResponseCallback callback, void* user_data)

set response callback

PARAMETERS

HttpRequest* request Request object.
HttpResponseCallback callback Response callback.
void* user_data User data.

RETURNS

HttpResult HTTP_RESULT_OK on success.

HttpSetResponsePath

HttpResult HttpSetResponsePath(HttpRequest* request, const char* path)

Stores a user supplied path with the request. The HTTP API does not write the response to this path; it is returned in response callbacks for callers that want to write response data themselves.

PARAMETERS

HttpRequest* request Request object.
const char* path Response path, or 0 to clear.

RETURNS

HttpResult HTTP_RESULT_OK on success.

HttpSetTimeout

HttpResult HttpSetTimeout(HttpRequest* request, uint32_t timeout_us)

set request timeout

PARAMETERS

HttpRequest* request Request object.
uint32_t timeout_us Timeout in microseconds.

RETURNS

HttpResult HTTP_RESULT_OK on success.

HttpSetURL

HttpResult HttpSetURL(HttpRequest* request, const char* url)

set request URL

PARAMETERS

HttpRequest* request Request object.
const char* url Full request URL.

RETURNS

HttpResult HTTP_RESULT_OK on success.

Constants

HTTP_REQUEST_HANDLE_INVALID

invalid HTTP request handle

HTTP_SERVICE_CONTEXT_NAME

Name used when registering the HTTP service with dmExtension context params.

Types

HttpRequest

void HttpRequest()

The caller owns the request until HttpPushRequest() succeeds.

PARAMETERS

HttpRequestHandle

void HttpRequestHandle()

Opaque service-local value identifying a request after ownership has been transferred to the HTTP service.

PARAMETERS

HttpResponseCallback

HttpCallbackResult HttpResponseCallback(HttpRequest* request, void* user_data, const HttpResponseInfo* response)

Called from the HTTP client worker thread. HTTP_RESPONSE_EVENT_DATA events are sent as response chunks arrive; the receiver is responsible for processing or copying them before returning. The receiver is also responsible for synchronizing with other threads. Pointers in HttpResponseInfo are valid only for the duration of the callback. Returning HTTP_CALLBACK_RESULT_CANCEL from header, data, or progress events cancels the request.

PARAMETERS

HttpRequest* request Request object. Valid only for the duration of the callback.
void* user_data User data.
const HttpResponseInfo* response Response data.

RETURNS

HttpCallbackResult callback result.

HttpResponseInfo

void HttpResponseInfo()

Opaque data passed to HttpResponseCallback.

PARAMETERS

HttpService

void HttpService()

HTTP service context provided by the engine.

PARAMETERS

Enums

HttpCallbackResult

Return value from HttpResponseCallback.

HTTP_CALLBACK_RESULT_CONTINUE Continue processing the request.
HTTP_CALLBACK_RESULT_CANCEL Cancel the request. Ignored for HTTP_RESPONSE_EVENT_COMPLETE.

HttpResponseEvent

HTTP response event

HTTP_RESPONSE_EVENT_HEADER Response header data is available.
HTTP_RESPONSE_EVENT_DATA Response body data is available.
HTTP_RESPONSE_EVENT_COMPLETE Request completed.
HTTP_RESPONSE_EVENT_PROGRESS Request progress data is available.

HttpResult

HTTP result values

HTTP_RESULT_NOT_200_OK = 1
HTTP_RESULT_OK = 0
HTTP_RESULT_SOCKET_ERROR = -1
HTTP_RESULT_HTTP_HEADERS_ERROR = -2
HTTP_RESULT_INVALID_RESPONSE = -3
HTTP_RESULT_PARTIAL_CONTENT = -4
HTTP_RESULT_UNSUPPORTED_TRANSFER_ENCODING = -5
HTTP_RESULT_INVAL_ERROR = -6
HTTP_RESULT_UNEXPECTED_EOF = -7
HTTP_RESULT_IO_ERROR = -8
HTTP_RESULT_HANDSHAKE_FAILED = -9
HTTP_RESULT_INVAL = -10
HTTP_RESULT_UNKNOWN = -1000