Simple HTTP Client

Data Structures
struct	pj_http_header_elmt
struct	pj_http_headers
struct	pj_http_auth_cred
struct	pj_http_req_param
struct	pj_http_auth_chal
struct	pj_http_resp
struct	pj_http_url
struct	pj_http_req_callback

Macros
#define	PJ_HTTP_HEADER_SIZE   32

Typedefs
typedef struct pj_http_req	pj_http_req

Functions
void	pj_http_req_param_default (pj_http_req_param *param)
pj_status_t	pj_http_headers_add_elmt (pj_http_headers *headers, pj_str_t *name, pj_str_t *val)
pj_status_t	pj_http_headers_add_elmt2 (pj_http_headers *headers, char *name, char *val)
pj_status_t	pj_http_req_parse_url (const pj_str_t *url, pj_http_url *hurl)
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)
void	pj_http_req_set_timeout (pj_http_req *http_req, const pj_time_val *timeout)
pj_status_t	pj_http_req_start (pj_http_req *http_req)
pj_status_t	pj_http_req_cancel (pj_http_req *http_req, pj_bool_t notify)
pj_status_t	pj_http_req_destroy (pj_http_req *http_req)
pj_bool_t	pj_http_req_is_running (const pj_http_req *http_req)
void *	pj_http_req_get_user_data (pj_http_req *http_req)

---

Detailed Description

This contains a simple HTTP client implementation. Some known limitations:

• Does not support chunked Transfer-Encoding.

---

Macro Definition Documentation

#define PJ_HTTP_HEADER_SIZE   32

Defines the maximum number of elements in a pj_http_headers structure.

---

Typedef Documentation

typedef struct pj_http_req pj_http_req

This opaque structure describes the http request.

---

Function Documentation

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.
value	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.
value	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_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_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.

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.

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.

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_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_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.

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.