docs/reference/html/libsoup-server-howto.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <title>Soup Server Basics</title>
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
   7 <link rel="home" href="index.html" title="libsoup Reference Manual">
   8 <link rel="up" href="ch01.html" title="Tutorial">
   9 <link rel="prev" href="libsoup-client-howto.html" title="Soup Client Basics">
  10 <link rel="next" href="ch02.html" title="Core API">
  11 <meta name="generator" content="GTK-Doc V1.18 (XML mode)">
  12 <link rel="stylesheet" href="style.css" type="text/css">
  13 </head>
  14 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  15 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle">
  16 <td><a accesskey="p" href="libsoup-client-howto.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
  17 <td><a accesskey="u" href="ch01.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
  18 <td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
  19 <th width="100%" align="center">libsoup Reference Manual</th>
  20 <td><a accesskey="n" href="ch02.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
  21 </tr></table>
  22 <div class="refentry">
  23 <a name="libsoup-server-howto"></a><div class="titlepage"></div>
  24 <div class="refnamediv"><table width="100%"><tr>
  25 <td valign="top">
  26 <h2><span class="refentrytitle">Soup Server Basics</span></h2>
  27 <p>Soup Server Basics — Server-side tutorial</p>
  28 </td>
  29 <td valign="top" align="right"></td>
  30 </tr></table></div>
  31 <div class="refsect2">
  32 <a name="id444239"></a><h3>Creating a SoupSession</h3>
  33 <p>
  34 As with the client API, there is a single object that will encapsulate
  35 most of your interactions with libsoup. In this case, <a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a>.
  36 </p>
  37 <p>
  38 You create the server with <a class="link" href="SoupServer.html#soup-server-new" title="soup_server_new ()"><code class="function">soup_server_new</code></a>,
  39 and as with the <span class="type">SoupSession</span> constructor, you can specify
  40 various additional options:
  41 </p>
  42 <div class="variablelist"><table border="0">
  43 <col align="left" valign="top">
  44 <tbody>
  45 <tr>
  46 <td><p><span class="term"><a class="link" href="SoupServer.html#SOUP-SERVER-PORT:CAPS" title="SOUP_SERVER_PORT"><code class="literal">SOUP_SERVER_PORT</code></a></span></p></td>
  47 <td><p>
  48             The TCP port to listen on. If <code class="literal">0</code> (or
  49             left unspecified), some unused port will be selected for
  50             you. (You can find out what port by calling <a class="link" href="SoupServer.html#soup-server-get-port" title="soup_server_get_port ()"><code class="function">soup_server_get_port</code></a>.
  51         </p></td>
  52 </tr>
  53 <tr>
  54 <td><p><span class="term"><a class="link" href="SoupServer.html#SOUP-SERVER-INTERFACE:CAPS" title="SOUP_SERVER_INTERFACE"><code class="literal">SOUP_SERVER_INTERFACE</code></a></span></p></td>
  55 <td><p>
  56             A <a class="link" href="SoupAddress.html" title="SoupAddress"><span class="type">SoupAddress</span></a>,
  57             specifying the IP address of the network interface to run
  58             the server on. If <code class="literal">NULL</code> (or left
  59             unspecified), the server will listen on all interfaces.
  60         </p></td>
  61 </tr>
  62 <tr>
  63 <td><p><span class="term"><a class="link" href="SoupServer.html#SOUP-SERVER-SSL-CERT-FILE:CAPS" title="SOUP_SERVER_SSL_CERT_FILE"><code class="literal">SOUP_SERVER_SSL_CERT_FILE</code></a></span></p></td>
  64 <td><p>
  65             Points to a file containing an SSL certificate to use. If
  66             this is set, then the server will speak HTTPS; otherwise
  67             it will speak HTTP.
  68         </p></td>
  69 </tr>
  70 <tr>
  71 <td><p><span class="term"><a class="link" href="SoupServer.html#SOUP-SERVER-SSL-KEY-FILE:CAPS" title="SOUP_SERVER_SSL_KEY_FILE"><code class="literal">SOUP_SERVER_SSL_KEY_FILE</code></a></span></p></td>
  72 <td><p>
  73             Points to a file containing the private key for the
  74             <code class="literal">SOUP_SERVER_SSL_CERT_FILE</code>. (It may
  75             point to the same file.)
  76         </p></td>
  77 </tr>
  78 <tr>
  79 <td><p><span class="term"><a class="link" href="SoupServer.html#SOUP-SERVER-ASYNC-CONTEXT:CAPS" title="SOUP_SERVER_ASYNC_CONTEXT"><code class="literal">SOUP_SERVER_ASYNC_CONTEXT</code></a></span></p></td>
  80 <td><p>
  81             A <a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GMainContext"><span class="type">GMainContext</span></a> which
  82             the server will use for asynchronous operations. This can
  83             be set if you want to use a SoupServer in a thread
  84             other than the main thread.
  85         </p></td>
  86 </tr>
  87 <tr>
  88 <td><p><span class="term"><a class="link" href="SoupServer.html#SOUP-SERVER-RAW-PATHS:CAPS" title="SOUP_SERVER_RAW_PATHS"><code class="literal">SOUP_SERVER_RAW_PATHS</code></a></span></p></td>
  89 <td><p>
  90             Set this to <code class="literal">TRUE</code> if you don't want
  91             <span class="application">libsoup</span> to decode %-encoding
  92             in the Request-URI. (Eg, because you need to treat
  93             <code class="literal">"/foo/bar"</code> and
  94             <code class="literal">"/foo%2Fbar"</code> as different paths.
  95         </p></td>
  96 </tr>
  97 </tbody>
  98 </table></div>
  99 </div>
 100 <hr>
 101 <div class="refsect2">
 102 <a name="id441651"></a><h3>Adding Handlers</h3>
 103 <p>
 104 By default, <a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a>
 105 returns "404 Not Found" in response to all requests (except ones that
 106 it can't parse, which get "400 Bad Request"). To override this
 107 behavior, call <a class="link" href="SoupServer.html#soup-server-add-handler" title="soup_server_add_handler ()"><code class="function">soup_server_add_handler</code></a>
 108 to set a callback to handle certain URI paths.
 109 </p>
 110 <div class="informalexample">
 111   <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
 112     <tbody>
 113       <tr>
 114         <td class="listing_lines" align="right"><pre>1
 115 2</pre></td>
 116         <td class="listing_code"><pre class="programlisting"><span class="function"><a href="SoupServer.html#soup-server-add-handler">soup_server_add_handler</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">server</span><span class="symbol">,</span><span class="normal"> </span><span class="string">"/foo"</span><span class="symbol">,</span><span class="normal"> server_callback</span><span class="symbol">,</span>
 117 <span class="normal">             data</span><span class="symbol">,</span><span class="normal"> destroy_notify</span><span class="symbol">);</span></pre></td>
 118       </tr>
 119     </tbody>
 120   </table>
 121 </div>
 122
 123 <p>
 124 The <code class="literal">"/foo"</code> indicates the base path for this
 125 handler. When a request comes in, if there is a handler registered for
 126 exactly the path in the request's <code class="literal">Request-URI</code>, then
 127 that handler will be called. Otherwise
 128 <span class="application">libsoup</span> will strip path components one by
 129 one until it finds a matching handler. So for example, a request of
 130 the form
 131 "<code class="literal">GET /foo/bar/baz.html?a=1&amp;b=2 HTTP/1.1</code>"
 132 would look for handlers for "<code class="literal">/foo/bar/baz.html</code>",
 133 "<code class="literal">/foo/bar</code>", and "<code class="literal">/foo</code>". If a
 134 handler has been registered with a <code class="literal">NULL</code> base path,
 135 then it is used as the default handler for any request that doesn't
 136 match any other handler.
 137 </p>
 138 </div>
 139 <hr>
 140 <div class="refsect2">
 141 <a name="id432902"></a><h3>Responding to Requests</h3>
 142 <p>
 143 A handler callback looks something like this:
 144 </p>
 145 <div class="informalexample">
 146   <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
 147     <tbody>
 148       <tr>
 149         <td class="listing_lines" align="right"><pre>1
 150 2
 151 3
 152 4
 153 5
 154 6
 155 7
 156 8
 157 9
 158 10</pre></td>
 159         <td class="listing_code"><pre class="programlisting"><span class="keyword">static</span><span class="normal"> </span><span class="type">void</span>
 160 <span class="function">server_callback</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">SoupServer</span><span class="normal">        </span><span class="symbol">*</span><span class="normal">server</span><span class="symbol">,</span>
 161 <span class="normal">         </span><span class="usertype">SoupMessage</span><span class="normal">       </span><span class="symbol">*</span><span class="normal">msg</span><span class="symbol">,</span><span class="normal"> </span>
 162 <span class="normal">         </span><span class="keyword">const</span><span class="normal"> </span><span class="type">char</span><span class="normal">        </span><span class="symbol">*</span><span class="normal">path</span><span class="symbol">,</span>
 163 <span class="normal">         </span><span class="usertype">GHashTable</span><span class="normal">        </span><span class="symbol">*</span><span class="normal">query</span><span class="symbol">,</span>
 164 <span class="normal">         </span><span class="usertype">SoupClientContext</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">client</span><span class="symbol">,</span>
 165 <span class="normal">         </span><span class="usertype">gpointer</span><span class="normal">           user_data</span><span class="symbol">)</span>
 166 <span class="cbracket">{</span>
 167 <span class="normal">    </span><span class="symbol">...</span>
 168 <span class="cbracket">}</span></pre></td>
 169       </tr>
 170     </tbody>
 171   </table>
 172 </div>
 173
 174 <p>
 175 <code class="literal">msg</code> is the request that has been received and
 176 <code class="literal">user_data</code> is the data that was passed to <a class="link" href="SoupServer.html#soup-server-add-handler" title="soup_server_add_handler ()"><code class="function">soup_server_add_handler</code></a>.
 177 <code class="literal">path</code> is the path (from <code class="literal">msg</code>'s
 178 URI), and <code class="literal">query</code> contains the result of parsing the
 179 URI query field. (It is <code class="literal">NULL</code> if there was no
 180 query.) <code class="literal">client</code> is a <a class="link" href="SoupServer.html#SoupClientContext"><span class="type">SoupClientContext</span></a>,
 181 which contains additional information about the client (including its
 182 IP address, and whether or not it used HTTP authentication).
 183 </p>
 184 <p>
 185 By default, <span class="application">libsoup</span> assumes that you have
 186 completely finished processing the message when you return from the
 187 callback, and that it can therefore begin sending the response. If you
 188 are not ready to send a response immediately (eg, you have to contact
 189 another server, or wait for data from a database), you must call <a class="link" href="SoupServer.html#soup-server-pause-message" title="soup_server_pause_message ()"><code class="function">soup_server_pause_message</code></a>
 190 on the message before returning from the callback. This will delay
 191 sending a response until you call <a class="link" href="SoupServer.html#soup-server-unpause-message" title="soup_server_unpause_message ()"><code class="function">soup_server_unpause_message</code></a>.
 192 (You must also connect to the <a class="link" href="SoupMessage.html#SoupMessage-finished" title='The "finished" signal'>finished</a> signal on the message
 193 in this case, so that you can break off processing if the client
 194 unexpectedly disconnects before you start sending the data.)
 195 </p>
 196 <p>
 197 To set the response status, call <a class="link" href="SoupMessage.html#soup-message-set-status" title="soup_message_set_status ()"><code class="function">soup_message_set_status</code></a>
 198 or <a class="link" href="SoupMessage.html#soup-message-set-status-full" title="soup_message_set_status_full ()"><code class="function">soup_message_set_status_full</code></a>.
 199 If the response requires a body, you must decide whether to use
 200 <code class="literal">Content-Length</code> encoding (the default), or
 201 <code class="literal">chunked</code> encoding.
 202 </p>
 203 <div class="refsect3">
 204 <a name="id445778"></a><h4>Responding with <code class="literal">Content-Length</code>
 205 Encoding</h4>
 206 <p>
 207 This is the simpler way to set a response body, if you have all of the
 208 data available at once.
 209 </p>
 210 <div class="informalexample">
 211   <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
 212     <tbody>
 213       <tr>
 214         <td class="listing_lines" align="right"><pre>1
 215 2
 216 3
 217 4
 218 5
 219 6
 220 7
 221 8
 222 9
 223 10
 224 11
 225 12
 226 13
 227 14
 228 15
 229 16
 230 17
 231 18
 232 19
 233 20
 234 21
 235 22
 236 23
 237 24
 238 25
 239 26
 240 27
 241 28
 242 29
 243 30
 244 31</pre></td>
 245         <td class="listing_code"><pre class="programlisting"><span class="keyword">static</span><span class="normal"> </span><span class="type">void</span>
 246 <span class="function">server_callback</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">SoupServer</span><span class="normal">        </span><span class="symbol">*</span><span class="normal">server</span><span class="symbol">,</span>
 247 <span class="normal">         </span><span class="usertype">SoupMessage</span><span class="normal">       </span><span class="symbol">*</span><span class="normal">msg</span><span class="symbol">,</span><span class="normal"> </span>
 248 <span class="normal">         </span><span class="keyword">const</span><span class="normal"> </span><span class="type">char</span><span class="normal">        </span><span class="symbol">*</span><span class="normal">path</span><span class="symbol">,</span>
 249 <span class="normal">         </span><span class="usertype">GHashTable</span><span class="normal">        </span><span class="symbol">*</span><span class="normal">query</span><span class="symbol">,</span>
 250 <span class="normal">         </span><span class="usertype">SoupClientContext</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">client</span><span class="symbol">,</span>
 251 <span class="normal">         </span><span class="usertype">gpointer</span><span class="normal">           user_data</span><span class="symbol">)</span>
 252 <span class="cbracket">{</span>
 253 <span class="normal">    </span><span class="usertype">MyServerData</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">server_data </span><span class="symbol">=</span><span class="normal"> user_data</span><span class="symbol">;</span>
 254 <span class="normal">    </span><span class="keyword">const</span><span class="normal"> </span><span class="type">char</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">mime_type</span><span class="symbol">;</span>
 255 <span class="normal">    </span><span class="usertype">GByteArray</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">body</span><span class="symbol">;</span>
 256
 257 <span class="normal">    </span><span class="keyword">if</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">msg</span><span class="symbol">-&gt;</span><span class="normal">method </span><span class="symbol">!=</span><span class="normal"> <a href="libsoup-2.4-soup-method.html#SOUP-METHOD-GET:CAPS">SOUP_METHOD_GET</a></span><span class="symbol">)</span><span class="normal"> </span><span class="cbracket">{</span>
 258 <span class="normal">        </span><span class="function"><a href="SoupMessage.html#soup-message-set-status">soup_message_set_status</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">msg</span><span class="symbol">,</span><span class="normal"> <a href="libsoup-2.4-soup-status.html#SOUP-STATUS-NOT-IMPLEMENTED:CAPS">SOUP_STATUS_NOT_IMPLEMENTED</a></span><span class="symbol">);</span>
 259 <span class="normal">        </span><span class="keyword">return</span><span class="symbol">;</span>
 260 <span class="normal">    </span><span class="cbracket">}</span>
 261
 262 <span class="normal">    </span><span class="comment">/* This is somewhat silly. Presumably your server will do</span>
 263 <span class="comment">     * something more interesting.</span>
 264 <span class="comment">     */</span>
 265 <span class="normal">    body </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="http://library.gnome.org/devel/glib/unstable/glib-Hash-Tables.html#g-hash-table-lookup">g_hash_table_lookup</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">server_data</span><span class="symbol">-&gt;</span><span class="normal">bodies</span><span class="symbol">,</span><span class="normal"> path</span><span class="symbol">);</span>
 266 <span class="normal">    mime_type </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="http://library.gnome.org/devel/glib/unstable/glib-Hash-Tables.html#g-hash-table-lookup">g_hash_table_lookup</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">server_data</span><span class="symbol">-&gt;</span><span class="normal">mime_types</span><span class="symbol">,</span><span class="normal"> path</span><span class="symbol">);</span>
 267 <span class="normal">    </span><span class="keyword">if</span><span class="normal"> </span><span class="symbol">(!</span><span class="normal">body </span><span class="symbol">||</span><span class="normal"> </span><span class="symbol">!</span><span class="normal">mime_type</span><span class="symbol">)</span><span class="normal"> </span><span class="cbracket">{</span>
 268 <span class="normal">        </span><span class="function"><a href="SoupMessage.html#soup-message-set-status">soup_message_set_status</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">msg</span><span class="symbol">,</span><span class="normal"> <a href="libsoup-2.4-soup-status.html#SOUP-STATUS-NOT-FOUND:CAPS">SOUP_STATUS_NOT_FOUND</a></span><span class="symbol">);</span>
 269 <span class="normal">        </span><span class="keyword">return</span><span class="symbol">;</span>
 270 <span class="normal">    </span><span class="cbracket">}</span>
 271
 272 <span class="normal">    </span><span class="function"><a href="SoupMessage.html#soup-message-set-status">soup_message_set_status</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">msg</span><span class="symbol">,</span><span class="normal"> <a href="libsoup-2.4-soup-status.html#SOUP-STATUS-OK:CAPS">SOUP_STATUS_OK</a></span><span class="symbol">);</span>
 273 <span class="normal">    </span><span class="function"><a href="SoupMessage.html#soup-message-set-response">soup_message_set_response</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">msg</span><span class="symbol">,</span><span class="normal"> mime_type</span><span class="symbol">,</span><span class="normal"> <a href="SoupMessageBody.html#SOUP-MEMORY-COPY:CAPS">SOUP_MEMORY_COPY</a></span><span class="symbol">,</span>
 274 <span class="normal">                   body</span><span class="symbol">-&gt;</span><span class="normal">data</span><span class="symbol">,</span><span class="normal"> body</span><span class="symbol">-&gt;</span><span class="normal">len</span><span class="symbol">);</span>
 275 <span class="cbracket">}</span></pre></td>
 276       </tr>
 277     </tbody>
 278   </table>
 279 </div>
 280
 281 </div>
 282 <div class="refsect3">
 283 <a name="id445810"></a><h4>Responding with <code class="literal">chunked</code> Encoding</h4>
 284 <p>
 285 If you want to supply the response body in chunks as it becomes
 286 available, use <code class="literal">chunked</code> encoding instead. In this
 287 case, first call <a class="link" href="SoupMessageHeaders.html#soup-message-headers-set-encoding" title="soup_message_headers_set_encoding ()"><code class="function">soup_message_headers_set_encoding</code></a> <code class="literal">(msg-&gt;response_headers, <a class="link" href="SoupMessageHeaders.html#SoupEncoding" title="enum SoupEncoding">SOUP_ENCODING_CHUNKED</a>)</code>
 288 to tell <span class="application">libsoup</span> that you'll be using
 289 chunked encoding. Then call <a class="link" href="SoupMessageBody.html#soup-message-body-append" title="soup_message_body_append ()"><code class="function">soup_message_body_append</code></a>
 290 (or <a class="link" href="SoupMessageBody.html#soup-message-body-append-buffer" title="soup_message_body_append_buffer ()"><code class="function">soup_message_body_append_buffer</code></a>)
 291 on <code class="literal">msg-&gt;response_body</code> with each chunk of the
 292 response body as it becomes available, and call <a class="link" href="SoupMessageBody.html#soup-message-body-complete" title="soup_message_body_complete ()"><code class="function">soup_message_body_complete</code></a>
 293 when the response is complete. After each of these calls, you must
 294 also call <a class="link" href="SoupServer.html#soup-server-unpause-message" title="soup_server_unpause_message ()"><code class="function">soup_server_unpause_message</code></a>
 295 to cause the chunk to be sent. (You do not normally need to call <a class="link" href="SoupServer.html#soup-server-pause-message" title="soup_server_pause_message ()"><code class="function">soup_server_pause_message</code></a>,
 296 because I/O is automatically paused when doing a
 297 <code class="literal">chunked</code> transfer if no chunks are available.)
 298 </p>
 299 <p>
 300 When using chunked encoding, you must also connect to the <a class="link" href="SoupMessage.html#SoupMessage-finished" title='The "finished" signal'>finished</a> signal on the message,
 301 so that you will be notified if the client disconnects between two
 302 chunks; <span class="type">SoupServer</span> will unref the message if that
 303 happens, so you must stop adding new chunks to the response at that
 304 point. (An alternate possibility is to write each new chunk only when
 305 the <a class="link" href="SoupMessage.html#SoupMessage-wrote-chunk" title='The "wrote-chunk" signal'>wrote_chunk</a> signal
 306 is emitted indicating that the previous one was written successfully.)
 307 </p>
 308 <p>
 309 The <span class="bold"><strong><code class="literal">simple-proxy</code></strong></span>
 310 example in the <code class="literal">tests/</code> directory gives an example of
 311 using <code class="literal">chunked</code> encoding.
 312 </p>
 313 </div>
 314 </div>
 315 <hr>
 316 <div class="refsect2">
 317 <a name="id445966"></a><h3>Handling Authentication</h3>
 318 <p>
 319 To have <a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a>
 320 handle HTTP authentication for you, create a <a class="link" href="SoupAuthDomainBasic.html" title="SoupAuthDomainBasic"><span class="type">SoupAuthDomainBasic</span></a>
 321 or <a class="link" href="SoupAuthDomainDigest.html" title="SoupAuthDomainDigest"><span class="type">SoupAuthDomainDigest</span></a>,
 322 and pass it to <a class="link" href="SoupServer.html#soup-server-add-auth-domain" title="soup_server_add_auth_domain ()"><code class="function">soup_server_add_auth_domain</code></a>:
 323 </p>
 324 <div class="informalexample">
 325   <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
 326     <tbody>
 327       <tr>
 328         <td class="listing_lines" align="right"><pre>1
 329 2
 330 3
 331 4
 332 5
 333 6
 334 7
 335 8
 336 9
 337 10
 338 11</pre></td>
 339         <td class="listing_code"><pre class="programlisting"><span class="usertype">SoupAuthDomain</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">domain</span><span class="symbol">;</span>
 340
 341 <span class="normal">domain </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="SoupAuthDomainBasic.html#soup-auth-domain-basic-new">soup_auth_domain_basic_new</a></span><span class="normal"> </span><span class="symbol">(</span>
 342 <span class="normal">    <a href="SoupAuthDomain.html#SOUP-AUTH-DOMAIN-REALM:CAPS">SOUP_AUTH_DOMAIN_REALM</a></span><span class="symbol">,</span><span class="normal"> </span><span class="string">"My Realm"</span><span class="symbol">,</span>
 343 <span class="normal">    <a href="SoupAuthDomainBasic.html#SOUP-AUTH-DOMAIN-BASIC-AUTH-CALLBACK:CAPS">SOUP_AUTH_DOMAIN_BASIC_AUTH_CALLBACK</a></span><span class="symbol">,</span><span class="normal"> auth_callback</span><span class="symbol">,</span>
 344 <span class="normal">    <a href="SoupAuthDomainBasic.html#SOUP-AUTH-DOMAIN-BASIC-AUTH-DATA:CAPS">SOUP_AUTH_DOMAIN_BASIC_AUTH_DATA</a></span><span class="symbol">,</span><span class="normal"> auth_data</span><span class="symbol">,</span>
 345 <span class="normal">    <a href="SoupAuthDomain.html#SOUP-AUTH-DOMAIN-ADD-PATH:CAPS">SOUP_AUTH_DOMAIN_ADD_PATH</a></span><span class="symbol">,</span><span class="normal"> </span><span class="string">"/foo"</span><span class="symbol">,</span>
 346 <span class="normal">    <a href="SoupAuthDomain.html#SOUP-AUTH-DOMAIN-ADD-PATH:CAPS">SOUP_AUTH_DOMAIN_ADD_PATH</a></span><span class="symbol">,</span><span class="normal"> </span><span class="string">"/bar/private"</span><span class="symbol">,</span>
 347 <span class="normal">    <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">);</span>
 348 <span class="function"><a href="SoupServer.html#soup-server-add-auth-domain">soup_server_add_auth_domain</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">server</span><span class="symbol">,</span><span class="normal"> domain</span><span class="symbol">);</span>
 349 <span class="function"><a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#g-object-unref">g_object_unref</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">domain</span><span class="symbol">);</span></pre></td>
 350       </tr>
 351     </tbody>
 352   </table>
 353 </div>
 354
 355 <p>
 356 Then, every request under one of the auth domain's paths will be
 357 passed to the <code class="literal">auth_callback</code> first before being
 358 passed to the <code class="literal">server_callback</code>:
 359 </p>
 360 <div class="informalexample">
 361   <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
 362     <tbody>
 363       <tr>
 364         <td class="listing_lines" align="right"><pre>1
 365 2
 366 3
 367 4
 368 5
 369 6
 370 7
 371 8
 372 9
 373 10
 374 11
 375 12
 376 13
 377 14
 378 15
 379 16
 380 17</pre></td>
 381         <td class="listing_code"><pre class="programlisting"><span class="keyword">static</span><span class="normal"> <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean">gboolean</a></span>
 382 <span class="function">auth_callback</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">SoupAuthDomain</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">domain</span><span class="symbol">,</span><span class="normal"> </span><span class="usertype">SoupMessage</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">msg</span><span class="symbol">,</span>
 383 <span class="normal">           </span><span class="keyword">const</span><span class="normal"> </span><span class="type">char</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">username</span><span class="symbol">,</span><span class="normal"> </span><span class="keyword">const</span><span class="normal"> </span><span class="type">char</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">password</span><span class="symbol">,</span>
 384 <span class="normal">           </span><span class="usertype">gpointer</span><span class="normal"> user_data</span><span class="symbol">)</span>
 385 <span class="cbracket">{</span>
 386 <span class="normal">    </span><span class="usertype">MyServerData</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">server_data </span><span class="symbol">=</span><span class="normal"> user_data</span><span class="symbol">;</span>
 387 <span class="normal">    </span><span class="usertype">MyUserData</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">user</span><span class="symbol">;</span>
 388
 389 <span class="normal">    user </span><span class="symbol">=</span><span class="normal"> </span><span class="function">my_server_data_lookup_user</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">server_data</span><span class="symbol">,</span><span class="normal"> username</span><span class="symbol">);</span>
 390 <span class="normal">    </span><span class="keyword">if</span><span class="normal"> </span><span class="symbol">(!</span><span class="normal">user</span><span class="symbol">)</span>
 391 <span class="normal">        </span><span class="keyword">return</span><span class="normal"> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS">FALSE</a></span><span class="symbol">;</span>
 392
 393 <span class="normal">    </span><span class="comment">/* </span><span class="todo">FIXME:</span><span class="comment"> Don't do this. Keeping a cleartext password database</span>
 394 <span class="comment">     * is bad.</span>
 395 <span class="comment">     */</span>
 396 <span class="normal">    </span><span class="keyword">return</span><span class="normal"> </span><span class="function">strcmp</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">password</span><span class="symbol">,</span><span class="normal"> user</span><span class="symbol">-&gt;</span><span class="normal">password</span><span class="symbol">)</span><span class="normal"> </span><span class="symbol">==</span><span class="normal"> </span><span class="number">0</span><span class="symbol">;</span>
 397 <span class="cbracket">}</span></pre></td>
 398       </tr>
 399     </tbody>
 400   </table>
 401 </div>
 402
 403 <p>
 404 The <a class="link" href="SoupAuthDomainBasic.html#SoupAuthDomainBasicAuthCallback" title="SoupAuthDomainBasicAuthCallback ()"><span class="type">SoupAuthDomainBasicAuthCallback</span></a>
 405 is given the username and password from the
 406 <code class="literal">Authorization</code> header and must determine, in some
 407 server-specific manner, whether or not to accept them. (In this
 408 example we compare the password against a cleartext password database,
 409 but it would be better to store the password somehow encoded, as in
 410 the UNIX password database. Alternatively, you may need to delegate
 411 the password check to PAM or some other service.)
 412 </p>
 413 <p>
 414 If you are using Digest authentication, note that <a class="link" href="SoupAuthDomainDigest.html#SoupAuthDomainDigestAuthCallback" title="SoupAuthDomainDigestAuthCallback ()"><span class="type">SoupAuthDomainDigestAuthCallback</span></a>
 415 works completely differently (since the server doesn't receive the
 416 cleartext password from the client in that case, so there's no way to
 417 compare it directly). See the documentation for <a class="link" href="SoupAuthDomainDigest.html" title="SoupAuthDomainDigest"><span class="type">SoupAuthDomainDigest</span></a>
 418 for more details.
 419 </p>
 420 <p>
 421 You can have multiple <span class="type">SoupAuthDomain</span>s attached to a
 422 <code class="literal">SoupServer</code>, either in separate parts of the path
 423 hierarchy, or overlapping. (Eg, you might want to accept either Basic
 424 or Digest authentication for a given path.) When more than one auth
 425 domain covers a given path, the request will be accepted if the user
 426 authenticates successfully against <span class="emphasis"><em>any</em></span> of the
 427 domains.
 428 </p>
 429 <p>
 430 If you want to require authentication for some requests under a
 431 certain path, but not all of them (eg, you want to authenticate
 432 <code class="literal">PUT</code>s, but not <code class="literal">GET</code>s), use a
 433 <a class="link" href="SoupAuthDomain.html#SoupAuthDomainFilter" title="SoupAuthDomainFilter ()"><span class="type">SoupAuthDomainFilter</span></a>.
 434 </p>
 435 </div>
 436 </div>
 437 <div class="footer">
 438 <hr>
 439           Generated by GTK-Doc V1.18</div>
 440 </body>
 441 </html>