http_client.h 16 KB

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