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_ */ 962