diff options
Diffstat (limited to 'docs/reference/client-howto.xml')
| -rw-r--r-- | docs/reference/client-howto.xml | 180 |
1 files changed, 73 insertions, 107 deletions
diff --git a/docs/reference/client-howto.xml b/docs/reference/client-howto.xml index ac7caa06..c52f6353 100644 --- a/docs/reference/client-howto.xml +++ b/docs/reference/client-howto.xml @@ -44,7 +44,7 @@ slightly different behavior: </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 @@ only need to create the message and it's ready to send: <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 @@ headers and body of the message: 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 @@ linkend="soup-session-send-message"><function>soup_session_send_message</functio </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 @@ message. <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 @@ linkend="SoupSessionAsync"><type>SoupSessionAsync</type></link>), use } 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 @@ response be will be read. When the message is complete, 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 @@ asynchronously, you can look at the response fields in the 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 @@ it. <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 @@ linkend="soup-session-send-message"><function>soup_session_send_message</functio <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 @@ linkend="soup-session-add-filter"><function>soup_session_add_filter</function></ 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 @@ A few sample programs are available in the </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> |