Advertisement
tomkiewicz

http-api-proposal

Oct 10th, 2012
167
0
Never
Not a member of Pastebin yet? Sign Up, it unlocks many cool features!
C 8.82 KB | None | 0 0
  1. /**
  2.  * @file http.h HTTP API proposal
  3.  * @ingroup core
  4.  */
  5.  
  6. /* purple license here */
  7.  
  8. #ifndef _PURPLE_HTTP_H_
  9. #define _PURPLE_HTTP_H_
  10.  
  11. /**
  12.  * A structure containing all data required to generate a single HTTP request.
  13.  */
  14. typedef struct _PurpleHttpRequest PurpleHttpRequest;
  15.  
  16. /**
  17.  * A representation of actually running HTTP request. Can be used to cancel the
  18.  * request.
  19.  */
  20. typedef struct _PurpleHttpConnection PurpleHttpConnection;
  21.  
  22. /**
  23.  * All information got with response for HTTP request.
  24.  */
  25. typedef struct _PurpleHttpResponse PurpleHttpResponse;
  26.  
  27. /**
  28.  * An collection of cookies, got from HTTP response or provided for HTTP
  29.  * request.
  30.  */
  31. typedef struct _PurpleHTTPCookieJar PurpleHTTPCookieJar;
  32.  
  33. /**
  34.  * An callback called after performing (successfully or not) HTTP request.
  35.  */
  36. typedef void (*PurpleHttpCallback)(PurpleHttpConnection *http_conn,
  37.     PurpleHttpResponse *response, gpointer user_data);
  38.  
  39. /**
  40.  * An callback called after storing data requested by PurpleHttpContentReader.
  41.  */
  42. typedef void (*PurpleHttpContentReaderCb)(PurpleHttpConnection *http_conn,
  43.     gboolean success, size_t stored);
  44.  
  45. /**
  46.  * An callback for getting large request contents (ie. from file stored on
  47.  * disk).
  48.  *
  49.  * @param http_conn Connection, which requests data.
  50.  * @param buffer    Buffer to store data to (with offset ignored).
  51.  * @param offset    Position, from where to read data.
  52.  * @param length    Length of data to read.
  53.  * @param user_data The user data passed with callback function.
  54.  * @param cb        The function to call after storing data to buffer.
  55.  */
  56. typedef void (*PurpleHttpContentReader)(PurpleHttpConnection *http_conn,
  57.     gchar *buffer, size_t offset, size_t length, gpointer user_data,
  58.     PurpleHttpContentReaderCb cb);
  59.  
  60. /**
  61.  * An callback for writting large response contents.
  62.  *
  63.  * @param http_conn Connection, which requests data.
  64.  * @param buffer    Buffer to read data from (with offset ignored).
  65.  * @param offset    Position of data got (its value is offset + length of
  66.  *                  previous call), can be safely ignored.
  67.  * @param length    Length of data read.
  68.  * @param user_data The user data passed with callback function.
  69.  */
  70. typedef void (*PurpleHttpContentWriter)(PurpleHttpConnection *http_conn,
  71.     const gchar *buffer, size_t offset, size_t length, gpointer user_data);
  72.  
  73. G_BEGIN_DECLS
  74.  
  75. /**************************************************************************/
  76. /** @name Performing HTTP requests                                        */
  77. /**************************************************************************/
  78. /*@{*/
  79.  
  80. /**
  81.  * Fetches the data from a URL with GET request, and passes it to a callback
  82.  * function.
  83.  *
  84.  * @param gc       The connection for which the request is needed, or NULL.
  85.  * @param url      The URL.
  86.  * @param callback The callback function.
  87.  * @param data     The user data to pass to the callback function.
  88.  * @return         The HTTP connection struct.
  89.  */
  90. PurpleHttpConnection * purple_http_get(PurpleConnection *gc, const gchar *url,
  91.     PurpleHttpCallback callback, gpointer user_data);
  92.  
  93. /**
  94.  * Fetches a HTTP request and passes the response to a callback function.
  95.  * Provided request struct can be shared by multiple http requests but can not
  96.  * be modified when any of these is running.
  97.  *
  98.  * @param gc        The connection for which the request is needed, or NULL.
  99.  * @param request   The request.
  100.  * @param callback  The callback function.
  101.  * @param user_data The user data to pass to the callback function.
  102.  * @return          The HTTP connection struct.
  103.  */
  104. PurpleHttpConnection * purple_http_request(PurpleConnection *gc,
  105.     PurpleHttpRequest *request, PurpleHttpCallback callback,
  106.     gpointer user_data);
  107.  
  108. /**************************************************************************/
  109. /** @name HTTP connection API                                             */
  110. /**************************************************************************/
  111. /*@{*/
  112.  
  113. /**
  114.  * Cancel a pending HTTP request.
  115.  *
  116.  * @param http_conn The data returned when you initiated the HTTP request.
  117.  */
  118. void purple_http_conn_cancel(PurpleHttpConnection *http_conn);
  119.  
  120. /**
  121.  * Checks, if provided HTTP request is running.
  122.  *
  123.  * @param http_conn The HTTP connection.
  124.  * @return          TRUE, if provided connection is currently running.
  125.  */
  126. gboolean purple_http_conn_is_running(PurpleHttpConnection *http_conn);
  127.  
  128. PurpleHttpRequest * purple_http_conn_get_request(
  129.     PurpleHttpConnection *http_conn);
  130.  
  131. /*@}*/
  132.  
  133.  
  134. /**************************************************************************/
  135. /** @name Cookie jar API                                                  */
  136. /**************************************************************************/
  137. /*@{*/
  138.  
  139. PurpleHTTPCookieJar * purple_http_cookie_jar_new(void);
  140.  
  141. void purple_http_cookie_jar_ref(PurpleHTTPCookieJar *cookie_jar);
  142.  
  143. void purple_http_cookie_jar_unref(PurpleHTTPCookieJar *cookie_jar);
  144.  
  145. void purple_http_cookie_jar_set(PurpleHTTPCookieJar *cookie_jar,
  146.     const gchar *name, const gchar *value);
  147.  
  148. const gchar * purple_http_cookie_jar_get(PurpleHTTPCookieJar *cookie_jar,
  149.     const gchar *name);
  150.  
  151. void purple_http_cookie_jar_remove(PurpleHTTPCookieJar *cookie_jar,
  152.     const gchar *name);
  153.  
  154. /*@}*/
  155.  
  156.  
  157. /**************************************************************************/
  158. /** @name HTTP Request API                                                */
  159. /**************************************************************************/
  160. /*@{*/
  161.  
  162. PurpleHttpRequest * purple_http_request_new(const gchar *url);
  163.  
  164. void purple_http_request_ref(PurpleHttpRequest *request);
  165.  
  166. void purple_http_request_unref(PurpleHttpRequest *request); // instead of free
  167.  
  168. void purple_http_request_set_url(PurpleHttpRequest *request, const gchar *url); // +get
  169.  
  170. void purple_http_request_set_method(PurpleHttpRequest *request,
  171.     const gchar *method); // +get
  172.  
  173. /**
  174.  * Sets contents of HTTP request (for example, POST data).
  175.  *
  176.  * @param request  The request.
  177.  * @param contents The contents.
  178.  * @param length   The length of contents (-1 if it's a NULL-terminated string)
  179.  */
  180. void purple_http_request_set_contents(PurpleHttpRequest *request,
  181.     const gchar *contents, int length); // +get
  182.  
  183. /**
  184.  * Sets contents reader for HTTP request, used mainly for possible large
  185.  * uploads.
  186.  *
  187.  * @param request   The request.
  188.  * @param reader    The reader callback.
  189.  * @param user_data The user data to pass to the callback function.
  190.  */
  191. void purple_http_request_set_contents_reader(PurpleHttpRequest *request,
  192.     PurpleHttpContentReader reader, gpointer user_data);
  193.  
  194. /**
  195.  * Set contents writer for HTTP response.
  196.  *
  197.  * @param request   The request.
  198.  * @param reader    The writer callback.
  199.  * @param user_data The user data to pass to the callback function.
  200.  */
  201. void purple_http_request_set_response_writer(PurpleHttpRequest *request,
  202.     PurpleHttpContentWriter writer, gpointer user_data);
  203.  
  204. /**
  205.  * -1 for unlimited
  206.  */
  207. void purple_http_request_set_max_redirects(PurpleHttpRequest *request,
  208.     int max_redirects); // +get
  209.  
  210. /**
  211.  * NULL for disabling cookie support
  212.  */
  213. void purple_http_request_set_cookie_jar(PurpleHttpRequest *request,
  214.     PurpleHTTPCookieJar *cookie_jar); // +get
  215.  
  216. /**
  217.  * NULL for default
  218.  */
  219. void purple_http_request_set_user_agent(PurpleHttpRequest *request,
  220.     const gchar *user_agent); // +get
  221.  
  222. void purple_http_request_set_http11(PurpleHttpRequest *request,
  223.     gboolean http11); // +is
  224.  
  225. /**
  226.  * -1 for unlimited
  227.  */
  228. void purple_http_request_set_max_len(PurpleHttpRequest *request, int max_len); // +get
  229.  
  230. /**
  231.  * Sets (replaces, if exists) specified HTTP request header with provided value.
  232.  *
  233.  * @param key   A header to be set.
  234.  * @param value A value to set, or NULL to remove specified header from request.
  235.  *
  236.  * @see purple_http_request_header_add
  237.  */
  238. void purple_http_request_header_set(PurpleHttpRequest *request,
  239.     const gchar *key, const gchar *value);
  240.  
  241. /**
  242.  * Adds (without replacing, if exists) an HTTP request header.
  243.  *
  244.  * @param key   A header to be set.
  245.  * @param value A value to set.
  246.  *
  247.  * @see purple_http_request_header_set
  248.  */
  249. void purple_http_request_header_add(PurpleHttpRequest *request,
  250.     const gchar *key, const gchar *value);
  251.  
  252. /*@}*/
  253.  
  254. /**************************************************************************/
  255. /** @name HTTP response API                                               */
  256. /**************************************************************************/
  257. /*@{*/
  258.  
  259. gboolean purple_http_response_is_successfull(PurpleHttpResponse *response);
  260.  
  261. int purple_http_response_get_code(PurpleHttpResponse *response);
  262.  
  263. const gchar * purple_http_response_get_error(PurpleHttpResponse *response);
  264.  
  265. gsize purple_http_response_get_data_len(PurpleHttpResponse *response);
  266.  
  267. const gchar * purple_http_response_get_data(PurpleHttpResponse *response);
  268.  
  269. const GList purple_http_response_get_all_headers(PurpleHttpResponse *response);
  270.  
  271. const GList purple_http_response_get_headers_by_name(
  272.     PurpleHttpResponse *response, const gchar *name);
  273.  
  274. const gchar * purple_http_response_get_header(PurpleHttpResponse *response,
  275.     const gchar *name);
  276.  
  277. /*@}*/
  278.  
  279.  
  280. G_END_DECLS
  281.  
  282. #endif /* _PURPLE_HTTP_H_ */
Advertisement
Add Comment
Please, Sign In to add comment
Advertisement