libpurple/http.h

   1 /* purple
   2  *
   3  * Purple is the legal property of its developers, whose names are too numerous
   4  * to list here.  Please refer to the COPYRIGHT file distributed with this
   5  * source distribution.
   6  *
   7  * This program is free software; you can redistribute it and/or modify
   8  * it under the terms of the GNU General Public License as published by
   9  * the Free Software Foundation; either version 2 of the License, or
  10  * (at your option) any later version.
  11  *
  12  * This program is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  * GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with this program; if not, write to the Free Software
  19  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA
  20  */
  21
  22 #ifndef PURPLE_HTTP_H
  23 #define PURPLE_HTTP_H
  24 /**
  25  * SECTION:http
  26  * @section_id: libpurple-http
  27  * @short_description: <filename>http.h</filename>
  28  * @title: HTTP API
  29  */
  30
  31 #include <glib.h>
  32
  33 #include "connection.h"
  34
  35 /**
  36  * PurpleHttpRequest:
  37  *
  38  * A structure containing all data required to generate a single HTTP request.
  39  */
  40 typedef struct _PurpleHttpRequest PurpleHttpRequest;
  41
  42 /**
  43  * PurpleHttpConnection:
  44  *
  45  * A representation of actually running HTTP request. Can be used to cancel the
  46  * request.
  47  */
  48 typedef struct _PurpleHttpConnection PurpleHttpConnection;
  49
  50 /**
  51  * PurpleHttpResponse:
  52  *
  53  * All information got with response for HTTP request.
  54  */
  55 typedef struct _PurpleHttpResponse PurpleHttpResponse;
  56
  57 /**
  58  * PurpleHttpURL:
  59  *
  60  * Parsed representation for the URL.
  61  */
  62 typedef struct _PurpleHttpURL PurpleHttpURL;
  63
  64 /**
  65  * PurpleHttpCookieJar:
  66  *
  67  * An collection of cookies, got from HTTP response or provided for HTTP
  68  * request.
  69  */
  70 typedef struct _PurpleHttpCookieJar PurpleHttpCookieJar;
  71
  72 /**
  73  * PurpleHttpKeepalivePool:
  74  *
  75  * A pool of TCP connections for HTTP Keep-Alive session.
  76  */
  77 typedef struct _PurpleHttpKeepalivePool PurpleHttpKeepalivePool;
  78
  79 /**
  80  * PurpleHttpConnectionSet:
  81  *
  82  * A set of running HTTP requests. Can be used to cancel all of them at once.
  83  */
  84 typedef struct _PurpleHttpConnectionSet PurpleHttpConnectionSet;
  85
  86 /**
  87  * PurpleHttpCallback:
  88  *
  89  * An callback called after performing (successfully or not) HTTP request.
  90  */
  91 typedef void (*PurpleHttpCallback)(PurpleHttpConnection *http_conn,
  92         PurpleHttpResponse *response, gpointer user_data);
  93
  94 /**
  95  * PurpleHttpContentReaderCb:
  96  *
  97  * An callback called after storing data requested by PurpleHttpContentReader.
  98  */
  99 typedef void (*PurpleHttpContentReaderCb)(PurpleHttpConnection *http_conn,
 100         gboolean success, gboolean eof, size_t stored);
 101
 102 /**
 103  * PurpleHttpContentReader:
 104  * @http_conn: Connection, which requests data.
 105  * @buffer:    Buffer to store data to (with offset ignored).
 106  * @offset:    Position, from where to read data.
 107  * @length:    Length of data to read.
 108  * @user_data: The user data passed with callback function.
 109  * @cb:        The function to call after storing data to buffer.
 110  *
 111  * An callback for getting large request contents (ie. from file stored on
 112  * disk).
 113  */
 114 typedef void (*PurpleHttpContentReader)(PurpleHttpConnection *http_conn,
 115         gchar *buffer, size_t offset, size_t length, gpointer user_data,
 116         PurpleHttpContentReaderCb cb);
 117
 118 /**
 119  * PurpleHttpContentWriter:
 120  * @http_conn: Connection, which requests data.
 121  * @response:  Response at point got so far (may change later).
 122  * @buffer:    Buffer to read data from (with offset ignored).
 123  * @offset:    Position of data got (its value is offset + length of
 124  *                  previous call), can be safely ignored.
 125  * @length:    Length of data read.
 126  * @user_data: The user data passed with callback function.
 127  *
 128  * An callback for writting large response contents.
 129  *
 130  * Returns:          TRUE, if succeeded, FALSE otherwise.
 131  */
 132 typedef gboolean (*PurpleHttpContentWriter)(PurpleHttpConnection *http_conn,
 133         PurpleHttpResponse *response, const gchar *buffer, size_t offset,
 134         size_t length, gpointer user_data);
 135
 136 /**
 137  * PurpleHttpProgressWatcher:
 138  * @http_conn:     The HTTP Connection.
 139  * @reading_state: FALSE, is we are sending the request, TRUE, when reading
 140  *                      the response.
 141  * @processed:     The amount of data already processed.
 142  * @total:         Total amount of data (in current state).
 143  * @user_data:     The user data passed with callback function.
 144  *
 145  * An callback for watching HTTP connection progress.
 146  */
 147 typedef void (*PurpleHttpProgressWatcher)(PurpleHttpConnection *http_conn,
 148         gboolean reading_state, int processed, int total, gpointer user_data);
 149
 150 G_BEGIN_DECLS
 151
 152 /**************************************************************************/
 153 /* Performing HTTP requests                                               */
 154 /**************************************************************************/
 155
 156 /**
 157  * purple_http_get: (skip)
 158  * @gc:        The connection for which the request is needed, or NULL.
 159  * @callback:  (scope call): The callback function.
 160  * @user_data: The user data to pass to the callback function.
 161  * @url:       The URL.
 162  *
 163  * Fetches the data from a URL with GET request, and passes it to a callback
 164  * function.
 165  *
 166  * Returns:          The HTTP connection struct.
 167  */
 168 PurpleHttpConnection * purple_http_get(PurpleConnection *gc,
 169         PurpleHttpCallback callback, gpointer user_data, const gchar *url);
 170
 171 /**
 172  * purple_http_get_printf: (skip)
 173  * @gc:        The connection for which the request is needed, or NULL.
 174  * @callback:  (scope call): The callback function.
 175  * @user_data: The user data to pass to the callback function.
 176  * @format:    The format string.
 177  * @...:       The parameters to insert into the format string.
 178  *
 179  * Constructs an URL and fetches the data from it with GET request, then passes
 180  * it to a callback function.
 181  *
 182  * Returns:          The HTTP connection struct.
 183  */
 184 PurpleHttpConnection * purple_http_get_printf(PurpleConnection *gc,
 185         PurpleHttpCallback callback, gpointer user_data,
 186         const gchar *format, ...) G_GNUC_PRINTF(4, 5);
 187
 188 /**
 189  * purple_http_request: (skip)
 190  * @gc:        The connection for which the request is needed, or NULL.
 191  * @request:   The request.
 192  * @callback:  (scope call): The callback function.
 193  * @user_data: The user data to pass to the callback function.
 194  *
 195  * Fetches a HTTP request and passes the response to a callback function.
 196  * Provided request struct can be shared by multiple http requests but can not
 197  * be modified when any of these is running.
 198  *
 199  * Returns:          The HTTP connection struct.
 200  */
 201 PurpleHttpConnection * purple_http_request(PurpleConnection *gc,
 202         PurpleHttpRequest *request, PurpleHttpCallback callback,
 203         gpointer user_data);
 204
 205 /**************************************************************************/
 206 /* HTTP connection API                                                    */
 207 /**************************************************************************/
 208
 209 /**
 210  * purple_http_conn_cancel: (skip)
 211  * @http_conn: The data returned when you initiated the HTTP request.
 212  *
 213  * Cancel a pending HTTP request.
 214  */
 215 void purple_http_conn_cancel(PurpleHttpConnection *http_conn);
 216
 217 /**
 218  * purple_http_conn_cancel_all: (skip)
 219  * @gc: The handle.
 220  *
 221  * Cancels all HTTP connections associated with the specified handle.
 222  */
 223 void purple_http_conn_cancel_all(PurpleConnection *gc);
 224
 225 /**
 226  * purple_http_conn_is_running: (skip)
 227  * @http_conn: The HTTP connection (may be invalid pointer).
 228  *
 229  * Checks, if provided HTTP request is running.
 230  *
 231  * Returns:          TRUE, if provided connection is currently running.
 232  */
 233 gboolean purple_http_conn_is_running(PurpleHttpConnection *http_conn);
 234
 235 /**
 236  * purple_http_conn_get_request: (skip)
 237  * @http_conn: The HTTP connection.
 238  *
 239  * Gets PurpleHttpRequest used for specified HTTP connection.
 240  *
 241  * Returns:          The PurpleHttpRequest object.
 242  */
 243 PurpleHttpRequest * purple_http_conn_get_request(
 244         PurpleHttpConnection *http_conn);
 245
 246 /**
 247  * purple_http_conn_get_cookie_jar: (skip)
 248  * @http_conn: The HTTP connection.
 249  *
 250  * Gets cookie jar used within connection.
 251  *
 252  * Returns:          The cookie jar.
 253  */
 254 PurpleHttpCookieJar * purple_http_conn_get_cookie_jar(
 255         PurpleHttpConnection *http_conn);
 256
 257 /**
 258  * purple_http_conn_get_purple_connection: (skip)
 259  * @http_conn: The HTTP connection.
 260  *
 261  * Gets PurpleConnection tied with specified HTTP connection.
 262  *
 263  * Returns:          The PurpleConnection object.
 264  */
 265 PurpleConnection * purple_http_conn_get_purple_connection(
 266         PurpleHttpConnection *http_conn);
 267
 268 /**
 269  * purple_http_conn_set_progress_watcher: (skip)
 270  * @http_conn:             The HTTP connection.
 271  * @watcher: (scope call): The watcher.
 272  * @user_data:             The user data to pass to the callback function.
 273  * @interval_threshold:    Minimum interval (in microseconds) of calls to
 274  *                         watcher, or -1 for default.
 275  *
 276  * Sets the watcher, called after writing or reading data to/from HTTP stream.
 277  * May be used for updating transfer progress gauge.
 278  */
 279 void purple_http_conn_set_progress_watcher(PurpleHttpConnection *http_conn,
 280         PurpleHttpProgressWatcher watcher, gpointer user_data,
 281         gint interval_threshold);
 282
 283
 284 /**************************************************************************/
 285 /* URL processing API                                                     */
 286 /**************************************************************************/
 287
 288 /**
 289  * purple_http_url_parse: (skip)
 290  * @url: The URL to parse.
 291  *
 292  * Parses a URL.
 293  *
 294  * The returned data must be freed with purple_http_url_free.
 295  *
 296  * Returns:    The parsed url or NULL, if the URL is invalid.
 297  */
 298 PurpleHttpURL *
 299 purple_http_url_parse(const char *url);
 300
 301 /**
 302  * purple_http_url_free: (skip)
 303  * @parsed_url: The parsed URL struct, or NULL.
 304  *
 305  * Frees the parsed URL struct.
 306  */
 307 void
 308 purple_http_url_free(PurpleHttpURL *parsed_url);
 309
 310 /**
 311  * purple_http_url_relative: (skip)
 312  * @base_url:     The base URL. The result is stored here.
 313  * @relative_url: The relative URL.
 314  *
 315  * Converts the base URL to the absolute form of the provided relative URL.
 316  *
 317  * Example: "https://example.com/path/to/file.html" + "subdir/other-file.html" =
 318  *          "https://example.com/path/to/subdir/another-file.html"
 319  */
 320 void
 321 purple_http_url_relative(PurpleHttpURL *base_url, PurpleHttpURL *relative_url);
 322
 323 /**
 324  * purple_http_url_print: (skip)
 325  * @parsed_url: The URL struct.
 326  *
 327  * Converts the URL struct to the printable form. The result may not be a valid
 328  * URL (in cases, when the struct doesn't have all fields filled properly).
 329  *
 330  * The result must be g_free'd.
 331  *
 332  * Returns:           The printable form of the URL.
 333  */
 334 gchar *
 335 purple_http_url_print(PurpleHttpURL *parsed_url);
 336
 337 /**
 338  * purple_http_url_get_protocol: (skip)
 339  * @parsed_url: The URL struct.
 340  *
 341  * Gets the protocol part of URL.
 342  *
 343  * Returns:           The protocol.
 344  */
 345 const gchar *
 346 purple_http_url_get_protocol(const PurpleHttpURL *parsed_url);
 347
 348 /**
 349  * purple_http_url_get_username: (skip)
 350  * @parsed_url: The URL struct.
 351  *
 352  * Gets the username part of URL.
 353  *
 354  * Returns:           The username.
 355  */
 356 const gchar *
 357 purple_http_url_get_username(const PurpleHttpURL *parsed_url);
 358
 359 /**
 360  * purple_http_url_get_password: (skip)
 361  * @parsed_url: The URL struct.
 362  *
 363  * Gets the password part of URL.
 364  *
 365  * Returns:           The password.
 366  */
 367 const gchar *
 368 purple_http_url_get_password(const PurpleHttpURL *parsed_url);
 369
 370 /**
 371  * purple_http_url_get_host: (skip)
 372  * @parsed_url: The URL struct.
 373  *
 374  * Gets the hostname part of URL.
 375  *
 376  * Returns:           The hostname.
 377  */
 378 const gchar *
 379 purple_http_url_get_host(const PurpleHttpURL *parsed_url);
 380
 381 /**
 382  * purple_http_url_get_port: (skip)
 383  * @parsed_url: The URL struct.
 384  *
 385  * Gets the port part of URL.
 386  *
 387  * Returns:           The port number.
 388  */
 389 int
 390 purple_http_url_get_port(const PurpleHttpURL *parsed_url);
 391
 392 /**
 393  * purple_http_url_get_path: (skip)
 394  * @parsed_url: The URL struct.
 395  *
 396  * Gets the path part of URL.
 397  *
 398  * Returns:           The path.
 399  */
 400 const gchar *
 401 purple_http_url_get_path(const PurpleHttpURL *parsed_url);
 402
 403 /**
 404  * purple_http_url_get_fragment: (skip)
 405  * @parsed_url: The URL struct.
 406  *
 407  * Gets the fragment part of URL.
 408  *
 409  * Returns:           The fragment.
 410  */
 411 const gchar *
 412 purple_http_url_get_fragment(const PurpleHttpURL *parsed_url);
 413
 414
 415 /**************************************************************************/
 416 /* Cookie jar API                                                         */
 417 /**************************************************************************/
 418
 419 /**
 420  * purple_http_cookie_jar_new: (skip)
 421  *
 422  * Creates new cookie jar,
 423  *
 424  * Returns: empty cookie jar.
 425  */
 426 PurpleHttpCookieJar * purple_http_cookie_jar_new(void);
 427
 428 /**
 429  * purple_http_cookie_jar_ref: (skip)
 430  * @cookie_jar: The cookie jar.
 431  *
 432  * Increment the reference count.
 433  */
 434 void purple_http_cookie_jar_ref(PurpleHttpCookieJar *cookie_jar);
 435
 436 /**
 437  * purple_http_cookie_jar_unref: (skip)
 438  * @cookie_jar: The cookie jar.
 439  *
 440  * Decrement the reference count.
 441  *
 442  * If the reference count reaches zero, the cookie jar will be freed.
 443  *
 444  * Returns: @cookie_jar or %NULL if the reference count reached zero.
 445  */
 446 PurpleHttpCookieJar * purple_http_cookie_jar_unref(
 447         PurpleHttpCookieJar *cookie_jar);
 448
 449 /**
 450  * purple_http_cookie_jar_set: (skip)
 451  * @cookie_jar: The cookie jar.
 452  * @name:       Cookie name.
 453  * @value:      Cookie contents.
 454  *
 455  * Sets the cookie.
 456  */
 457 void purple_http_cookie_jar_set(PurpleHttpCookieJar *cookie_jar,
 458         const gchar *name, const gchar *value);
 459
 460 /**
 461  * purple_http_cookie_jar_get: (skip)
 462  * @cookie_jar: The cookie jar.
 463  * @name:       Cookie name.
 464  *
 465  * Gets the cookie.
 466  *
 467  * The result must be g_free'd.
 468  *
 469  * Returns:           Cookie contents, or NULL, if cookie doesn't exists.
 470  */
 471 gchar * purple_http_cookie_jar_get(PurpleHttpCookieJar *cookie_jar,
 472         const gchar *name);
 473
 474 /**
 475  * purple_http_cookie_jar_is_empty: (skip)
 476  * @cookie_jar: The cookie jar.
 477  *
 478  * Checks, if the cookie jar contains any cookies.
 479  *
 480  * Returns:           TRUE, if cookie jar contains any cookie, FALSE otherwise.
 481  */
 482 gboolean purple_http_cookie_jar_is_empty(PurpleHttpCookieJar *cookie_jar);
 483
 484
 485 /**************************************************************************/
 486 /* HTTP Request API                                                       */
 487 /**************************************************************************/
 488
 489 /**
 490  * purple_http_request_new: (skip)
 491  * @url: The URL to request for, or NULL to leave empty (to be set with
 492  *            purple_http_request_set_url).
 493  *
 494  * Creates the new instance of HTTP request configuration.
 495  *
 496  * Returns: The new instance of HTTP request struct.
 497  */
 498 PurpleHttpRequest * purple_http_request_new(const gchar *url);
 499
 500 /**
 501  * purple_http_request_ref: (skip)
 502  * @request: The request.
 503  *
 504  * Increment the reference count.
 505  */
 506 void purple_http_request_ref(PurpleHttpRequest *request);
 507
 508 /**
 509  * purple_http_request_unref: (skip)
 510  * @request: The request.
 511  *
 512  * Decrement the reference count.
 513  *
 514  * If the reference count reaches zero, the http request struct will be freed.
 515  *
 516  * Returns: @request or %NULL if the reference count reached zero.
 517  */
 518 PurpleHttpRequest * purple_http_request_unref(PurpleHttpRequest *request);
 519
 520 /**
 521  * purple_http_request_set_url: (skip)
 522  * @request: The request.
 523  * @url:     The url.
 524  *
 525  * Sets URL for HTTP request.
 526  */
 527 void purple_http_request_set_url(PurpleHttpRequest *request, const gchar *url);
 528
 529 /**
 530  * purple_http_request_set_url_printf: (skip)
 531  * @request: The request.
 532  * @format:  The format string.
 533  * @...:       The parameters to insert into the format string.
 534  *
 535  * Constructs and sets an URL for HTTP request.
 536  */
 537 void purple_http_request_set_url_printf(PurpleHttpRequest *request,
 538         const gchar *format, ...) G_GNUC_PRINTF(2, 3);
 539
 540 /**
 541  * purple_http_request_get_url: (skip)
 542  * @request: The request.
 543  *
 544  * Gets URL set for the HTTP request.
 545  *
 546  * Returns:        URL set for this request.
 547  */
 548 const gchar * purple_http_request_get_url(PurpleHttpRequest *request);
 549
 550 /**
 551  * purple_http_request_set_method: (skip)
 552  * @request: The request.
 553  * @method:  The method, or NULL for default.
 554  *
 555  * Sets custom HTTP method used for the request.
 556  */
 557 void purple_http_request_set_method(PurpleHttpRequest *request,
 558         const gchar *method);
 559
 560 /**
 561  * purple_http_request_get_method: (skip)
 562  * @request: The request.
 563  *
 564  * Gets HTTP method set for the request.
 565  *
 566  * Returns:        The method.
 567  */
 568 const gchar * purple_http_request_get_method(PurpleHttpRequest *request);
 569
 570 /**
 571  * purple_http_request_set_keepalive_pool: (skip)
 572  * @request: The request.
 573  * @pool:    The new KeepAlive pool, or NULL to reset.
 574  *
 575  * Sets HTTP KeepAlive connections pool for the request.
 576  *
 577  * It increases pool's reference count.
 578  */
 579 void
 580 purple_http_request_set_keepalive_pool(PurpleHttpRequest *request,
 581         PurpleHttpKeepalivePool *pool);
 582
 583 /**
 584  * purple_http_request_get_keepalive_pool: (skip)
 585  * @request: The request.
 586  *
 587  * Gets HTTP KeepAlive connections pool associated with the request.
 588  *
 589  * It doesn't affect pool's reference count.
 590  *
 591  * Returns:        The KeepAlive pool, used for the request.
 592  */
 593 PurpleHttpKeepalivePool *
 594 purple_http_request_get_keepalive_pool(PurpleHttpRequest *request);
 595
 596 /**
 597  * purple_http_request_set_contents: (skip)
 598  * @request:  The request.
 599  * @contents: The contents.
 600  * @length:   The length of contents (-1 if it's a NULL-terminated string)
 601  *
 602  * Sets contents of HTTP request (for example, POST data).
 603  */
 604 void purple_http_request_set_contents(PurpleHttpRequest *request,
 605         const gchar *contents, int length);
 606
 607 /**
 608  * purple_http_request_set_contents_reader: (skip)
 609  * @request:              The request.
 610  * @reader: (scope call): The reader callback.
 611  * @contents_length:      The size of all contents.
 612  * @user_data:            The user data to pass to the callback function.
 613  *
 614  * Sets contents reader for HTTP request, used mainly for possible large
 615  * uploads.
 616  */
 617 void purple_http_request_set_contents_reader(PurpleHttpRequest *request,
 618         PurpleHttpContentReader reader, int contents_length, gpointer user_data);
 619
 620 /**
 621  * purple_http_request_set_response_writer: (skip)
 622  * @request:              The request.
 623  * @writer: (scope call): The writer callback, or %NULL to remove existing.
 624  * @user_data:            The user data to pass to the callback function.
 625  *
 626  * Set contents writer for HTTP response.
 627  */
 628 void purple_http_request_set_response_writer(PurpleHttpRequest *request,
 629         PurpleHttpContentWriter writer, gpointer user_data);
 630
 631 /**
 632  * purple_http_request_set_timeout: (skip)
 633  * @request: The request.
 634  * @timeout: Time (in seconds) after that timeout will be cancelled,
 635  *                -1 for infinite time.
 636  *
 637  * Set maximum amount of time, that request is allowed to run.
 638  */
 639 void purple_http_request_set_timeout(PurpleHttpRequest *request, int timeout);
 640
 641 /**
 642  * purple_http_request_get_timeout: (skip)
 643  * @request: The request.
 644  *
 645  * Get maximum amount of time, that request is allowed to run.
 646  *
 647  * Returns:        Timeout currently set (-1 for infinite).
 648  */
 649 int purple_http_request_get_timeout(PurpleHttpRequest *request);
 650
 651 /**
 652  * purple_http_request_set_max_redirects: (skip)
 653  * @request:       The request.
 654  * @max_redirects: Maximum amount of redirects, or -1 for unlimited.
 655  *
 656  * Sets maximum amount of redirects.
 657  */
 658 void purple_http_request_set_max_redirects(PurpleHttpRequest *request,
 659         int max_redirects);
 660
 661 /**
 662  * purple_http_request_get_max_redirects: (skip)
 663  * @request: The request.
 664  *
 665  * Gets maximum amount of redirects.
 666  *
 667  * Returns:        Current maximum amount of redirects (-1 for unlimited).
 668  */
 669 int purple_http_request_get_max_redirects(PurpleHttpRequest *request);
 670
 671 /**
 672  * purple_http_request_set_cookie_jar: (skip)
 673  * @request:    The request.
 674  * @cookie_jar: The cookie jar.
 675  *
 676  * Sets cookie jar used for the request.
 677  */
 678 void purple_http_request_set_cookie_jar(PurpleHttpRequest *request,
 679         PurpleHttpCookieJar *cookie_jar);
 680
 681 /**
 682  * purple_http_request_get_cookie_jar: (skip)
 683  * @request: The request.
 684  *
 685  * Gets cookie jar used for the request.
 686  *
 687  * Returns:        The cookie jar.
 688  */
 689 PurpleHttpCookieJar * purple_http_request_get_cookie_jar(
 690         PurpleHttpRequest *request);
 691
 692 /**
 693  * purple_http_request_set_http11: (skip)
 694  * @request: The request.
 695  * @http11:  TRUE for HTTP/1.1, FALSE for HTTP/1.0.
 696  *
 697  * Sets HTTP version to use.
 698  */
 699 void purple_http_request_set_http11(PurpleHttpRequest *request,
 700         gboolean http11);
 701
 702 /**
 703  * purple_http_request_is_http11: (skip)
 704  * @request: The request.
 705  *
 706  * Gets used HTTP version.
 707  *
 708  * Returns:        TRUE, if we use HTTP/1.1, FALSE for HTTP/1.0.
 709  */
 710 gboolean purple_http_request_is_http11(PurpleHttpRequest *request);
 711
 712 /**
 713  * purple_http_request_set_max_len: (skip)
 714  * @request: The request.
 715  * @max_len: Maximum length of response to read (-1 for the maximum
 716  *                supported amount).
 717  *
 718  * Sets maximum length of response content to read.
 719  *
 720  * Headers length doesn't count here.
 721  *
 722  */
 723 void purple_http_request_set_max_len(PurpleHttpRequest *request, int max_len);
 724
 725 /**
 726  * purple_http_request_get_max_len: (skip)
 727  * @request: The request.
 728  *
 729  * Gets maximum length of response content to read.
 730  *
 731  * Returns:        Maximum length of response to read, or -1 if unlimited.
 732  */
 733 int purple_http_request_get_max_len(PurpleHttpRequest *request);
 734
 735 /**
 736  * purple_http_request_header_set: (skip)
 737  * @request: The request.
 738  * @key:     A header to be set.
 739  * @value:   A value to set, or NULL to remove specified header.
 740  *
 741  * Sets (replaces, if exists) specified HTTP request header with provided value.
 742  *
 743  * See purple_http_request_header_add().
 744  */
 745 void purple_http_request_header_set(PurpleHttpRequest *request,
 746         const gchar *key, const gchar *value);
 747
 748 /**
 749  * purple_http_request_header_set_printf: (skip)
 750  * @request: The request.
 751  * @key:     A header to be set.
 752  * @format:  The format string.
 753  *
 754  * Constructs and sets (replaces, if exists) specified HTTP request header.
 755  */
 756 void purple_http_request_header_set_printf(PurpleHttpRequest *request,
 757         const gchar *key, const gchar *format, ...) G_GNUC_PRINTF(3, 4);
 758
 759 /**
 760  * purple_http_request_header_add: (skip)
 761  * @request: The request.
 762  * @key:   A header to be set.
 763  * @value: A value to set.
 764  *
 765  * Adds (without replacing, if exists) an HTTP request header.
 766  *
 767  * See purple_http_request_header_set().
 768  */
 769 void purple_http_request_header_add(PurpleHttpRequest *request,
 770         const gchar *key, const gchar *value);
 771
 772
 773 /**************************************************************************/
 774 /* HTTP Keep-Alive pool API                                               */
 775 /**************************************************************************/
 776
 777 /**
 778  * purple_http_keepalive_pool_new: (skip)
 779  *
 780  * Creates a new HTTP Keep-Alive pool.
 781  */
 782 PurpleHttpKeepalivePool *
 783 purple_http_keepalive_pool_new(void);
 784
 785 /**
 786  * purple_http_keepalive_pool_ref: (skip)
 787  * @pool: The HTTP Keep-Alive pool.
 788  *
 789  * Increment the reference count.
 790  */
 791 void
 792 purple_http_keepalive_pool_ref(PurpleHttpKeepalivePool *pool);
 793
 794 /**
 795  * purple_http_keepalive_pool_unref: (skip)
 796  * @pool: The HTTP Keep-Alive pool.
 797  *
 798  * Decrement the reference count.
 799  *
 800  * If the reference count reaches zero, the pool will be freed and all
 801  * connections will be closed.
 802  *
 803  * Returns: @pool or %NULL if the reference count reached zero.
 804  */
 805 PurpleHttpKeepalivePool *
 806 purple_http_keepalive_pool_unref(PurpleHttpKeepalivePool *pool);
 807
 808 /**
 809  * purple_http_keepalive_pool_set_limit_per_host: (skip)
 810  * @pool:  The HTTP Keep-Alive pool.
 811  * @limit: The new limit, 0 for unlimited.
 812  *
 813  * Sets maximum allowed number of connections to specific host-triple (is_ssl +
 814  * hostname + port).
 815  */
 816 void
 817 purple_http_keepalive_pool_set_limit_per_host(PurpleHttpKeepalivePool *pool,
 818         guint limit);
 819
 820 /**
 821  * purple_http_keepalive_pool_get_limit_per_host: (skip)
 822  * @pool: The HTTP Keep-Alive pool.
 823  *
 824  * Gets maximum allowed number of connections to specific host-triple (is_ssl +
 825  * hostname + port).
 826  *
 827  * Returns:     The limit.
 828  */
 829 guint
 830 purple_http_keepalive_pool_get_limit_per_host(PurpleHttpKeepalivePool *pool);
 831
 832
 833 /**************************************************************************/
 834 /* HTTP connection set API                                                */
 835 /**************************************************************************/
 836
 837 /**
 838  * purple_http_connection_set_new: (skip)
 839  *
 840  * Creates a new connection set.
 841  *
 842  * Returns: A new connection set.
 843  */
 844 PurpleHttpConnectionSet *
 845 purple_http_connection_set_new(void);
 846
 847 /**
 848  * purple_http_connection_set_destroy: (skip)
 849  * @set: The connection set to be destroyed
 850  *
 851  * Destroys connection set @set.
 852  */
 853 void
 854 purple_http_connection_set_destroy(PurpleHttpConnectionSet *set);
 855
 856 /**
 857  * purple_http_connection_set_add: (skip)
 858  * @set: The connection set to add to
 859  * @http_conn: The connection to add
 860  *
 861  * Adds @http_conn to @set.
 862  */
 863 void
 864 purple_http_connection_set_add(PurpleHttpConnectionSet *set,
 865         PurpleHttpConnection *http_conn);
 866
 867
 868 /**************************************************************************/
 869 /* HTTP response API                                                      */
 870 /**************************************************************************/
 871
 872 /**
 873  * purple_http_response_is_successful: (skip)
 874  * @response: The response.
 875  *
 876  * Checks, if HTTP request was performed successfully.
 877  *
 878  * Returns:         TRUE, if request was performed successfully.
 879  */
 880 gboolean purple_http_response_is_successful(PurpleHttpResponse *response);
 881
 882 /**
 883  * purple_http_response_get_code: (skip)
 884  * @response: The response.
 885  *
 886  * Gets HTTP response code.
 887  *
 888  * Returns:         HTTP response code.
 889  */
 890 int purple_http_response_get_code(PurpleHttpResponse *response);
 891
 892 /**
 893  * purple_http_response_get_error: (skip)
 894  * @response: The response.
 895  *
 896  * Gets error description.
 897  *
 898  * Returns:         Localized error description or NULL, if there was no error.
 899  */
 900 const gchar * purple_http_response_get_error(PurpleHttpResponse *response);
 901
 902 /**
 903  * purple_http_response_get_data_len: (skip)
 904  * @response: The response.
 905  *
 906  * Gets HTTP response data length.
 907  *
 908  * Returns:         Data length;
 909  */
 910 gsize purple_http_response_get_data_len(PurpleHttpResponse *response);
 911
 912 /**
 913  * purple_http_response_get_data: (skip)
 914  * @response: The response.
 915  * @len:      Return address for the size of the data.  Can be NULL.
 916  *
 917  * Gets HTTP response data.
 918  *
 919  * Response data is not written, if writer callback was set for request.
 920  *
 921  * Returns:         The data.
 922  */
 923 const gchar * purple_http_response_get_data(PurpleHttpResponse *response, size_t *len);
 924
 925 /**
 926  * purple_http_response_get_all_headers: (skip)
 927  * @response: The response.
 928  *
 929  * Gets all headers got with response.
 930  *
 931  * Returns: (element-type PurpleKeyValuePair) (transfer none): Keys are header
 932  *          field names (gchar*) and values are its contents (gchar*).
 933  */
 934 const GList * purple_http_response_get_all_headers(PurpleHttpResponse *response);
 935
 936 /**
 937  * purple_http_response_get_headers_by_name: (skip)
 938  * @response: The response.
 939  * @name:     The name of header field.
 940  *
 941  * Gets all headers with specified name got with response.
 942  *
 943  * Returns: (element-type gchar*) (transfer none): Header field record contents.
 944  */
 945 const GList * purple_http_response_get_headers_by_name(
 946         PurpleHttpResponse *response, const gchar *name);
 947
 948 /**
 949  * purple_http_response_get_header: (skip)
 950  * @response: The response.
 951  * @name:     The name of header field.
 952  *
 953  * Gets one header contents with specified name got with response.
 954  *
 955  * To get all headers with the same name, use
 956  * purple_http_response_get_headers_by_name instead.
 957  *
 958  * Returns:         Header field contents or NULL, if there is no such one.
 959  */
 960 const gchar * purple_http_response_get_header(PurpleHttpResponse *response,
 961         const gchar *name);
 962
 963
 964 /**************************************************************************/
 965 /* HTTP Subsystem                                                         */
 966 /**************************************************************************/
 967
 968 /**
 969  * purple_http_init:
 970  *
 971  * Initializes the http subsystem.
 972  */
 973 void purple_http_init(void);
 974
 975 /**
 976  * purple_http_uninit:
 977  *
 978  * Uninitializes the http subsystem.
 979  */
 980 void purple_http_uninit(void);
 981
 982 G_END_DECLS
 983
 984 #endif /* PURPLE_HTTP_H */