Tristan Matthews | 0a329cc | 2013-07-17 13:20:14 -0400 | [diff] [blame] | 1 | /* $Id$ */ |
| 2 | /* |
| 3 | * Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com) |
| 4 | * |
| 5 | * This program is free software; you can redistribute it and/or modify |
| 6 | * it under the terms of the GNU General Public License as published by |
| 7 | * the Free Software Foundation; either version 2 of the License, or |
| 8 | * (at your option) any later version. |
| 9 | * |
| 10 | * This program is distributed in the hope that it will be useful, |
| 11 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 12 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| 13 | * GNU General Public License for more details. |
| 14 | * |
| 15 | * You should have received a copy of the GNU General Public License |
| 16 | * along with this program; if not, write to the Free Software |
| 17 | * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA |
| 18 | */ |
| 19 | #ifndef __PJLIB_UTIL_HTTP_CLIENT_H__ |
| 20 | #define __PJLIB_UTIL_HTTP_CLIENT_H__ |
| 21 | |
| 22 | /** |
| 23 | * @file http_client.h |
| 24 | * @brief Simple HTTP Client |
| 25 | */ |
| 26 | #include <pj/activesock.h> |
| 27 | #include <pjlib-util/types.h> |
| 28 | |
| 29 | PJ_BEGIN_DECL |
| 30 | |
| 31 | /** |
| 32 | * @defgroup PJ_HTTP_CLIENT Simple HTTP Client |
| 33 | * @ingroup PJ_PROTOCOLS |
| 34 | * @{ |
| 35 | * This contains a simple HTTP client implementation. |
| 36 | * Some known limitations: |
| 37 | * - Does not support chunked Transfer-Encoding. |
| 38 | */ |
| 39 | |
| 40 | /** |
| 41 | * This opaque structure describes the http request. |
| 42 | */ |
| 43 | typedef struct pj_http_req pj_http_req; |
| 44 | |
| 45 | /** |
| 46 | * Defines the maximum number of elements in a pj_http_headers |
| 47 | * structure. |
| 48 | */ |
| 49 | #define PJ_HTTP_HEADER_SIZE 32 |
| 50 | |
| 51 | /** |
| 52 | * HTTP header representation. |
| 53 | */ |
| 54 | typedef struct pj_http_header_elmt |
| 55 | { |
| 56 | pj_str_t name; /**< Header name */ |
| 57 | pj_str_t value; /**< Header value */ |
| 58 | } pj_http_header_elmt; |
| 59 | |
| 60 | /** |
| 61 | * This structure describes http request/response headers. |
| 62 | * Application should call #pj_http_headers_add_elmt() to |
| 63 | * add a header field. |
| 64 | */ |
| 65 | typedef struct pj_http_headers |
| 66 | { |
| 67 | /**< Number of header fields */ |
| 68 | unsigned count; |
| 69 | |
| 70 | /** Header elements/fields */ |
| 71 | pj_http_header_elmt header[PJ_HTTP_HEADER_SIZE]; |
| 72 | } pj_http_headers; |
| 73 | |
| 74 | /** |
| 75 | * Structure to save HTTP authentication credential. |
| 76 | */ |
| 77 | typedef struct pj_http_auth_cred |
| 78 | { |
| 79 | /** |
| 80 | * Specify specific authentication schemes to be responded. Valid values |
| 81 | * are "basic" and "digest". If this field is not set, any authentication |
| 82 | * schemes will be responded. |
| 83 | * |
| 84 | * Default is empty. |
| 85 | */ |
| 86 | pj_str_t scheme; |
| 87 | |
| 88 | /** |
| 89 | * Specify specific authentication realm to be responded. If this field |
| 90 | * is set, only 401/407 response with matching realm will be responded. |
| 91 | * If this field is not set, any realms will be responded. |
| 92 | * |
| 93 | * Default is empty. |
| 94 | */ |
| 95 | pj_str_t realm; |
| 96 | |
| 97 | /** |
| 98 | * Specify authentication username. |
| 99 | * |
| 100 | * Default is empty. |
| 101 | */ |
| 102 | pj_str_t username; |
| 103 | |
| 104 | /** |
| 105 | * The type of password in \a data field. Currently only 0 is |
| 106 | * supported, meaning the \a data contains plain-text password. |
| 107 | * |
| 108 | * Default is 0. |
| 109 | */ |
| 110 | unsigned data_type; |
| 111 | |
| 112 | /** |
| 113 | * Specify authentication password. The encoding of the password depends |
| 114 | * on the value of \a data_type field above. |
| 115 | * |
| 116 | * Default is empty. |
| 117 | */ |
| 118 | pj_str_t data; |
| 119 | |
| 120 | } pj_http_auth_cred; |
| 121 | |
| 122 | |
| 123 | /** |
| 124 | * Parameters that can be given during http request creation. Application |
| 125 | * must initialize this structure with #pj_http_req_param_default(). |
| 126 | */ |
| 127 | typedef struct pj_http_req_param |
| 128 | { |
| 129 | /** |
| 130 | * The address family of the URL. |
| 131 | * Default is pj_AF_INET(). |
| 132 | */ |
| 133 | int addr_family; |
| 134 | |
| 135 | /** |
| 136 | * The HTTP request method. |
| 137 | * Default is GET. |
| 138 | */ |
| 139 | pj_str_t method; |
| 140 | |
| 141 | /** |
| 142 | * The HTTP protocol version ("1.0" or "1.1"). |
| 143 | * Default is "1.0". |
| 144 | */ |
| 145 | pj_str_t version; |
| 146 | |
| 147 | /** |
| 148 | * HTTP request operation timeout. |
| 149 | * Default is PJ_HTTP_DEFAULT_TIMEOUT. |
| 150 | */ |
| 151 | pj_time_val timeout; |
| 152 | |
| 153 | /** |
| 154 | * User-defined data. |
| 155 | * Default is NULL. |
| 156 | */ |
| 157 | void *user_data; |
| 158 | |
| 159 | /** |
| 160 | * HTTP request headers. |
| 161 | * Default is empty. |
| 162 | */ |
| 163 | pj_http_headers headers; |
| 164 | |
| 165 | /** |
| 166 | * This structure describes the http request body. If application |
| 167 | * specifies the data to send, the data must remain valid until |
| 168 | * the HTTP request is sent. Alternatively, application can choose |
| 169 | * to specify total_size as the total data size to send instead |
| 170 | * while leaving the data NULL (and its size 0). In this case, |
| 171 | * HTTP request will then call on_send_data() callback once it is |
| 172 | * ready to send the request body. This will be useful if |
| 173 | * application does not wish to load the data into the buffer at |
| 174 | * once. |
| 175 | * |
| 176 | * Default is empty. |
| 177 | */ |
| 178 | struct pj_http_reqdata |
| 179 | { |
| 180 | void *data; /**< Request body data */ |
| 181 | pj_size_t size; /**< Request body size */ |
| 182 | pj_size_t total_size; /**< If total_size > 0, data */ |
| 183 | /**< will be provided later */ |
| 184 | } reqdata; |
| 185 | |
| 186 | /** |
| 187 | * Authentication credential needed to respond to 401/407 response. |
| 188 | */ |
| 189 | pj_http_auth_cred auth_cred; |
| 190 | |
| 191 | /** |
| 192 | * Optional source port range to use when binding the socket. |
| 193 | * This can be used if the source port needs to be within a certain range |
| 194 | * for instance due to strict firewall settings. The port used will be |
| 195 | * randomized within the range. |
| 196 | * |
| 197 | * Note that if authentication is configured, the authentication response |
| 198 | * will be a new transaction |
| 199 | * |
| 200 | * Default is 0 (The OS will select the source port automatically) |
| 201 | */ |
| 202 | pj_uint16_t source_port_range_start; |
| 203 | |
| 204 | /** |
| 205 | * Optional source port range to use when binding. |
| 206 | * The size of the port restriction range |
| 207 | * |
| 208 | * Default is 0 (The OS will select the source port automatically)) |
| 209 | */ |
| 210 | pj_uint16_t source_port_range_size; |
| 211 | |
| 212 | /** |
| 213 | * Max number of retries if binding to a port fails. |
| 214 | * Note that this does not adress the scenario where a request times out |
| 215 | * or errors. This needs to be taken care of by the on_complete callback. |
| 216 | * |
| 217 | * Default is 3 |
| 218 | */ |
| 219 | pj_uint16_t max_retries; |
| 220 | |
| 221 | } pj_http_req_param; |
| 222 | |
| 223 | /** |
| 224 | * HTTP authentication challenge, parsed from WWW-Authenticate header. |
| 225 | */ |
| 226 | typedef struct pj_http_auth_chal |
| 227 | { |
| 228 | pj_str_t scheme; /**< Auth scheme. */ |
| 229 | pj_str_t realm; /**< Realm for the challenge. */ |
| 230 | pj_str_t domain; /**< Domain. */ |
| 231 | pj_str_t nonce; /**< Nonce challenge. */ |
| 232 | pj_str_t opaque; /**< Opaque value. */ |
| 233 | int stale; /**< Stale parameter. */ |
| 234 | pj_str_t algorithm; /**< Algorithm parameter. */ |
| 235 | pj_str_t qop; /**< Quality of protection. */ |
| 236 | } pj_http_auth_chal; |
| 237 | |
| 238 | /** |
| 239 | * This structure describes HTTP response. |
| 240 | */ |
| 241 | typedef struct pj_http_resp |
| 242 | { |
| 243 | pj_str_t version; /**< HTTP version of the server */ |
| 244 | pj_uint16_t status_code; /**< Status code of the request */ |
| 245 | pj_str_t reason; /**< Reason phrase */ |
| 246 | pj_http_headers headers; /**< Response headers */ |
| 247 | pj_http_auth_chal auth_chal; /**< Parsed WWW-Authenticate header, if |
| 248 | any. */ |
| 249 | pj_int32_t content_length; /**< The value of content-length header |
| 250 | field. -1 if not specified. */ |
| 251 | void *data; /**< Data received */ |
| 252 | pj_size_t size; /**< Data size */ |
| 253 | } pj_http_resp; |
| 254 | |
| 255 | /** |
| 256 | * This structure describes HTTP URL. |
| 257 | */ |
| 258 | typedef struct pj_http_url |
| 259 | { |
| 260 | pj_str_t username; /**< Username part */ |
| 261 | pj_str_t passwd; /**< Password part */ |
| 262 | pj_str_t protocol; /**< Protocol used */ |
| 263 | pj_str_t host; /**< Host name */ |
| 264 | pj_uint16_t port; /**< Port number */ |
| 265 | pj_str_t path; /**< Path */ |
| 266 | } pj_http_url; |
| 267 | |
| 268 | /** |
| 269 | * This structure describes the callbacks to be called by the HTTP request. |
| 270 | */ |
| 271 | typedef struct pj_http_req_callback |
| 272 | { |
| 273 | /** |
| 274 | * This callback is called when a complete HTTP response header |
| 275 | * is received. |
| 276 | * |
| 277 | * @param http_req The http request. |
| 278 | * @param resp The response of the request. |
| 279 | */ |
| 280 | void (*on_response)(pj_http_req *http_req, const pj_http_resp *resp); |
| 281 | |
| 282 | /** |
| 283 | * This callback is called when the HTTP request is ready to send |
| 284 | * its request body. Application may wish to use this callback if |
| 285 | * it wishes to load the data at a later time or if it does not |
| 286 | * wish to load the whole data into memory. In order for this |
| 287 | * callback to be called, application MUST set http_req_param.total_size |
| 288 | * to a value greater than 0. |
| 289 | * |
| 290 | * @param http_req The http request. |
| 291 | * @param data Pointer to the data that will be sent. Application |
| 292 | * must set the pointer to the current data chunk/segment |
| 293 | * to be sent. Data must remain valid until the next |
| 294 | * on_send_data() callback or for the last segment, |
| 295 | * until it is sent. |
| 296 | * @param size Pointer to the data size that will be sent. |
| 297 | */ |
| 298 | void (*on_send_data)(pj_http_req *http_req, |
| 299 | void **data, pj_size_t *size); |
| 300 | |
| 301 | /** |
| 302 | * This callback is called when a segment of response body data |
| 303 | * arrives. If this callback is specified (i.e. not NULL), the |
| 304 | * on_complete() callback will be called with zero-length data |
| 305 | * (within the response parameter), hence the application must |
| 306 | * store and manage its own data buffer, otherwise the |
| 307 | * on_complete() callback will be called with the response |
| 308 | * parameter containing the complete data. |
| 309 | * |
| 310 | * @param http_req The http request. |
| 311 | * @param data The buffer containing the data. |
| 312 | * @param size The length of data in the buffer. |
| 313 | */ |
| 314 | void (*on_data_read)(pj_http_req *http_req, |
| 315 | void *data, pj_size_t size); |
| 316 | |
| 317 | /** |
| 318 | * This callback is called when the HTTP request is completed. |
| 319 | * If the callback on_data_read() is specified, the variable |
| 320 | * response->data will be set to NULL, otherwise it will |
| 321 | * contain the complete data. Response data is allocated from |
| 322 | * pj_http_req's internal memory pool so the data remain valid |
| 323 | * as long as pj_http_req is not destroyed and application does |
| 324 | * not start a new request. |
| 325 | * |
| 326 | * If no longer required, application may choose to destroy |
| 327 | * pj_http_req immediately by calling #pj_http_req_destroy() inside |
| 328 | * the callback. |
| 329 | * |
| 330 | * @param http_req The http request. |
| 331 | * @param status The status of the request operation. PJ_SUCCESS |
| 332 | * if the operation completed successfully |
| 333 | * (connection-wise). To check the server's |
| 334 | * status-code response to the HTTP request, |
| 335 | * application should check resp->status_code instead. |
| 336 | * @param resp The response of the corresponding request. If |
| 337 | * the status argument is non-PJ_SUCCESS, this |
| 338 | * argument will be set to NULL. |
| 339 | */ |
| 340 | void (*on_complete)(pj_http_req *http_req, |
| 341 | pj_status_t status, |
| 342 | const pj_http_resp *resp); |
| 343 | |
| 344 | } pj_http_req_callback; |
| 345 | |
| 346 | |
| 347 | /** |
| 348 | * Initialize the http request parameters with the default values. |
| 349 | * |
| 350 | * @param param The parameter to be initialized. |
| 351 | */ |
| 352 | PJ_DECL(void) pj_http_req_param_default(pj_http_req_param *param); |
| 353 | |
| 354 | /** |
| 355 | * Add a header element/field. Application MUST make sure that |
| 356 | * name and val pointer remains valid until the HTTP request is sent. |
| 357 | * |
| 358 | * @param headers The headers. |
| 359 | * @param name The header field name. |
| 360 | * @param value The header field value. |
| 361 | * |
| 362 | * @return PJ_SUCCESS if the operation has been successful, |
| 363 | * or the appropriate error code on failure. |
| 364 | */ |
| 365 | PJ_DECL(pj_status_t) pj_http_headers_add_elmt(pj_http_headers *headers, |
| 366 | pj_str_t *name, |
| 367 | pj_str_t *val); |
| 368 | |
| 369 | /** |
| 370 | * The same as #pj_http_headers_add_elmt() with char * as |
| 371 | * its parameters. Application MUST make sure that name and val pointer |
| 372 | * remains valid until the HTTP request is sent. |
| 373 | * |
| 374 | * @param headers The headers. |
| 375 | * @param name The header field name. |
| 376 | * @param value The header field value. |
| 377 | * |
| 378 | * @return PJ_SUCCESS if the operation has been successful, |
| 379 | * or the appropriate error code on failure. |
| 380 | */ |
| 381 | PJ_DECL(pj_status_t) pj_http_headers_add_elmt2(pj_http_headers *headers, |
| 382 | char *name, char *val); |
| 383 | |
| 384 | /** |
| 385 | * Parse a http URL into its components. |
| 386 | * |
| 387 | * @param url The URL to be parsed. |
| 388 | * @param hurl Pointer to receive the parsed result. |
| 389 | * |
| 390 | * @return PJ_SUCCESS if the operation has been successful, |
| 391 | * or the appropriate error code on failure. |
| 392 | */ |
| 393 | PJ_DECL(pj_status_t) pj_http_req_parse_url(const pj_str_t *url, |
| 394 | pj_http_url *hurl); |
| 395 | |
| 396 | /** |
| 397 | * Create the HTTP request. |
| 398 | * |
| 399 | * @param pool Pool to use. HTTP request will use the pool's factory |
| 400 | * to allocate its own memory pool. |
| 401 | * @param url HTTP URL request. |
| 402 | * @param timer The timer to use. |
| 403 | * @param ioqueue The ioqueue to use. |
| 404 | * @param param Optional parameters. When this parameter is not |
| 405 | * specifed (NULL), the default values will be used. |
| 406 | * @param hcb Pointer to structure containing application |
| 407 | * callbacks. |
| 408 | * @param http_req Pointer to receive the http request instance. |
| 409 | * |
| 410 | * @return PJ_SUCCESS if the operation has been successful, |
| 411 | * or the appropriate error code on failure. |
| 412 | */ |
| 413 | PJ_DECL(pj_status_t) pj_http_req_create(pj_pool_t *pool, |
| 414 | const pj_str_t *url, |
| 415 | pj_timer_heap_t *timer, |
| 416 | pj_ioqueue_t *ioqueue, |
| 417 | const pj_http_req_param *param, |
| 418 | const pj_http_req_callback *hcb, |
| 419 | pj_http_req **http_req); |
| 420 | |
| 421 | /** |
| 422 | * Set the timeout of the HTTP request operation. Note that if the |
| 423 | * HTTP request is currently running, the timeout will only affect |
| 424 | * subsequent request operations. |
| 425 | * |
| 426 | * @param http_req The http request. |
| 427 | * @param timeout Timeout value for HTTP request operation. |
| 428 | */ |
| 429 | PJ_DECL(void) pj_http_req_set_timeout(pj_http_req *http_req, |
| 430 | const pj_time_val* timeout); |
| 431 | |
| 432 | /** |
| 433 | * Starts an asynchronous HTTP request to the URL specified. |
| 434 | * |
| 435 | * @param http_req The http request. |
| 436 | * |
| 437 | * @return |
| 438 | * - PJ_SUCCESS if success |
| 439 | * - non-zero which indicates the appropriate error code. |
| 440 | */ |
| 441 | PJ_DECL(pj_status_t) pj_http_req_start(pj_http_req *http_req); |
| 442 | |
| 443 | /** |
| 444 | * Cancel the asynchronous HTTP request. |
| 445 | * |
| 446 | * @param http_req The http request. |
| 447 | * @param notify If non-zero, the on_complete() callback will be |
| 448 | * called with status PJ_ECANCELLED to notify that |
| 449 | * the query has been cancelled. |
| 450 | * |
| 451 | * @return |
| 452 | * - PJ_SUCCESS if success |
| 453 | * - non-zero which indicates the appropriate error code. |
| 454 | */ |
| 455 | PJ_DECL(pj_status_t) pj_http_req_cancel(pj_http_req *http_req, |
| 456 | pj_bool_t notify); |
| 457 | |
| 458 | /** |
| 459 | * Destroy the http request. |
| 460 | * |
| 461 | * @param http_req The http request to be destroyed. |
| 462 | * |
| 463 | * @return PJ_SUCCESS if success. |
| 464 | */ |
| 465 | PJ_DECL(pj_status_t) pj_http_req_destroy(pj_http_req *http_req); |
| 466 | |
| 467 | /** |
| 468 | * Find out whether the http request is running. |
| 469 | * |
| 470 | * @param http_req The http request. |
| 471 | * |
| 472 | * @return PJ_TRUE if a request is pending, or |
| 473 | * PJ_FALSE if idle |
| 474 | */ |
| 475 | PJ_DECL(pj_bool_t) pj_http_req_is_running(const pj_http_req *http_req); |
| 476 | |
| 477 | /** |
| 478 | * Retrieve the user data previously associated with this http |
| 479 | * request. |
| 480 | * |
| 481 | * @param http_req The http request. |
| 482 | * |
| 483 | * @return The user data. |
| 484 | */ |
| 485 | PJ_DECL(void *) pj_http_req_get_user_data(pj_http_req *http_req); |
| 486 | |
| 487 | /** |
| 488 | * @} |
| 489 | */ |
| 490 | |
| 491 | PJ_END_DECL |
| 492 | |
| 493 | |
| 494 | #endif /* __PJLIB_UTIL_HTTP_CLIENT_H__ */ |