/cpw/tomkiewicz/http: 379bf9ad6973: Initial HTTP API definitions
Tomasz Wasilczyk
tomkiewicz at cpw.pidgin.im
Fri Oct 12 17:04:09 EDT 2012
Changeset: 379bf9ad69732913bbff5a5164c50a2837a7d8e5
Author: Tomasz Wasilczyk <tomkiewicz at cpw.pidgin.im>
Date: 2012-10-12 23:03 +0200
Branch: default
URL: http://hg.pidgin.im/cpw/tomkiewicz/http/rev/379bf9ad6973
Description:
Initial HTTP API definitions
diffstat:
libpurple/Makefile.am | 1 +
libpurple/http.c | 28 ++++
libpurple/http.h | 312 ++++++++++++++++++++++++++++++++++++++++++++++++++
3 files changed, 341 insertions(+), 0 deletions(-)
diffs (truncated from 361 to 300 lines):
diff --git a/libpurple/Makefile.am b/libpurple/Makefile.am
--- a/libpurple/Makefile.am
+++ b/libpurple/Makefile.am
@@ -50,6 +50,7 @@ purple_coresources = \
desktopitem.c \
eventloop.c \
ft.c \
+ http.c \
idle.c \
imgstore.c \
log.c \
diff --git a/libpurple/http.c b/libpurple/http.c
new file mode 100644
--- /dev/null
+++ b/libpurple/http.c
@@ -0,0 +1,28 @@
+/**
+ * @file http.c 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
+ */
+
+#include "http.h"
+
diff --git a/libpurple/http.h b/libpurple/http.h
new file mode 100644
--- /dev/null
+++ b/libpurple/http.h
@@ -0,0 +1,312 @@
+/**
+ * @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;
+
+/**
+ * An collection of cookies, got from HTTP response or provided for HTTP
+ * request.
+ */
+typedef struct _PurpleHTTPCookieJar PurpleHTTPCookieJar;
+
+/**
+ * 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, 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 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.
+ */
+typedef void (*PurpleHttpContentWriter)(PurpleHttpConnection *http_conn,
+ const gchar *buffer, size_t offset, size_t length, 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 url The URL.
+ * @param callback The callback function.
+ * @param data The user data to pass to the callback function.
+ * @return The HTTP connection struct.
+ */
+PurpleHttpConnection * purple_http_get(PurpleConnection *gc, const gchar *url,
+ PurpleHttpCallback callback, gpointer user_data);
+
+/**
+ * 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);
+
+/**
+ * Checks, if provided HTTP request is running.
+ *
+ * @param http_conn The HTTP connection.
+ * @return TRUE, if provided connection is currently running.
+ */
+gboolean purple_http_conn_is_running(PurpleHttpConnection *http_conn);
+
+PurpleHttpRequest * purple_http_conn_get_request(
+ PurpleHttpConnection *http_conn);
+
+PurpleConnection * purple_http_conn_get_purple_connection(
+ PurpleHttpConnection *http_conn);
+
+const GSList * purple_http_conn_get_all(PurpleConnection *gc);
+
+void purple_http_conn_cancel_all(PurpleConnection *gc);
+
+/*@}*/
+
+
+/**************************************************************************/
+/** @name Cookie jar API */
+/**************************************************************************/
+/*@{*/
+
+PurpleHTTPCookieJar * purple_http_cookie_jar_new(void);
+
+void purple_http_cookie_jar_ref(PurpleHTTPCookieJar *cookie_jar);
+
+void purple_http_cookie_jar_unref(PurpleHTTPCookieJar *cookie_jar);
+
+void purple_http_cookie_jar_set(PurpleHTTPCookieJar *cookie_jar,
+ const gchar *name, const gchar *value);
+
+const gchar * purple_http_cookie_jar_get(PurpleHTTPCookieJar *cookie_jar,
+ const gchar *name);
+
+void purple_http_cookie_jar_remove(PurpleHTTPCookieJar *cookie_jar,
+ const gchar *name);
+
+/*@}*/
+
+
+/**************************************************************************/
+/** @name HTTP Request API */
+/**************************************************************************/
+/*@{*/
+
+PurpleHttpRequest * purple_http_request_new(const gchar *url);
+
+void purple_http_request_ref(PurpleHttpRequest *request);
+
+void purple_http_request_unref(PurpleHttpRequest *request); // instead of free
+
+void purple_http_request_set_url(PurpleHttpRequest *request, const gchar *url); // +get
+
+void purple_http_request_set_method(PurpleHttpRequest *request,
+ const gchar *method); // +get
+
+/**
+ * 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); // +get
+
+/**
+ * Sets contents reader for HTTP request, used mainly for possible large
+ * uploads.
+ *
+ * @param request The request.
+ * @param reader The reader callback.
+ * @param user_data The user data to pass to the callback function.
+ */
+void purple_http_request_set_contents_reader(PurpleHttpRequest *request,
+ PurpleHttpContentReader reader, gpointer user_data);
+
+/**
+ * Set contents writer for HTTP response.
+ *
+ * @param request The request.
+ * @param reader The writer callback.
+ * @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);
+
+/**
+ * -1 for unlimited
+ */
+void purple_http_request_set_max_redirects(PurpleHttpRequest *request,
+ int max_redirects); // +get
+
+/**
+ * NULL for disabling cookie support
+ */
+void purple_http_request_set_cookie_jar(PurpleHttpRequest *request,
+ PurpleHTTPCookieJar *cookie_jar); // +get
+
+/**
+ * NULL for default
+ */
+void purple_http_request_set_user_agent(PurpleHttpRequest *request,
+ const gchar *user_agent); // +get
+
More information about the Commits
mailing list