123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493 |
- /*
- * Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com)
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
- */
- #ifndef __PJLIB_UTIL_HTTP_CLIENT_H__
- #define __PJLIB_UTIL_HTTP_CLIENT_H__
- /**
- * @file http_client.h
- * @brief Simple HTTP Client
- */
- #include <pj/activesock.h>
- #include <pjlib-util/types.h>
- PJ_BEGIN_DECL
- /**
- * @defgroup PJ_HTTP_CLIENT Simple HTTP Client
- * @ingroup PJ_PROTOCOLS
- * @{
- * This contains a simple HTTP client implementation.
- * Some known limitations:
- * - Does not support chunked Transfer-Encoding.
- */
- /**
- * This opaque structure describes the http request.
- */
- typedef struct pj_http_req pj_http_req;
- /**
- * Defines the maximum number of elements in a pj_http_headers
- * structure.
- */
- #define PJ_HTTP_HEADER_SIZE 32
- /**
- * HTTP header representation.
- */
- typedef struct pj_http_header_elmt
- {
- pj_str_t name; /**< Header name */
- pj_str_t value; /**< Header value */
- } pj_http_header_elmt;
- /**
- * This structure describes http request/response headers.
- * Application should call #pj_http_headers_add_elmt() to
- * add a header field.
- */
- typedef struct pj_http_headers
- {
- /**< Number of header fields */
- unsigned count;
- /** Header elements/fields */
- pj_http_header_elmt header[PJ_HTTP_HEADER_SIZE];
- } pj_http_headers;
- /**
- * Structure to save HTTP authentication credential.
- */
- typedef struct pj_http_auth_cred
- {
- /**
- * 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 scheme;
- /**
- * 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.
- */
- pj_str_t realm;
- /**
- * Specify authentication username.
- *
- * Default is empty.
- */
- pj_str_t username;
- /**
- * The type of password in \a data field. Currently only 0 is
- * supported, meaning the \a data contains plain-text password.
- *
- * Default is 0.
- */
- unsigned data_type;
- /**
- * Specify authentication password. The encoding of the password depends
- * on the value of \a data_type field above.
- *
- * Default is empty.
- */
- pj_str_t data;
- } pj_http_auth_cred;
- /**
- * Parameters that can be given during http request creation. Application
- * must initialize this structure with #pj_http_req_param_default().
- */
- typedef struct pj_http_req_param
- {
- /**
- * The address family of the URL.
- * Default is pj_AF_INET().
- */
- int addr_family;
- /**
- * The HTTP request method.
- * Default is GET.
- */
- pj_str_t method;
- /**
- * The HTTP protocol version ("1.0" or "1.1").
- * Default is "1.0".
- */
- pj_str_t version;
- /**
- * HTTP request operation timeout.
- * Default is PJ_HTTP_DEFAULT_TIMEOUT.
- */
- pj_time_val timeout;
- /**
- * User-defined data.
- * Default is NULL.
- */
- void *user_data;
- /**
- * HTTP request headers.
- * Default is empty.
- */
- pj_http_headers headers;
- /**
- * 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.
- */
- struct pj_http_reqdata
- {
- void *data; /**< Request body data */
- pj_size_t size; /**< Request body size */
- pj_size_t total_size; /**< If total_size > 0, data */
- /**< will be provided later */
- } reqdata; /**< The request body */
- /**
- * Authentication credential needed to respond to 401/407 response.
- */
- pj_http_auth_cred auth_cred;
- /**
- * 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_start;
- /**
- * 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 source_port_range_size;
- /**
- * 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
- */
- pj_uint16_t max_retries;
- } pj_http_req_param;
- /**
- * HTTP authentication challenge, parsed from WWW-Authenticate header.
- */
- typedef struct pj_http_auth_chal
- {
- pj_str_t scheme; /**< Auth scheme. */
- pj_str_t realm; /**< Realm for the challenge. */
- pj_str_t domain; /**< Domain. */
- pj_str_t nonce; /**< Nonce challenge. */
- pj_str_t opaque; /**< Opaque value. */
- int stale; /**< Stale parameter. */
- pj_str_t algorithm; /**< Algorithm parameter. */
- pj_str_t qop; /**< Quality of protection. */
- } pj_http_auth_chal;
- /**
- * This structure describes HTTP response.
- */
- typedef struct pj_http_resp
- {
- pj_str_t version; /**< HTTP version of the server */
- pj_uint16_t status_code; /**< Status code of the request */
- pj_str_t reason; /**< Reason phrase */
- 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_size_t size; /**< Data size */
- } pj_http_resp;
- /**
- * This structure describes HTTP URL.
- */
- typedef struct pj_http_url
- {
- pj_str_t username; /**< Username part */
- pj_str_t passwd; /**< Password part */
- pj_str_t protocol; /**< Protocol used */
- pj_str_t host; /**< Host name */
- pj_uint16_t port; /**< Port number */
- pj_str_t path; /**< Path */
- } pj_http_url;
- /**
- * This structure describes the callbacks to be called by the HTTP request.
- */
- typedef struct pj_http_req_callback
- {
- /**
- * 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_response)(pj_http_req *http_req, const pj_http_resp *resp);
- /**
- * 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_send_data)(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_data_read)(pj_http_req *http_req,
- void *data, pj_size_t size);
- /**
- * 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_complete)(pj_http_req *http_req,
- pj_status_t status,
- const pj_http_resp *resp);
- } pj_http_req_callback;
- /**
- * Initialize the http request parameters with the default values.
- *
- * @param param The parameter to be initialized.
- */
- PJ_DECL(void) pj_http_req_param_default(pj_http_req_param *param);
- /**
- * Add a header element/field. Application MUST make sure that
- * name and val pointer remains valid until the HTTP request is sent.
- *
- * @param headers The headers.
- * @param name The header field name.
- * @param val The header field value.
- *
- * @return PJ_SUCCESS if the operation has been successful,
- * or the appropriate error code on failure.
- */
- PJ_DECL(pj_status_t) pj_http_headers_add_elmt(pj_http_headers *headers,
- pj_str_t *name,
- pj_str_t *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.
- *
- * @param headers The headers.
- * @param name The header field name.
- * @param val The header field value.
- *
- * @return PJ_SUCCESS if the operation has been successful,
- * or the appropriate error code on failure.
- */
- PJ_DECL(pj_status_t) pj_http_headers_add_elmt2(pj_http_headers *headers,
- char *name, char *val);
- /**
- * Parse a http URL into its components.
- *
- * @param url The URL to be parsed.
- * @param hurl Pointer to receive the parsed result.
- *
- * @return PJ_SUCCESS if the operation has been successful,
- * or the appropriate error code on failure.
- */
- PJ_DECL(pj_status_t) pj_http_req_parse_url(const pj_str_t *url,
- pj_http_url *hurl);
- /**
- * Create the HTTP request.
- *
- * @param pool Pool to use. HTTP request will use the pool's factory
- * to allocate its own memory pool.
- * @param url HTTP URL request.
- * @param timer The timer to use.
- * @param ioqueue The ioqueue to use.
- * @param param Optional parameters. When this parameter is not
- * specifed (NULL), the default values will be used.
- * @param hcb Pointer to structure containing application
- * callbacks.
- * @param http_req Pointer to receive the http request instance.
- *
- * @return PJ_SUCCESS if the operation has been successful,
- * or the appropriate error code on failure.
- */
- PJ_DECL(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);
- /**
- * 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.
- *
- * @param http_req The http request.
- * @param timeout Timeout value for HTTP request operation.
- */
- PJ_DECL(void) pj_http_req_set_timeout(pj_http_req *http_req,
- const pj_time_val* timeout);
- /**
- * Starts an asynchronous HTTP request to the URL specified.
- *
- * @param http_req The http request.
- *
- * @return
- * - PJ_SUCCESS if success
- * - non-zero which indicates the appropriate error code.
- */
- PJ_DECL(pj_status_t) pj_http_req_start(pj_http_req *http_req);
- /**
- * Cancel the asynchronous HTTP request.
- *
- * @param http_req The http request.
- * @param notify If non-zero, the on_complete() callback will be
- * called with status PJ_ECANCELLED to notify that
- * the query has been cancelled.
- *
- * @return
- * - PJ_SUCCESS if success
- * - non-zero which indicates the appropriate error code.
- */
- PJ_DECL(pj_status_t) pj_http_req_cancel(pj_http_req *http_req,
- pj_bool_t notify);
- /**
- * Destroy the http request.
- *
- * @param http_req The http request to be destroyed.
- *
- * @return PJ_SUCCESS if success.
- */
- PJ_DECL(pj_status_t) pj_http_req_destroy(pj_http_req *http_req);
- /**
- * Find out whether the http request is running.
- *
- * @param http_req The http request.
- *
- * @return PJ_TRUE if a request is pending, or
- * PJ_FALSE if idle
- */
- PJ_DECL(pj_bool_t) pj_http_req_is_running(const pj_http_req *http_req);
- /**
- * Retrieve the user data previously associated with this http
- * request.
- *
- * @param http_req The http request.
- *
- * @return The user data.
- */
- PJ_DECL(void *) pj_http_req_get_user_data(pj_http_req *http_req);
- /**
- * @}
- */
- PJ_END_DECL
- #endif /* __PJLIB_UTIL_HTTP_CLIENT_H__ */
|