libsoup r1018 - in branches/libsoup-2.4: . docs/reference docs/reference/tmpl libsoup
- From: danw svn gnome org
- To: svn-commits-list gnome org
- Subject: libsoup r1018 - in branches/libsoup-2.4: . docs/reference docs/reference/tmpl libsoup
- Date: Mon, 7 Jan 2008 14:51:32 +0000 (GMT)
Author: danw
Date: Mon Jan 7 14:51:31 2008
New Revision: 1018
URL: http://svn.gnome.org/viewvc/libsoup?rev=1018&view=rev
Log:
* libsoup/*.c: Move gtk-doc stuff from docs/reference/tmpl/ to the
C files themselves. Some updates.
* docs/reference/Makefile.am: fix (kludge?) this up to not require
tmpl/ to exist
* docs/reference/client-howto.xml:
* docs/reference/server-howto.xml: update
Removed:
branches/libsoup-2.4/docs/reference/tmpl/
branches/libsoup-2.4/libsoup/soup-method.c
Modified:
branches/libsoup-2.4/ChangeLog
branches/libsoup-2.4/docs/reference/ (props changed)
branches/libsoup-2.4/docs/reference/Makefile.am
branches/libsoup-2.4/docs/reference/client-howto.xml
branches/libsoup-2.4/docs/reference/libsoup-overrides.txt
branches/libsoup-2.4/docs/reference/libsoup-sections.txt
branches/libsoup-2.4/docs/reference/server-howto.xml
branches/libsoup-2.4/libsoup/soup-address.c
branches/libsoup-2.4/libsoup/soup-address.h
branches/libsoup-2.4/libsoup/soup-auth-domain-basic.c
branches/libsoup-2.4/libsoup/soup-auth-domain-digest.c
branches/libsoup-2.4/libsoup/soup-auth-domain.c
branches/libsoup-2.4/libsoup/soup-auth.c
branches/libsoup-2.4/libsoup/soup-connection.h
branches/libsoup-2.4/libsoup/soup-date.c
branches/libsoup-2.4/libsoup/soup-date.h
branches/libsoup-2.4/libsoup/soup-dns.h
branches/libsoup-2.4/libsoup/soup-gnutls.c
branches/libsoup-2.4/libsoup/soup-message-body.c
branches/libsoup-2.4/libsoup/soup-message-body.h
branches/libsoup-2.4/libsoup/soup-message-headers.c
branches/libsoup-2.4/libsoup/soup-message-headers.h
branches/libsoup-2.4/libsoup/soup-message-queue.h
branches/libsoup-2.4/libsoup/soup-message.c
branches/libsoup-2.4/libsoup/soup-message.h
branches/libsoup-2.4/libsoup/soup-method.h
branches/libsoup-2.4/libsoup/soup-misc.c
branches/libsoup-2.4/libsoup/soup-misc.h
branches/libsoup-2.4/libsoup/soup-server.c
branches/libsoup-2.4/libsoup/soup-server.h
branches/libsoup-2.4/libsoup/soup-session-async.c
branches/libsoup-2.4/libsoup/soup-session-sync.c
branches/libsoup-2.4/libsoup/soup-session.c
branches/libsoup-2.4/libsoup/soup-socket.c
branches/libsoup-2.4/libsoup/soup-socket.h
branches/libsoup-2.4/libsoup/soup-status.c
branches/libsoup-2.4/libsoup/soup-status.h
branches/libsoup-2.4/libsoup/soup-uri.c
branches/libsoup-2.4/libsoup/soup-value-utils.c
branches/libsoup-2.4/libsoup/soup-value-utils.h
branches/libsoup-2.4/libsoup/soup-xmlrpc.c
Modified: branches/libsoup-2.4/ChangeLog
==============================================================================
--- branches/libsoup-2.4/ChangeLog (original)
+++ branches/libsoup-2.4/ChangeLog Mon Jan 7 14:51:31 2008
@@ -1,3 +1,14 @@
+2008-01-07 Dan Winship <danw gnome org>
+
+ * libsoup/*.c: Move gtk-doc stuff from docs/reference/tmpl/ to the
+ C files themselves. Some updates.
+
+ * docs/reference/Makefile.am: fix (kludge?) this up to not require
+ tmpl/ to exist
+
+ * docs/reference/client-howto.xml:
+ * docs/reference/server-howto.xml: update
+
2008-01-06 Dan Winship <danw gnome org>
* libsoup/soup-soap-message.c:
Modified: branches/libsoup-2.4/docs/reference/Makefile.am
==============================================================================
--- branches/libsoup-2.4/docs/reference/Makefile.am (original)
+++ branches/libsoup-2.4/docs/reference/Makefile.am Mon Jan 7 14:51:31 2008
@@ -29,7 +29,13 @@
CFILE_GLOB=
# Header files to ignore when scanning.
-IGNORE_HFILES= soup.h soup-marshal.h soup-types.h
+IGNORE_HFILES= soup.h soup-marshal.h \
+ soup-message-private.h soup-session-private.h \
+ soup-types.h soup-enum-types.h \
+ soup-auth-basic.h soup-auth-digest.h soup-auth-ntlm.h \
+ soup-connection.h soup-connection-ntlm.h \
+ soup-dns.h soup-auth-manager.h soup-md5-utils.h \
+ soup-message-queue.h soup-path-map.h soup-ssl.h
# Images to copy into HTML directory.
HTML_IMAGES =
@@ -51,7 +57,11 @@
GTKDOC_LIBS = $(top_builddir)/libsoup/libsoup-$(SOUP_API_VERSION).la
-
# include common portion ...
include $(top_srcdir)/gtk-doc.make
+# kludges
+tmpl/*.sgml:
+
+clean: clean-am
+ rm -rf tmpl
Modified: branches/libsoup-2.4/docs/reference/client-howto.xml
==============================================================================
--- branches/libsoup-2.4/docs/reference/client-howto.xml (original)
+++ branches/libsoup-2.4/docs/reference/client-howto.xml Mon Jan 7 14:51:31 2008
@@ -44,7 +44,7 @@
</itemizedlist>
<para>
-If you want to do a mix of synchronous and asynchronous I/O, you will
+If you want to do a mix of mainloop-based and blocking I/O, you will
need to create two different session objects.
</para>
@@ -142,8 +142,10 @@
<para>
In more complicated cases, you can use various <link
-linkend="SoupMessage">SoupMessage</link> methods to set the request
-headers and body of the message:
+linkend="SoupMessage">SoupMessage</link>, <link
+linkend="SoupMessageHeaders">SoupMessageHeaders</link>, and <link
+linkend="SoupMessageBody">SoupMessageBody</link> methods to set the
+request headers and body of the message:
</para>
<informalexample><programlisting>
@@ -151,8 +153,8 @@
msg = soup_message_new ("POST", "http://example.com/form.cgi";);
soup_message_set_request (msg, "application/x-www-form-urlencoded",
- SOUP_BUFFER_USER_OWNED, formdata, strlen (formdata));
- soup_message_add_header (msg->request_headers, "Referer", referring_url);
+ SOUP_MEMORY_COPY, formdata, strlen (formdata));
+ soup_message_headers_append (msg->request_headers, "Referer", referring_url);
</programlisting></informalexample>
<para>
@@ -180,20 +182,18 @@
</programlisting></informalexample>
<para>
-<literal>session</literal> can be either a <link
-linkend="SoupSessionSync"><type>SoupSessionSync</type></link> or a
-<link linkend="SoupSessionAsync"><type>SoupSessionAsync</type></link>;
-if you use <function>soup_session_send_message</function> on an async
-session, it will run the main loop itself until the message is
-complete.
+(If you use <function>soup_session_send_message</function> with a
+<link linkend="SoupSessionAsync"><type>SoupSessionAsync</type></link>,
+it will run the main loop itself until the message is complete.)
</para>
<para>
-The return value from <function>soup_session_send</function> is a <link
-linkend="soup-status">soup status code</link>, indicating either a
-transport error that prevented the message from being sent, or the
+The return value from <function>soup_session_send</function> is a
+<link linkend="soup-status">soup status code</link>, indicating either
+a transport error that prevented the message from being sent, or the
HTTP status that was returned by the server in response to the
-message.
+message. (The status is also available as
+<literal>msg->status_code</literal>.)
</para>
</refsect3>
@@ -202,10 +202,8 @@
<title>Sending a Message Asynchronously</title>
<para>
-To send a message asynchronously (which can only be done if you're
-using <link
-linkend="SoupSessionAsync"><type>SoupSessionAsync</type></link>), use
-<link linkend="soup-session-queue-message"><function>soup_session_queue_message</function></link>:
+To send a message asynchronously, use <link
+linkend="soup-session-queue-message"><function>soup_session_queue_message</function></link>:
</para>
<informalexample><programlisting>
@@ -215,7 +213,7 @@
}
static void
-my_callback (SoupMessage *msg, gpointer user_data)
+my_callback (SoupSession, *session, SoupMessage *msg, gpointer user_data)
{
/* Handle the response here */
}
@@ -229,6 +227,15 @@
passed to <function>soup_session_queue_message</function>.
</para>
+<para>
+(If you use <link
+linkend="soup-session-queue-message"><function>soup_session_queue_message</function></link>
+with a <link
+linkend="SoupSessionSync"><type>SoupSessionSync</type></link>, the
+message will be sent in another thread, with the callback eventually
+being invoked in the session's <link linkend="SOUP-SESSION-ASYNC-CONTEXT:CAPS"><literal>SOUP_SESSION_ASYNC_CONTEXT</literal></link>.)
+</para>
+
</refsect3>
</refsect2>
@@ -245,11 +252,11 @@
status and textual status response from the server.
<structfield>response_headers</structfield> contains the response
headers, which you can investigate using <link
-linkend="soup-message-get-header"><function>soup_message_get_header</function></link> and
+linkend="soup-message-headers-get"><function>soup_message_headers_get</function></link> and
<link
- linkend="soup-message-foreach-header"><function>soup_message_foreach_header</function></link>.
+ linkend="soup-message-headers-foreach"><function>soup_message_headers_foreach</function></link>.
The response body (if any) is in the
-<structfield>response</structfield> field.
+<structfield>response_body</structfield> field.
</para>
<para>
@@ -272,17 +279,17 @@
<title>Intermediate/Automatic Processing</title>
<para>
-You can also connect to various <literal>SoupMessage</literal>
-signals, or set up handlers using <link
-linkend="soup-message-add-handler"><function>soup_message_add_handler</function></link>
-and the other handler methods. Notably, <link
+You can also connect to various <literal>SoupMessage</literal> signals
+to do processing at intermediate stages of HTTP I/O.
+<literal>SoupMessage</literal> also provides two convenience methods,
+<link
linkend="soup-message-add-header-handler"><function>soup_message_add_header_handler</function></link>,
-<link linkend="soup-message-add-status-code-handler"><function>soup_message_add_status_code_handler</function></link>,
-and
-<link linkend="soup-message-add-status-class-handler"><function>soup_message_add_status_class_handler</function></link>
-allow you to invoke a handler automatically for messages with certain
-response headers or status codes. <type>SoupSession</type> uses
-this internally to handle authentication and redirection.
+and <link
+linkend="soup-message-add-status-code-handler"><function>soup_message_add_status_code_handler</function></link>,
+which allow you to set up a signal handler that will only be invoked
+for messages with certain response headers or status codes.
+<type>SoupSession</type> uses this internally to handle authentication
+and redirection.
</para>
<para>
@@ -293,10 +300,9 @@
<para>
To automatically set up handlers on all messages sent via a session,
-you can create a <link
-linkend="SoupMessageFilter">SoupMessageFilter</link> and attach it to
-the session with <link
-linkend="soup-session-add-filter"><function>soup_session_add_filter</function></link>.
+you can connect to the session's <link
+linkend="SoupSession-request-started"><literal>request_started</literal></link>
+signal, and add handlers to each message from there.
</para>
</refsect2>
@@ -309,76 +315,36 @@
authentication for you. If it receives a 401 ("Unauthorized") or 407
("Proxy Authentication Required") response, the session will emit the
<link linkend="SoupSession-authenticate">authenticate</link> signal,
-indicating the authentication type ("Basic", "Digest", or "NTLM") and
-the realm name provided by the server. You should connect to this
-signal and, if possible, fill in the <parameter>username</parameter>
-and <parameter>password</parameter> parameters with authentication
-information. (The session will <function>g_free</function> the strings
-when it is done with them.) If the handler doesn't fill in those
-parameters, then the session will just return the message to the
-application with its 401 or 407 status.
+providing you with a <link
+linkend="SoupAuth"><type>SoupAuth</type></link> object indicating the
+authentication type ("Basic", "Digest", or "NTLM") and the realm name
+provided by the server. If you have a username and password available
+(or can generate one), call <link
+linkend="soup-auth-authenticate"><function>soup_auth_authenticate</function></link>
+to give the information to libsoup. The session will automatically
+requeue the message and try it again with that authentication
+information. (If you don't call
+<function>soup_auth_authenticate</function>, the session will just
+return the message to the application with its 401 or 407 status.)
</para>
<para>
-If the <literal>authenticate</literal> handler returns a username and
-password, but the request still gets an authorization error using that
-information, then the session will emit the <link
-linkend="SoupSession-reauthenticate">reauthenticate</link> signal.
-This lets the application know that the information it provided
-earlier was incorrect, and gives it a chance to try again. If this
+If the server doesn't accept the username and password provided, the
+session will emit <link
+linkend="SoupSession-authenticate">authenticate</link> again, with the
+<literal>retrying</literal> parameter set to <link
+linkend="TRUE:CAPS"><literal>TRUE</literal></link>. This lets the
+application know that the information it provided earlier was
+incorrect, and gives it a chance to try again. If this
username/password pair also doesn't work, the session will contine to
-emit <literal>reauthenticate</literal> again and again until the
-returned username/password successfully authentications, or until the
-signal handler fails to provide a username, at which point
-<application>libsoup</application> will allow the message to fail
-(with status 401 or 407).
+emit <literal>authenticate</literal> again and again until the
+provided username/password successfully authenticates, or until the
+signal handler fails to call <link
+linkend="soup-auth-authenticate"><function>soup_auth_authenticate</function></link>,
+at which point <application>libsoup</application> will allow the
+message to fail (with status 401 or 407).
</para>
-<para>
-There are basically three ways an application might want to use
-the signals:
-</para>
-
-<itemizedlist>
- <listitem><para>
- An interactive application that doesn't cache passwords could
- just connect both <literal>authenticate</literal> and
- <literal>reauthenticate</literal> to the same signal handler,
- which would ask the user for a username and password and then
- return that to soup. This handler would be called repeatedly
- until the provided information worked, or until it failed to
- return any information (eg, because the user hit "Cancel"
- instead of "OK").
- </para></listitem>
-
- <listitem><para>
- A slightly cleverer interactive application would look in its
- password cache from the <literal>authenticate</literal>
- handler, and return a password from there if one was
- available. If no password was cached, it would just call its
- <literal>reauthenticate</literal> handler to prompt the user.
- The <literal>reauthenticate</literal> handler would first
- clear any cached password for this host, auth type, and realm,
- then ask the user as in the case above, and then store that
- information in its cache before returning it to soup. (If the
- password turns out to be incorrect, then
- <literal>reauthenticate</literal> will be called again to
- force it to be uncached.)
- </para></listitem>
-
- <listitem><para>
- A non-interactive program that only has access to cached
- passwords would only connect to
- <literal>authenticate</literal>. If the username and password
- that <literal>authenticate</literal> returns fail, the session
- will emit <literal>reauthenticate</literal>, but since the
- application is not listening to that signal, no new username
- and password will be returned there, so the message will be
- returned to the application with a 401 or 407 status, which
- the application can deal with as it needs to.
- </para></listitem>
-</itemizedlist>
-
</refsect2>
<refsect2>
@@ -396,12 +362,12 @@
</para></listitem>
<listitem><para>
- <emphasis role="bold"><literal>dict</literal></emphasis> and
- <emphasis role="bold"><literal>getbug</literal></emphasis> are trivial
- demonstrations of the <link
- linkend="SoupSoapMessage">SOAP</link> and <link
- linkend="SoupXmlrpcMessage">XMLRPC</link> interfaces,
- respectively.
+ <emphasis role="bold"><literal>getbug</literal></emphasis> is a trivial
+ demonstration of the <link
+ linkend="libsoup-XMLRPC-Support">XMLRPC</link> interface.
+ (<emphasis
+ role="bold"><literal>xmlrpc-test</literal></emphasis> provides
+ a slightly more complicated example.)
</para></listitem>
<listitem><para>
Modified: branches/libsoup-2.4/docs/reference/libsoup-overrides.txt
==============================================================================
--- branches/libsoup-2.4/docs/reference/libsoup-overrides.txt (original)
+++ branches/libsoup-2.4/docs/reference/libsoup-overrides.txt Mon Jan 7 14:51:31 2008
@@ -1,9 +1,4 @@
<FUNCTION>
-<NAME>soup_dns_lookup_get_address</NAME>
-<RETURNS>struct sockaddr *</RETURNS>
-SoupDNSLookup *lookup
-</FUNCTION>
-<FUNCTION>
<NAME>soup_address_get_sockaddr</NAME>
<RETURNS>struct sockaddr *</RETURNS>
SoupAddress *addr,
Modified: branches/libsoup-2.4/docs/reference/libsoup-sections.txt
==============================================================================
--- branches/libsoup-2.4/docs/reference/libsoup-sections.txt (original)
+++ branches/libsoup-2.4/docs/reference/libsoup-sections.txt Mon Jan 7 14:51:31 2008
@@ -39,8 +39,6 @@
SOUP_IS_MESSAGE_CLASS
SOUP_MESSAGE_GET_CLASS
SoupMessageClass
-SoupMessagePrivate
-SOUP_MESSAGE_GET_PRIVATE
<SUBSECTION Private>
soup_message_wrote_informational
soup_message_wrote_headers
@@ -121,6 +119,9 @@
soup_message_body_complete
soup_message_body_flatten
soup_message_body_get_chunk
+<SUBSECTION Standard>
+SOUP_TYPE_BUFFER
+soup_buffer_get_type
</SECTION>
<SECTION>
@@ -155,9 +156,13 @@
SoupServerCallback
soup_server_add_handler
soup_server_remove_handler
+<SUBSECTION>
SoupClientContext
+soup_client_context_get_socket
soup_client_context_get_address
soup_client_context_get_host
+soup_client_context_get_auth_domain
+soup_client_context_get_auth_user
<SUBSECTION>
soup_server_add_auth_domain
soup_server_remove_auth_domain
@@ -170,6 +175,7 @@
SOUP_SERVER_SSL_CERT_FILE
SOUP_SERVER_SSL_KEY_FILE
SOUP_SERVER_ASYNC_CONTEXT
+SOUP_SERVER_RAW_PATHS
<SUBSECTION Standard>
SOUP_SERVER
SOUP_IS_SERVER
@@ -179,6 +185,8 @@
SOUP_IS_SERVER_CLASS
SOUP_SERVER_GET_CLASS
SoupServerClass
+SOUP_TYPE_CLIENT_CONTEXT
+soup_client_context_get_type
</SECTION>
<SECTION>
@@ -188,6 +196,7 @@
<SUBSECTION>
soup_auth_domain_add_path
soup_auth_domain_remove_path
+SoupAuthDomainFilter
soup_auth_domain_set_filter
soup_auth_domain_get_realm
<SUBSECTION>
@@ -286,6 +295,8 @@
SOUP_IS_ADDRESS_CLASS
SOUP_ADDRESS_GET_CLASS
SoupAddressClass
+<SUBSECTION Private>
+AF_INET6
</SECTION>
<SECTION>
@@ -300,6 +311,9 @@
soup_session_cancel_message
soup_session_abort
<SUBSECTION>
+soup_session_pause_message
+soup_session_unpause_message
+<SUBSECTION>
soup_session_get_async_context
<SUBSECTION>
SOUP_SESSION_PROXY_URI
@@ -404,6 +418,7 @@
<SUBSECTION>
soup_socket_start_ssl
soup_socket_start_proxy_ssl
+soup_socket_is_ssl
<SUBSECTION>
soup_socket_disconnect
soup_socket_is_connected
@@ -467,6 +482,7 @@
soup_date_new
soup_date_new_from_string
soup_date_new_from_time_t
+soup_date_new_from_now
soup_date_to_string
soup_date_free
<SUBSECTION>
@@ -496,7 +512,8 @@
<SUBSECTION Private>
soup_date_copy
soup_signal_connect_once
-soup_xml_real_node
+SOUP_TYPE_DATE
+soup_date_get_type
</SECTION>
<SECTION>
@@ -506,6 +523,7 @@
soup_xmlrpc_build_method_call
soup_xmlrpc_request_new
soup_xmlrpc_parse_method_response
+soup_xmlrpc_extract_method_response
<SUBSECTION>
soup_xmlrpc_parse_method_call
soup_xmlrpc_extract_method_call
Modified: branches/libsoup-2.4/docs/reference/server-howto.xml
==============================================================================
--- branches/libsoup-2.4/docs/reference/server-howto.xml (original)
+++ branches/libsoup-2.4/docs/reference/server-howto.xml Mon Jan 7 14:51:31 2008
@@ -21,17 +21,6 @@
linkend="SoupServer"><type>SoupServer</type></link>.
</para>
-<warning>
- <para>
- Note that <type>SoupServer</type> isn't as polished as
- <type>SoupSession</type>, and thus not as stable, and the APIs
- will likely change in incompatible (but not
- difficult-to-port-to) ways in the future to make things nicer.
- We apologize in advance for the inconvenience.
- </para>
-</warning>
-
-
<para>
You create the server with <link
linkend="soup-server-new"><function>soup_server_new</function></link>,
@@ -83,6 +72,16 @@
other than the main thread.
</para></listitem>
</varlistentry>
+ <varlistentry>
+ <term><link linkend="SOUP-SERVER-RAW-PATHS:CAPS"><literal>SOUP_SERVER_RAW_PATHS</literal></link></term>
+ <listitem><para>
+ Set this to <literal>TRUE</literal> if you don't want
+ <application>libsoup</application> to decode %-encoding
+ in the Request-URI. (Eg, because you need to treat
+ <literal>"/foo/bar"</literal> and
+ <literal>"/foo%2Fbar"</literal> as different paths.
+ </para></listitem>
+ </varlistentry>
</variablelist>
</refsect2>
@@ -100,8 +99,8 @@
</para>
<informalexample><programlisting>
-soup_server_add_handler (server, "/foo", NULL, server_callback,
- unregister_callback, data);
+ soup_server_add_handler (server, "/foo", server_callback,
+ data, destroy_notify);
</programlisting></informalexample>
<para>
@@ -131,18 +130,28 @@
<informalexample><programlisting>
static void
-server_callback (SoupServerContext *context, SoupMessage *msg, gpointer data)
+server_callback (SoupServer *server,
+ SoupMessage *msg,
+ const char *path,
+ GHashTable *query,
+ SoupClientContext *client,
+ gpointer user_data)
{
...
}
</programlisting></informalexample>
<para>
-<literal>msg</literal> is the request that has been received.
-<literal>data</literal> is the same data that was passed to <link
+<literal>msg</literal> is the request that has been received and
+<literal>user_data</literal> is the data that was passed to <link
linkend="soup-server-add-handler"><function>soup_server_add_handler</function></link>.
-The <link>context</link> argument contains some additional information
-related to the request.
+<literal>path</literal> is the path (from <literal>msg</literal>'s
+URI), and <literal>query</literal> contains the result of parsing the
+URI query field. (It is <literal>NULL</literal> if there was no
+query.) <literal>client</literal> is a <link
+linkend="SoupClientContext"><type>SoupClientContext</type></link>,
+which contains additional information about the client (including its
+IP address, and whether or not it used HTTP authentication).
</para>
<para>
@@ -151,10 +160,10 @@
callback, and that it can therefore begin sending the response. If you
are not ready to send a response immediately (eg, you have to contact
another server, or wait for data from a database), you must call <link
-linkend="soup-message-io-pause"><function>soup_message_io_pause</function></link>
+linkend="soup-server-pause-message"><function>soup_server_pause_message</function></link>
on the message before returning from the callback. This will delay
sending a response until you call <link
-linkend="soup-message-io-unpause"><function>soup_message_io_unpause</function></link>.
+linkend="soup-server-unpause-message"><function>soup_server_unpause_message</function></link>.
(You must also connect to the <link
linkend="SoupMessage-finished">finished</link> signal on the message
in this case, so that you can break off processing if the client
@@ -166,10 +175,8 @@
linkend="soup-message-set-status"><function>soup_message_set_status</function></link>
or <link
linkend="soup-message-set-status-full"><function>soup_message_set_status_full</function></link>.
-If the response requires a body, the callback must call <link
-linkend="soup-server-message-set-encoding"><function>soup_server_message_set_encoding</function></link>
-to indicate whether it will provide the response all at once with
-<literal>Content-Length</literal> encoding, or in pieces with
+If the response requires a body, you must decide whether to use
+<literal>Content-Length</literal> encoding (the default), or
<literal>chunked</literal> encoding.
</para>
@@ -184,29 +191,34 @@
<informalexample><programlisting>
static void
-server_callback (SoupServerContext *context, SoupMessage *msg, gpointer data)
+server_callback (SoupServer *server,
+ SoupMessage *msg,
+ const char *path,
+ GHashTable *query,
+ SoupClientContext *client,
+ gpointer user_data)
{
- MyServerData *server_data = data;
- SoupUri *uri = soup_message_get_uri (msg);
+ MyServerData *server_data = user_data;
const char *mime_type;
GByteArray *body;
- if (context->method_id != SOUP_METHOD_ID_GET) {
+ if (msg->method != SOUP_METHOD_GET) {
soup_message_set_status (msg, SOUP_STATUS_NOT_IMPLEMENTED);
return;
}
- body = g_hash_table_lookup (server_data->bodies, uri->path);
- mime_type = g_hash_table_lookup (server_data->mime_types, uri->path);
+ /* This is somewhat silly. Presumably your server will do
+ * something more interesting.
+ */
+ body = g_hash_table_lookup (server_data->bodies, path);
+ mime_type = g_hash_table_lookup (server_data->mime_types, path);
if (!body || !mime_type) {
soup_message_set_status (msg, SOUP_STATUS_NOT_FOUND);
return;
}
soup_message_set_status (msg, SOUP_STATUS_OK);
- soup_server_message_set_encoding (SOUP_SERVER_MESSAGE (msg),
- SOUP_TRANSFER_CONTENT_LENGTH);
- soup_message_set_response (msg, mime_type, SOUP_BUFFER_USER_OWNED,
+ soup_message_set_response (msg, mime_type, SOUP_MEMORY_COPY,
body->data, body->len);
}
</programlisting></informalexample>
@@ -219,16 +231,22 @@
<para>
If you want to supply the response body in chunks as it becomes
available, use <literal>chunked</literal> encoding instead. In this
-case, call <link
-linkend="soup-message-add-chunk"><function>soup_message_add_chunk</function></link> with
-each chunk of the response body as it becomes available, and call
-<link
-linkend="soup-message-add-final-chunk"><function>soup_message_add_final_chunk</function></link>
+case, first call <link
+linkend="soup-message-headers-set-encoding"><function>soup_message_headers_set_encoding</function></link> <literal>(msg->response_headers, <link
+linkend="SoupEncoding">SOUP_ENCODING_CHUNKED</link>)</literal>
+to tell <application>libsoup</application> that you'll be using
+chunked encoding. Then call <link
+linkend="soup-message-body-append"><function>soup_message_body_append</function></link>
+(or <link
+linkend="soup-message-body-append-buffer"><function>soup_message_body_append_buffer</function></link>)
+on <literal>msg->response_body</literal> with each chunk of the
+response body as it becomes available, and call <link
+linkend="soup-message-body-complete"><function>soup_message_body_complete</function></link>
when the response is complete. After each of these calls, you must
also call <link
-linkend="soup-message-io-unpause"><function>soup_message_io_unpause</function></link> to
-cause the chunk to be sent. (You do not normally need to call
-<link linkend="soup-message-io-pause"><function>soup_message_io_pause</function></link>,
+linkend="soup-server-unpause-message"><function>soup_server_unpause_message</function></link>
+to cause the chunk to be sent. (You do not normally need to call <link
+linkend="soup-server-pause-message"><function>soup_server_pause_message</function></link>,
because I/O is automatically paused when doing a
<literal>chunked</literal> transfer if no chunks are available.)
</para>
@@ -239,7 +257,9 @@
so that you will be notified if the client disconnects between two
chunks; <type>SoupServer</type> will unref the message if that
happens, so you must stop adding new chunks to the response at that
-point.
+point. (An alternate possibility is to write each new chunk only when
+the <link linkend="SoupMessage-wrote-chunk">wrote_chunk</link> signal
+is emitted indicating that the previous one was written successfully.)
</para>
<para>
@@ -257,59 +277,92 @@
<para>
To have <link linkend="SoupServer"><type>SoupServer</type></link>
-handle HTTP authentication for you, pass a <link
-linkend="SoupAuthContext"><type>SoupAuthContext</type></link> to <link
-linkend="soup-server-add-handler"><function>soup_server_add_handler</function></link>:
+handle HTTP authentication for you, create a <link
+linkend="SoupAuthDomainBasic"><type>SoupAuthDomainBasic</type></link>
+or <link
+linkend="SoupAuthDomainDigest"><type>SoupAuthDomainDigest</type></link>,
+and pass it to <link
+linkend="soup-server-add-auth-domain"><function>soup_server_add_auth_domain</function></link>:
</para>
<informalexample><programlisting>
-SoupServerAuthContext auth_ctx;
+ SoupAuthDomain *domain;
-auth_ctx.types = SOUP_AUTH_TYPE_BASIC;
-auth_ctx.callback = auth_callback;
-auth_ctx.user_data = data;
-auth_ctx.basic_info.realm = "My Realm";
-
-soup_server_add_handler (server, "/bar", &auth_ctx, server_callback,
- unregister_callback, data);
+ domain = soup_auth_domain_basic_new (
+ SOUP_AUTH_DOMAIN_REALM, "My Realm",
+ SOUP_AUTH_DOMAIN_BASIC_AUTH_CALLBACK, auth_callback,
+ SOUP_AUTH_DOMAIN_BASIC_AUTH_DATA, auth_data,
+ SOUP_AUTH_DOMAIN_ADD_PATH, "/foo",
+ SOUP_AUTH_DOMAIN_ADD_PATH, "/bar/private",
+ NULL);
+ soup_server_add_auth_domain (server, domain);
+ g_object_unref (domain);
</programlisting></informalexample>
<para>
-Then, every request that matches that handler will be passed to the
-<literal>auth_callback</literal> first before being passed to the
-<literal>server_callback</literal>:
+Then, every request under one of the auth domain's paths will be
+passed to the <literal>auth_callback</literal> first before being
+passed to the <literal>server_callback</literal>:
</para>
<informalexample><programlisting>
static gboolean
-auth_callback (SoupServerAuthContext *auth_ctx, SoupServerAuth *auth,
- SoupMessage *msg, gpointer user_data)
+auth_callback (SoupAuthDomain *domain, SoupMessage *msg,
+ const char *username, const char *password,
+ gpointer user_data)
{
MyServerData *server_data = user_data;
- const char *username, *password;
-
- if (!auth)
- return FALSE;
+ MyUserData *user;
- username = soup_server_auth_get_user (auth);
- password = g_hash_table_lookup (server_data->passwords, username);
- if (!password)
+ user = my_server_data_lookup_user (server_data, username);
+ if (!user)
return FALSE;
- return soup_server_auth_check_passwd (auth, password);
+ /* FIXME: Don't do this. Keeping a cleartext password database
+ * is bad.
+ */
+ return strcmp (password, user->password) == 0;
}
</programlisting></informalexample>
<para>
-The <literal>auth</literal> parameter indicates the authentication
-information passed by the client. If no
-<literal>WWW-Authenticate</literal> header was present, this will be
-<literal>NULL</literal>, so we return <literal>FALSE</literal> from
-the callback to indicate that the server should return a <literal>401
-Unauthorized</literal> response. If it is non-<literal>NULL</literal>,
-we extract the username from it, and compare it against our stored
-password. Assuming it matches, we return <literal>TRUE</literal>, and
-the server callback is then invoked normally.
+The <link
+linkend="SoupAuthDomainBasicAuthCallback"><type>SoupAuthDomainBasicAuthCallback</type></link>
+is given the username and password from the
+<literal>Authorization</literal> header and must determine, in some
+server-specific manner, whether or not to accept them. (In this
+example we compare the password against a cleartext password database,
+but it would be better to store the password somehow encoded, as in
+the UNIX password database. Alternatively, you may need to delegate
+the password check to PAM or some other service.)
+</para>
+
+<para>
+If you are using Digest authentication, note that <link
+linkend="SoupAuthDomainDigestAuthCallback"><type>SoupAuthDomainDigestAuthCallback</type></link>
+works completely differently (since the server doesn't receive the
+cleartext password from the client in that case, so there's no way to
+compare it directly). See the documentation for <link
+linkend="SoupAuthDomainDigest"><type>SoupAuthDomainDigest</type></link>
+for more details.
+</para>
+
+<para>
+You can have multiple <type>SoupAuthDomain</type>s attached to a
+<literal>SoupServer</literal>, either in separate parts of the path
+hierarchy, or overlapping. (Eg, you might want to accept either Basic
+or Digest authentication for a given path.) When more than one auth
+domain covers a given path, the request will be accepted if the user
+authenticates successfully against <emphasis>any</emphasis> of the
+domains.
+</para>
+
+<para>
+If you want to require authentication for some requests under a
+certain path, but not all of them (eg, you want to authenticate
+<literal>PUT</literal>s, but not <literal>GET</literal>s), use a
+<link
+linkend="SoupAuthDomainFilter"><type>SoupAuthDomainFilter</type></link>.
</para>
</refsect2>
Modified: branches/libsoup-2.4/libsoup/soup-address.c
==============================================================================
--- branches/libsoup-2.4/libsoup/soup-address.c (original)
+++ branches/libsoup-2.4/libsoup/soup-address.c Mon Jan 7 14:51:31 2008
@@ -30,6 +30,18 @@
#define INADDR_NONE -1
#endif
+/**
+ * SECTION:soup-address
+ * @short_description: DNS support
+ *
+ * #SoupAddress represents the address of a TCP connection endpoint;
+ * both the IP address and the port. (It is somewhat like an
+ * object-oriented version of struct sockaddr.)
+ *
+ * If libsoup was built with IPv6 support, #SoupAddress will allow
+ * both IPv4 and IPv6 addresses.
+ **/
+
typedef struct {
struct sockaddr *sockaddr;
@@ -220,6 +232,13 @@
**/
/**
+ * SOUP_ADDRESS_ANY_PORT:
+ *
+ * This can be passed to any #SoupAddress method that expects a port,
+ * to indicate that you don't care what port is used.
+ **/
+
+/**
* soup_address_new_any:
* @family: the address family
* @port: the port number (usually %SOUP_ADDRESS_ANY_PORT)
@@ -385,6 +404,16 @@
}
/**
+ * SoupAddressCallback:
+ * @addr: the #SoupAddress that was resolved
+ * @status: %SOUP_STATUS_OK or %SOUP_STATUS_CANT_RESOLVE
+ * @data: the user data that was passed to
+ * soup_address_resolve_async()
+ *
+ * The callback function passed to soup_address_resolve_async().
+ **/
+
+/**
* soup_address_resolve_async:
* @addr: a #SoupAddress
* @async_context: the #GMainContext to call @callback from
Modified: branches/libsoup-2.4/libsoup/soup-address.h
==============================================================================
--- branches/libsoup-2.4/libsoup/soup-address.h (original)
+++ branches/libsoup-2.4/libsoup/soup-address.h Mon Jan 7 14:51:31 2008
@@ -44,23 +44,8 @@
#undef AF_INET6
#endif
-/**
- * SOUP_ADDRESS_ANY_PORT:
- *
- * This can be passed to any #SoupAddress method that expects a port,
- * to indicate that you don't care what port is used.
- **/
#define SOUP_ADDRESS_ANY_PORT 0
-/**
- * SoupAddressCallback:
- * @addr: the #SoupAddress that was resolved
- * @status: %SOUP_STATUS_OK or %SOUP_STATUS_CANT_RESOLVE
- * @data: the user data that was passed to
- * soup_address_resolve_async()
- *
- * The callback function passed to soup_address_resolve_async().
- **/
typedef void (*SoupAddressCallback) (SoupAddress *addr,
guint status,
gpointer data);
Modified: branches/libsoup-2.4/libsoup/soup-auth-domain-basic.c
==============================================================================
--- branches/libsoup-2.4/libsoup/soup-auth-domain-basic.c (original)
+++ branches/libsoup-2.4/libsoup/soup-auth-domain-basic.c Mon Jan 7 14:51:31 2008
@@ -15,6 +15,14 @@
#include "soup-marshal.h"
#include "soup-message.h"
+/**
+ * SECTION:soup-auth-domain-basic
+ * @short_description: Server-side "Basic" authentication
+ *
+ * #SoupAuthDomainBasic handles the server side of HTTP "Basic" (ie,
+ * cleartext password) authentication.
+ **/
+
enum {
PROP_0,
Modified: branches/libsoup-2.4/libsoup/soup-auth-domain-digest.c
==============================================================================
--- branches/libsoup-2.4/libsoup/soup-auth-domain-digest.c (original)
+++ branches/libsoup-2.4/libsoup/soup-auth-domain-digest.c Mon Jan 7 14:51:31 2008
@@ -19,6 +19,14 @@
#include "soup-message.h"
#include "soup-uri.h"
+/**
+ * SECTION:soup-auth-domain-digest
+ * @short_description: Server-side "Digest" authentication
+ *
+ * #SoupAuthDomainBasic handles the server side of HTTP "Digest"
+ * authentication.
+ **/
+
enum {
PROP_0,
Modified: branches/libsoup-2.4/libsoup/soup-auth-domain.c
==============================================================================
--- branches/libsoup-2.4/libsoup/soup-auth-domain.c (original)
+++ branches/libsoup-2.4/libsoup/soup-auth-domain.c Mon Jan 7 14:51:31 2008
@@ -16,6 +16,28 @@
#include "soup-path-map.h"
#include "soup-uri.h"
+/**
+ * SECTION:soup-auth-domain
+ * @short_description: Server-side authentication
+ * @see_also: #SoupServer
+ *
+ * A #SoupAuthDomain manages authentication for all or part of a
+ * #SoupServer. To make a server require authentication, first create
+ * an appropriate subclass of #SoupAuthDomain, and then add it to the
+ * server with soup_server_add_auth_domain().
+ *
+ * In order for an auth domain to have any effect, you must add one or
+ * more paths to it (via soup_auth_domain_add_path() or the
+ * %SOUP_AUTH_DOMAIN_ADD_PATH property). To require authentication for
+ * all requests, add the path "/".
+ *
+ * If you need greater control over which requests should and
+ * shouldn't be authenticated, add paths covering everything you
+ * <emphasis>might</emphasis> want authenticated, and then use a
+ * filter (soup_auth_domain_set_filter()) to bypass authentication for
+ * those requests that don't need it.
+ **/
+
enum {
PROP_0,
Modified: branches/libsoup-2.4/libsoup/soup-auth.c
==============================================================================
--- branches/libsoup-2.4/libsoup/soup-auth.c (original)
+++ branches/libsoup-2.4/libsoup/soup-auth.c Mon Jan 7 14:51:31 2008
@@ -17,6 +17,25 @@
#include "soup-headers.h"
#include "soup-uri.h"
+/**
+ * SECTION:soup-auth
+ * @short_description: HTTP client-side authentication support
+ * @see_also: #SoupSession
+ *
+ * #SoupAuth objects store the authentication data associated with a
+ * given bit of web space. They are created automatically by
+ * #SoupSession.
+ **/
+
+/**
+ * SoupAuth:
+ *
+ * The abstract base class for handling authentication. Specific HTTP
+ * Authentication mechanisms are implemented by its subclasses, but
+ * applications never need to be aware of the specific subclasses
+ * being used.
+ **/
+
typedef struct {
gboolean proxy;
char *host;
Modified: branches/libsoup-2.4/libsoup/soup-connection.h
==============================================================================
--- branches/libsoup-2.4/libsoup/soup-connection.h (original)
+++ branches/libsoup-2.4/libsoup/soup-connection.h Mon Jan 7 14:51:31 2008
@@ -43,14 +43,6 @@
GType soup_connection_get_type (void);
-/**
- * SoupConnectionCallback:
- * @conn: the #SoupConnection
- * @status: an HTTP status code indicating success or failure
- * @data: the data passed to soup_connection_connect_async()
- *
- * The callback function passed to soup_connection_connect_async().
- **/
typedef void (*SoupConnectionCallback) (SoupConnection *conn,
guint status,
gpointer data);
Modified: branches/libsoup-2.4/libsoup/soup-date.c
==============================================================================
--- branches/libsoup-2.4/libsoup/soup-date.c (original)
+++ branches/libsoup-2.4/libsoup/soup-date.c Mon Jan 7 14:51:31 2008
@@ -16,6 +16,26 @@
#include "soup-date.h"
+/**
+ * SoupDate:
+ * @year: the year, 1 to 9999
+ * @month: the month, 1 to 12
+ * @day: day of the month, 1 to 31
+ * @hour: hour of the day, 0 to 23
+ * @minute: minute, 0 to 59
+ * @second: second, 0 to 59 (or up to 61 in the case of leap seconds)
+ * @utc: %TRUE if the date is in UTC
+ * @offset: offset from UTC
+
+ * A date and time. The date is assumed to be in the (proleptic)
+ * Gregorian calendar. The time is in UTC if @utc is %TRUE. Otherwise,
+ * the time is a local time, and @offset gives the offset from UTC in
+ * minutes (such that adding @offset to the time would give the
+ * correct UTC time). If @utc is %FALSE and @offset is 0, then the
+ * %SoupDate represents a "floating" time with no associated timezone
+ * information.
+ **/
+
/* Do not internationalize */
static const char *months[] = {
"Jan", "Feb", "Mar", "Apr", "May", "Jun",
@@ -312,7 +332,33 @@
}
/**
- * soup_date_from_now:
+ * SoupDateFormat:
+ * @SOUP_DATE_HTTP: RFC 1123 format, used by the HTTP "Date" header. Eg
+ * "Sun, 06 Nov 1994 08:49:37 GMT"
+ * @SOUP_DATE_COOKIE: The format for the "Expires" timestamp in the
+ * Netscape cookie specification. Eg, "Sun, 06-Nov-1994 08:49:37 GMT".
+ * @SOUP_DATE_RFC2822: RFC 2822 format, eg "Sun, 6 Nov 1994 09:49:37 -0100"
+ * @SOUP_DATE_ISO8601_COMPACT: ISO 8601 date/time with no optional
+ * punctuation. Eg, "19941106T094937-0100".
+ * @SOUP_DATE_ISO8601_FULL: ISO 8601 date/time with all optional
+ * punctuation. Eg, "1994-11-06T09:49:37-01:00".
+ * @SOUP_DATE_ISO8601_XMLRPC: ISO 8601 date/time as used by XML-RPC.
+ * Eg, "19941106T09:49:37".
+ * @SOUP_DATE_ISO8601: An alias for @SOUP_DATE_ISO8601_FULL.
+ *
+ * Date formats that soup_date_to_string() can use.
+ *
+ * @SOUP_DATE_HTTP and @SOUP_DATE_COOKIE always coerce the time to
+ * UTC. @SOUP_DATE_ISO8601_XMLRPC uses the time as given, ignoring the
+ * offset completely. @SOUP_DATE_RFC2822 and the other ISO 8601
+ * variants use the local time, appending the offset information if
+ * available.
+ *
+ * This enum may be extended with more values in future releases.
+ **/
+
+/**
+ * soup_date_new_from_string:
* @date_string: the date in some plausible format
*
* Parses @date_string and tries to extract a date from it. This
Modified: branches/libsoup-2.4/libsoup/soup-date.h
==============================================================================
--- branches/libsoup-2.4/libsoup/soup-date.h (original)
+++ branches/libsoup-2.4/libsoup/soup-date.h Mon Jan 7 14:51:31 2008
@@ -12,25 +12,6 @@
G_BEGIN_DECLS
-/**
- * SoupDate:
- * @year: the year, 1 to 9999
- * @month: the month, 1 to 12
- * @day: day of the month, 1 to 31
- * @hour: hour of the day, 0 to 23
- * @minute: minute, 0 to 59
- * @second: second, 0 to 59 (or up to 61 in the case of leap seconds)
- * @utc: %TRUE if the date is in UTC
- * @offset: offset from UTC
-
- * A date and time. The date is assumed to be in the (proleptic)
- * Gregorian calendar. The time is in UTC if @utc is %TRUE. Otherwise,
- * the time is a local time, and @offset gives the offset from UTC in
- * minutes (such that adding @offset to the time would give the
- * correct UTC time). If @utc is %FALSE and @offset is 0, then the
- * %SoupDate represents a "floating" time with no associated timezone
- * information.
- **/
typedef struct {
int year;
int month;
@@ -44,31 +25,6 @@
int offset;
} SoupDate;
-/**
- * SoupDateFormat:
- * @SOUP_DATE_HTTP: RFC 1123 format, used by the HTTP "Date" header. Eg
- * "Sun, 06 Nov 1994 08:49:37 GMT"
- * @SOUP_DATE_COOKIE: The format for the "Expires" timestamp in the
- * Netscape cookie specification. Eg, "Sun, 06-Nov-1994 08:49:37 GMT".
- * @SOUP_DATE_RFC2822: RFC 2822 format, eg "Sun, 6 Nov 1994 09:49:37 -0100"
- * @SOUP_DATE_ISO8601_COMPACT: ISO 8601 date/time with no optional
- * punctuation. Eg, "19941106T094937-0100".
- * @SOUP_DATE_ISO8601_FULL: ISO 8601 date/time with all optional
- * punctuation. Eg, "1994-11-06T09:49:37-01:00".
- * @SOUP_DATE_ISO8601_XMLRPC: ISO 8601 date/time as used by XML-RPC.
- * Eg, "19941106T09:49:37".
- * @SOUP_DATE_ISO8601: An alias for @SOUP_DATE_ISO8601_FULL.
- *
- * Date formats that soup_date_to_string() can use.
- *
- * @SOUP_DATE_HTTP and @SOUP_DATE_COOKIE always coerce the time to
- * UTC. @SOUP_DATE_ISO8601_XMLRPC uses the time as given, ignoring the
- * offset completely. @SOUP_DATE_RFC2822 and the other ISO 8601
- * variants use the local time, appending the offset information if
- * available.
- *
- * This enum may be extended with more values in future releases.
- **/
typedef enum {
SOUP_DATE_HTTP = 1,
SOUP_DATE_COOKIE,
Modified: branches/libsoup-2.4/libsoup/soup-dns.h
==============================================================================
--- branches/libsoup-2.4/libsoup/soup-dns.h (original)
+++ branches/libsoup-2.4/libsoup/soup-dns.h Mon Jan 7 14:51:31 2008
@@ -14,25 +14,12 @@
void soup_dns_init (void);
char *soup_dns_ntop (struct sockaddr *sa);
-/**
- * SoupDNSLookup:
- *
- * An opaque type that represents a DNS lookup operation.
- **/
typedef struct SoupDNSLookup SoupDNSLookup;
SoupDNSLookup *soup_dns_lookup_name (const char *name);
SoupDNSLookup *soup_dns_lookup_address (struct sockaddr *sockaddr);
void soup_dns_lookup_free (SoupDNSLookup *lookup);
-/**
- * SoupDNSCallback:
- * @lookup: the completed lookup
- * @success: %TRUE if @lookup completed successfully, %FALSE if it failed
- * @user_data: the data passed to soup_dns_lookup_resolve_async()
- *
- * The callback function passed to soup_dns_lookup_resolve_async().
- **/
typedef void (*SoupDNSCallback) (SoupDNSLookup *lookup, gboolean success, gpointer user_data);
gboolean soup_dns_lookup_resolve (SoupDNSLookup *lookup);
Modified: branches/libsoup-2.4/libsoup/soup-gnutls.c
==============================================================================
--- branches/libsoup-2.4/libsoup/soup-gnutls.c (original)
+++ branches/libsoup-2.4/libsoup/soup-gnutls.c Mon Jan 7 14:51:31 2008
@@ -26,6 +26,11 @@
#include "soup-ssl.h"
#include "soup-misc.h"
+/**
+ * soup_ssl_supported:
+ *
+ * Can be used to test if libsoup was compiled with ssl support.
+ **/
gboolean soup_ssl_supported = TRUE;
#define DH_BITS 1024
Modified: branches/libsoup-2.4/libsoup/soup-message-body.c
==============================================================================
--- branches/libsoup-2.4/libsoup/soup-message-body.c (original)
+++ branches/libsoup-2.4/libsoup/soup-message-body.c Mon Jan 7 14:51:31 2008
@@ -9,6 +9,54 @@
#include "soup-message-body.h"
+/**
+ * SECTION:soup-message-body
+ * @short_description: HTTP message body
+ * @see_also: #SoupMessage
+ *
+ * #SoupMessageBody represents the request or response body of a
+ * #SoupMessage.
+ *
+ * In addition to #SoupMessageBody, libsoup also defines a "smaller"
+ * data buffer type, #SoupBuffer, which is primarily used as a
+ * component of #SoupMessageBody. In particular, when using chunked
+ * encoding to transmit or receive a message, each chunk is
+ * represented as a #SoupBuffer.
+ **/
+
+/**
+ * SoupMemoryUse:
+ * @SOUP_MEMORY_STATIC: The memory is statically allocated and
+ * constant; libsoup can use the passed-in buffer directly and not
+ * need to worry about it being modified or freed.
+ * @SOUP_MEMORY_TAKE: The caller has allocated the memory for the
+ * #SoupBuffer's use; libsoup will assume ownership of it and free it
+ * (with g_free()) when it is done with it.
+ * @SOUP_MEMORY_COPY: The passed-in data belongs to the caller; the
+ * #SoupBuffer will copy it into new memory, leaving the caller free
+ * to reuse the original memory.
+ * @SOUP_MEMORY_TEMPORARY: The passed-in data belongs to the caller,
+ * but will remain valid for the lifetime of the #SoupBuffer. The
+ * difference between this and @SOUP_MEMORY_STATIC is that if you copy
+ * a @SOUP_MEMORY_TEMPORARY buffer, it will make a copy of the memory
+ * as well, rather than reusing the original memory.
+ *
+ * Describes how #SoupBuffer should use the data passed in by the
+ * caller.
+ **/
+
+/**
+ * SoupBuffer:
+ * @data: the data
+ * @length: length of @data
+ *
+ * A data buffer, generally used to represent a chunk of a
+ * #SoupMessageBody.
+ *
+ * @data is a #char because that's generally convenient; in some
+ * situations you may need to cast it to #guchar or another type.
+ **/
+
typedef struct {
SoupBuffer buffer;
SoupMemoryUse use;
@@ -146,6 +194,27 @@
return type;
}
+
+/**
+ * SoupMessageBody:
+ * @data: the data
+ * @length: length of @data
+ *
+ * A #SoupMessage request or response body.
+ *
+ * Note that while @length always reflects the full length of the
+ * message body, @data is normally %NULL, and will only be filled in
+ * after soup_message_body_flatten() is called. For client-side
+ * messages, this automatically happens for the response body after it
+ * has been fully read, unless you set the
+ * %SOUP_MESSAGE_OVERWRITE_CHUNKS flags. Likewise, for server-side
+ * messages, the request body is automatically filled in after being
+ * read.
+ *
+ * As an added bonus, when @data is filled in, it is always terminated
+ * with a '\0' byte (which is not reflected in @length).
+ **/
+
typedef struct {
SoupMessageBody body;
GSList *chunks, *last;
Modified: branches/libsoup-2.4/libsoup/soup-message-body.h
==============================================================================
--- branches/libsoup-2.4/libsoup/soup-message-body.h (original)
+++ branches/libsoup-2.4/libsoup/soup-message-body.h Mon Jan 7 14:51:31 2008
@@ -10,26 +10,6 @@
G_BEGIN_DECLS
-/**
- * SoupMemoryUse:
- * @SOUP_MEMORY_STATIC: The memory is statically allocated and
- * constant; libsoup can use the passed-in buffer directly and not
- * need to worry about it being modified or freed.
- * @SOUP_MEMORY_TAKE: The caller has allocated the memory for the
- * #SoupBuffer's use; libsoup will assume ownership of it and free it
- * (with g_free()) when it is done with it.
- * @SOUP_MEMORY_COPY: The passed-in data belongs to the caller; the
- * #SoupBuffer will copy it into new memory, leaving the caller free
- * to reuse the original memory.
- * @SOUP_MEMORY_TEMPORARY: The passed-in data belongs to the caller,
- * but will remain valid for the lifetime of the #SoupBuffer. The
- * difference between this and @SOUP_MEMORY_STATIC is that if you copy
- * a @SOUP_MEMORY_TEMPORARY buffer, it will make a copy of the memory
- * as well, rather than reusing the original memory.
- *
- * Describes how #SoupBuffer should use the data passed in by the
- * caller.
- **/
typedef enum {
SOUP_MEMORY_STATIC,
SOUP_MEMORY_TAKE,
@@ -37,17 +17,6 @@
SOUP_MEMORY_TEMPORARY,
} SoupMemoryUse;
-/**
- * SoupBuffer:
- * @data: the data
- * @length: length of @data
- *
- * A data buffer, generally used to represent a chunk of a
- * #SoupMessageBody.
- *
- * @data is a #char because that's generally convenient; in some
- * situations you may need to cast it to #guchar or another type.
- **/
typedef struct {
const char *data;
gsize length;
@@ -66,25 +35,6 @@
SoupBuffer *soup_buffer_copy (SoupBuffer *buffer);
void soup_buffer_free (SoupBuffer *buffer);
-/**
- * SoupMessageBody:
- * @data: the data
- * @length: length of @data
- *
- * A #SoupMessage request or response body.
- *
- * Note that while @length always reflects the full length of the
- * message body, @data is normally %NULL, and will only be filled in
- * after soup_message_body_flatten() is called. For client-side
- * messages, this automatically happens for the response body after it
- * has been fully read, unless you set the
- * %SOUP_MESSAGE_OVERWRITE_CHUNKS flags. Likewise, for server-side
- * messages, the request body is automatically filled in after being
- * read.
- *
- * As an added bonus, when @data is filled in, it is always terminated
- * with a '\0' byte (which is not reflected in @length).
- **/
typedef struct {
const char *data;
goffset length;
Modified: branches/libsoup-2.4/libsoup/soup-message-headers.c
==============================================================================
--- branches/libsoup-2.4/libsoup/soup-message-headers.c (original)
+++ branches/libsoup-2.4/libsoup/soup-message-headers.c Mon Jan 7 14:51:31 2008
@@ -10,6 +10,15 @@
#include "soup-message-headers.h"
#include "soup-misc.h"
+/**
+ * SECTION:soup-message-headers
+ * @short_description: HTTP message headers
+ * @see_also: #SoupMessage
+ *
+ * #SoupMessageHeaders represents the HTTP message headers associated
+ * with a request or response.
+ **/
+
typedef void (*SoupHeaderSetter) (SoupMessageHeaders *, const char *);
static const char *intern_header_name (const char *name, SoupHeaderSetter *setter);
Modified: branches/libsoup-2.4/libsoup/soup-message-headers.h
==============================================================================
--- branches/libsoup-2.4/libsoup/soup-message-headers.h (original)
+++ branches/libsoup-2.4/libsoup/soup-message-headers.h Mon Jan 7 14:51:31 2008
@@ -42,20 +42,6 @@
/* Specific headers */
-/**
- * SoupEncoding:
- * @SOUP_ENCODING_UNRECOGNIZED: unknown / error
- * @SOUP_ENCODING_NONE: no body is present (which is not the same as a
- * 0-length body, and only occurs in certain places)
- * @SOUP_ENCODING_CONTENT_LENGTH: Content-Length encoding
- * @SOUP_ENCODING_EOF: Response body ends when the connection is closed
- * @SOUP_ENCODING_CHUNKED: chunked encoding (currently only supported
- * for response)
- * @SOUP_ENCODING_BYTERANGES: multipart/byteranges (Reserved for future
- * use: NOT CURRENTLY IMPLEMENTED)
- *
- * How a message body is encoded for transport
- **/
typedef enum {
SOUP_ENCODING_UNRECOGNIZED,
SOUP_ENCODING_NONE,
Modified: branches/libsoup-2.4/libsoup/soup-message-queue.h
==============================================================================
--- branches/libsoup-2.4/libsoup/soup-message-queue.h (original)
+++ branches/libsoup-2.4/libsoup/soup-message-queue.h Mon Jan 7 14:51:31 2008
@@ -13,14 +13,7 @@
typedef struct SoupMessageQueue SoupMessageQueue;
-/**
- * SoupMessageQueueIter:
- *
- * An opaque data structure used to iterate the elements of a
- * #SoupMessageQueue.
- **/
typedef struct {
- /*< private >*/
GList *cur, *next;
} SoupMessageQueueIter;
Modified: branches/libsoup-2.4/libsoup/soup-message.c
==============================================================================
--- branches/libsoup-2.4/libsoup/soup-message.c (original)
+++ branches/libsoup-2.4/libsoup/soup-message.c Mon Jan 7 14:51:31 2008
@@ -16,6 +16,43 @@
#include "soup-misc.h"
#include "soup-uri.h"
+/**
+ * SECTION:soup-message
+ * @short_description: An HTTP request and response.
+ * @see_also: #SoupMessageHeaders, #SoupMessageBody
+ *
+ **/
+
+/**
+ * SoupMessage:
+ * @method: the HTTP method
+ * @status_code: the HTTP status code
+ * @reason_phrase: the status phrase associated with @status_code
+ * @request_body: the request body
+ * @request_headers: the request headers
+ * @response_body: the response body
+ * @response_headers: the response headers
+ *
+ * Represents an HTTP message being sent or received.
+ *
+ * As described in the #SoupMessageBody documentation, the
+ * @request_body and @response_body %data fields will not necessarily
+ * be filled in at all times. When they are filled in, they will be
+ * terminated with a '\0' byte (which is not included in the %length),
+ * so you can use them as ordinary C strings (assuming that you know
+ * that the body doesn't have any other '\0' bytes).
+ *
+ * For a client-side #SoupMessage, @request_body's %data is usually
+ * filled in right before libsoup writes the request to the network,
+ * but you should not count on this; use soup_message_body_flatten()
+ * if you want to ensure that %data is filled in. @response_body's
+ * %data will be filled in before #SoupMessage::finished is emitted,
+ * unless you set the %SOUP_MESSAGE_OVERWRITE_CHUNKS flag.
+ *
+ * For a server-side #SoupMessage, @request_body's %data will be
+ * filled in before #SoupMessage::got_body is emitted.
+ **/
+
G_DEFINE_TYPE (SoupMessage, soup_message, G_TYPE_OBJECT)
enum {
@@ -1021,6 +1058,20 @@
}
/**
+ * SoupMessageFlags:
+ * @SOUP_MESSAGE_NO_REDIRECT: The session should not follow redirect
+ * (3xx) responses received by this message.
+ * @SOUP_MESSAGE_OVERWRITE_CHUNKS: Each chunk of the response will be
+ * freed after its corresponding %got_chunk signal is emitted, meaning
+ * %response will still be empty after the message is complete. You
+ * can use this to save memory if you expect the response to be large
+ * and you are able to process it a chunk at a time.
+ *
+ * Various flags that can be set on a #SoupMessage to alter its
+ * behavior.
+ **/
+
+/**
* soup_message_set_flags:
* @msg: a #SoupMessage
* @flags: a set of #SoupMessageFlags values
@@ -1028,7 +1079,7 @@
* Sets the specified flags on @msg.
**/
void
-soup_message_set_flags (SoupMessage *msg, guint flags)
+soup_message_set_flags (SoupMessage *msg, SoupMessageFlags flags)
{
g_return_if_fail (SOUP_IS_MESSAGE (msg));
@@ -1043,7 +1094,7 @@
*
* Return value: the flags
**/
-guint
+SoupMessageFlags
soup_message_get_flags (SoupMessage *msg)
{
g_return_val_if_fail (SOUP_IS_MESSAGE (msg), 0);
@@ -1052,6 +1103,14 @@
}
/**
+ * SoupHTTPVersion:
+ * @SOUP_HTTP_1_0: HTTP 1.0 (RFC 1945)
+ * @SOUP_HTTP_1_1: HTTP 1.1 (RFC 2616)
+ *
+ * Indicates the HTTP protocol version being used.
+ **/
+
+/**
* soup_message_set_http_version:
* @msg: a #SoupMessage
* @version: the HTTP version
Modified: branches/libsoup-2.4/libsoup/soup-message.h
==============================================================================
--- branches/libsoup-2.4/libsoup/soup-message.h (original)
+++ branches/libsoup-2.4/libsoup/soup-message.h Mon Jan 7 14:51:31 2008
@@ -20,35 +20,6 @@
#define SOUP_IS_MESSAGE_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((obj), SOUP_TYPE_MESSAGE))
#define SOUP_MESSAGE_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), SOUP_TYPE_MESSAGE, SoupMessageClass))
-/**
- * SoupMessage:
- * @method: the HTTP method
- * @status_code: the HTTP status code
- * @reason_phrase: the status phrase associated with @status_code
- * @request_body: the request body
- * @request_headers: the request headers
- * @response_body: the response body
- * @response_headers: the response headers
- *
- * Represents an HTTP message being sent or received.
- *
- * As described in the #SoupMessageBody documentation, the
- * @request_body and @response_body %data fields will not necessarily
- * be filled in at all times. When they are filled in, they will be
- * terminated with a '\0' byte (which is not included in the %length),
- * so you can use them as ordinary C strings (assuming that you know
- * that the body doesn't have any other '\0' bytes).
- *
- * For a client-side #SoupMessage, @request_body's %data is usually
- * filled in right before libsoup writes the request to the network,
- * but you should not count on this; use soup_message_body_flatten()
- * if you want to ensure that %data is filled in. @response_body's
- * %data will be filled in before #SoupMessage::finished is emitted,
- * unless you set the %SOUP_MESSAGE_OVERWRITE_CHUNKS flag.
- *
- * For a server-side #SoupMessage, @request_body's %data will be
- * filled in before #SoupMessage::got_body is emitted.
- **/
struct SoupMessage {
GObject parent;
@@ -106,13 +77,6 @@
const char *resp_body,
gsize resp_length);
-/**
- * SoupHTTPVersion:
- * @SOUP_HTTP_1_0: HTTP 1.0 (RFC 1945)
- * @SOUP_HTTP_1_1: HTTP 1.1 (RFC 2616)
- *
- * Indicates the HTTP protocol version being used.
- **/
typedef enum {
SOUP_HTTP_1_0 = 0,
SOUP_HTTP_1_1 = 1
@@ -128,28 +92,15 @@
void soup_message_set_uri (SoupMessage *msg,
SoupURI *uri);
-/**
- * SoupMessageFlags:
- * @SOUP_MESSAGE_NO_REDIRECT: The session should not follow redirect
- * (3xx) responses received by this message.
- * @SOUP_MESSAGE_OVERWRITE_CHUNKS: Each chunk of the response will be
- * freed after its corresponding %got_chunk signal is emitted, meaning
- * %response will still be empty after the message is complete. You
- * can use this to save memory if you expect the response to be large
- * and you are able to process it a chunk at a time.
- *
- * Various flags that can be set on a #SoupMessage to alter its
- * behavior.
- **/
typedef enum {
SOUP_MESSAGE_NO_REDIRECT = (1 << 1),
SOUP_MESSAGE_OVERWRITE_CHUNKS = (1 << 3),
} SoupMessageFlags;
void soup_message_set_flags (SoupMessage *msg,
- guint flags);
+ SoupMessageFlags flags);
-guint soup_message_get_flags (SoupMessage *msg);
+SoupMessageFlags soup_message_get_flags (SoupMessage *msg);
/* Specialized signal handlers */
guint soup_message_add_header_handler (SoupMessage *msg,
Modified: branches/libsoup-2.4/libsoup/soup-method.h
==============================================================================
--- branches/libsoup-2.4/libsoup/soup-method.h (original)
+++ branches/libsoup-2.4/libsoup/soup-method.h Mon Jan 7 14:51:31 2008
@@ -8,6 +8,29 @@
G_BEGIN_DECLS
+/**
+ * SECTION:soup-method
+ * @short_description: HTTP method definitions
+ *
+ * soup-method.h contains a number of defines for standard HTTP and
+ * WebDAV headers. You do not need to use these defines; you can pass
+ * arbitrary strings to soup_message_new() if you prefer.
+ *
+ * The thing that these defines <emphasis>are</emphasis> useful for is
+ * performing quick comparisons against #SoupMessage's %method field;
+ * because that field always contains an interned string, and these
+ * macros return interned strings, you can compare %method directly
+ * against these macros rather than needing to use strcmp(). This is
+ * most useful in SoupServer handlers. Eg:
+ *
+ * <informalexample><programlisting>
+ * if (msg->method != SOUP_METHOD_GET && msg->method != SOUP_METHOD_HEAD) {
+ * soup_message_set_status (msg, SOUP_METHOD_NOT_IMPLEMENTED);
+ * return;
+ * }
+ * </programlisting></informalexample>
+ **/
+
#define SOUP_METHOD_POST (g_intern_static_string ("POST"))
#define SOUP_METHOD_GET (g_intern_static_string ("GET"))
#define SOUP_METHOD_HEAD (g_intern_static_string ("HEAD"))
Modified: branches/libsoup-2.4/libsoup/soup-misc.c
==============================================================================
--- branches/libsoup-2.4/libsoup/soup-misc.c (original)
+++ branches/libsoup-2.4/libsoup/soup-misc.c Mon Jan 7 14:51:31 2008
@@ -11,6 +11,12 @@
#include "soup-misc.h"
/**
+ * SECTION:soup-misc
+ * @short_description: Miscellaneous functions
+ *
+ **/
+
+/**
* soup_str_case_hash:
* @key: ASCII string to hash
*
Modified: branches/libsoup-2.4/libsoup/soup-misc.h
==============================================================================
--- branches/libsoup-2.4/libsoup/soup-misc.h (original)
+++ branches/libsoup-2.4/libsoup/soup-misc.h Mon Jan 7 14:51:31 2008
@@ -35,11 +35,6 @@
gboolean soup_str_case_equal (gconstpointer v1,
gconstpointer v2);
-/**
- * soup_ssl_supported:
- *
- * Can be used to test if libsoup was compiled with ssl support.
- **/
extern gboolean soup_ssl_supported;
#define SOUP_SSL_ERROR soup_ssl_error_quark()
Modified: branches/libsoup-2.4/libsoup/soup-server.c
==============================================================================
--- branches/libsoup-2.4/libsoup/soup-server.c (original)
+++ branches/libsoup-2.4/libsoup/soup-server.c Mon Jan 7 14:51:31 2008
@@ -26,6 +26,39 @@
#include "soup-socket.h"
#include "soup-ssl.h"
+/**
+ * SECTION:soup-server
+ * @short_description: HTTP server
+ * @see_also: #SoupAuthDomain
+ *
+ * #SoupServer implements a simple HTTP server.
+ *
+ * To begin, create a server using soup_server_new(). Add at least one
+ * handler by calling soup_server_add_handler(); the handler will be
+ * called to process any requests underneath the path passed to
+ * soup_server_add_handler(). (If you want all requests to go to the
+ * same handler, just pass "/" (or %NULL) for the path.) Any request
+ * that does not match any handler will automatically be returned to
+ * the client with a 404 (Not Found) status.
+ *
+ * To add authentication to some or all paths, create an appropriate
+ * #SoupAuthDomain (qv), and add it to the server via
+ * soup_server_add_auth_domain.
+ *
+ * Additional processing options are available via #SoupServer's
+ * signals; Connect to #SoupServer::request-started to be notified
+ * every time a new request is being processed. (This gives you a
+ * chance to connect to the #SoupMessage "got-" signals in case you
+ * want to do processing before the body has been fully read.)
+ *
+ * Once the server is set up, start it processing connections by
+ * calling soup_server_run_async() or soup_server_run(). #SoupServer
+ * runs via the glib main loop; if you need to have a server that runs
+ * in another thread (or merely isn't bound to the default main loop),
+ * create a #GMainContext for it to use, and set that via the
+ * #SOUP_SERVER_ASYNC_CONTEXT property.
+ **/
+
G_DEFINE_TYPE (SoupServer, soup_server, G_TYPE_OBJECT)
enum {
Modified: branches/libsoup-2.4/libsoup/soup-server.h
==============================================================================
--- branches/libsoup-2.4/libsoup/soup-server.h (original)
+++ branches/libsoup-2.4/libsoup/soup-server.h Mon Jan 7 14:51:31 2008
@@ -70,17 +70,17 @@
/* Handlers and auth */
-void soup_server_add_handler (SoupServer *serv,
+void soup_server_add_handler (SoupServer *server,
const char *path,
SoupServerCallback callback,
gpointer data,
GDestroyNotify destroy);
-void soup_server_remove_handler (SoupServer *serv,
+void soup_server_remove_handler (SoupServer *server,
const char *path);
-void soup_server_add_auth_domain (SoupServer *serv,
+void soup_server_add_auth_domain (SoupServer *server,
SoupAuthDomain *auth_domain);
-void soup_server_remove_auth_domain (SoupServer *serv,
+void soup_server_remove_auth_domain (SoupServer *server,
SoupAuthDomain *auth_domain);
/* I/O */
Modified: branches/libsoup-2.4/libsoup/soup-session-async.c
==============================================================================
--- branches/libsoup-2.4/libsoup/soup-session-async.c (original)
+++ branches/libsoup-2.4/libsoup/soup-session-async.c Mon Jan 7 14:51:31 2008
@@ -14,6 +14,15 @@
#include "soup-message-private.h"
#include "soup-misc.h"
+/**
+ * SECTION:soup-session-async
+ * @short_description: Soup session for asynchronous (main-loop-based) I/O.
+ *
+ * #SoupSessionAsync is an implementation of #SoupSession that uses
+ * non-blocking I/O via the glib main loop. It is intended for use in
+ * single-threaded programs.
+ **/
+
static gboolean run_queue (SoupSessionAsync *sa, gboolean try_pruning);
static void queue_message (SoupSession *session, SoupMessage *req,
Modified: branches/libsoup-2.4/libsoup/soup-session-sync.c
==============================================================================
--- branches/libsoup-2.4/libsoup/soup-session-sync.c (original)
+++ branches/libsoup-2.4/libsoup/soup-session-sync.c Mon Jan 7 14:51:31 2008
@@ -14,6 +14,14 @@
#include "soup-message-private.h"
#include "soup-misc.h"
+/**
+ * SECTION:soup-session-sync
+ * @short_description: Soup session for blocking I/O in multithreaded programs.
+ *
+ * #SoupSessionSync is an implementation of #SoupSession that uses
+ * synchronous I/O, intended for use in multi-threaded programs.
+ **/
+
typedef struct {
GMutex *lock;
GCond *cond;
Modified: branches/libsoup-2.4/libsoup/soup-session.c
==============================================================================
--- branches/libsoup-2.4/libsoup/soup-session.c (original)
+++ branches/libsoup-2.4/libsoup/soup-session.c Mon Jan 7 14:51:31 2008
@@ -27,6 +27,12 @@
#include "soup-ssl.h"
#include "soup-uri.h"
+/**
+ * SECTION:soup-session
+ * @short_description: Soup session state object
+ *
+ **/
+
typedef struct {
SoupURI *root_uri;
Modified: branches/libsoup-2.4/libsoup/soup-socket.c
==============================================================================
--- branches/libsoup-2.4/libsoup/soup-socket.c (original)
+++ branches/libsoup-2.4/libsoup/soup-socket.c Mon Jan 7 14:51:31 2008
@@ -24,6 +24,12 @@
#include <sys/time.h>
#include <sys/types.h>
+/**
+ * SECTION:soup-socket
+ * @short_description: A network socket
+ *
+ **/
+
G_DEFINE_TYPE (SoupSocket, soup_socket, G_TYPE_OBJECT)
enum {
@@ -515,6 +521,15 @@
}
/**
+ * SoupSocketCallback:
+ * @sock: the #SoupSocket
+ * @status: an HTTP status code indicating success or failure
+ * @user_data: the data passed to soup_socket_connect_async()
+ *
+ * The callback function passed to soup_socket_connect_async().
+ **/
+
+/**
* soup_socket_connect_async:
* @sock: a client #SoupSocket (which must not already be connected)
* @callback: callback to call after connecting
@@ -1009,6 +1024,16 @@
}
/**
+ * SoupSocketIOStatus:
+ * @SOUP_SOCKET_OK: Success
+ * @SOUP_SOCKET_WOULD_BLOCK: Cannot read/write any more at this time
+ * @SOUP_SOCKET_EOF: End of file
+ * @SOUP_SOCKET_ERROR: Other error
+ *
+ * Return value from the #SoupSocket IO methods.
+ **/
+
+/**
* soup_socket_read:
* @sock: the socket
* @buffer: buffer to read into
Modified: branches/libsoup-2.4/libsoup/soup-socket.h
==============================================================================
--- branches/libsoup-2.4/libsoup/soup-socket.h (original)
+++ branches/libsoup-2.4/libsoup/soup-socket.h Mon Jan 7 14:51:31 2008
@@ -41,14 +41,6 @@
#define SOUP_SOCKET_ASYNC_CONTEXT "async-context"
#define SOUP_SOCKET_TIMEOUT "timeout"
-/**
- * SoupSocketCallback:
- * @sock: the #SoupSocket
- * @status: an HTTP status code indicating success or failure
- * @user_data: the data passed to soup_socket_connect_async()
- *
- * The callback function passed to soup_socket_connect_async().
- **/
typedef void (*SoupSocketCallback) (SoupSocket *sock,
guint status,
gpointer user_data);
@@ -77,15 +69,6 @@
SoupAddress *soup_socket_get_remote_address (SoupSocket *sock);
-/**
- * SoupSocketIOStatus:
- * @SOUP_SOCKET_OK: Success
- * @SOUP_SOCKET_WOULD_BLOCK: Cannot read/write any more at this time
- * @SOUP_SOCKET_EOF: End of file
- * @SOUP_SOCKET_ERROR: Other error
- *
- * Return value from the #SoupSocket IO methods.
- **/
typedef enum {
SOUP_SOCKET_OK,
SOUP_SOCKET_WOULD_BLOCK,
Modified: branches/libsoup-2.4/libsoup/soup-status.c
==============================================================================
--- branches/libsoup-2.4/libsoup/soup-status.c (original)
+++ branches/libsoup-2.4/libsoup/soup-status.c Mon Jan 7 14:51:31 2008
@@ -9,6 +9,145 @@
#include "soup-status.h"
+/**
+ * SECTION:soup-status
+ * @short_description: HTTP (and libsoup) status codes
+ *
+ **/
+
+/**
+ * SOUP_STATUS_IS_TRANSPORT_ERROR:
+ * @status: a status code
+ *
+ * Tests if @status is a libsoup transport error.
+ *
+ * Return value: %TRUE or %FALSE
+ **/
+/**
+ * SOUP_STATUS_IS_INFORMATIONAL:
+ * @status: an HTTP status code
+ *
+ * Tests if @status is an Informational (1xx) response.
+ *
+ * Return value: %TRUE or %FALSE
+ **/
+/**
+ * SOUP_STATUS_IS_SUCCESSFUL:
+ * @status: an HTTP status code
+ *
+ * Tests if @status is a Successful (2xx) response.
+ *
+ * Return value: %TRUE or %FALSE
+ **/
+/**
+ * SOUP_STATUS_IS_REDIRECTION:
+ * @status: an HTTP status code
+ *
+ * Tests if @status is a Redirection (3xx) response.
+ *
+ * Return value: %TRUE or %FALSE
+ **/
+/**
+ * SOUP_STATUS_IS_CLIENT_ERROR:
+ * @status: an HTTP status code
+ *
+ * Tests if @status is a Client Error (4xx) response.
+ *
+ * Return value: %TRUE or %FALSE
+ **/
+/**
+ * SOUP_STATUS_IS_SERVER_ERROR:
+ * @status: an HTTP status code
+ *
+ * Tests if @status is a Server Error (5xx) response.
+ *
+ * Return value: %TRUE or %FALSE
+ **/
+
+/**
+ * SoupKnownStatusCode:
+ * @SOUP_STATUS_NONE: No status available. (Eg, the message has not
+ * been sent yet)
+ * @SOUP_STATUS_CANCELLED: Message was cancelled locally
+ * @SOUP_STATUS_CANT_RESOLVE: Unable to resolve destination host name
+ * @SOUP_STATUS_CANT_RESOLVE_PROXY: Unable to resolve proxy host name
+ * @SOUP_STATUS_CANT_CONNECT: Unable to connect to remote host
+ * @SOUP_STATUS_CANT_CONNECT_PROXY: Unable to connect to proxy
+ * @SOUP_STATUS_SSL_FAILED: SSL negotiation failed
+ * @SOUP_STATUS_IO_ERROR: A network error occurred, or the other end
+ * closed the connection unexpectedly
+ * @SOUP_STATUS_MALFORMED: Malformed data (usually a programmer error)
+ * @SOUP_STATUS_TRY_AGAIN: Try again. (Only returned in certain
+ * specifically documented cases)
+ * @SOUP_STATUS_CONTINUE: 100 Continue (HTTP)
+ * @SOUP_STATUS_SWITCHING_PROTOCOLS: 101 Switching Protocols (HTTP)
+ * @SOUP_STATUS_PROCESSING: 102 Processing (WebDAV)
+ * @SOUP_STATUS_OK: 200 Success (HTTP). Also used by many lower-level
+ * soup routines to indicate success.
+ * @SOUP_STATUS_CREATED: 201 Created (HTTP)
+ * @SOUP_STATUS_ACCEPTED: 202 Accepted (HTTP)
+ * @SOUP_STATUS_NON_AUTHORITATIVE: 203 Non-Authoritative Information
+ * (HTTP)
+ * @SOUP_STATUS_NO_CONTENT: 204 No Content (HTTP)
+ * @SOUP_STATUS_RESET_CONTENT: 205 Reset Content (HTTP)
+ * @SOUP_STATUS_PARTIAL_CONTENT: 206 Partial Content (HTTP)
+ * @SOUP_STATUS_MULTI_STATUS: 207 Multi-Status (WebDAV)
+ * @SOUP_STATUS_MULTIPLE_CHOICES: 300 Multiple Choices (HTTP)
+ * @SOUP_STATUS_MOVED_PERMANENTLY: 301 Moved Permanently (HTTP)
+ * @SOUP_STATUS_FOUND: 302 Found (HTTP)
+ * @SOUP_STATUS_MOVED_TEMPORARILY: 302 Moved Temporarily (old name,
+ * RFC 2068)
+ * @SOUP_STATUS_SEE_OTHER: 303 See Other (HTTP)
+ * @SOUP_STATUS_NOT_MODIFIED: 304 Not Modified (HTTP)
+ * @SOUP_STATUS_USE_PROXY: 305 Use Proxy (HTTP)
+ * @SOUP_STATUS_NOT_APPEARING_IN_THIS_PROTOCOL: 306 [Unused] (HTTP)
+ * @SOUP_STATUS_TEMPORARY_REDIRECT: 307 Temporary Redirect (HTTP)
+ * @SOUP_STATUS_BAD_REQUEST: 400 Bad Request (HTTP)
+ * @SOUP_STATUS_UNAUTHORIZED: 401 Unauthorized (HTTP)
+ * @SOUP_STATUS_PAYMENT_REQUIRED: 402 Payment Required (HTTP)
+ * @SOUP_STATUS_FORBIDDEN: 403 Forbidden (HTTP)
+ * @SOUP_STATUS_NOT_FOUND: 404 Not Found (HTTP)
+ * @SOUP_STATUS_METHOD_NOT_ALLOWED: 405 Method Not Allowed (HTTP)
+ * @SOUP_STATUS_NOT_ACCEPTABLE: 406 Not Acceptable (HTTP)
+ * @SOUP_STATUS_PROXY_AUTHENTICATION_REQUIRED: 407 Proxy Authentication
+ * Required (HTTP)
+ * @SOUP_STATUS_PROXY_UNAUTHORIZED: shorter alias for
+ * %SOUP_STATUS_PROXY_AUTHENTICATION_REQUIRED
+ * @SOUP_STATUS_REQUEST_TIMEOUT: 408 Request Timeout (HTTP)
+ * @SOUP_STATUS_CONFLICT: 409 Conflict (HTTP)
+ * @SOUP_STATUS_GONE: 410 Gone (HTTP)
+ * @SOUP_STATUS_LENGTH_REQUIRED: 411 Length Required (HTTP)
+ * @SOUP_STATUS_PRECONDITION_FAILED: 412 Precondition Failed (HTTP)
+ * @SOUP_STATUS_REQUEST_ENTITY_TOO_LARGE: 413 Request Entity Too Large
+ * (HTTP)
+ * @SOUP_STATUS_REQUEST_URI_TOO_LONG: 414 Request-URI Too Long (HTTP)
+ * @SOUP_STATUS_UNSUPPORTED_MEDIA_TYPE: 415 Unsupported Media Type
+ * (HTTP)
+ * @SOUP_STATUS_REQUESTED_RANGE_NOT_SATISFIABLE: 416 Requested Range
+ * Not Satisfiable (HTTP)
+ * @SOUP_STATUS_INVALID_RANGE: shorter alias for
+ * %SOUP_STATUS_REQUESTED_RANGE_NOT_SATISFIABLE
+ * @SOUP_STATUS_EXPECTATION_FAILED: 417 Expectation Failed (HTTP)
+ * @SOUP_STATUS_UNPROCESSABLE_ENTITY: 422 Unprocessable Entity
+ * (WebDAV)
+ * @SOUP_STATUS_LOCKED: 423 Locked (WebDAV)
+ * @SOUP_STATUS_FAILED_DEPENDENCY: 424 Failed Dependency (WebDAV)
+ * @SOUP_STATUS_INTERNAL_SERVER_ERROR: 500 Internal Server Error
+ * (HTTP)
+ * @SOUP_STATUS_NOT_IMPLEMENTED: 501 Not Implemented (HTTP)
+ * @SOUP_STATUS_BAD_GATEWAY: 502 Bad Gateway (HTTP)
+ * @SOUP_STATUS_SERVICE_UNAVAILABLE: 503 Service Unavailable (HTTP)
+ * @SOUP_STATUS_GATEWAY_TIMEOUT: 504 Gateway Timeout (HTTP)
+ * @SOUP_STATUS_HTTP_VERSION_NOT_SUPPORTED: 505 HTTP Version Not
+ * Supported (HTTP)
+ * @SOUP_STATUS_INSUFFICIENT_STORAGE: 507 Insufficient Storage
+ * (WebDAV)
+ * @SOUP_STATUS_NOT_EXTENDED: 510 Not Extended (RFC 2774)
+ *
+ * These represent the known HTTP status code values, plus various
+ * network and internal errors.
+ **/
+
static struct {
guint code;
const char *phrase;
Modified: branches/libsoup-2.4/libsoup/soup-status.h
==============================================================================
--- branches/libsoup-2.4/libsoup/soup-status.h (original)
+++ branches/libsoup-2.4/libsoup/soup-status.h Mon Jan 7 14:51:31 2008
@@ -12,55 +12,6 @@
G_BEGIN_DECLS
-/**
- * SOUP_STATUS_IS_TRANSPORT_ERROR:
- * @status: a status code
- *
- * Tests if @status is a libsoup transport error.
- *
- * Return value: %TRUE or %FALSE
- **/
-/**
- * SOUP_STATUS_IS_INFORMATIONAL:
- * @status: an HTTP status code
- *
- * Tests if @status is an Informational (1xx) response.
- *
- * Return value: %TRUE or %FALSE
- **/
-/**
- * SOUP_STATUS_IS_SUCCESSFUL:
- * @status: an HTTP status code
- *
- * Tests if @status is a Successful (2xx) response.
- *
- * Return value: %TRUE or %FALSE
- **/
-/**
- * SOUP_STATUS_IS_REDIRECTION:
- * @status: an HTTP status code
- *
- * Tests if @status is a Redirection (3xx) response.
- *
- * Return value: %TRUE or %FALSE
- **/
-/**
- * SOUP_STATUS_IS_CLIENT_ERROR:
- * @status: an HTTP status code
- *
- * Tests if @status is a Client Error (4xx) response.
- *
- * Return value: %TRUE or %FALSE
- **/
-/**
- * SOUP_STATUS_IS_SERVER_ERROR:
- * @status: an HTTP status code
- *
- * Tests if @status is a Server Error (5xx) response.
- *
- * Return value: %TRUE or %FALSE
- **/
-
#define SOUP_STATUS_IS_TRANSPORT_ERROR(status) ((status) > 0 && (status) < 100)
#define SOUP_STATUS_IS_INFORMATIONAL(status) ((status) >= 100 && (status) < 200)
#define SOUP_STATUS_IS_SUCCESSFUL(status) ((status) >= 200 && (status) < 300)
@@ -68,89 +19,6 @@
#define SOUP_STATUS_IS_CLIENT_ERROR(status) ((status) >= 400 && (status) < 500)
#define SOUP_STATUS_IS_SERVER_ERROR(status) ((status) >= 500 && (status) < 600)
-/**
- * SoupKnownStatusCode:
- * @SOUP_STATUS_NONE: No status available. (Eg, the message has not
- * been sent yet)
- * @SOUP_STATUS_CANCELLED: Message was cancelled locally
- * @SOUP_STATUS_CANT_RESOLVE: Unable to resolve destination host name
- * @SOUP_STATUS_CANT_RESOLVE_PROXY: Unable to resolve proxy host name
- * @SOUP_STATUS_CANT_CONNECT: Unable to connect to remote host
- * @SOUP_STATUS_CANT_CONNECT_PROXY: Unable to connect to proxy
- * @SOUP_STATUS_SSL_FAILED: SSL negotiation failed
- * @SOUP_STATUS_IO_ERROR: A network error occurred, or the other end
- * closed the connection unexpectedly
- * @SOUP_STATUS_MALFORMED: Malformed data (usually a programmer error)
- * @SOUP_STATUS_TRY_AGAIN: Try again. (Only returned in certain
- * specifically documented cases)
- * @SOUP_STATUS_CONTINUE: 100 Continue (HTTP)
- * @SOUP_STATUS_SWITCHING_PROTOCOLS: 101 Switching Protocols (HTTP)
- * @SOUP_STATUS_PROCESSING: 102 Processing (WebDAV)
- * @SOUP_STATUS_OK: 200 Success (HTTP). Also used by many lower-level
- * soup routines to indicate success.
- * @SOUP_STATUS_CREATED: 201 Created (HTTP)
- * @SOUP_STATUS_ACCEPTED: 202 Accepted (HTTP)
- * @SOUP_STATUS_NON_AUTHORITATIVE: 203 Non-Authoritative Information
- * (HTTP)
- * @SOUP_STATUS_NO_CONTENT: 204 No Content (HTTP)
- * @SOUP_STATUS_RESET_CONTENT: 205 Reset Content (HTTP)
- * @SOUP_STATUS_PARTIAL_CONTENT: 206 Partial Content (HTTP)
- * @SOUP_STATUS_MULTI_STATUS: 207 Multi-Status (WebDAV)
- * @SOUP_STATUS_MULTIPLE_CHOICES: 300 Multiple Choices (HTTP)
- * @SOUP_STATUS_MOVED_PERMANENTLY: 301 Moved Permanently (HTTP)
- * @SOUP_STATUS_FOUND: 302 Found (HTTP)
- * @SOUP_STATUS_MOVED_TEMPORARILY: 302 Moved Temporarily (old name,
- * RFC 2068)
- * @SOUP_STATUS_SEE_OTHER: 303 See Other (HTTP)
- * @SOUP_STATUS_NOT_MODIFIED: 304 Not Modified (HTTP)
- * @SOUP_STATUS_USE_PROXY: 305 Use Proxy (HTTP)
- * @SOUP_STATUS_NOT_APPEARING_IN_THIS_PROTOCOL: 306 [Unused] (HTTP)
- * @SOUP_STATUS_TEMPORARY_REDIRECT: 307 Temporary Redirect (HTTP)
- * @SOUP_STATUS_BAD_REQUEST: 400 Bad Request (HTTP)
- * @SOUP_STATUS_UNAUTHORIZED: 401 Unauthorized (HTTP)
- * @SOUP_STATUS_PAYMENT_REQUIRED: 402 Payment Required (HTTP)
- * @SOUP_STATUS_FORBIDDEN: 403 Forbidden (HTTP)
- * @SOUP_STATUS_NOT_FOUND: 404 Not Found (HTTP)
- * @SOUP_STATUS_METHOD_NOT_ALLOWED: 405 Method Not Allowed (HTTP)
- * @SOUP_STATUS_NOT_ACCEPTABLE: 406 Not Acceptable (HTTP)
- * @SOUP_STATUS_PROXY_AUTHENTICATION_REQUIRED: 407 Proxy Authentication
- * Required (HTTP)
- * @SOUP_STATUS_PROXY_UNAUTHORIZED: shorter alias for
- * %SOUP_STATUS_PROXY_AUTHENTICATION_REQUIRED
- * @SOUP_STATUS_REQUEST_TIMEOUT: 408 Request Timeout (HTTP)
- * @SOUP_STATUS_CONFLICT: 409 Conflict (HTTP)
- * @SOUP_STATUS_GONE: 410 Gone (HTTP)
- * @SOUP_STATUS_LENGTH_REQUIRED: 411 Length Required (HTTP)
- * @SOUP_STATUS_PRECONDITION_FAILED: 412 Precondition Failed (HTTP)
- * @SOUP_STATUS_REQUEST_ENTITY_TOO_LARGE: 413 Request Entity Too Large
- * (HTTP)
- * @SOUP_STATUS_REQUEST_URI_TOO_LONG: 414 Request-URI Too Long (HTTP)
- * @SOUP_STATUS_UNSUPPORTED_MEDIA_TYPE: 415 Unsupported Media Type
- * (HTTP)
- * @SOUP_STATUS_REQUESTED_RANGE_NOT_SATISFIABLE: 416 Requested Range
- * Not Satisfiable (HTTP)
- * @SOUP_STATUS_INVALID_RANGE: shorter alias for
- * %SOUP_STATUS_REQUESTED_RANGE_NOT_SATISFIABLE
- * @SOUP_STATUS_EXPECTATION_FAILED: 417 Expectation Failed (HTTP)
- * @SOUP_STATUS_UNPROCESSABLE_ENTITY: 422 Unprocessable Entity
- * (WebDAV)
- * @SOUP_STATUS_LOCKED: 423 Locked (WebDAV)
- * @SOUP_STATUS_FAILED_DEPENDENCY: 424 Failed Dependency (WebDAV)
- * @SOUP_STATUS_INTERNAL_SERVER_ERROR: 500 Internal Server Error
- * (HTTP)
- * @SOUP_STATUS_NOT_IMPLEMENTED: 501 Not Implemented (HTTP)
- * @SOUP_STATUS_BAD_GATEWAY: 502 Bad Gateway (HTTP)
- * @SOUP_STATUS_SERVICE_UNAVAILABLE: 503 Service Unavailable (HTTP)
- * @SOUP_STATUS_GATEWAY_TIMEOUT: 504 Gateway Timeout (HTTP)
- * @SOUP_STATUS_HTTP_VERSION_NOT_SUPPORTED: 505 HTTP Version Not
- * Supported (HTTP)
- * @SOUP_STATUS_INSUFFICIENT_STORAGE: 507 Insufficient Storage
- * (WebDAV)
- * @SOUP_STATUS_NOT_EXTENDED: 510 Not Extended (RFC 2774)
- *
- * These represent the known HTTP status code values, plus various
- * network and internal errors.
- **/
typedef enum {
SOUP_STATUS_NONE,
Modified: branches/libsoup-2.4/libsoup/soup-uri.c
==============================================================================
--- branches/libsoup-2.4/libsoup/soup-uri.c (original)
+++ branches/libsoup-2.4/libsoup/soup-uri.c Mon Jan 7 14:51:31 2008
@@ -12,6 +12,18 @@
#include "soup-uri.h"
#include "soup-misc.h"
+/**
+ * SECTION:soup-uri
+ * @short_description: URIs
+ *
+ * A #SoupURI represents a (parsed) URI.
+ *
+ * Many applications will not need to use #SoupURI directly at all; on
+ * the client side, soup_message_new() takes a stringified URI, and on
+ * the server side, the path and query components are provided for you
+ * in the server callback.
+ **/
+
static void append_uri_encoded (GString *str, const char *in, const char *extra_enc_chars);
static const char *http_scheme, *https_scheme;
Modified: branches/libsoup-2.4/libsoup/soup-value-utils.c
==============================================================================
--- branches/libsoup-2.4/libsoup/soup-value-utils.c (original)
+++ branches/libsoup-2.4/libsoup/soup-value-utils.c Mon Jan 7 14:51:31 2008
@@ -9,6 +9,34 @@
#include <string.h>
+/**
+ * SECTION:soup-value-utils
+ * @short_description: #GValue utilities
+ *
+ **/
+
+/**
+ * SOUP_VALUE_SETV:
+ * @val: a #GValue
+ * @type: a #GType
+ * @args: #va_list pointing to a value of type @type
+ *
+ * Copies an argument of type @type from @args into @val. @val will
+ * point directly to the value in @args rather than copying it, so you
+ * must g_value_copy() it if you want it to remain valid.
+ **/
+
+/**
+ * SOUP_VALUE_GETV:
+ * @val: a #GValue
+ * @type: a #GType
+ * @args: #va_list pointing to a value of type pointer-to- type
+ *
+ * Extracts a value of type @type from @val into @args. The return
+ * value will point to the same data as @val rather than being a copy
+ * of it.
+ **/
+
static void
soup_value_hash_value_free (gpointer val)
{
Modified: branches/libsoup-2.4/libsoup/soup-value-utils.h
==============================================================================
--- branches/libsoup-2.4/libsoup/soup-value-utils.h (original)
+++ branches/libsoup-2.4/libsoup/soup-value-utils.h Mon Jan 7 14:51:31 2008
@@ -11,16 +11,6 @@
G_BEGIN_DECLS
-/**
- * SOUP_VALUE_SETV:
- * @val: a #GValue
- * @type: a #GType
- * @args: #va_list pointing to a value of type @type
- *
- * Copies an argument of type @type from @args into @val. @val will
- * point directly to the value in @args rather than copying it, so you
- * must g_value_copy() it if you want it to remain valid.
- **/
#define SOUP_VALUE_SETV(val, type, args) \
G_STMT_START { \
char *error = NULL; \
@@ -32,16 +22,6 @@
g_free (error); \
} G_STMT_END
-/**
- * SOUP_VALUE_GETV:
- * @val: a #GValue
- * @type: a #GType
- * @args: #va_list pointing to a value of type pointer-to- type
- *
- * Extracts a value of type @type from @val into @args. The return
- * value will point to the same data as @val rather than being a copy
- * of it.
- **/
#define SOUP_VALUE_GETV(val, type, args) \
G_STMT_START { \
char *error = NULL; \
Modified: branches/libsoup-2.4/libsoup/soup-xmlrpc.c
==============================================================================
--- branches/libsoup-2.4/libsoup/soup-xmlrpc.c (original)
+++ branches/libsoup-2.4/libsoup/soup-xmlrpc.c Mon Jan 7 14:51:31 2008
@@ -21,6 +21,12 @@
#include "soup-misc.h"
#include "soup-session.h"
+/**
+ * SECTION:soup-xmlrpc
+ * @short_description: XML-RPC support
+ *
+ **/
+
static xmlNode *find_real_node (xmlNode *node);
static gboolean insert_value (xmlNode *parent, GValue *value);
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
