docs/reference/porting-2.2-2.4.xml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
   3                "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
   4 <refentry id="libsoup-porting-2.2-2.4">
   5 <refmeta>
   6 <refentrytitle>libsoup 2.2 to 2.4 porting notes</refentrytitle>
   7 <manvolnum>3</manvolnum>
   8 <refmiscinfo>LIBSOUP Library</refmiscinfo>
   9 </refmeta>
  10
  11 <refnamediv>
  12 <refname>Porting notes</refname><refpurpose>Notes on porting from libsoup 2.2 to 2.4</refpurpose>
  13 </refnamediv>
  14
  15 <refsect2>
  16 <title>Overview</title>
  17
  18 <para>
  19 After many API-compatible releases in the 2.2 series,
  20 <application>libsoup</application> has now changed its API and bumped
  21 its version number to 2.4. Changes were made for a variety of reasons:
  22 </para>
  23
  24 <itemizedlist>
  25     <listitem><para>
  26         To fix bugs and add features that couldn't be done ABI-compatibly.
  27     </para></listitem>
  28
  29     <listitem><para>
  30         To make it easier to generate bindings for libsoup for
  31         languages other than C.
  32     </para></listitem>
  33
  34     <listitem><para>
  35         To clean up ugly/confusing old APIs
  36     </para></listitem>
  37
  38     <listitem><para>
  39         To be more glib/gobject/gtk-like in general.
  40     </para></listitem>
  41 </itemizedlist>
  42
  43 </refsect2>
  44
  45 <refsect2>
  46 <title>SoupMessage</title>
  47
  48 <para>
  49 <link linkend="SoupMessage"><type>SoupMessage</type></link> has had a
  50 number of API changes made, mostly to increase its
  51 language-bindability.
  52 </para>
  53
  54 <refsect3>
  55 <title>SoupMessageHeaders</title>
  56
  57 <para>
  58     <type>SoupMessage</type>'s
  59     <structfield>request_headers</structfield> and
  60     <structfield>response_headers</structfield> fields are now an
  61     opaque type (<link
  62     linkend="SoupMessageHeaders"><type>SoupMessageHeaders</type></link>)
  63     rather than being <type>GHashTables</type>. The method names have
  64     changed slightly to reflect this:
  65 </para>
  66
  67 <variablelist>
  68     <varlistentry>
  69         <term><function>soup_message_add_header</function></term>
  70         <listitem><para>
  71             &#8594; <link linkend="soup-message-headers-append"><function>soup_message_headers_append</function></link>
  72         </para></listitem>
  73     </varlistentry>
  74     <varlistentry>
  75         <term><function>soup_message_get_header</function></term>
  76         <listitem><para>
  77             &#8594; <link linkend="soup-message-headers-get"><function>soup_message_headers_get</function></link>
  78         </para></listitem>
  79     </varlistentry>
  80     <varlistentry>
  81         <term><function>soup_message_foreach_header</function></term>
  82         <listitem><para>
  83             &#8594; <link linkend="soup-message-headers-foreach"><function>soup_message_headers_foreach</function></link>
  84         </para></listitem>
  85     </varlistentry>
  86     <varlistentry>
  87         <term><function>soup_message_remove_header</function></term>
  88         <listitem><para>
  89             &#8594; <link linkend="soup-message-headers-remove"><function>soup_message_headers_remove</function></link>
  90         </para></listitem>
  91     </varlistentry>
  92     <varlistentry>
  93         <term><function>soup_message_clear_headers</function></term>
  94         <listitem><para>
  95             &#8594; <link linkend="soup-message-headers-clear"><function>soup_message_headers_clear</function></link>
  96         </para></listitem>
  97     </varlistentry>
  98 </variablelist>
  99
 100 <para>
 101     <function>soup_message_get_header_list</function> has no equivalent;
 102     if multiple copies of a header are present,
 103     <function>soup_message_headers_get</function> will return all of
 104     them, concatenated together and separated by commas; RFC 2616 says
 105     that the two forms (multiple headers, and a single header with
 106     comma-separated values) are equivalent; this change to libsoup
 107     ensures that applications will treat them as equivalent.
 108 </para>
 109
 110 <para>
 111     In addition, certain important header fields now have
 112     dedicated get/set methods:
 113 </para>
 114
 115 <itemizedlist>
 116     <listitem><para>
 117         <link linkend="soup-message-headers-get-encoding"><function>soup_message_headers_get_encoding</function></link> / <link linkend="soup-message-headers-set-encoding"><function>soup_message_headers_set_encoding</function></link>
 118     </para></listitem>
 119
 120     <listitem><para>
 121         <link linkend="soup-message-headers-get-content-length"><function>soup_message_headers_get_content_length</function></link> / <link linkend="soup-message-headers-set-content-length"><function>soup_message_headers_set_content_length</function></link>
 122     </para></listitem>
 123
 124     <listitem><para>
 125         <link linkend="soup-message-headers-get-expectations"><function>soup_message_headers_get_expectations</function></link> / <link linkend="soup-message-headers-set-expectations"><function>soup_message_headers_set_expectations</function></link>
 126     </para></listitem>
 127 </itemizedlist>
 128
 129 <para>
 130     (<literal>soup_message_headers_set_expectation(msg,&#160;SOUP_EXPECTATION_CONTINUE)</literal>
 131     replaces the <literal>SOUP_MESSAGE_EXPECT_CONTINUE</literal>
 132     message flag).
 133 </para>
 134
 135 </refsect3>
 136
 137 <refsect3>
 138 <title>SoupMessageBody</title>
 139
 140 <para>
 141     Similarly, the <structfield>request_body</structfield> and
 142     <structfield>response</structfield> fields (renamed from
 143     <structfield>request</structfield> and <structfield>response</structfield>) are
 144     now a new type, <link
 145     linkend="SoupMessageBody"><type>SoupMessageBody</type></link>,
 146     implemented in terms of <link
 147     linkend="SoupBuffer"><type>SoupBuffer</type></link>, a refcounted
 148     memory buffer type with clearer semantics than the old
 149     <type>SoupDataBuffer</type>/<type>SoupOwnership</type>.
 150 </para>
 151
 152 <variablelist>
 153     <varlistentry>
 154         <term><literal>SOUP_BUFFER_STATIC</literal></term>
 155         <listitem><para>
 156             &#8594; <link
 157             linkend="SOUP-MEMORY-STATIC:CAPS"><literal>SOUP_MEMORY_STATIC</literal></link>
 158         </para></listitem>
 159     </varlistentry>
 160     <varlistentry>
 161         <term><literal>SOUP_BUFFER_SYSTEM_OWNED</literal></term>
 162         <listitem><para>
 163             &#8594; <link
 164             linkend="SOUP-MEMORY-TAKE:CAPS"><literal>SOUP_MEMORY_TAKE</literal></link>
 165             (meaning <application>libsoup</application>
 166             should take ownership of the memory from your).
 167         </para></listitem>
 168     </varlistentry>
 169     <varlistentry>
 170         <term><literal>SOUP_BUFFER_USER_OWNED</literal></term>
 171         <listitem><para>
 172             &#8594; <link
 173             linkend="SOUP-MEMORY-COPY:CAPS"><literal>SOUP_MEMORY_COPY</literal></link>
 174             (meaning <application>libsoup</application>
 175             should make a copy of the memory, because you
 176             can't make any guarantees about how long it will
 177             last.)
 178         </para></listitem>
 179     </varlistentry>
 180 </variablelist>
 181
 182 <para>
 183     A fourth <type>SoupMemoryUse</type> value is also available: <link
 184     linkend="SOUP-MEMORY-TEMPORARY:CAPS"><literal>SOUP_MEMORY_TEMPORARY</literal></link>,
 185     which helps to avoid extra copies in some cases.
 186     <literal>SOUP_MEMORY_TEMPORARY</literal> means that the memory
 187     will last at least as long as the object you are handing it to (a
 188     <type>SoupBuffer</type>, <type>SoupMessageBody</type>, or
 189     <type>SoupMessage</type>), and so doesn't need to be copied right
 190     away, but that if anyone makes a copy of the buffer,
 191     <application>libsoup</application> needs to make a new copy of the
 192     memory for them at that point, since the original pointer may not
 193     remain valid for the lifetime of the new copy.
 194 </para>
 195
 196 <para>
 197     (In the future, there may be additional <type>SoupBuffer</type>
 198     and <type>SoupMessageBody</type> methods to work directly with
 199     mmapped memory, splicing to file descriptors, etc.)
 200 </para>
 201
 202 <para>
 203     <link
 204         linkend="soup-message-set-request"><function>soup_message_set_request</function></link>
 205     and <link
 206     linkend="soup-message-set-response"><function>soup_message_set_response</function></link>
 207     still work roughly like they used to.
 208 </para>
 209
 210 <para>
 211     Unlike the old <structfield>request</structfield> and
 212     <structfield>response</structfield> fields, the new
 213     <structfield>request_body</structfield> and
 214     <structfield>response_body</structfield> fields are not guaranteed
 215     to be filled in at all times. (In particular, the
 216     <structfield>response_body</structfield> is not filled in until it
 217     has been fully read, although you can use <link
 218     linkend="soup-message-body-get-chunk"><function>soup_message_body_get_chunk</function></link>
 219     to iterate through the chunks before that point if you need to.)
 220 </para>
 221
 222 <para>
 223     When <structfield>request_body</structfield> and
 224     <structfield>response_body</structfield> <emphasis>are</emphasis>
 225     filled in, they are <literal>'\0'</literal>-terminated for your
 226     processing convenience. (The terminating 0 byte is not included in
 227     their length.)
 228 </para>
 229
 230 </refsect3>
 231
 232 <refsect3>
 233 <title>Chunked encoding</title>
 234
 235 <para>
 236     The prototype of the <link
 237     linkend="SoupMessage-got-chunk"><literal>SoupMessage::got_chunk</literal></link>
 238     signal has been changed; it now includes the chunk as a
 239     <type>SoupBuffer</type> parameter (rather than storing the chunk
 240     data in <literal>msg->response</literal> as in 2.2). <link
 241     linkend="SoupMessageFlags"><literal>SOUP_MESSAGE_OVERWRITE_CHUNKS</literal></link>
 242     is now somewhat poorly named, but still has essentially the same
 243     semantics: if you set it, each chunk will be discarded after it is
 244     read, and <literal>msg->response_body</literal> will not be filled
 245     in with the complete response at the end of message processing.
 246 </para>
 247
 248 <para>
 249     The API for sending chunked responses from a
 250     <type>SoupServer</type> is also slightly different now:
 251 </para>
 252
 253 <variablelist>
 254     <varlistentry>
 255         <term><function>soup_server_message_set_encoding</function></term>
 256         <listitem><para>
 257             &#8594; <link
 258             linkend="soup-message-headers-set-encoding"><function>soup_message_headers_set_encoding</function></link>
 259         </para></listitem>
 260     </varlistentry>
 261     <varlistentry>
 262         <term><function>soup_message_add_chunk</function></term>
 263         <listitem><para>
 264             &#8594; <link
 265             linkend="soup-message-body-append"><function>soup_message_body_append</function></link>
 266             or <link
 267             linkend="soup-message-body-append-buffer"><function>soup_message_body_append_buffer</function></link>
 268         </para></listitem>
 269     </varlistentry>
 270     <varlistentry>
 271         <term><function>soup_message_add_final_chunk</function></term>
 272         <listitem><para>
 273             &#8594; <link
 274             linkend="soup-message-body-complete"><function>soup_message_body_complete</function></link>
 275         </para></listitem>
 276     </varlistentry>
 277 </variablelist>
 278
 279 <para>
 280     Since the new chunk-sending APIs require you to explicitly pass
 281     the
 282     <structfield>request_headers</structfield>/<structfield>request_body</structfield>
 283     fields, rather than just assuming you're talking about the
 284     response body, in theory it is now possible to use chunked
 285     encoding with the request as well. As of the 2.3.0 release this
 286     has not yet been tested.
 287 </para>
 288
 289 </refsect3>
 290
 291 <refsect3>
 292 <title>Methods</title>
 293
 294 <para>
 295     <type>SoupMessage</type>'s
 296     <structfield>method</structfield> field is now an interned
 297     string, and you can compare the method directly against
 298     the defines such as <link
 299     linkend="SOUP-METHOD-GET:CAPS"><literal>SOUP_METHOD_GET</literal></link>
 300     (eg, in a <type>SoupServer</type> request handler).
 301     <function>soup_method_get_id</function> and the
 302     <literal>SOUP_METHOD_ID_*</literal> macros are now gone.
 303 </para>
 304 </refsect3>
 305
 306 <refsect3>
 307 <title>Handlers</title>
 308
 309 <para>
 310     <link
 311     linkend="soup-message-add-header-handler"><function>soup_message_add_header_handler</function></link>
 312     and <link
 313     linkend="soup-message-add-status-code-handler"><function>soup_message_add_status_code_handler</function></link>
 314     are now just clever wrappers around
 315     <function>g_signal_connect</function>. In particular, you now pass
 316     a signal name to them rather than a <type>SoupHandlerPhase</type>,
 317     and you remove them with the normal signal handler remove methods.
 318     However, they still retain the special behavior that if the
 319     message has been cancelled or requeued when the time comes for the
 320     handler to run, then the handler will be skipped. (Use plain
 321     <function>g_signal_connect</function> if you don't want that
 322     behavior.)
 323 </para>
 324 </refsect3>
 325
 326 <refsect3>
 327 <title>I/O-related <type>SoupMessage</type> methods</title>
 328
 329 <para>
 330     <function>soup_message_io_pause</function> and
 331     <function>soup_message_io_unpause</function> have been moved to
 332     <type>SoupSession</type> and <type>SoupServer</type>, to better
 333     reflect the fact that the session/server control the I/O, and
 334     <type>SoupMessage</type> is merely acted-upon by them.
 335 </para>
 336
 337 <variablelist>
 338     <varlistentry>
 339         <term><function>soup_message_io_pause</function></term>
 340         <listitem><para>
 341             &#8594; <link linkend="soup-session-pause-message"><function>soup_session_pause_message</function></link> / <link linkend="soup-server-pause-message"><function>soup_server_pause_message</function></link>
 342         </para></listitem>
 343     </varlistentry>
 344     <varlistentry>
 345         <term><function>soup_message_io_unpause</function></term>
 346         <listitem><para>
 347             &#8594; <link linkend="soup-session-unpause-message"><function>soup_session_unpause_message</function></link> / <link linkend="soup-server-unpause-message"><function>soup_server_unpause_message</function></link>
 348         </para></listitem>
 349     </varlistentry>
 350 </variablelist>
 351
 352 <para>
 353     <literal>msg->status</literal> (the I/O status) is now
 354     gone as well, because (a) it's really an internal state of
 355     <type>SoupSession</type>, and (b) it's too easy to confuse
 356     with <literal>msg->status_code</literal> (the HTTP status)
 357     anyway. Code that used to check if status was
 358     <literal>SOUP_MESSAGE_STATUS_FINISHED</literal> needs to
 359     be rewritten to track whether or not the <link
 360     linkend="SoupMessage-finished"><literal>finished</literal></link>
 361     signal has been emitted.
 362 </para>
 363
 364 </refsect3>
 365
 366 <refsect3>
 367 <title>HTTP-Version</title>
 368
 369 <para>
 370     <type>SoupHttpVersion</type> is now <link
 371     linkend="SoupHTTPVersion"><type>SoupHTTPVersion</type></link>
 372 </para>
 373 </refsect3>
 374
 375 </refsect2>
 376
 377 <refsect2>
 378 <title>SoupSession</title>
 379
 380 <refsect3>
 381 <title><function>soup_session_queue_message</function> callback</title>
 382
 383 <para>
 384     <link
 385     linkend="soup-session-queue-message"><function>soup_session_queue_message</function></link>'s
 386     callback parameter now includes the <type>SoupSession</type> as a
 387     parameter, reflecting the fact that it is a
 388     <type>SoupSession</type> callback, not a <type>SoupMessage</type>
 389     callback. (It has also been renamed, from
 390     <type>SoupMessageCallbackFn</type> to <link
 391     linkend="SoupSessionCallback"><type>SoupSessionCallback</type></link>.)
 392 </para>
 393 </refsect3>
 394
 395 <refsect3>
 396 <title>Authentication</title>
 397
 398 <para>
 399     <type>SoupSession</type>'s <literal>authenticate</literal> and
 400     <literal>reauthenticate</literal> signals have been merged into a
 401     single <link
 402     linkend="SoupSession-authenticate"><literal>authenticate</literal></link>
 403     signal with a <parameter>retrying</parameter> parameter to indicate if
 404     it's the second (or later) try. Also, the signal now includes a
 405     <link linkend="SoupAuth"><type>SoupAuth</type></link> directly,
 406     and you authenticate by calling <link
 407     linkend="soup-auth-authenticate"><function>soup_auth_authenticate</function></link>
 408     on the auth (rather than passing back a username and password from
 409     the signal handler).
 410 </para>
 411 </refsect3>
 412
 413 <refsect3>
 414 <title><type>SoupLogger</type></title>
 415
 416 <para>
 417 <link linkend="libsoup-SoupLogger"><type>SoupLogger</type></link> is a
 418 new object that copies the behavior of
 419 <application>evolution-exchange</application>'s
 420 <literal>E2K_DEBUG</literal> and its clones. That is, it causes a
 421 <type>SoupSession</type> to start logging some or all of its HTTP
 422 traffic to stdout, for debugging purposes.
 423 </para>
 424 </refsect3>
 425
 426 <refsect3>
 427 <title><type>SoupMessageFilter</type></title>
 428
 429 <para>
 430     <type>SoupMessageFilter</type> is gone; code that used to use it
 431     can now connect to the <link
 432     linkend="SoupSession-request-started"><literal>SoupSession::request-started</literal></link>
 433     signal to get a chance to act on each message as it is sent.
 434     (This is how <type>SoupLogger</type> works.)
 435 </para>
 436 </refsect3>
 437
 438 <refsect3>
 439 <title>Internal types</title>
 440
 441 <para>
 442     The <type>SoupConnection</type> and <type>SoupMessageQueue</type>
 443     types (which should always have been internal to
 444     <type>SoupSession</type>) have been removed from the public API.
 445 </para>
 446 </refsect3>
 447
 448 </refsect2>
 449
 450 <refsect2>
 451 <title>SoupURI</title>
 452
 453 <type>SoupUri</type> has been renamed <link
 454 linkend="SoupURI"><type>SoupURI</type></link>, and its behavior has
 455 changed in a few ways:
 456
 457 <itemizedlist>
 458     <listitem>
 459         <para>
 460             It no longer fully-decodes %-encoded URI components. This
 461             is necessary to ensure that complicated URIs (eg, URIs
 462             that include other URIs as query parameters) can be
 463             round-tripped correctly. This corresponds to the old
 464             <structfield>broken_encoding</structfield> behavior, but
 465             that flag no longer exists, since it is the default and
 466             there's no way to turn it off.
 467         </para>
 468
 469         <para>
 470             In theory, this is an ABI-breaking change, especially for
 471             <link
 472             linkend="SoupServer"><type>SoupServer</type></link>s.
 473             However, it is unlikely to actually break anything. (And
 474             in the <type>SoupServer</type> case, servers now
 475             fully-decode the <structfield>path</structfield> component
 476             themselves unless you set the <link
 477             linkend="SOUP-SERVER-RAW-PATHS:CAPS"><literal>SOUP_SERVER_RAW_PATHS</literal></link>
 478             flag on the server, so the behavior should still be the
 479             same.
 480         </para>
 481     </listitem>
 482
 483     <listitem><para>
 484         It uses the RFC3986 parsing rules, including support for IPv6 literal
 485         addresses.
 486     </para></listitem>
 487
 488     <listitem>
 489         <para>
 490             The field formerly called
 491             <structfield>protocol</structfield> is now
 492             <structfield>scheme</structfield>, to match the spec, and
 493             it's an interned string rather than a quark. The names of
 494             the predefined values have changed to match:
 495         </para>
 496
 497         <variablelist>
 498             <varlistentry>
 499                 <term><function>SOUP_PROTOCOL_HTTP</function></term>
 500                 <listitem><para>
 501                     &#8594; <link linkend="SOUP-URI-SCHEME-HTTP:CAPS"><literal>SOUP_URI_SCHEME_HTTP</literal></link>
 502                 </para></listitem>
 503             </varlistentry>
 504             <varlistentry>
 505                 <term><function>SOUP_PROTOCOL_HTTPS</function></term>
 506                 <listitem><para>
 507                     &#8594; <link linkend="SOUP-URI-SCHEME-HTTPS:CAPS"><literal>SOUP_URI_SCHEME_HTTPS</literal></link>
 508                 </para></listitem>
 509             </varlistentry>
 510         </variablelist>
 511     </listitem>
 512 </itemizedlist>
 513
 514 <para>
 515 <link linkend="soup-uri-decode"><function>soup_uri_decode</function></link>
 516 now returns a new string rather than modifying its input string in
 517 place. The new method <link
 518 linkend="soup-uri-normalize"><function>soup_uri_normalize</function></link>,
 519 which removes some, but not all, %-encoding, behaves similarly.
 520 </para>
 521
 522 <para>
 523 Finally, <type>SoupURI</type> (as well as most other struct types in
 524 <application>libsoup</application>) now uses the glib "slice"
 525 allocator, so any code that uses <link
 526 linkend="g-new"><function>g_new</function></link> to create
 527 <type>SoupURI</type>s is wrong. If you want to create a URI "by hand",
 528 you can call <link
 529 linkend="soup-uri-new"><function>soup_uri_new</function></link>,
 530 passing <literal>NULL</literal>, and you will get back an empty
 531 <type>SoupURI</type>. There are also now methods that can be used to
 532 set its fields (eg, <link
 533 linkend="soup-uri-set-scheme"><function>soup_uri_set_scheme</function></link>,
 534 <link
 535 linkend="soup-uri-set-path"><function>soup_uri_set_path</function></link>,
 536 etc) rather than mucking with the fields directly.
 537 </para>
 538
 539 <refsect3>
 540 <title>Forms</title>
 541
 542 <para>
 543 Related to <type>SoupURI</type>, there are some new helper methods for
 544 dealing with HTML forms. <link
 545 linkend="soup-form-decode-urlencoded">soup_form_decode_urlencoded</link>
 546 decodes a URI <structfield>query</structfield> component (or an
 547 <literal>application/x-www-form-urlencoded</literal> request body)
 548 into a <type>GHashTable</type>. <link
 549 linkend="soup-form-encode-urlencoded">soup_form_encode_urlencoded</link>
 550 reverses the process, allowing you to fill in a
 551 <literal>uri->query</literal> with a properly-encoded form dataset.
 552 (<type>SoupURI</type> also provides <link
 553 linkend="soup-uri-set-query-from-form"><function>soup_uri_set_query_from_form</function></link>
 554 to help with this.)
 555 </para>
 556 </refsect3>
 557
 558 </refsect2>
 559
 560
 561 <refsect2>
 562 <title>XML-RPC and SOAP</title>
 563
 564 <refsect3>
 565 <title>SOAP</title>
 566 <para>
 567 SOAP support has been removed; the existing methods covered only a
 568 teeny tiny subset of SOAP, which was really only useful to a single
 569 application. (The code that was formerly in libsoup has been moved to
 570 that application.). If you were using this code, you can resurrect a
 571 libsoup-2.4-compatible version of it from revision 1016 of libsoup
 572 svn.
 573 </para>
 574 </refsect3>
 575
 576 <refsect3>
 577 <title>XML-RPC</title>
 578 <para>
 579 The XML-RPC code has been completely rewritten to make it simpler to
 580 implement XML-RPC clients and servers. (Note: the server-side code has
 581 not been heavily tested yet.) The <link
 582 linkend="libsoup-XMLRPC-Support">new XML-RPC API</link> makes use of
 583 <type>GValue</type>s, with the following type mappings:
 584 </para>
 585
 586 <variablelist>
 587     <varlistentry>
 588         <term><literal>int</literal></term>
 589         <listitem><para>
 590             &#8594; <type>int</type> (<link linkend="G-TYPE-INT:CAPS"><literal>G_TYPE_INT</literal></link>)
 591         </para></listitem>
 592     </varlistentry>
 593     <varlistentry>
 594         <term><literal>boolean</literal></term>
 595         <listitem><para>
 596             &#8594; <type>gboolean</type> (<link linkend="G-TYPE-BOOLEAN:CAPS"><literal>G_TYPE_BOOLEAN</literal></link>)
 597         </para></listitem>
 598     </varlistentry>
 599     <varlistentry>
 600         <term><literal>string</literal></term>
 601         <listitem><para>
 602             &#8594; <type>char *</type> (<link linkend="G-TYPE-STRING:CAPS"><literal>G_TYPE_STRING</literal></link>)
 603         </para></listitem>
 604     </varlistentry>
 605     <varlistentry>
 606         <term><literal>double</literal></term>
 607         <listitem><para>
 608             &#8594; <type>double</type> (<link linkend="G-TYPE-DOUBLE:CAPS"><literal>G_TYPE_DOUBLE</literal></link>)
 609         </para></listitem>
 610     </varlistentry>
 611     <varlistentry>
 612         <term><literal>dateTime.iso8601</literal></term>
 613         <listitem><para>
 614             &#8594; <link linkend="SoupDate"><type>SoupDate</type></link> (<link linkend="SOUP-TYPE-DATE:CAPS"><literal>SOUP_TYPE_DATE</literal></link>)
 615         </para></listitem>
 616     </varlistentry>
 617     <varlistentry>
 618         <term><literal>base64</literal></term>
 619         <listitem><para>
 620             &#8594; <type>GByteArray</type> (<link linkend="SOUP-TYPE-BYTE-ARRAY:CAPS"><literal>SOUP_TYPE_BYTE_ARRAY</literal></link>)
 621         </para></listitem>
 622     </varlistentry>
 623     <varlistentry>
 624         <term><literal>struct</literal></term>
 625         <listitem><para>
 626             &#8594; <type>GHashTable</type> (<link linkend="G-TYPE-HASH-TABLE:CAPS"><literal>G_TYPE_HASH_TABLE</literal></link>)
 627         </para></listitem>
 628     </varlistentry>
 629     <varlistentry>
 630         <term><literal>array</literal></term>
 631         <listitem><para>
 632             &#8594; <type>GValueArray</type> (<link linkend="G-TYPE-VALUE-ARRAY:CAPS"><literal>G_TYPE_VALUE_ARRAY</literal></link>)
 633         </para></listitem>
 634     </varlistentry>
 635 </variablelist>
 636
 637 <para>
 638 <type>SoupDate</type> is discussed below.
 639 <literal>SOUP_TYPE_BYTE_ARRAY</literal> is just a new
 640 <type>GType</type> value defined by <application>libsoup</application>
 641 to represent <type>GByteArray</type>s, which glib does not define a
 642 <type>GType</type> for.
 643 </para>
 644
 645 <para>
 646 <application>libsoup</application> provides some additional <link
 647 linkend="libsoup-GValue-Support"><type>GValue</type> support
 648 methods</link> for working with
 649 <type>GValueArray</type>s, and <type>GHashTable</type>s of
 650 <type>GValue</type>s, for the XML-RPC <literal>struct</literal> and
 651 <literal>array</literal> types. Eg, you can use <link
 652 linkend="soup-value-hash-new"><function>soup_value_hash_new</function></link>
 653 to create a <type>GHashTable</type> to use with the XML-RPC methods,
 654 and <link
 655 linkend="soup-value-hash-insert"><function>soup_value_hash_insert</function></link>
 656 to add values to it without needing to muck with <type>GValue</type>s
 657 directly.
 658 </para>
 659
 660 <para>
 661 The <literal>getbug</literal> and <literal>xmlrpc-test</literal>
 662 programs in the <application>libsoup</application> sources provide
 663 examples of how to use the new API. (Beware that
 664 <literal>xmlrpc-test</literal>'s use of the API is a little
 665 complicated because of the way it sends all calls through a single
 666 <literal>do_xmlrpc</literal> method.)
 667 </para>
 668
 669 </refsect3>
 670 </refsect2>
 671
 672 <refsect2>
 673 <title>SoupServer</title>
 674
 675 <refsect3>
 676 <title>SoupServer handlers</title>
 677
 678 <para>
 679     The prototypes for <link
 680     linkend="soup-server-add-handler"><function>soup_server_add_handler</function></link>,
 681     and for the <link
 682     linkend="SoupServerCallback"><type>SoupServer</type>
 683     handlers</link> themselves have changed:
 684 </para>
 685
 686 <informalexample><programlisting>
 687 typedef void (*SoupServerCallback)     (SoupServer         *server,
 688                                         SoupMessage        *msg,
 689                                         const char         *path,
 690                                         GHashTable         *query,
 691                                         SoupClientContext  *client,
 692                                         gpointer            user_data);
 693
 694 void           soup_server_add_handler (SoupServer         *server,
 695                                         const char         *path,
 696                                         SoupServerCallback  callback,
 697                                         gpointer            data,
 698                                         GDestroyNotify      destroy);
 699 </programlisting></informalexample>
 700
 701 <para>
 702     <function>soup_server_add_handler</function> no longer takes a
 703     <type>SoupServerAuthContext</type> (see the discussion of server
 704     authentication below), and the order of the final two arguments
 705     has been swapped. (Additionally, <type>SoupServerCallbackFn</type>
 706     has been renamed to <type>SoupServerCallback</type>, and the old
 707     <parameter>unregister</parameter> parameter of type
 708     <type>SoupServerUnregisterFn</type> is now a standard
 709     <type>GDestroyNotify</type>. The change to
 710     <type>GDestroyNotify</type> and the swapping of the final two
 711     arguments is to make the method conform to standard glib/gtk
 712     practices.)
 713 </para>
 714
 715 <para>
 716     In <type>SoupServerCallback</type>, several bits of data that used
 717     to be part of the <parameter>context</parameter> argument are now
 718     provided directly, and <parameter>context</parameter> specifically
 719     only contains more specifically-client-related information (such
 720     as the <type>SoupSocket</type> that the request arrived on, and
 721     information about authentication).
 722 </para>
 723
 724 <para>
 725     <parameter>path</parameter> is the fully %-decoded path component
 726     of <parameter>msg</parameter>'s URI, and
 727     <parameter>query</parameter> is a hash table containing
 728     <parameter>msg</parameter>'s URI's
 729     <structfield>query</structfield> component decoded with <link
 730     linkend="soup-form-decode-urlencoded">soup_form_decode_urlencoded</link>.
 731     These are provided for your convenience; if you need the raw
 732     query, you can get it out of <parameter>msg</parameter>'s URI
 733     directly. If you need the raw path, you'll need to set the <link
 734     linkend="SOUP-SERVER-RAW-PATHS:CAPS"><literal>SOUP_SERVER_RAW_PATHS</literal></link>
 735     property on the server, which actually changes the behavior of the
 736     server with respect to how paths are matched; see the
 737     documentation for details.
 738 </para>
 739 </refsect3>
 740
 741 <refsect3>
 742 <title>Server-side authentication</title>
 743
 744 <para>
 745     <type>SoupServer</type> authentication has been completely
 746     rewritten, with <type>SoupServerAuthContext</type> being replaced
 747     with <link
 748     linkend="SoupAuthDomain"><type>SoupAuthDomain</type></link>. Among
 749     other improvements, you no longer need to have the cleartext
 750     password available to check against. See the
 751     <type>SoupAuthDomain</type> documentation, the <link
 752     linkend="libsoup-server-howto">server tutorial</link>, and
 753     <literal>tests/server-auth-test.c</literal>.
 754 </para>
 755 </refsect3>
 756
 757 <refsect3>
 758 <title><literal>Expect: 100-continue</literal> and other early <type>SoupMessage</type> processing</title>
 759
 760 <para>
 761     <type>SoupServer</type> now handles
 762     "<literal>Expect:&#160;100-continue</literal>" correctly. In
 763     particular, if the client passes that header, and your server
 764     requires authentication, then authentication will be checked
 765     before reading the request body.
 766 </para>
 767
 768 <para>
 769     If you want to do additional pre-request-body handling, you can
 770     connect to <type>SoupServer</type>'s <link
 771     linkend="SoupServer-request-started"><literal>request_started</literal></link>
 772     signal, and connect to the request's <link
 773     linkend="SoupMessage-got-headers"><literal>got_headers</literal></link>
 774     signal from there. (See the description of
 775     <literal>request_started</literal> for information about other
 776     related <type>SoupServer</type> signals.)
 777 </para>
 778 </refsect3>
 779
 780 <refsect3>
 781 <title>Date header</title>
 782
 783 <para>
 784     <type>SoupServer</type> now automatically sets the
 785     <literal>Date</literal> header on all responses, as required by
 786     RFC 2616.
 787 </para>
 788 </refsect3>
 789
 790 <refsect3>
 791 <title>SoupServerMessage</title>
 792
 793 <para>
 794     <type>SoupServerMessage</type> is now merged into
 795     <type>SoupMessage</type>.
 796     <function>soup_server_message_set_encoding</function> is replaced
 797     with <link
 798     linkend="soup-message-headers-set-encoding"><function>soup_message_headers_set_encoding</function></link>
 799     as described in the section on <type>SoupMessage</type> above.
 800 </para>
 801 </refsect3>
 802
 803 <refsect3>
 804 <title><function>soup_server_run</function> / <function>soup_server_quit</function></title>
 805
 806 <para>
 807     <link
 808     linkend="soup-server-run"><function>soup_server_run</function></link>
 809     and <link
 810     linkend="soup-server-run-async"><function>soup_server_run_async</function></link>
 811     no longer <function>g_object_ref</function> the server, and
 812     <link
 813     linkend="soup-server-quit"><function>soup_server_quit</function></link>
 814     no longer unrefs it.
 815 </para>
 816 </refsect3>
 817
 818 </refsect2>
 819
 820 <refsect2>
 821 <title>Miscellaneous</title>
 822
 823 <refsect3>
 824 <title>SoupDate</title>
 825
 826 <para>
 827     The new <link linkend="SoupDate"><type>SoupDate</type></link> type
 828     replaces the old <function>soup_date_*</function> methods, and has
 829     an improved (more liberal) date parser.
 830 </para>
 831 </refsect3>
 832
 833 <refsect3>
 834 <title>Header parsing</title>
 835
 836 <para>
 837     <literal>soup-headers.h</literal> now has a few additional methods
 838     for parsing list-type headers.
 839 </para>
 840 </refsect3>
 841
 842 <refsect3>
 843 <title>SoupAddress, SoupSocket</title>
 844
 845 <para>
 846     <type>SoupSocket</type> has had various simplifications made to
 847     reflect the fact that this is specifically libsoup's socket
 848     implementation, not some random generic socket API.
 849 </para>
 850
 851 <para>
 852     Various <type>SoupAddress</type> and <type>SoupSocket</type>
 853     methods now take arguments of the new <link
 854     linkend="GCancellable"><type>GCancellable</type></link> type, from
 855     libgio. When porting old code, you can just pass
 856     <literal>NULL</literal> for these. (<link
 857     linkend="soup-address-resolve-async"><function>soup_address_resolve_async</function></link>
 858     also takes another new argument, a <link
 859     linkend="GMainContext"><type>GMainContext</type></link> that
 860     you'll want to pass <literal>NULL</literal> for.) If you pass a
 861     <type>GCancellable</type>, you can use it to cleanly cancel the
 862     address resolution / socket operation.
 863 </para>
 864
 865 </refsect3>
 866
 867 <refsect3>
 868 <title>Base64 methods</title>
 869
 870 <para>
 871     The deprecated base64 methods are now gone; use glib's base64
 872     methods instead.
 873 </para>
 874 </refsect3>
 875
 876 </refsect2>
 877
 878 </refentry>