pidgin/pidgin
Clone
Summary
Browse
Changes
Graph
Merge the release-2.x.y branch into default.
2014-02-01, Mark Doliner
3c9c77b80a6c
Merge the release-2.x.y branch into default.
A few manual merges... nothing too bad.
/**
* @file http.h HTTP API
* @ingroup core
*/
/* purple
*
* Purple is the legal property of its developers, whose names are too numerous
* to list here. Please refer to the COPYRIGHT file distributed with this
* source distribution.
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA
*/
#ifndef _PURPLE_HTTP_H_
#define _PURPLE_HTTP_H_
#include
<glib.h>
#include
"connection.h"
/**
* A structure containing all data required to generate a single HTTP request.
*/
typedef
struct
_PurpleHttpRequest
PurpleHttpRequest
;
/**
* A representation of actually running HTTP request. Can be used to cancel the
* request.
*/
typedef
struct
_PurpleHttpConnection
PurpleHttpConnection
;
/**
* All information got with response for HTTP request.
*/
typedef
struct
_PurpleHttpResponse
PurpleHttpResponse
;
/**
* Parsed representation for the URL.
*/
typedef
struct
_PurpleHttpURL
PurpleHttpURL
;
/**
* An collection of cookies, got from HTTP response or provided for HTTP
* request.
*/
typedef
struct
_PurpleHttpCookieJar
PurpleHttpCookieJar
;
/**
* A pool of TCP connections for HTTP Keep-Alive session.
*/
typedef
struct
_PurpleHttpKeepalivePool
PurpleHttpKeepalivePool
;
/**
* A set of running HTTP requests. Can be used to cancel all of them at once.
*/
typedef
struct
_PurpleHttpConnectionSet
PurpleHttpConnectionSet
;
/**
* An callback called after performing (successfully or not) HTTP request.
*/
typedef
void
(
*
PurpleHttpCallback
)(
PurpleHttpConnection
*
http_conn
,
PurpleHttpResponse
*
response
,
gpointer
user_data
);
/**
* An callback called after storing data requested by PurpleHttpContentReader.
*/
typedef
void
(
*
PurpleHttpContentReaderCb
)(
PurpleHttpConnection
*
http_conn
,
gboolean
success
,
gboolean
eof
,
size_t
stored
);
/**
* An callback for getting large request contents (ie. from file stored on
* disk).
*
* @param http_conn Connection, which requests data.
* @param buffer Buffer to store data to (with offset ignored).
* @param offset Position, from where to read data.
* @param length Length of data to read.
* @param user_data The user data passed with callback function.
* @param cb The function to call after storing data to buffer.
*/
typedef
void
(
*
PurpleHttpContentReader
)(
PurpleHttpConnection
*
http_conn
,
gchar
*
buffer
,
size_t
offset
,
size_t
length
,
gpointer
user_data
,
PurpleHttpContentReaderCb
cb
);
/**
* An callback for writting large response contents.
*
* @param http_conn Connection, which requests data.
* @param response Response at point got so far (may change later).
* @param buffer Buffer to read data from (with offset ignored).
* @param offset Position of data got (its value is offset + length of
* previous call), can be safely ignored.
* @param length Length of data read.
* @param user_data The user data passed with callback function.
* @return TRUE, if succeeded, FALSE otherwise.
*/
typedef
gboolean
(
*
PurpleHttpContentWriter
)(
PurpleHttpConnection
*
http_conn
,
PurpleHttpResponse
*
response
,
const
gchar
*
buffer
,
size_t
offset
,
size_t
length
,
gpointer
user_data
);
/**
* An callback for watching HTTP connection progress.
*
* @param http_conn The HTTP Connection.
* @param reading_state FALSE, is we are sending the request, TRUE, when reading
* the response.
* @param processed The amount of data already processed.
* @param total Total amount of data (in current state).
* @param user_data The user data passed with callback function.
*/
typedef
void
(
*
PurpleHttpProgressWatcher
)(
PurpleHttpConnection
*
http_conn
,
gboolean
reading_state
,
int
processed
,
int
total
,
gpointer
user_data
);
G_BEGIN_DECLS
/**************************************************************************/
/** @name Performing HTTP requests */
/**************************************************************************/
/*@{*/
/**
* Fetches the data from a URL with GET request, and passes it to a callback
* function.
*
* @param gc The connection for which the request is needed, or NULL.
* @param callback The callback function.
* @param user_data The user data to pass to the callback function.
* @param url The URL.
* @return The HTTP connection struct.
*/
PurpleHttpConnection
*
purple_http_get
(
PurpleConnection
*
gc
,
PurpleHttpCallback
callback
,
gpointer
user_data
,
const
gchar
*
url
);
/**
* Constructs an URL and fetches the data from it with GET request, then passes
* it to a callback function.
*
* @param gc The connection for which the request is needed, or NULL.
* @param callback The callback function.
* @param user_data The user data to pass to the callback function.
* @param format The format string.
* @return The HTTP connection struct.
*/
PurpleHttpConnection
*
purple_http_get_printf
(
PurpleConnection
*
gc
,
PurpleHttpCallback
callback
,
gpointer
user_data
,
const
gchar
*
format
,
...)
G_GNUC_PRINTF
(
4
,
5
);
/**
* Fetches a HTTP request and passes the response to a callback function.
* Provided request struct can be shared by multiple http requests but can not
* be modified when any of these is running.
*
* @param gc The connection for which the request is needed, or NULL.
* @param request The request.
* @param callback The callback function.
* @param user_data The user data to pass to the callback function.
* @return The HTTP connection struct.
*/
PurpleHttpConnection
*
purple_http_request
(
PurpleConnection
*
gc
,
PurpleHttpRequest
*
request
,
PurpleHttpCallback
callback
,
gpointer
user_data
);
/**************************************************************************/
/** @name HTTP connection API */
/**************************************************************************/
/*@{*/
/**
* Cancel a pending HTTP request.
*
* @param http_conn The data returned when you initiated the HTTP request.
*/
void
purple_http_conn_cancel
(
PurpleHttpConnection
*
http_conn
);
/**
* Cancels all HTTP connections associated with the specified handle.
*
* @param gc The handle.
*/
void
purple_http_conn_cancel_all
(
PurpleConnection
*
gc
);
/**
* Checks, if provided HTTP request is running.
*
* @param http_conn The HTTP connection (may be invalid pointer).
* @return TRUE, if provided connection is currently running.
*/
gboolean
purple_http_conn_is_running
(
PurpleHttpConnection
*
http_conn
);
/**
* Gets PurpleHttpRequest used for specified HTTP connection.
*
* @param http_conn The HTTP connection.
* @return The PurpleHttpRequest object.
*/
PurpleHttpRequest
*
purple_http_conn_get_request
(
PurpleHttpConnection
*
http_conn
);
/**
* Gets cookie jar used within connection.
*
* @param http_conn The HTTP connection.
* @return The cookie jar.
*/
PurpleHttpCookieJar
*
purple_http_conn_get_cookie_jar
(
PurpleHttpConnection
*
http_conn
);
/**
* Gets PurpleConnection tied with specified HTTP connection.
*
* @param http_conn The HTTP connection.
* @return The PurpleConnection object.
*/
PurpleConnection
*
purple_http_conn_get_purple_connection
(
PurpleHttpConnection
*
http_conn
);
/**
* Sets the watcher, called after writing or reading data to/from HTTP stream.
* May be used for updating transfer progress gauge.
*
* @param http_conn The HTTP connection.
* @param watcher The watcher.
* @param user_data The user data to pass to the callback function.
* @param interval_threshold Minimum interval (in microseconds) of calls to
* watcher, or -1 for default.
*/
void
purple_http_conn_set_progress_watcher
(
PurpleHttpConnection
*
http_conn
,
PurpleHttpProgressWatcher
watcher
,
gpointer
user_data
,
gint
interval_threshold
);
/*@}*/
/**************************************************************************/
/** @name URL processing API */
/**************************************************************************/
/*@{*/
/**
* Parses a URL.
*
* The returned data must be freed with purple_http_url_free.
*
* @param url The URL to parse.
* @return The parsed url or NULL, if the URL is invalid.
*/
PurpleHttpURL
*
purple_http_url_parse
(
const
char
*
url
);
/**
* Frees the parsed URL struct.
*
* @param parsed_url The parsed URL struct, or NULL.
*/
void
purple_http_url_free
(
PurpleHttpURL
*
parsed_url
);
/**
* Converts the base URL to the absolute form of the provided relative URL.
*
* Example: "https://example.com/path/to/file.html" + "subdir/other-file.html" =
* "https://example.com/path/to/subdir/another-file.html"
*
* @param base_url The base URL. The result is stored here.
* @param relative_url The relative URL.
*/
void
purple_http_url_relative
(
PurpleHttpURL
*
base_url
,
PurpleHttpURL
*
relative_url
);
/**
* Converts the URL struct to the printable form. The result may not be a valid
* URL (in cases, when the struct doesn't have all fields filled properly).
*
* The result must be g_free'd.
*
* @param parsed_url The URL struct.
* @return The printable form of the URL.
*/
gchar
*
purple_http_url_print
(
PurpleHttpURL
*
parsed_url
);
/**
* Gets the protocol part of URL.
*
* @param parsed_url The URL struct.
* @return The protocol.
*/
const
gchar
*
purple_http_url_get_protocol
(
const
PurpleHttpURL
*
parsed_url
);
/**
* Gets the username part of URL.
*
* @param parsed_url The URL struct.
* @return The username.
*/
const
gchar
*
purple_http_url_get_username
(
const
PurpleHttpURL
*
parsed_url
);
/**
* Gets the password part of URL.
*
* @param parsed_url The URL struct.
* @return The password.
*/
const
gchar
*
purple_http_url_get_password
(
const
PurpleHttpURL
*
parsed_url
);
/**
* Gets the hostname part of URL.
*
* @param parsed_url The URL struct.
* @return The hostname.
*/
const
gchar
*
purple_http_url_get_host
(
const
PurpleHttpURL
*
parsed_url
);
/**
* Gets the port part of URL.
*
* @param parsed_url The URL struct.
* @return The port number.
*/
int
purple_http_url_get_port
(
const
PurpleHttpURL
*
parsed_url
);
/**
* Gets the path part of URL.
*
* @param parsed_url The URL struct.
* @return The path.
*/
const
gchar
*
purple_http_url_get_path
(
const
PurpleHttpURL
*
parsed_url
);
/**
* Gets the fragment part of URL.
*
* @param parsed_url The URL struct.
* @return The fragment.
*/
const
gchar
*
purple_http_url_get_fragment
(
const
PurpleHttpURL
*
parsed_url
);
/*@}*/
/**************************************************************************/
/** @name Cookie jar API */
/**************************************************************************/
/*@{*/
/**
* Creates new cookie jar,
*
* @return empty cookie jar.
*/
PurpleHttpCookieJar
*
purple_http_cookie_jar_new
(
void
);
/**
* Increment the reference count.
*
* @param cookie_jar The cookie jar.
*/
void
purple_http_cookie_jar_ref
(
PurpleHttpCookieJar
*
cookie_jar
);
/**
* Decrement the reference count.
*
* If the reference count reaches zero, the cookie jar will be freed.
*
* @param cookie_jar The cookie jar.
* @return @a cookie_jar or @c NULL if the reference count reached zero.
*/
PurpleHttpCookieJar
*
purple_http_cookie_jar_unref
(
PurpleHttpCookieJar
*
cookie_jar
);
/**
* Sets the cookie.
*
* @param cookie_jar The cookie jar.
* @param name Cookie name.
* @param value Cookie contents.
*/
void
purple_http_cookie_jar_set
(
PurpleHttpCookieJar
*
cookie_jar
,
const
gchar
*
name
,
const
gchar
*
value
);
/**
* Gets the cookie.
*
* @param cookie_jar The cookie jar.
* @param name Cookie name.
* @return Cookie contents, or NULL, if cookie doesn't exists.
*/
const
gchar
*
purple_http_cookie_jar_get
(
PurpleHttpCookieJar
*
cookie_jar
,
const
gchar
*
name
);
/**
* Checks, if the cookie jar contains any cookies.
*
* @param cookie_jar The cookie jar.
* @return TRUE, if cookie jar contains any cookie, FALSE otherwise.
*/
gboolean
purple_http_cookie_jar_is_empty
(
PurpleHttpCookieJar
*
cookie_jar
);
/*@}*/
/**************************************************************************/
/** @name HTTP Request API */
/**************************************************************************/
/*@{*/
/**
* Creates the new instance of HTTP request configuration.
*
* @param url The URL to request for, or NULL to leave empty (to be set with
* purple_http_request_set_url).
* @return The new instance of HTTP request struct.
*/
PurpleHttpRequest
*
purple_http_request_new
(
const
gchar
*
url
);
/**
* Increment the reference count.
*
* @param request The request.
*/
void
purple_http_request_ref
(
PurpleHttpRequest
*
request
);
/**
* Decrement the reference count.
*
* If the reference count reaches zero, the http request struct will be freed.
*
* @param request The request.
* @return @a request or @c NULL if the reference count reached zero.
*/
PurpleHttpRequest
*
purple_http_request_unref
(
PurpleHttpRequest
*
request
);
/**
* Sets URL for HTTP request.
*
* @param request The request.
* @param url The url.
*/
void
purple_http_request_set_url
(
PurpleHttpRequest
*
request
,
const
gchar
*
url
);
/**
* Constructs and sets an URL for HTTP request.
*
* @param request The request.
* @param format The format string.
*/
void
purple_http_request_set_url_printf
(
PurpleHttpRequest
*
request
,
const
gchar
*
format
,
...)
G_GNUC_PRINTF
(
2
,
3
);
/**
* Gets URL set for the HTTP request.
*
* @param request The request.
* @return URL set for this request.
*/
const
gchar
*
purple_http_request_get_url
(
PurpleHttpRequest
*
request
);
/**
* Sets custom HTTP method used for the request.
*
* @param request The request.
* @param method The method, or NULL for default.
*/
void
purple_http_request_set_method
(
PurpleHttpRequest
*
request
,
const
gchar
*
method
);
/**
* Gets HTTP method set for the request.
*
* @param request The request.
* @return The method.
*/
const
gchar
*
purple_http_request_get_method
(
PurpleHttpRequest
*
request
);
/**
* Sets HTTP KeepAlive connections pool for the request.
*
* It increases pool's reference count.
*
* @param request The request.
* @param pool The new KeepAlive pool, or NULL to reset.
*/
void
purple_http_request_set_keepalive_pool
(
PurpleHttpRequest
*
request
,
PurpleHttpKeepalivePool
*
pool
);
/**
* Gets HTTP KeepAlive connections pool associated with the request.
*
* It doesn't affect pool's reference count.
*
* @param request The request.
* @return The KeepAlive pool, used for the request.
*/
PurpleHttpKeepalivePool
*
purple_http_request_get_keepalive_pool
(
PurpleHttpRequest
*
request
);
/**
* Sets contents of HTTP request (for example, POST data).
*
* @param request The request.
* @param contents The contents.
* @param length The length of contents (-1 if it's a NULL-terminated string)
*/
void
purple_http_request_set_contents
(
PurpleHttpRequest
*
request
,
const
gchar
*
contents
,
int
length
);
/**
* Sets contents reader for HTTP request, used mainly for possible large
* uploads.
*
* @param request The request.
* @param reader The reader callback.
* @param contents_size The size of all contents.
* @param user_data The user data to pass to the callback function.
*/
void
purple_http_request_set_contents_reader
(
PurpleHttpRequest
*
request
,
PurpleHttpContentReader
reader
,
int
contents_length
,
gpointer
user_data
);
/**
* Set contents writer for HTTP response.
*
* @param request The request.
* @param reader The writer callback, or NULL to remove existing.
* @param user_data The user data to pass to the callback function.
*/
void
purple_http_request_set_response_writer
(
PurpleHttpRequest
*
request
,
PurpleHttpContentWriter
writer
,
gpointer
user_data
);
/**
* Set maximum amount of time, that request is allowed to run.
*
* @param request The request.
* @param timeout Time (in seconds) after that timeout will be cancelled,
* -1 for infinite time.
*/
void
purple_http_request_set_timeout
(
PurpleHttpRequest
*
request
,
int
timeout
);
/**
* Get maximum amount of time, that request is allowed to run.
*
* @param request The request.
* @return Timeout currently set (-1 for infinite).
*/
int
purple_http_request_get_timeout
(
PurpleHttpRequest
*
request
);
/**
* Sets maximum amount of redirects.
*
* @param request The request.
* @param max_redirects Maximum amount of redirects, or -1 for unlimited.
*/
void
purple_http_request_set_max_redirects
(
PurpleHttpRequest
*
request
,
int
max_redirects
);
/**
* Gets maximum amount of redirects.
*
* @param request The request.
* @return Current maximum amount of redirects (-1 for unlimited).
*/
int
purple_http_request_get_max_redirects
(
PurpleHttpRequest
*
request
);
/**
* Sets cookie jar used for the request.
*
* @param request The request.
* @param cookie_jar The cookie jar.
*/
void
purple_http_request_set_cookie_jar
(
PurpleHttpRequest
*
request
,
PurpleHttpCookieJar
*
cookie_jar
);
/**
* Gets cookie jar used for the request.
*
* @param request The request.
* @return The cookie jar.
*/
PurpleHttpCookieJar
*
purple_http_request_get_cookie_jar
(
PurpleHttpRequest
*
request
);
/**
* Sets HTTP version to use.
*
* @param request The request.
* @param http11 TRUE for HTTP/1.1, FALSE for HTTP/1.0.
*/
void
purple_http_request_set_http11
(
PurpleHttpRequest
*
request
,
gboolean
http11
);
/**
* Gets used HTTP version.
*
* @param request The request.
* @return TRUE, if we use HTTP/1.1, FALSE for HTTP/1.0.
*/
gboolean
purple_http_request_is_http11
(
PurpleHttpRequest
*
request
);
/**
* Sets maximum length of response content to read.
*
* Headers length doesn't count here.
*
* @param request The request.
* @param max_len Maximum length of response to read (-1 for the maximum
* supported amount).
*/
void
purple_http_request_set_max_len
(
PurpleHttpRequest
*
request
,
int
max_len
);
/**
* Gets maximum length of response content to read.
*
* @param request The request.
* @return Maximum length of response to read, or -1 if unlimited.
*/
int
purple_http_request_get_max_len
(
PurpleHttpRequest
*
request
);
/**
* Sets (replaces, if exists) specified HTTP request header with provided value.
*
* @param request The request.
* @param key A header to be set.
* @param value A value to set, or NULL to remove specified header.
*
* @see purple_http_request_header_add
*/
void
purple_http_request_header_set
(
PurpleHttpRequest
*
request
,
const
gchar
*
key
,
const
gchar
*
value
);
/**
* Constructs and sets (replaces, if exists) specified HTTP request header.
*
* @param request The request.
* @param key A header to be set.
* @param format The format string.
*/
void
purple_http_request_header_set_printf
(
PurpleHttpRequest
*
request
,
const
gchar
*
key
,
const
gchar
*
format
,
...)
G_GNUC_PRINTF
(
3
,
4
);
/**
* Adds (without replacing, if exists) an HTTP request header.
*
* @param key A header to be set.
* @param value A value to set.
*
* @see purple_http_request_header_set
*/
void
purple_http_request_header_add
(
PurpleHttpRequest
*
request
,
const
gchar
*
key
,
const
gchar
*
value
);
/*@}*/
/**************************************************************************/
/** @name HTTP Keep-Alive pool API */
/**************************************************************************/
/*@{*/
/**
* Creates a new HTTP Keep-Alive pool.
*/
PurpleHttpKeepalivePool
*
purple_http_keepalive_pool_new
(
void
);
/**
* Increment the reference count.
*
* @param pool The HTTP Keep-Alive pool.
*/
void
purple_http_keepalive_pool_ref
(
PurpleHttpKeepalivePool
*
pool
);
/**
* Decrement the reference count.
*
* If the reference count reaches zero, the pool will be freed and all
* connections will be closed.
*
* @param pool The HTTP Keep-Alive pool.
* @return @a pool or @c NULL if the reference count reached zero.
*/
PurpleHttpKeepalivePool
*
purple_http_keepalive_pool_unref
(
PurpleHttpKeepalivePool
*
pool
);
/**
* Sets maximum allowed number of connections to specific host-triple (is_ssl +
* hostname + port).
*
* @param pool The HTTP Keep-Alive pool.
* @param limit The new limit, 0 for unlimited.
*/
void
purple_http_keepalive_pool_set_limit_per_host
(
PurpleHttpKeepalivePool
*
pool
,
guint
limit
);
/**
* Gets maximum allowed number of connections to specific host-triple (is_ssl +
* hostname + port).
*
* @param pool The HTTP Keep-Alive pool.
* @return The limit.
*/
guint
purple_http_keepalive_pool_get_limit_per_host
(
PurpleHttpKeepalivePool
*
pool
);
/*@}*/
/**************************************************************************/
/** @name HTTP connection set API */
/**************************************************************************/
/*@{*/
PurpleHttpConnectionSet
*
purple_http_connection_set_new
(
void
);
void
purple_http_connection_set_destroy
(
PurpleHttpConnectionSet
*
set
);
void
purple_http_connection_set_add
(
PurpleHttpConnectionSet
*
set
,
PurpleHttpConnection
*
http_conn
);
/*@}*/
/**************************************************************************/
/** @name HTTP response API */
/**************************************************************************/
/*@{*/
/**
* Checks, if HTTP request was performed successfully.
*
* @param response The response.
* @return TRUE, if request was performed successfully.
*/
gboolean
purple_http_response_is_successful
(
PurpleHttpResponse
*
response
);
/**
* Gets HTTP response code.
*
* @param response The response.
* @return HTTP response code.
*/
int
purple_http_response_get_code
(
PurpleHttpResponse
*
response
);
/**
* Gets error description.
*
* @param response The response.
* @return Localized error description or NULL, if there was no error.
*/
const
gchar
*
purple_http_response_get_error
(
PurpleHttpResponse
*
response
);
/**
* Gets HTTP response data length.
*
* @param response The response.
* @return Data length;
*/
gsize
purple_http_response_get_data_len
(
PurpleHttpResponse
*
response
);
/**
* Gets HTTP response data.
*
* Response data is not written, if writer callback was set for request.
*
* @param response The response.
* @param len Return address for the size of the data. Can be NULL.
* @return The data.
*/
const
gchar
*
purple_http_response_get_data
(
PurpleHttpResponse
*
response
,
size_t
*
len
);
/**
* Gets all headers got with response.
*
* @param response The response.
* @return GList of PurpleKeyValuePair, which keys are header field
* names (gchar*) and values are its contents (gchar*).
*/
const
GList
*
purple_http_response_get_all_headers
(
PurpleHttpResponse
*
response
);
/**
* Gets all headers with specified name got with response.
*
* @param response The response.
* @param name The name of header field.
* @return GList of header field records contents (gchar*).
*/
const
GList
*
purple_http_response_get_headers_by_name
(
PurpleHttpResponse
*
response
,
const
gchar
*
name
);
/**
* Gets one header contents with specified name got with response.
*
* To get all headers with the same name, use
* purple_http_response_get_headers_by_name instead.
*
* @param response The response.
* @param name The name of header field.
* @return Header field contents or NULL, if there is no such one.
*/
const
gchar
*
purple_http_response_get_header
(
PurpleHttpResponse
*
response
,
const
gchar
*
name
);
/*@}*/
/**************************************************************************/
/** @name HTTP Subsystem */
/**************************************************************************/
/*@{*/
/**
* Initializes the http subsystem.
*/
void
purple_http_init
(
void
);
/**
* Uninitializes the http subsystem.
*/
void
purple_http_uninit
(
void
);
/*@}*/
G_END_DECLS
#endif
/* _PURPLE_HTTP_H_ */