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:
 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:
 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  *
 178  * Constructs an URL and fetches the data from it with GET request, then passes
 179  * it to a callback function.
 180  *
 181  * Returns:          The HTTP connection struct.
 182  */
 183 PurpleHttpConnection * purple_http_get_printf(PurpleConnection *gc,
 184         PurpleHttpCallback callback, gpointer user_data,
 185         const gchar *format, ...) G_GNUC_PRINTF(4, 5);
 186
 187 /**
 188  * purple_http_request:
 189  * @gc:        The connection for which the request is needed, or NULL.
 190  * @request:   The request.
 191  * @callback:  (scope call): The callback function.
 192  * @user_data: The user data to pass to the callback function.
 193  *
 194  * Fetches a HTTP request and passes the response to a callback function.
 195  * Provided request struct can be shared by multiple http requests but can not
 196  * be modified when any of these is running.
 197  *
 198  * Returns:          The HTTP connection struct.
 199  */
 200 PurpleHttpConnection * purple_http_request(PurpleConnection *gc,
 201         PurpleHttpRequest *request, PurpleHttpCallback callback,
 202         gpointer user_data);
 203
 204 /**************************************************************************/
 205 /* HTTP connection API                                                    */
 206 /**************************************************************************/
 207
 208 /**
 209  * purple_http_conn_cancel:
 210  * @http_conn: The data returned when you initiated the HTTP request.
 211  *
 212  * Cancel a pending HTTP request.
 213  */
 214 void purple_http_conn_cancel(PurpleHttpConnection *http_conn);
 215
 216 /**
 217  * purple_http_conn_cancel_all:
 218  * @gc: The handle.
 219  *
 220  * Cancels all HTTP connections associated with the specified handle.
 221  */
 222 void purple_http_conn_cancel_all(PurpleConnection *gc);
 223
 224 /**
 225  * purple_http_conn_is_running:
 226  * @http_conn: The HTTP connection (may be invalid pointer).
 227  *
 228  * Checks, if provided HTTP request is running.
 229  *
 230  * Returns:          TRUE, if provided connection is currently running.
 231  */
 232 gboolean purple_http_conn_is_running(PurpleHttpConnection *http_conn);
 233
 234 /**
 235  * purple_http_conn_get_request:
 236  * @http_conn: The HTTP connection.
 237  *
 238  * Gets PurpleHttpRequest used for specified HTTP connection.
 239  *
 240  * Returns:          The PurpleHttpRequest object.
 241  */
 242 PurpleHttpRequest * purple_http_conn_get_request(
 243         PurpleHttpConnection *http_conn);
 244
 245 /**
 246  * purple_http_conn_get_cookie_jar:
 247  * @http_conn: The HTTP connection.
 248  *
 249  * Gets cookie jar used within connection.
 250  *
 251  * Returns:          The cookie jar.
 252  */
 253 PurpleHttpCookieJar * purple_http_conn_get_cookie_jar(
 254         PurpleHttpConnection *http_conn);
 255
 256 /**
 257  * purple_http_conn_get_purple_connection:
 258  * @http_conn: The HTTP connection.
 259  *
 260  * Gets PurpleConnection tied with specified HTTP connection.
 261  *
 262  * Returns:          The PurpleConnection object.
 263  */
 264 PurpleConnection * purple_http_conn_get_purple_connection(
 265         PurpleHttpConnection *http_conn);
 266
 267 /**
 268  * purple_http_conn_set_progress_watcher:
 269  * @http_conn:             The HTTP connection.
 270  * @watcher: (scope call): The watcher.
 271  * @user_data:             The user data to pass to the callback function.
 272  * @interval_threshold:    Minimum interval (in microseconds) of calls to
 273  *                         watcher, or -1 for default.
 274  *
 275  * Sets the watcher, called after writing or reading data to/from HTTP stream.
 276  * May be used for updating transfer progress gauge.
 277  */
 278 void purple_http_conn_set_progress_watcher(PurpleHttpConnection *http_conn,
 279         PurpleHttpProgressWatcher watcher, gpointer user_data,
 280         gint interval_threshold);
 281
 282
 283 /**************************************************************************/
 284 /* URL processing API                                                     */
 285 /**************************************************************************/
 286
 287 /**
 288  * purple_http_url_parse:
 289  * @url: The URL to parse.
 290  *
 291  * Parses a URL.
 292  *
 293  * The returned data must be freed with purple_http_url_free.
 294  *
 295  * Returns:    The parsed url or NULL, if the URL is invalid.
 296  */
 297 PurpleHttpURL *
 298 purple_http_url_parse(const char *url);
 299
 300 /**
 301  * purple_http_url_free:
 302  * @parsed_url: The parsed URL struct, or NULL.
 303  *
 304  * Frees the parsed URL struct.
 305  */
 306 void
 307 purple_http_url_free(PurpleHttpURL *parsed_url);
 308
 309 /**
 310  * purple_http_url_relative:
 311  * @base_url:     The base URL. The result is stored here.
 312  * @relative_url: The relative URL.
 313  *
 314  * Converts the base URL to the absolute form of the provided relative URL.
 315  *
 316  * Example: "https://example.com/path/to/file.html" + "subdir/other-file.html" =
 317  *          "https://example.com/path/to/subdir/another-file.html"
 318  */
 319 void
 320 purple_http_url_relative(PurpleHttpURL *base_url, PurpleHttpURL *relative_url);
 321
 322 /**
 323  * purple_http_url_print:
 324  * @parsed_url: The URL struct.
 325  *
 326  * Converts the URL struct to the printable form. The result may not be a valid
 327  * URL (in cases, when the struct doesn't have all fields filled properly).
 328  *
 329  * The result must be g_free'd.
 330  *
 331  * Returns:           The printable form of the URL.
 332  */
 333 gchar *
 334 purple_http_url_print(PurpleHttpURL *parsed_url);
 335
 336 /**
 337  * purple_http_url_get_protocol:
 338  * @parsed_url: The URL struct.
 339  *
 340  * Gets the protocol part of URL.
 341  *
 342  * Returns:           The protocol.
 343  */
 344 const gchar *
 345 purple_http_url_get_protocol(const PurpleHttpURL *parsed_url);
 346
 347 /**
 348  * purple_http_url_get_username:
 349  * @parsed_url: The URL struct.
 350  *
 351  * Gets the username part of URL.
 352  *
 353  * Returns:           The username.
 354  */
 355 const gchar *
 356 purple_http_url_get_username(const PurpleHttpURL *parsed_url);
 357
 358 /**
 359  * purple_http_url_get_password:
 360  * @parsed_url: The URL struct.
 361  *
 362  * Gets the password part of URL.
 363  *
 364  * Returns:           The password.
 365  */
 366 const gchar *
 367 purple_http_url_get_password(const PurpleHttpURL *parsed_url);
 368
 369 /**
 370  * purple_http_url_get_host:
 371  * @parsed_url: The URL struct.
 372  *
 373  * Gets the hostname part of URL.
 374  *
 375  * Returns:           The hostname.
 376  */
 377 const gchar *
 378 purple_http_url_get_host(const PurpleHttpURL *parsed_url);
 379
 380 /**
 381  * purple_http_url_get_port:
 382  * @parsed_url: The URL struct.
 383  *
 384  * Gets the port part of URL.
 385  *
 386  * Returns:           The port number.
 387  */
 388 int
 389 purple_http_url_get_port(const PurpleHttpURL *parsed_url);
 390
 391 /**
 392  * purple_http_url_get_path:
 393  * @parsed_url: The URL struct.
 394  *
 395  * Gets the path part of URL.
 396  *
 397  * Returns:           The path.
 398  */
 399 const gchar *
 400 purple_http_url_get_path(const PurpleHttpURL *parsed_url);
 401
 402 /**
 403  * purple_http_url_get_fragment:
 404  * @parsed_url: The URL struct.
 405  *
 406  * Gets the fragment part of URL.
 407  *
 408  * Returns:           The fragment.
 409  */
 410 const gchar *
 411 purple_http_url_get_fragment(const PurpleHttpURL *parsed_url);
 412
 413
 414 /**************************************************************************/
 415 /* Cookie jar API                                                         */
 416 /**************************************************************************/
 417
 418 /**
 419  * purple_http_cookie_jar_new:
 420  *
 421  * Creates new cookie jar,
 422  *
 423  * Returns: empty cookie jar.
 424  */
 425 PurpleHttpCookieJar * purple_http_cookie_jar_new(void);
 426
 427 /**
 428  * purple_http_cookie_jar_ref:
 429  * @cookie_jar: The cookie jar.
 430  *
 431  * Increment the reference count.
 432  */
 433 void purple_http_cookie_jar_ref(PurpleHttpCookieJar *cookie_jar);
 434
 435 /**
 436  * purple_http_cookie_jar_unref:
 437  * @cookie_jar: The cookie jar.
 438  *
 439  * Decrement the reference count.
 440  *
 441  * If the reference count reaches zero, the cookie jar will be freed.
 442  *
 443  * Returns: @cookie_jar or %NULL if the reference count reached zero.
 444  */
 445 PurpleHttpCookieJar * purple_http_cookie_jar_unref(
 446         PurpleHttpCookieJar *cookie_jar);
 447
 448 /**
 449  * purple_http_cookie_jar_set:
 450  * @cookie_jar: The cookie jar.
 451  * @name:       Cookie name.
 452  * @value:      Cookie contents.
 453  *
 454  * Sets the cookie.
 455  */
 456 void purple_http_cookie_jar_set(PurpleHttpCookieJar *cookie_jar,
 457         const gchar *name, const gchar *value);
 458
 459 /**
 460  * purple_http_cookie_jar_get:
 461  * @cookie_jar: The cookie jar.
 462  * @name:       Cookie name.
 463  *
 464  * Gets the cookie.
 465  *
 466  * The result must be g_free'd.
 467  *
 468  * Returns:           Cookie contents, or NULL, if cookie doesn't exists.
 469  */
 470 gchar * purple_http_cookie_jar_get(PurpleHttpCookieJar *cookie_jar,
 471         const gchar *name);
 472
 473 /**
 474  * purple_http_cookie_jar_is_empty:
 475  * @cookie_jar: The cookie jar.
 476  *
 477  * Checks, if the cookie jar contains any cookies.
 478  *
 479  * Returns:           TRUE, if cookie jar contains any cookie, FALSE otherwise.
 480  */
 481 gboolean purple_http_cookie_jar_is_empty(PurpleHttpCookieJar *cookie_jar);
 482
 483
 484 /**************************************************************************/
 485 /* HTTP Request API                                                       */
 486 /**************************************************************************/
 487
 488 /**
 489  * purple_http_request_new:
 490  * @url: The URL to request for, or NULL to leave empty (to be set with
 491  *            purple_http_request_set_url).
 492  *
 493  * Creates the new instance of HTTP request configuration.
 494  *
 495  * Returns: The new instance of HTTP request struct.
 496  */
 497 PurpleHttpRequest * purple_http_request_new(const gchar *url);
 498
 499 /**
 500  * purple_http_request_ref:
 501  * @request: The request.
 502  *
 503  * Increment the reference count.
 504  */
 505 void purple_http_request_ref(PurpleHttpRequest *request);
 506
 507 /**
 508  * purple_http_request_unref:
 509  * @request: The request.
 510  *
 511  * Decrement the reference count.
 512  *
 513  * If the reference count reaches zero, the http request struct will be freed.
 514  *
 515  * Returns: @request or %NULL if the reference count reached zero.
 516  */
 517 PurpleHttpRequest * purple_http_request_unref(PurpleHttpRequest *request);
 518
 519 /**
 520  * purple_http_request_set_url:
 521  * @request: The request.
 522  * @url:     The url.
 523  *
 524  * Sets URL for HTTP request.
 525  */
 526 void purple_http_request_set_url(PurpleHttpRequest *request, const gchar *url);
 527
 528 /**
 529  * purple_http_request_set_url_printf:
 530  * @request: The request.
 531  * @format:  The format string.
 532  *
 533  * Constructs and sets an URL for HTTP request.
 534  */
 535 void purple_http_request_set_url_printf(PurpleHttpRequest *request,
 536         const gchar *format, ...) G_GNUC_PRINTF(2, 3);
 537
 538 /**
 539  * purple_http_request_get_url:
 540  * @request: The request.
 541  *
 542  * Gets URL set for the HTTP request.
 543  *
 544  * Returns:        URL set for this request.
 545  */
 546 const gchar * purple_http_request_get_url(PurpleHttpRequest *request);
 547
 548 /**
 549  * purple_http_request_set_method:
 550  * @request: The request.
 551  * @method:  The method, or NULL for default.
 552  *
 553  * Sets custom HTTP method used for the request.
 554  */
 555 void purple_http_request_set_method(PurpleHttpRequest *request,
 556         const gchar *method);
 557
 558 /**
 559  * purple_http_request_get_method:
 560  * @request: The request.
 561  *
 562  * Gets HTTP method set for the request.
 563  *
 564  * Returns:        The method.
 565  */
 566 const gchar * purple_http_request_get_method(PurpleHttpRequest *request);
 567
 568 /**
 569  * purple_http_request_set_keepalive_pool:
 570  * @request: The request.
 571  * @pool:    The new KeepAlive pool, or NULL to reset.
 572  *
 573  * Sets HTTP KeepAlive connections pool for the request.
 574  *
 575  * It increases pool's reference count.
 576  */
 577 void
 578 purple_http_request_set_keepalive_pool(PurpleHttpRequest *request,
 579         PurpleHttpKeepalivePool *pool);
 580
 581 /**
 582  * purple_http_request_get_keepalive_pool:
 583  * @request: The request.
 584  *
 585  * Gets HTTP KeepAlive connections pool associated with the request.
 586  *
 587  * It doesn't affect pool's reference count.
 588  *
 589  * Returns:        The KeepAlive pool, used for the request.
 590  */
 591 PurpleHttpKeepalivePool *
 592 purple_http_request_get_keepalive_pool(PurpleHttpRequest *request);
 593
 594 /**
 595  * purple_http_request_set_contents:
 596  * @request:  The request.
 597  * @contents: The contents.
 598  * @length:   The length of contents (-1 if it's a NULL-terminated string)
 599  *
 600  * Sets contents of HTTP request (for example, POST data).
 601  */
 602 void purple_http_request_set_contents(PurpleHttpRequest *request,
 603         const gchar *contents, int length);
 604
 605 /**
 606  * purple_http_request_set_contents_reader:
 607  * @request:              The request.
 608  * @reader: (scope call): The reader callback.
 609  * @contents_length:      The size of all contents.
 610  * @user_data:            The user data to pass to the callback function.
 611  *
 612  * Sets contents reader for HTTP request, used mainly for possible large
 613  * uploads.
 614  */
 615 void purple_http_request_set_contents_reader(PurpleHttpRequest *request,
 616         PurpleHttpContentReader reader, int contents_length, gpointer user_data);
 617
 618 /**
 619  * purple_http_request_set_response_writer:
 620  * @request:              The request.
 621  * @writer: (scope call): The writer callback, or %NULL to remove existing.
 622  * @user_data:            The user data to pass to the callback function.
 623  *
 624  * Set contents writer for HTTP response.
 625  */
 626 void purple_http_request_set_response_writer(PurpleHttpRequest *request,
 627         PurpleHttpContentWriter writer, gpointer user_data);
 628
 629 /**
 630  * purple_http_request_set_timeout:
 631  * @request: The request.
 632  * @timeout: Time (in seconds) after that timeout will be cancelled,
 633  *                -1 for infinite time.
 634  *
 635  * Set maximum amount of time, that request is allowed to run.
 636  */
 637 void purple_http_request_set_timeout(PurpleHttpRequest *request, int timeout);
 638
 639 /**
 640  * purple_http_request_get_timeout:
 641  * @request: The request.
 642  *
 643  * Get maximum amount of time, that request is allowed to run.
 644  *
 645  * Returns:        Timeout currently set (-1 for infinite).
 646  */
 647 int purple_http_request_get_timeout(PurpleHttpRequest *request);
 648
 649 /**
 650  * purple_http_request_set_max_redirects:
 651  * @request:       The request.
 652  * @max_redirects: Maximum amount of redirects, or -1 for unlimited.
 653  *
 654  * Sets maximum amount of redirects.
 655  */
 656 void purple_http_request_set_max_redirects(PurpleHttpRequest *request,
 657         int max_redirects);
 658
 659 /**
 660  * purple_http_request_get_max_redirects:
 661  * @request: The request.
 662  *
 663  * Gets maximum amount of redirects.
 664  *
 665  * Returns:        Current maximum amount of redirects (-1 for unlimited).
 666  */
 667 int purple_http_request_get_max_redirects(PurpleHttpRequest *request);
 668
 669 /**
 670  * purple_http_request_set_cookie_jar:
 671  * @request:    The request.
 672  * @cookie_jar: The cookie jar.
 673  *
 674  * Sets cookie jar used for the request.
 675  */
 676 void purple_http_request_set_cookie_jar(PurpleHttpRequest *request,
 677         PurpleHttpCookieJar *cookie_jar);
 678
 679 /**
 680  * purple_http_request_get_cookie_jar:
 681  * @request: The request.
 682  *
 683  * Gets cookie jar used for the request.
 684  *
 685  * Returns:        The cookie jar.
 686  */
 687 PurpleHttpCookieJar * purple_http_request_get_cookie_jar(
 688         PurpleHttpRequest *request);
 689
 690 /**
 691  * purple_http_request_set_http11:
 692  * @request: The request.
 693  * @http11:  TRUE for HTTP/1.1, FALSE for HTTP/1.0.
 694  *
 695  * Sets HTTP version to use.
 696  */
 697 void purple_http_request_set_http11(PurpleHttpRequest *request,
 698         gboolean http11);
 699
 700 /**
 701  * purple_http_request_is_http11:
 702  * @request: The request.
 703  *
 704  * Gets used HTTP version.
 705  *
 706  * Returns:        TRUE, if we use HTTP/1.1, FALSE for HTTP/1.0.
 707  */
 708 gboolean purple_http_request_is_http11(PurpleHttpRequest *request);
 709
 710 /**
 711  * purple_http_request_set_max_len:
 712  * @request: The request.
 713  * @max_len: Maximum length of response to read (-1 for the maximum
 714  *                supported amount).
 715  *
 716  * Sets maximum length of response content to read.
 717  *
 718  * Headers length doesn't count here.
 719  *
 720  */
 721 void purple_http_request_set_max_len(PurpleHttpRequest *request, int max_len);
 722
 723 /**
 724  * purple_http_request_get_max_len:
 725  * @request: The request.
 726  *
 727  * Gets maximum length of response content to read.
 728  *
 729  * Returns:        Maximum length of response to read, or -1 if unlimited.
 730  */
 731 int purple_http_request_get_max_len(PurpleHttpRequest *request);
 732
 733 /**
 734  * purple_http_request_header_set:
 735  * @request: The request.
 736  * @key:     A header to be set.
 737  * @value:   A value to set, or NULL to remove specified header.
 738  *
 739  * Sets (replaces, if exists) specified HTTP request header with provided value.
 740  *
 741  * See purple_http_request_header_add().
 742  */
 743 void purple_http_request_header_set(PurpleHttpRequest *request,
 744         const gchar *key, const gchar *value);
 745
 746 /**
 747  * purple_http_request_header_set_printf:
 748  * @request: The request.
 749  * @key:     A header to be set.
 750  * @format:  The format string.
 751  *
 752  * Constructs and sets (replaces, if exists) specified HTTP request header.
 753  */
 754 void purple_http_request_header_set_printf(PurpleHttpRequest *request,
 755         const gchar *key, const gchar *format, ...) G_GNUC_PRINTF(3, 4);
 756
 757 /**
 758  * purple_http_request_header_add:
 759  * @key:   A header to be set.
 760  * @value: A value to set.
 761  *
 762  * Adds (without replacing, if exists) an HTTP request header.
 763  *
 764  * See purple_http_request_header_set().
 765  */
 766 void purple_http_request_header_add(PurpleHttpRequest *request,
 767         const gchar *key, const gchar *value);
 768
 769
 770 /**************************************************************************/
 771 /* HTTP Keep-Alive pool API                                               */
 772 /**************************************************************************/
 773
 774 /**
 775  * purple_http_keepalive_pool_new:
 776  *
 777  * Creates a new HTTP Keep-Alive pool.
 778  */
 779 PurpleHttpKeepalivePool *
 780 purple_http_keepalive_pool_new(void);
 781
 782 /**
 783  * purple_http_keepalive_pool_ref:
 784  * @pool: The HTTP Keep-Alive pool.
 785  *
 786  * Increment the reference count.
 787  */
 788 void
 789 purple_http_keepalive_pool_ref(PurpleHttpKeepalivePool *pool);
 790
 791 /**
 792  * purple_http_keepalive_pool_unref:
 793  * @pool: The HTTP Keep-Alive pool.
 794  *
 795  * Decrement the reference count.
 796  *
 797  * If the reference count reaches zero, the pool will be freed and all
 798  * connections will be closed.
 799  *
 800  * Returns: @pool or %NULL if the reference count reached zero.
 801  */
 802 PurpleHttpKeepalivePool *
 803 purple_http_keepalive_pool_unref(PurpleHttpKeepalivePool *pool);
 804
 805 /**
 806  * purple_http_keepalive_pool_set_limit_per_host:
 807  * @pool:  The HTTP Keep-Alive pool.
 808  * @limit: The new limit, 0 for unlimited.
 809  *
 810  * Sets maximum allowed number of connections to specific host-triple (is_ssl +
 811  * hostname + port).
 812  */
 813 void
 814 purple_http_keepalive_pool_set_limit_per_host(PurpleHttpKeepalivePool *pool,
 815         guint limit);
 816
 817 /**
 818  * purple_http_keepalive_pool_get_limit_per_host:
 819  * @pool: The HTTP Keep-Alive pool.
 820  *
 821  * Gets maximum allowed number of connections to specific host-triple (is_ssl +
 822  * hostname + port).
 823  *
 824  * Returns:     The limit.
 825  */
 826 guint
 827 purple_http_keepalive_pool_get_limit_per_host(PurpleHttpKeepalivePool *pool);
 828
 829
 830 /**************************************************************************/
 831 /* HTTP connection set API                                                */
 832 /**************************************************************************/
 833
 834 PurpleHttpConnectionSet *
 835 purple_http_connection_set_new(void);
 836
 837 void
 838 purple_http_connection_set_destroy(PurpleHttpConnectionSet *set);
 839
 840 void
 841 purple_http_connection_set_add(PurpleHttpConnectionSet *set,
 842         PurpleHttpConnection *http_conn);
 843
 844
 845 /**************************************************************************/
 846 /* HTTP response API                                                      */
 847 /**************************************************************************/
 848
 849 /**
 850  * purple_http_response_is_successful:
 851  * @response: The response.
 852  *
 853  * Checks, if HTTP request was performed successfully.
 854  *
 855  * Returns:         TRUE, if request was performed successfully.
 856  */
 857 gboolean purple_http_response_is_successful(PurpleHttpResponse *response);
 858
 859 /**
 860  * purple_http_response_get_code:
 861  * @response: The response.
 862  *
 863  * Gets HTTP response code.
 864  *
 865  * Returns:         HTTP response code.
 866  */
 867 int purple_http_response_get_code(PurpleHttpResponse *response);
 868
 869 /**
 870  * purple_http_response_get_error:
 871  * @response: The response.
 872  *
 873  * Gets error description.
 874  *
 875  * Returns:         Localized error description or NULL, if there was no error.
 876  */
 877 const gchar * purple_http_response_get_error(PurpleHttpResponse *response);
 878
 879 /**
 880  * purple_http_response_get_data_len:
 881  * @response: The response.
 882  *
 883  * Gets HTTP response data length.
 884  *
 885  * Returns:         Data length;
 886  */
 887 gsize purple_http_response_get_data_len(PurpleHttpResponse *response);
 888
 889 /**
 890  * purple_http_response_get_data:
 891  * @response: The response.
 892  * @len:      Return address for the size of the data.  Can be NULL.
 893  *
 894  * Gets HTTP response data.
 895  *
 896  * Response data is not written, if writer callback was set for request.
 897  *
 898  * Returns:         The data.
 899  */
 900 const gchar * purple_http_response_get_data(PurpleHttpResponse *response, size_t *len);
 901
 902 /**
 903  * purple_http_response_get_all_headers:
 904  * @response: The response.
 905  *
 906  * Gets all headers got with response.
 907  *
 908  * Returns:         GList of PurpleKeyValuePair, which keys are header field
 909  *                 names (gchar*) and values are its contents (gchar*).
 910  */
 911 const GList * purple_http_response_get_all_headers(PurpleHttpResponse *response);
 912
 913 /**
 914  * purple_http_response_get_headers_by_name:
 915  * @response: The response.
 916  * @name:     The name of header field.
 917  *
 918  * Gets all headers with specified name got with response.
 919  *
 920  * Returns:         GList of header field records contents (gchar*).
 921  */
 922 const GList * purple_http_response_get_headers_by_name(
 923         PurpleHttpResponse *response, const gchar *name);
 924
 925 /**
 926  * purple_http_response_get_header:
 927  * @response: The response.
 928  * @name:     The name of header field.
 929  *
 930  * Gets one header contents with specified name got with response.
 931  *
 932  * To get all headers with the same name, use
 933  * purple_http_response_get_headers_by_name instead.
 934  *
 935  * Returns:         Header field contents or NULL, if there is no such one.
 936  */
 937 const gchar * purple_http_response_get_header(PurpleHttpResponse *response,
 938         const gchar *name);
 939
 940
 941 /**************************************************************************/
 942 /* HTTP Subsystem                                                         */
 943 /**************************************************************************/
 944
 945 /**
 946  * purple_http_init:
 947  *
 948  * Initializes the http subsystem.
 949  */
 950 void purple_http_init(void);
 951
 952 /**
 953  * purple_http_uninit:
 954  *
 955  * Uninitializes the http subsystem.
 956  */
 957 void purple_http_uninit(void);
 958
 959 G_END_DECLS
 960
 961 #endif /* _PURPLE_HTTP_H_ */