diff options
Diffstat (limited to 'docs/reference/html/libsoup-session-porting.html')
| -rw-r--r-- | docs/reference/html/libsoup-session-porting.html | 217 |
1 files changed, 0 insertions, 217 deletions
diff --git a/docs/reference/html/libsoup-session-porting.html b/docs/reference/html/libsoup-session-porting.html deleted file mode 100644 index a177034a..00000000 --- a/docs/reference/html/libsoup-session-porting.html +++ /dev/null @@ -1,217 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> -<html> -<head> -<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> -<title>Porting to the new SoupSession: libsoup Reference Manual</title> -<meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> -<link rel="home" href="index.html" title="libsoup Reference Manual"> -<link rel="up" href="ch01.html" title="Tutorial"> -<link rel="prev" href="libsoup-request-howto.html" title="libsoup Client SoupRequest API"> -<link rel="next" href="libsoup-server-howto.html" title="libsoup Server Basics"> -<meta name="generator" content="GTK-Doc V1.28.1 (XML mode)"> -<link rel="stylesheet" href="style.css" type="text/css"> -</head> -<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> -<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle"> -<td width="100%" align="left" class="shortcuts"></td> -<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> -<td><a accesskey="u" href="ch01.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td> -<td><a accesskey="p" href="libsoup-request-howto.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> -<td><a accesskey="n" href="libsoup-server-howto.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> -</tr></table> -<div class="refentry"> -<a name="libsoup-session-porting"></a><div class="titlepage"></div> -<div class="refnamediv"><table width="100%"><tr> -<td valign="top"> -<h2><span class="refentrytitle">Porting to the new SoupSession</span></h2> -<p>Porting to the new SoupSession — Notes on -porting from SoupSessionAsync and SoupSessionSync to SoupSession</p> -</td> -<td class="gallery_image" valign="top" align="right"></td> -</tr></table></div> -<div class="refsect2"> -<a name="intro"></a><h3>Introduction</h3> -<p> -As of libsoup 2.42, <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> is no longer an -abstract class, and the base <span class="type">SoupSession</span> class is now -preferred over its traditional subclasses, <a class="link" href="SoupSessionAsync.html" title="SoupSessionAsync"><span class="type">SoupSessionAsync</span></a> and -<a class="link" href="SoupSessionSync.html" title="SoupSessionSync"><span class="type">SoupSessionSync</span></a>. -</p> -<p> -There are several changes in behavior between the old and new sessions -to be aware of. -</p> -</div> -<hr> -<div class="refsect2"> -<a name="defaults"></a><h3>Different defaults</h3> -<p> -The new <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> -has different (and hopefully better) defaults than <a class="link" href="SoupSessionAsync.html" title="SoupSessionAsync"><span class="type">SoupSessionAsync</span></a> and -<a class="link" href="SoupSessionSync.html" title="SoupSessionSync"><span class="type">SoupSessionSync</span></a>: -</p> -<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> -<li class="listitem"> -<p> - The system TLS/SSL certificate database is used by default to - validate https certificates, and sites with invalid certificates - will refuse to load with a - <a class="link" href="libsoup-2.4-soup-status.html#SOUP-STATUS-SSL-FAILED:CAPS"><code class="literal">SOUP_STATUS_SSL_FAILED</code></a> - error. - </p> -<p> - You can still override the CA database as before, by setting the - <a class="link" href="SoupSession.html#SoupSession--ssl-ca-file" title="The “ssl-ca-file” property"><span class="type">"ssl-ca-file"</span></a> - property, although the - <a class="link" href="SoupSession.html#SoupSession--tls-database" title="The “tls-database” property"><span class="type">"tls-database"</span></a> - property is preferred, since it allows you to do proper error - handling. - </p> -<p> - If you want to accept all certificates, set - <a class="link" href="SoupSession.html#SoupSession--ssl-strict" title="The “ssl-strict” property"><span class="type">"ssl-strict"</span></a> to - <code class="literal">FALSE</code>. Note that libsoup will still check - certificates, it will just continue with the HTTP request even - if the certificate fails to validate. You can use - <a class="link" href="SoupMessage.html#soup-message-get-https-status" title="soup_message_get_https_status ()"><code class="function">soup_message_get_https_status()</code></a> - to look at the certificate after the fact. - </p> -</li> -<li class="listitem"><p> - The - <a class="link" href="SoupSession.html#SoupSession--timeout" title="The “timeout” property"><span class="type">"timeout"</span></a> - and - <a class="link" href="SoupSession.html#SoupSession--idle-timeout" title="The “idle-timeout” property"><span class="type">"idle-timeout"</span></a> - properties both default to 60 seconds. - </p></li> -<li class="listitem"><p> - The - <a class="link" href="SoupSession.html#SoupSession--http-aliases" title="The “http-aliases” property"><span class="type">"http-aliases"</span></a> - property defaults to <code class="literal">NULL</code>, meaning that URI - schemes like "<code class="literal">webcal</code>" and - "<code class="literal">dav</code>" (and "<code class="literal">ftp</code>") are not - considered to be aliases for "<code class="literal">http</code>", and so - libsoup will not accept requests for such URIs, and will not - follow redirects to such URIs. - </p></li> -<li class="listitem"><p> - The new - <a class="link" href="SoupSession.html#SoupSession--proxy-resolver" title="The “proxy-resolver” property"><span class="type">"proxy-resolver"</span></a> - property is now initialized to the default - <span class="type">GProxyResolver</span>, - meaning that it will automatically use the user's system proxy - configuration. This replaces the use of the - <a class="link" href="SoupProxyResolverDefault.html" title="SoupProxyResolverDefault"><span class="type">SoupProxyResolverDefault</span></a>, - session feature in earlier releases. You can set this property to - <code class="literal">NULL</code> if you don't want to use proxies, and the - <a class="link" href="SoupSession.html#SoupSession--proxy-uri" title="The “proxy-uri” property"><span class="type">"proxy-uri"</span></a> - property still works if you want to use a single proxy for all requests. - </p></li> -<li class="listitem"><p> - Every session gets a - <a class="link" href="SoupContentDecoder.html" title="SoupContentDecoder"><span class="type">SoupContentDecoder</span></a> - attached to it by default, meaning that it will automatically - handle (and request) "gzip"- and "deflate"-encoded response - bodies. - </p></li> -</ul></div> -</div> -<hr> -<div class="refsect2"> -<a name="behavior"></a><h3>Differences in feature behavior</h3> -<p> -If you are using NTLM authentication, the new <span class="type">SoupSession</span> -behaves slightly differently from the old session types. -</p> -<p> -First, the deprecated <code class="literal">SOUP_SESSION_USE_NTLM</code> -property is no longer supported. If you want to add support for NTLM -to a session, call <a class="link" href="SoupSession.html#soup-session-add-feature-by-type" title="soup_session_add_feature_by_type ()"><code class="function">soup_session_add_feature_by_type()</code></a>, -passing <a class="link" href="SoupAuth.html#SOUP-TYPE-AUTH-NTLM:CAPS" title="SOUP_TYPE_AUTH_NTLM"><code class="literal">SOUP_TYPE_AUTH_NTLM</code></a>. -</p> -<p> -Second, with the old session types, enabling NTLM would cause all -(otherwise-unauthenticated) requests to be sent with an NTLM request -in the <code class="literal">Authorization</code> header. That is, libsoup would -assume that all servers supported NTLM, and would attempt to begin -negotiating NTLM authentication before the server ever returned a 401 -response. With the plain <span class="type">SoupSession</span>, this no longer -happens. If you want the old behavior, you need to call <a class="link" href="SoupAuthManager.html#soup-auth-manager-use-auth" title="soup_auth_manager_use_auth ()"><code class="function">soup_auth_manager_use_auth()</code></a> -for each host to "preload" the NTLM authentication: -</p> -<div class="informalexample"> - <table class="listing_frame" border="0" cellpadding="0" cellspacing="0"> - <tbody> - <tr> - <td class="listing_lines" align="right"><pre>1 -2 -3 -4 -5 -6 -7 -8 -9 -10</pre></td> - <td class="listing_code"><pre class="programlisting">SoupAuthManager <span class="gtkdoc opt">*</span>auth_manager<span class="gtkdoc opt">;</span> -SoupAuth <span class="gtkdoc opt">*</span>auth<span class="gtkdoc opt">;</span> -SoupURI <span class="gtkdoc opt">*</span>uri<span class="gtkdoc opt">;</span> - -auth_manager <span class="gtkdoc opt">=</span> <span class="function">SOUP_AUTH_MANAGER</span> <span class="gtkdoc opt">(</span><span class="function"><a href="SoupSession.html#soup-session-get-feature">soup_session_get_feature</a></span> <span class="gtkdoc opt">(</span>session<span class="gtkdoc opt">,</span> SOUP_TYPE_AUTH_MANAGER<span class="gtkdoc opt">));</span> -auth <span class="gtkdoc opt">=</span> <span class="function">g_object_new</span> <span class="gtkdoc opt">(</span>SOUP_TYPE_AUTH_NTLM<span class="gtkdoc opt">,</span> NULL<span class="gtkdoc opt">);</span> -uri <span class="gtkdoc opt">=</span> <span class="function"><a href="SoupURI.html#soup-uri-new">soup_uri_new</a></span> <span class="gtkdoc opt">(</span><span class="string">"http://ntlm-using-host.example.com/"</span><span class="gtkdoc opt">);</span> -<span class="function"><a href="SoupAuthManager.html#soup-auth-manager-use-auth">soup_auth_manager_use_auth</a></span> <span class="gtkdoc opt">(</span>auth_manager<span class="gtkdoc opt">,</span> uri<span class="gtkdoc opt">,</span> auth<span class="gtkdoc opt">);</span> -<span class="function">g_object_unref</span> <span class="gtkdoc opt">(</span>auth<span class="gtkdoc opt">);</span> -<span class="function"><a href="SoupURI.html#soup-uri-free">soup_uri_free</a></span> <span class="gtkdoc opt">(</span>auth<span class="gtkdoc opt">);</span></pre></td> - </tr> - </tbody> - </table> -</div> - -</div> -<hr> -<div class="refsect2"> -<a name="apis"></a><h3>Differences in SoupMessage-sending APIs</h3> -<p> -<span class="type">SoupSessionAsync</span> always uses asynchronous I/O, and -<span class="type">SoupSessionSync</span> always uses blocking I/O, regardless of -the operation. In the new <span class="type">SoupSession</span>, <a class="link" href="SoupSession.html#soup-session-queue-message" title="soup_session_queue_message ()"><code class="function">soup_session_queue_message()</code></a> -uses asynchronous I/O (like <span class="type">SoupSessionAsync</span>), and <a class="link" href="SoupSession.html#soup-session-send-message" title="soup_session_send_message ()"><code class="function">soup_session_send_message()</code></a> -uses blocking I/O (like <span class="type">SoupSessionSync</span>). There is no API -on the plain <span class="type">SoupSession</span> that simulates the effect of -calling <code class="function">soup_session_send_message()</code> on a -<span class="type">SoupSessionAsync</span> (ie, running the main loop internally), -or of calling <code class="function">soup_session_queue_message()</code> on a -<span class="type">SoupSessionSync</span> (ie, automatically sending the request in -another thread). -</p> -</div> -<hr> -<div class="refsect2"> -<a name="async"></a><h3>Differences in Asynchronous I/O</h3> -<p> -As compared to <a class="link" href="SoupSessionAsync.html" title="SoupSessionAsync"><span class="type">SoupSessionAsync</span></a>, <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> behaves more -like gio with respect to asynchronous I/O. -</p> -<p> -In particular, the <a class="link" href="SoupSession.html#SoupSession--async-context" title="The “async-context” property"><span class="type">"async-context"</span></a> -and <a class="link" href="SoupSession.html#SoupSession--use-thread-context" title="The “use-thread-context” property"><span class="type">"use-thread-context"</span></a> -properties are now effectively unused, and the session always queues -asynchronous requests in the <span class="type">GMainContext</span> that was is -the thread default when the asynchronous operation is started. Session -bookkeeping tasks (like closing idle connections) happen in the -context that was thread default when the session was created. -</p> -<p> -Additionally, <a class="link" href="SoupSession.html#soup-session-cancel-message" title="soup_session_cancel_message ()"><code class="function">soup_session_cancel_message()</code></a> -now acts asynchronously when you cancel an asynchronous request; -rather than having the request's callback be called from inside -<code class="function">soup_session_cancel_message()</code>, it just gets called -when you need return to the main loop. -</p> -</div> -</div> -<div class="footer"> -<hr>Generated by GTK-Doc V1.28.1</div> -</body> -</html>
\ No newline at end of file |