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__ */ 495