Group PJ_HTTP_CLIENT
- group PJ_HTTP_CLIENT
This contains a simple HTTP client implementation. Some known limitations:
Does not support chunked Transfer-Encoding.
Defines
-
PJ_HTTP_HEADER_SIZE
Defines the maximum number of elements in a pj_http_headers structure.
Typedefs
-
typedef struct pj_http_req pj_http_req
This opaque structure describes the http request.
Functions
-
void pj_http_req_param_default(pj_http_req_param *param)
Initialize the http request parameters with the default values.
- Parameters:
param – The parameter to be initialized.
-
pj_status_t pj_http_headers_add_elmt(pj_http_headers *headers, pj_str_t *name, pj_str_t *val)
Add a header element/field. Application MUST make sure that name and val pointer remains valid until the HTTP request is sent.
- Parameters:
headers – The headers.
name – The header field name.
val – The header field value.
- Returns:
PJ_SUCCESS if the operation has been successful, or the appropriate error code on failure.
-
pj_status_t pj_http_headers_add_elmt2(pj_http_headers *headers, char *name, char *val)
The same as pj_http_headers_add_elmt() with char * as its parameters. Application MUST make sure that name and val pointer remains valid until the HTTP request is sent.
- Parameters:
headers – The headers.
name – The header field name.
val – The header field value.
- Returns:
PJ_SUCCESS if the operation has been successful, or the appropriate error code on failure.
-
pj_status_t pj_http_req_parse_url(const pj_str_t *url, pj_http_url *hurl)
Parse a http URL into its components.
- Parameters:
url – The URL to be parsed.
hurl – Pointer to receive the parsed result.
- Returns:
PJ_SUCCESS if the operation has been successful, or the appropriate error code on failure.
-
pj_status_t pj_http_req_create(pj_pool_t *pool, const pj_str_t *url, pj_timer_heap_t *timer, pj_ioqueue_t *ioqueue, const pj_http_req_param *param, const pj_http_req_callback *hcb, pj_http_req **http_req)
Create the HTTP request.
- Parameters:
pool – Pool to use. HTTP request will use the pool’s factory to allocate its own memory pool.
url – HTTP URL request.
timer – The timer to use.
ioqueue – The ioqueue to use.
param – Optional parameters. When this parameter is not specifed (NULL), the default values will be used.
hcb – Pointer to structure containing application callbacks.
http_req – Pointer to receive the http request instance.
- Returns:
PJ_SUCCESS if the operation has been successful, or the appropriate error code on failure.
-
void pj_http_req_set_timeout(pj_http_req *http_req, const pj_time_val *timeout)
Set the timeout of the HTTP request operation. Note that if the HTTP request is currently running, the timeout will only affect subsequent request operations.
- Parameters:
http_req – The http request.
timeout – Timeout value for HTTP request operation.
-
pj_status_t pj_http_req_start(pj_http_req *http_req)
Starts an asynchronous HTTP request to the URL specified.
- Parameters:
http_req – The http request.
- Returns:
PJ_SUCCESS if success
non-zero which indicates the appropriate error code.
-
pj_status_t pj_http_req_cancel(pj_http_req *http_req, pj_bool_t notify)
Cancel the asynchronous HTTP request.
- Parameters:
http_req – The http request.
notify – If non-zero, the on_complete() callback will be called with status PJ_ECANCELLED to notify that the query has been cancelled.
- Returns:
PJ_SUCCESS if success
non-zero which indicates the appropriate error code.
-
pj_status_t pj_http_req_destroy(pj_http_req *http_req)
Destroy the http request.
- Parameters:
http_req – The http request to be destroyed.
- Returns:
PJ_SUCCESS if success.
-
pj_bool_t pj_http_req_is_running(const pj_http_req *http_req)
Find out whether the http request is running.
- Parameters:
http_req – The http request.
- Returns:
PJ_TRUE if a request is pending, or PJ_FALSE if idle
-
void *pj_http_req_get_user_data(pj_http_req *http_req)
Retrieve the user data previously associated with this http request.
- Parameters:
http_req – The http request.
- Returns:
The user data.
-
struct pj_http_header_elmt
- #include <http_client.h>
HTTP header representation.
-
struct pj_http_headers
- #include <http_client.h>
This structure describes http request/response headers. Application should call pj_http_headers_add_elmt() to add a header field.
Public Members
-
unsigned count
< Number of header fields
-
pj_http_header_elmt header[32]
Header elements/fields
-
unsigned count
-
struct pj_http_auth_cred
- #include <http_client.h>
Structure to save HTTP authentication credential.
Public Members
-
pj_str_t scheme
Specify specific authentication schemes to be responded. Valid values are “basic” and “digest”. If this field is not set, any authentication schemes will be responded.
Default is empty.
-
pj_str_t realm
Specify specific authentication realm to be responded. If this field is set, only 401/407 response with matching realm will be responded. If this field is not set, any realms will be responded.
Default is empty.
-
unsigned data_type
The type of password in data field. Currently only 0 is supported, meaning the data contains plain-text password.
Default is 0.
-
pj_str_t scheme
-
struct pj_http_req_param
- #include <http_client.h>
Parameters that can be given during http request creation. Application must initialize this structure with pj_http_req_param_default().
Public Members
-
int addr_family
The address family of the URL. Default is pj_AF_INET().
-
pj_time_val timeout
HTTP request operation timeout. Default is PJ_HTTP_DEFAULT_TIMEOUT.
-
void *user_data
User-defined data. Default is NULL.
-
pj_http_headers headers
HTTP request headers. Default is empty.
-
struct pj_http_req_param::pj_http_reqdata reqdata
The request body
-
pj_http_auth_cred auth_cred
Authentication credential needed to respond to 401/407 response.
-
pj_uint16_t source_port_range_start
Optional source port range to use when binding the socket. This can be used if the source port needs to be within a certain range for instance due to strict firewall settings. The port used will be randomized within the range.
Note that if authentication is configured, the authentication response will be a new transaction
Default is 0 (The OS will select the source port automatically)
-
pj_uint16_t source_port_range_size
Optional source port range to use when binding. The size of the port restriction range
Default is 0 (The OS will select the source port automatically))
-
pj_uint16_t max_retries
Max number of retries if binding to a port fails. Note that this does not adress the scenario where a request times out or errors. This needs to be taken care of by the on_complete callback.
Default is 3
-
struct pj_http_reqdata
- #include <http_client.h>
This structure describes the http request body. If application specifies the data to send, the data must remain valid until the HTTP request is sent. Alternatively, application can choose to specify total_size as the total data size to send instead while leaving the data NULL (and its size 0). In this case, HTTP request will then call on_send_data() callback once it is ready to send the request body. This will be useful if application does not wish to load the data into the buffer at once.
Default is empty.
-
int addr_family
-
struct pj_http_auth_chal
- #include <http_client.h>
HTTP authentication challenge, parsed from WWW-Authenticate header.
-
struct pj_http_resp
- #include <http_client.h>
This structure describes HTTP response.
Public Members
-
pj_uint16_t status_code
Status code of the request
-
pj_http_headers headers
Response headers
-
pj_http_auth_chal auth_chal
Parsed WWW-Authenticate header, if any.
-
pj_int32_t content_length
The value of content-length header field. -1 if not specified.
-
void *data
Data received
-
pj_uint16_t status_code
-
struct pj_http_url
- #include <http_client.h>
This structure describes HTTP URL.
-
struct pj_http_req_callback
- #include <http_client.h>
This structure describes the callbacks to be called by the HTTP request.
Public Members
-
void (*on_response)(pj_http_req *http_req, const pj_http_resp *resp)
This callback is called when a complete HTTP response header is received.
- Param http_req:
The http request.
- Param resp:
The response of the request.
-
void (*on_send_data)(pj_http_req *http_req, void **data, pj_size_t *size)
This callback is called when the HTTP request is ready to send its request body. Application may wish to use this callback if it wishes to load the data at a later time or if it does not wish to load the whole data into memory. In order for this callback to be called, application MUST set http_req_param.total_size to a value greater than 0.
- Param http_req:
The http request.
- Param data:
Pointer to the data that will be sent. Application must set the pointer to the current data chunk/segment to be sent. Data must remain valid until the next on_send_data() callback or for the last segment, until it is sent.
- Param size:
Pointer to the data size that will be sent.
-
void (*on_data_read)(pj_http_req *http_req, void *data, pj_size_t size)
This callback is called when a segment of response body data arrives. If this callback is specified (i.e. not NULL), the on_complete() callback will be called with zero-length data (within the response parameter), hence the application must store and manage its own data buffer, otherwise the on_complete() callback will be called with the response parameter containing the complete data.
- Param http_req:
The http request.
- Param data:
The buffer containing the data.
- Param size:
The length of data in the buffer.
-
void (*on_complete)(pj_http_req *http_req, pj_status_t status, const pj_http_resp *resp)
This callback is called when the HTTP request is completed. If the callback on_data_read() is specified, the variable response->data will be set to NULL, otherwise it will contain the complete data. Response data is allocated from pj_http_req’s internal memory pool so the data remain valid as long as pj_http_req is not destroyed and application does not start a new request.
If no longer required, application may choose to destroy pj_http_req immediately by calling pj_http_req_destroy() inside the callback.
- Param http_req:
The http request.
- Param status:
The status of the request operation. PJ_SUCCESS if the operation completed successfully (connection-wise). To check the server’s status-code response to the HTTP request, application should check resp->status_code instead.
- Param resp:
The response of the corresponding request. If the status argument is non-PJ_SUCCESS, this argument will be set to NULL.
-
void (*on_response)(pj_http_req *http_req, const pj_http_resp *resp)