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 * @...: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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 PurpleHttpConnectionSet * 838 purple_http_connection_set_new(void); 839 840 void 841 purple_http_connection_set_destroy(PurpleHttpConnectionSet *set); 842 843 void 844 purple_http_connection_set_add(PurpleHttpConnectionSet *set, 845 PurpleHttpConnection *http_conn); 846 847 848 /**************************************************************************/ 849 /* HTTP response API */ 850 /**************************************************************************/ 851 852 /** 853 * purple_http_response_is_successful: 854 * @response: The response. 855 * 856 * Checks, if HTTP request was performed successfully. 857 * 858 * Returns: TRUE, if request was performed successfully. 859 */ 860 gboolean purple_http_response_is_successful(PurpleHttpResponse *response); 861 862 /** 863 * purple_http_response_get_code: 864 * @response: The response. 865 * 866 * Gets HTTP response code. 867 * 868 * Returns: HTTP response code. 869 */ 870 int purple_http_response_get_code(PurpleHttpResponse *response); 871 872 /** 873 * purple_http_response_get_error: 874 * @response: The response. 875 * 876 * Gets error description. 877 * 878 * Returns: Localized error description or NULL, if there was no error. 879 */ 880 const gchar * purple_http_response_get_error(PurpleHttpResponse *response); 881 882 /** 883 * purple_http_response_get_data_len: 884 * @response: The response. 885 * 886 * Gets HTTP response data length. 887 * 888 * Returns: Data length; 889 */ 890 gsize purple_http_response_get_data_len(PurpleHttpResponse *response); 891 892 /** 893 * purple_http_response_get_data: 894 * @response: The response. 895 * @len: Return address for the size of the data. Can be NULL. 896 * 897 * Gets HTTP response data. 898 * 899 * Response data is not written, if writer callback was set for request. 900 * 901 * Returns: The data. 902 */ 903 const gchar * purple_http_response_get_data(PurpleHttpResponse *response, size_t *len); 904 905 /** 906 * purple_http_response_get_all_headers: 907 * @response: The response. 908 * 909 * Gets all headers got with response. 910 * 911 * Returns: GList of PurpleKeyValuePair, which keys are header field 912 * names (gchar*) and values are its contents (gchar*). 913 */ 914 const GList * purple_http_response_get_all_headers(PurpleHttpResponse *response); 915 916 /** 917 * purple_http_response_get_headers_by_name: 918 * @response: The response. 919 * @name: The name of header field. 920 * 921 * Gets all headers with specified name got with response. 922 * 923 * Returns: GList of header field records contents (gchar*). 924 */ 925 const GList * purple_http_response_get_headers_by_name( 926 PurpleHttpResponse *response, const gchar *name); 927 928 /** 929 * purple_http_response_get_header: 930 * @response: The response. 931 * @name: The name of header field. 932 * 933 * Gets one header contents with specified name got with response. 934 * 935 * To get all headers with the same name, use 936 * purple_http_response_get_headers_by_name instead. 937 * 938 * Returns: Header field contents or NULL, if there is no such one. 939 */ 940 const gchar * purple_http_response_get_header(PurpleHttpResponse *response, 941 const gchar *name); 942 943 944 /**************************************************************************/ 945 /* HTTP Subsystem */ 946 /**************************************************************************/ 947 948 /** 949 * purple_http_init: 950 * 951 * Initializes the http subsystem. 952 */ 953 void purple_http_init(void); 954 955 /** 956 * purple_http_uninit: 957 * 958 * Uninitializes the http subsystem. 959 */ 960 void purple_http_uninit(void); 961 962 G_END_DECLS 963 964 #endif /* _PURPLE_HTTP_H_ */ 965