Additional Features

Authentication
Caching
Cookie Storage Support
HSTS Support
Metrics
<refentry> <refmeta> <refentrytitle>SoupSessionFeature</refentrytitle> <manvolnum>3</manvolnum> <refmiscinfo>LIBSOUP-3.0 Library</refmiscinfo> </refmeta>

<refentrytitle>SoupSessionFeature</refentrytitle>

<refname>SoupSessionFeature</refname> <refpurpose>Interface for miscellaneous session features</refpurpose>

<refsect1> <title>Types and Values</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <tbody> <row><entry></entry><entry>SoupSessionFeature</entry></row> </tbody> </tgroup> </informaltable> </refsect1> <refsect1> <title>Object Hierarchy</title> <screen> GInterface <phrase>╰──</phrase> SoupSessionFeature </screen> </refsect1> <refsect1> <title>Prerequisites</title> <para> SoupSessionFeature requires GObject.</para> </refsect1> <refsect1> <title>Known Implementations</title> <para> SoupSessionFeature is implemented by SoupAuthManager, SoupCache, SoupContentDecoder, SoupContentSniffer, SoupCookieJar, SoupCookieJarDB, SoupCookieJarText, SoupHSTSEnforcer, SoupHSTSEnforcerDB, SoupLogger and SoupWebsocketExtensionManager.</para> </refsect1> <refsect1><title>Includes</title><synopsis>#include <libsoup/soup.h> </synopsis></refsect1> <refsect1> <title>Description</title> <para><type>SoupSessionFeature</type> is the interface used by classes that extend the functionality of a <type>SoupSession</type>. Some features like HTTP authentication handling are implemented internally via <type>SoupSessionFeature</type>s. Other features can be added to the session by the application. (Eg, <type>SoupLogger</type>, <type>SoupCookieJar</type>.)</para> <para>See <function>soup_session_add_feature()</function>, etc, to add a feature to a session.</para> </refsect1> <refsect1> <title>Functions</title> <para></para> </refsect1> <refsect1> <title>Types and Values</title> <refsect2> <title>SoupSessionFeature</title> <programlisting>typedef struct _SoupSessionFeature SoupSessionFeature;</programlisting> <para>An object that implement some sort of optional feature for <type>SoupSession</type>.</para> </refsect2> </refsect1> </refentry><refentry> <refmeta> <refentrytitle>SoupContentDecoder</refentrytitle> <manvolnum>3</manvolnum> <refmiscinfo>LIBSOUP-3.0 Library</refmiscinfo> </refmeta>

<refentrytitle>SoupContentDecoder</refentrytitle>

<refname>SoupContentDecoder</refname> <refpurpose>Content-Encoding handler</refpurpose>

<refsect1> <title>Types and Values</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <tbody> <row><entry></entry><entry>SoupContentDecoder</entry></row> </tbody> </tgroup> </informaltable> </refsect1> <refsect1> <title>Object Hierarchy</title> <screen> GObject <phrase>╰──</phrase> SoupContentDecoder </screen> </refsect1> <refsect1> <title>Implemented Interfaces</title> <para> SoupContentDecoder implements SoupSessionFeature and SoupContentProcessor.</para> </refsect1> <refsect1><title>Includes</title><synopsis>#include <libsoup/soup.h> </synopsis></refsect1> <refsect1> <title>Description</title> <para><type>SoupContentDecoder</type> handles adding the "Accept-Encoding" header on outgoing messages, and processing the "Content-Encoding" header on incoming ones. Currently it supports the "gzip", "deflate", and "br" content codings.</para> <para>A <type>SoupContentDecoder</type> will automatically be added to the session by default. (You can use <function>soup_session_remove_feature_by_type()</function> if you don't want this.)</para> <para>If <type>SoupContentDecoder</type> successfully decodes the Content-Encoding, the message body will contain the decoded data; however, the message headers will be unchanged (and so "Content-Encoding" will still be present, "Content-Length" will describe the original encoded length, etc).</para> <para>If "Content-Encoding" contains any encoding types that <type>SoupContentDecoder</type> doesn't recognize, then none of the encodings will be decoded.</para> <para>(Note that currently there is no way to (automatically) use Content-Encoding when sending a request body, or to pick specific encoding types to support.)</para> </refsect1> <refsect1> <title>Functions</title> <para></para> </refsect1> <refsect1> <title>Types and Values</title> <refsect2> <title>SoupContentDecoder</title> <programlisting>typedef struct _SoupContentDecoder SoupContentDecoder;</programlisting> <para>Class handling decoding of HTTP messages.</para> </refsect2> </refsect1> </refentry><refentry> <refmeta> <refentrytitle>SoupContentSniffer</refentrytitle> <manvolnum>3</manvolnum> <refmiscinfo>LIBSOUP-3.0 Library</refmiscinfo> </refmeta>

<refentrytitle>SoupContentSniffer</refentrytitle>

<refname>SoupContentSniffer</refname> <refpurpose>Content sniffing for SoupSession</refpurpose>

<refsect1> <title>Functions</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><returnvalue>SoupContentSniffer</returnvalue> * </entry><entry>soup_content_sniffer_new <phrase>()</phrase></entry></row> <row><entry><returnvalue>char</returnvalue> * </entry><entry>soup_content_sniffer_sniff <phrase>()</phrase></entry></row> </tbody> </tgroup> </informaltable> </refsect1> <refsect1> <title>Types and Values</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <tbody> <row><entry></entry><entry>SoupContentSniffer</entry></row> </tbody> </tgroup> </informaltable> </refsect1> <refsect1> <title>Object Hierarchy</title> <screen> GObject <phrase>╰──</phrase> SoupContentSniffer </screen> </refsect1> <refsect1> <title>Implemented Interfaces</title> <para> SoupContentSniffer implements SoupSessionFeature and SoupContentProcessor.</para> </refsect1> <refsect1><title>Includes</title><synopsis>#include <libsoup/soup.h> </synopsis></refsect1> <refsect1> <title>Description</title> <para>A <type>SoupContentSniffer</type> tries to detect the actual content type of the files that are being downloaded by looking at some of the data before the <type>SoupMessage</type> emits its <type>“got-headers”</type> signal. <type>SoupContentSniffer</type> implements <type>SoupSessionFeature</type>, so you can add content sniffing to a session with <function>soup_session_add_feature()</function> or <function>soup_session_add_feature_by_type()</function>.</para> </refsect1> <refsect1> <title>Functions</title> <refsect2> <title>soup_content_sniffer_new ()</title> <programlisting><returnvalue>SoupContentSniffer</returnvalue> * soup_content_sniffer_new (<parameter><type>void</type></parameter>);</programlisting> <para>Creates a new <type>SoupContentSniffer</type>.</para> <refsect3> <title>Returns</title> <para> a new <type>SoupContentSniffer</type></para> </refsect3></refsect2>
<refsect2> <title>soup_content_sniffer_sniff ()</title> <programlisting><returnvalue>char</returnvalue> * soup_content_sniffer_sniff (<parameter><type>SoupContentSniffer</type> *sniffer</parameter>, <parameter><type>SoupMessage</type> *msg</parameter>, <parameter><type>GBytes</type> *buffer</parameter>, <parameter><type>GHashTable</type> **params</parameter>);</programlisting> <para>Sniffs <parameter>buffer</parameter> to determine its Content-Type. The result may also be influenced by the Content-Type declared in <parameter>msg</parameter> 's response headers.</para> <refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>sniffer</para></entry> <entry><para>a <type>SoupContentSniffer</type></para></entry> <entry></entry></row> <row><entry><para>msg</para></entry> <entry><para>the message to sniff</para></entry> <entry></entry></row> <row><entry><para>buffer</para></entry> <entry><para>a buffer containing the start of <parameter>msg</parameter> 's response body</para></entry> <entry></entry></row> <row><entry><para>params</para></entry> <entry><para>return location for Content-Type parameters (eg, "charset"), or <literal>NULL</literal>. </para></entry> <entry><emphasis>[element-type utf8 utf8][out][transfer full][nullable]</emphasis></entry></row> </tbody></tgroup></informaltable> </refsect3><refsect3> <title>Returns</title> <para> the sniffed Content-Type of <parameter>buffer</parameter> ; this will never be <literal>NULL</literal>, but may be "application/octet-stream".</para> </refsect3></refsect2> </refsect1> <refsect1> <title>Types and Values</title> <refsect2> <title>SoupContentSniffer</title> <programlisting>typedef struct _SoupContentSniffer SoupContentSniffer;</programlisting> <para>Class that attempts to sniff the mime type of messages.</para> </refsect2> </refsect1> </refentry><refentry> <refmeta> <refentrytitle>SoupLogger</refentrytitle> <manvolnum>3</manvolnum> <refmiscinfo>LIBSOUP-3.0 Library</refmiscinfo> </refmeta>

<refentrytitle>SoupLogger</refentrytitle>

<refname>SoupLogger</refname> <refpurpose>Debug logging support</refpurpose>

<refsect1> <title>Functions</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><returnvalue>SoupLogger</returnvalue> * </entry><entry>soup_logger_new <phrase>()</phrase></entry></row> <row><entry><returnvalue>void</returnvalue> </entry><entry>soup_logger_set_max_body_size <phrase>()</phrase></entry></row> <row><entry><returnvalue>int</returnvalue> </entry><entry>soup_logger_get_max_body_size <phrase>()</phrase></entry></row> <row><entry><returnvalue>SoupLoggerLogLevel</returnvalue> </entry><entry><phrase>(</phrase>*SoupLoggerFilter<phrase>)</phrase> <phrase>()</phrase></entry></row> <row><entry><returnvalue>void</returnvalue> </entry><entry>soup_logger_set_request_filter <phrase>()</phrase></entry></row> <row><entry><returnvalue>void</returnvalue> </entry><entry>soup_logger_set_response_filter <phrase>()</phrase></entry></row> <row><entry><returnvalue>void</returnvalue> </entry><entry><phrase>(</phrase>*SoupLoggerPrinter<phrase>)</phrase> <phrase>()</phrase></entry></row> <row><entry><returnvalue>void</returnvalue> </entry><entry>soup_logger_set_printer <phrase>()</phrase></entry></row> </tbody> </tgroup> </informaltable> </refsect1> <refsect1> <title>Properties</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><type>SoupLoggerLogLevel</type></entry><entry>level</entry><entry>Read / Write</entry></row> <row><entry><type>int</type></entry><entry>max-body-size</entry><entry>Read / Write</entry></row> </tbody> </tgroup> </informaltable> </refsect1> <refsect1> <title>Types and Values</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <tbody> <row><entry></entry><entry>SoupLogger</entry></row> <row><entry>enum</entry><entry>SoupLoggerLogLevel</entry></row> </tbody> </tgroup> </informaltable> </refsect1> <refsect1> <title>Object Hierarchy</title> <screen> GObject <phrase>╰──</phrase> SoupLogger </screen> </refsect1> <refsect1> <title>Implemented Interfaces</title> <para> SoupLogger implements SoupSessionFeature and SoupContentProcessor.</para> </refsect1> <refsect1><title>Includes</title><synopsis>#include <libsoup/soup.h> </synopsis></refsect1> <refsect1> <title>Description</title> <para><type>SoupLogger</type> watches a <type>SoupSession</type> and logs the HTTP traffic that it generates, for debugging purposes. Many applications use an environment variable to determine whether or not to use <type>SoupLogger</type>, and to determine the amount of debugging output.</para> <para>To use <type>SoupLogger</type>, first create a logger with <function>soup_logger_new()</function>, optionally configure it with <function>soup_logger_set_request_filter()</function>, <function>soup_logger_set_response_filter()</function>, and <function>soup_logger_set_printer()</function>, and then attach it to a session (or multiple sessions) with <function>soup_session_add_feature()</function>.</para> <para>By default, the debugging output is sent to <literal>stdout</literal>, and looks something like:</para> <informalexample><screen> > POST /unauth HTTP/1.1 > Soup-Debug-Timestamp: 1200171744 > Soup-Debug: SoupSession 1 (0x612190), SoupMessage 1 (0x617000), GSocket 1 (0x612220) > Host: localhost > Content-Type: text/plain > Connection: close < HTTP/1.1 201 Created < Soup-Debug-Timestamp: 1200171744 < Soup-Debug: SoupMessage 1 (0x617000) < Date: Sun, 12 Jan 2008 21:02:24 GMT < Content-Length: 0 </screen></informalexample> <para>The <literal>Soup-Debug-Timestamp</literal> line gives the time (as a <type>time_t</type>) when the request was sent, or the response fully received.</para> <para>The <literal>Soup-Debug</literal> line gives further debugging information about the <type>SoupSession</type>, <type>SoupMessage</type>, and <type>GSocket</type> involved; the hex numbers are the addresses of the objects in question (which may be useful if you are running in a debugger). The decimal IDs are simply counters that uniquely identify objects across the lifetime of the <type>SoupLogger</type>. In particular, this can be used to identify when multiple messages are sent across the same connection.</para> <para>Currently, the request half of the message is logged just before the first byte of the request gets written to the network (from the <type>“starting”</type> signal).</para> <para>The response is logged just after the last byte of the response body is read from the network (from the <type>“got-body”</type> or <type>“got-informational”</type> signal), which means that the <type>“got-headers”</type> signal, and anything triggered off it (such as <type>“authenticate”</type>) will be emitted <emphasis>before</emphasis> the response headers are actually logged.</para> <para>If the response doesn't happen to trigger the <type>“got-body”</type> nor <type>“got-informational”</type> signals due to, for example, a cancellation before receiving the last byte of the response body, the response will still be logged on the event of the <type>“finished”</type> signal.</para> </refsect1> <refsect1> <title>Functions</title> <refsect2> <title>soup_logger_new ()</title> <programlisting><returnvalue>SoupLogger</returnvalue> * soup_logger_new (<parameter><type>SoupLoggerLogLevel</type> level</parameter>);</programlisting> <para>Creates a new <type>SoupLogger</type> with the given debug level.</para> <para>If you need finer control over what message parts are and aren't logged, use <function>soup_logger_set_request_filter()</function> and <function>soup_logger_set_response_filter()</function>.</para> <refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>level</para></entry> <entry><para>the debug level</para></entry> <entry></entry></row> </tbody></tgroup></informaltable> </refsect3><refsect3> <title>Returns</title> <para> a new <type>SoupLogger</type></para> </refsect3></refsect2>
<refsect2> <title>soup_logger_set_max_body_size ()</title> <programlisting><returnvalue>void</returnvalue> soup_logger_set_max_body_size (<parameter><type>SoupLogger</type> *logger</parameter>, <parameter><type>int</type> max_body_size</parameter>);</programlisting> <para>Sets the maximum body size for <parameter>logger</parameter> (-1 means no limit).</para> <refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>logger</para></entry> <entry><para>a <type>SoupLogger</type></para></entry> <entry></entry></row> <row><entry><para>max_body_size</para></entry> <entry><para>the maximum body size to log</para></entry> <entry></entry></row> </tbody></tgroup></informaltable> </refsect3></refsect2>
<refsect2> <title>soup_logger_get_max_body_size ()</title> <programlisting><returnvalue>int</returnvalue> soup_logger_get_max_body_size (<parameter><type>SoupLogger</type> *logger</parameter>);</programlisting> <para>Get the maximum body size for <parameter>logger</parameter> .</para> <refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>logger</para></entry> <entry><para>a <type>SoupLogger</type></para></entry> <entry></entry></row> </tbody></tgroup></informaltable> </refsect3><refsect3> <title>Returns</title> <para> the maximum body size, or -1 if unlimited</para> </refsect3></refsect2>
<refsect2> <title>SoupLoggerFilter ()</title> <programlisting><returnvalue>SoupLoggerLogLevel</returnvalue> <phrase>(</phrase>*SoupLoggerFilter<phrase>)</phrase> (<parameter><type>SoupLogger</type> *logger</parameter>, <parameter><type>SoupMessage</type> *msg</parameter>, <parameter><type>gpointer</type> user_data</parameter>);</programlisting> <para>The prototype for a logging filter. The filter callback will be invoked for each request or response, and should analyze it and return a <type>SoupLoggerLogLevel</type> value indicating how much of the message to log.</para> <refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>logger</para></entry> <entry><para>the <type>SoupLogger</type></para></entry> <entry></entry></row> <row><entry><para>msg</para></entry> <entry><para>the message being logged</para></entry> <entry></entry></row> <row><entry><para>user_data</para></entry> <entry><para>the data passed to <function>soup_logger_set_request_filter()</function> or <function>soup_logger_set_response_filter()</function></para></entry> <entry></entry></row> </tbody></tgroup></informaltable> </refsect3><refsect3> <title>Returns</title> <para> a <type>SoupLoggerLogLevel</type> value indicating how much of the message to log</para> </refsect3></refsect2>
<refsect2> <title>soup_logger_set_request_filter ()</title> <programlisting><returnvalue>void</returnvalue> soup_logger_set_request_filter (<parameter><type>SoupLogger</type> *logger</parameter>, <parameter><type>SoupLoggerFilter</type> request_filter</parameter>, <parameter><type>gpointer</type> filter_data</parameter>, <parameter><type>GDestroyNotify</type> destroy</parameter>);</programlisting> <para>Sets up a filter to determine the log level for a given request. For each HTTP request <parameter>logger</parameter> will invoke <parameter>request_filter</parameter> to determine how much (if any) of that request to log. (If you do not set a request filter, <parameter>logger</parameter> will just always log requests at the level passed to <function>soup_logger_new()</function>.)</para> <refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>logger</para></entry> <entry><para>a <type>SoupLogger</type></para></entry> <entry></entry></row> <row><entry><para>request_filter</para></entry> <entry><para>the callback for request debugging</para></entry> <entry></entry></row> <row><entry><para>filter_data</para></entry> <entry><para>data to pass to the callback</para></entry> <entry></entry></row> <row><entry><para>destroy</para></entry> <entry><para>a <type>GDestroyNotify</type> to free <parameter>filter_data</parameter> </para></entry> <entry></entry></row> </tbody></tgroup></informaltable> </refsect3></refsect2>
<refsect2> <title>soup_logger_set_response_filter ()</title> <programlisting><returnvalue>void</returnvalue> soup_logger_set_response_filter (<parameter><type>SoupLogger</type> *logger</parameter>, <parameter><type>SoupLoggerFilter</type> response_filter</parameter>, <parameter><type>gpointer</type> filter_data</parameter>, <parameter><type>GDestroyNotify</type> destroy</parameter>);</programlisting> <para>Sets up a filter to determine the log level for a given response. For each HTTP response <parameter>logger</parameter> will invoke <parameter>response_filter</parameter> to determine how much (if any) of that response to log. (If you do not set a response filter, <parameter>logger</parameter> will just always log responses at the level passed to <function>soup_logger_new()</function>.)</para> <refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>logger</para></entry> <entry><para>a <type>SoupLogger</type></para></entry> <entry></entry></row> <row><entry><para>response_filter</para></entry> <entry><para>the callback for response debugging</para></entry> <entry></entry></row> <row><entry><para>filter_data</para></entry> <entry><para>data to pass to the callback</para></entry> <entry></entry></row> <row><entry><para>destroy</para></entry> <entry><para>a <type>GDestroyNotify</type> to free <parameter>filter_data</parameter> </para></entry> <entry></entry></row> </tbody></tgroup></informaltable> </refsect3></refsect2>
<refsect2> <title>SoupLoggerPrinter ()</title> <programlisting><returnvalue>void</returnvalue> <phrase>(</phrase>*SoupLoggerPrinter<phrase>)</phrase> (<parameter><type>SoupLogger</type> *logger</parameter>, <parameter><type>SoupLoggerLogLevel</type> level</parameter>, <parameter><type>char</type> direction</parameter>, <parameter>const <type>char</type> *data</parameter>, <parameter><type>gpointer</type> user_data</parameter>);</programlisting> <para>The prototype for a custom printing callback.</para> <para><parameter>level</parameter> indicates what kind of information is being printed. Eg, it will be <literal>SOUP_LOGGER_LOG_HEADERS</literal> if <parameter>data</parameter> is header data.</para> <para><parameter>direction</parameter> is either '<', '>', or ' ', and <parameter>data</parameter> is the single line to print; the printer is expected to add a terminating newline.</para> <para>To get the effect of the default printer, you would do:</para> <informalexample><programlisting> printf ("%c %s\n", direction, data); </programlisting></informalexample> <refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>logger</para></entry> <entry><para>the <type>SoupLogger</type></para></entry> <entry></entry></row> <row><entry><para>level</para></entry> <entry><para>the level of the information being printed.</para></entry> <entry></entry></row> <row><entry><para>direction</para></entry> <entry><para>a single-character prefix to <parameter>data</parameter> </para></entry> <entry></entry></row> <row><entry><para>data</para></entry> <entry><para>data to print</para></entry> <entry></entry></row> <row><entry><para>user_data</para></entry> <entry><para>the data passed to <function>soup_logger_set_printer()</function></para></entry> <entry></entry></row> </tbody></tgroup></informaltable> </refsect3></refsect2>
<refsect2> <title>soup_logger_set_printer ()</title> <programlisting><returnvalue>void</returnvalue> soup_logger_set_printer (<parameter><type>SoupLogger</type> *logger</parameter>, <parameter><type>SoupLoggerPrinter</type> printer</parameter>, <parameter><type>gpointer</type> printer_data</parameter>, <parameter><type>GDestroyNotify</type> destroy</parameter>);</programlisting> <para>Sets up an alternate log printing routine, if you don't want the log to go to <literal>stdout</literal>.</para> <refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>logger</para></entry> <entry><para>a <type>SoupLogger</type></para></entry> <entry></entry></row> <row><entry><para>printer</para></entry> <entry><para>the callback for printing logging output</para></entry> <entry></entry></row> <row><entry><para>printer_data</para></entry> <entry><para>data to pass to the callback</para></entry> <entry></entry></row> <row><entry><para>destroy</para></entry> <entry><para>a <type>GDestroyNotify</type> to free <parameter>printer_data</parameter> </para></entry> <entry></entry></row> </tbody></tgroup></informaltable> </refsect3></refsect2> </refsect1> <refsect1> <title>Types and Values</title> <refsect2> <title>SoupLogger</title> <programlisting>typedef struct _SoupLogger SoupLogger;</programlisting> <para>Class implementing logging.</para> </refsect2>
<refsect2> <title>enum SoupLoggerLogLevel</title> <para>Describes the level of logging output to provide.</para> <refsect3> <title>Members</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>SOUP_LOGGER_LOG_NONE</para></entry> <entry><para>No logging</para> </entry> <entry></entry> </row> <row><entry><para>SOUP_LOGGER_LOG_MINIMAL</para></entry> <entry><para>Log the Request-Line or Status-Line and the Soup-Debug pseudo-headers</para> </entry> <entry></entry> </row> <row><entry><para>SOUP_LOGGER_LOG_HEADERS</para></entry> <entry><para>Log the full request/response headers</para> </entry> <entry></entry> </row> <row><entry><para>SOUP_LOGGER_LOG_BODY</para></entry> <entry><para>Log the full headers and request/response bodies</para> </entry> <entry></entry> </row> </tbody></tgroup></informaltable> </refsect3></refsect2> </refsect1> <refsect1> <title>Property Details</title> <refsect2><title>The <literal>“level”</literal> property</title> <programlisting> “level” <type>SoupLoggerLogLevel</type></programlisting> <para>The level of logging output</para> <para>Owner: SoupLogger</para> <para>Flags: Read / Write</para> <para>Default value: SOUP_LOGGER_LOG_MINIMAL</para> </refsect2>
<refsect2><title>The <literal>“max-body-size”</literal> property</title> <programlisting> “max-body-size” <type>int</type></programlisting> <para>If <type>“level”</type> is <literal>SOUP_LOGGER_LOG_BODY</literal>, this gives the maximum number of bytes of the body that will be logged. (-1 means "no limit".)</para> <para>Owner: SoupLogger</para> <para>Flags: Read / Write</para> <para>Allowed values: >= -1</para> <para>Default value: -1</para> </refsect2> </refsect1> </refentry>

Authentication

<refentry> <refmeta> <refentrytitle>SoupAuthManager</refentrytitle> <manvolnum>3</manvolnum> <refmiscinfo>LIBSOUP-3.0 Library</refmiscinfo> </refmeta>

<refentrytitle>SoupAuthManager</refentrytitle>

<refname>SoupAuthManager</refname> <refpurpose>HTTP client-side authentication handler</refpurpose>

<refsect1> <title>Functions</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><returnvalue>void</returnvalue> </entry><entry>soup_auth_manager_use_auth <phrase>()</phrase></entry></row> <row><entry><returnvalue>void</returnvalue> </entry><entry>soup_auth_manager_clear_cached_credentials <phrase>()</phrase></entry></row> </tbody> </tgroup> </informaltable> </refsect1> <refsect1> <title>Signals</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><returnvalue>void</returnvalue></entry><entry>authenticate</entry><entry>Run First</entry></row> </tbody> </tgroup> </informaltable> </refsect1> <refsect1> <title>Types and Values</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <tbody> <row><entry></entry><entry>SoupAuthManager</entry></row> <row><entry>#define</entry><entry>SOUP_TYPE_AUTH_MANAGER</entry></row> </tbody> </tgroup> </informaltable> </refsect1> <refsect1> <title>Object Hierarchy</title> <screen> GObject <phrase>╰──</phrase> SoupAuthManager </screen> </refsect1> <refsect1> <title>Implemented Interfaces</title> <para> SoupAuthManager implements SoupSessionFeature.</para> </refsect1> <refsect1><title>Includes</title><synopsis>#include <libsoup/soup.h> </synopsis></refsect1> <refsect1> <title>Description</title> <para><type>SoupAuthManager</type> is the <type>SoupSessionFeature</type> that handles HTTP authentication for a <type>SoupSession</type>.</para> <para>A <type>SoupAuthManager</type> is added to the session by default, and normally you don't need to worry about it at all. However, if you want to disable HTTP authentication, you can remove the feature from the session with <function>soup_session_remove_feature_by_type()</function>, or disable it on individual requests with <function>soup_message_disable_feature()</function>.</para> </refsect1> <refsect1> <title>Functions</title> <refsect2> <title>soup_auth_manager_use_auth ()</title> <programlisting><returnvalue>void</returnvalue> soup_auth_manager_use_auth (<parameter><type>SoupAuthManager</type> *manager</parameter>, <parameter><type>GUri</type> *uri</parameter>, <parameter><type>SoupAuth</type> *auth</parameter>);</programlisting> <para>Records that <parameter>auth</parameter> is to be used under <parameter>uri</parameter> , as though a WWW-Authenticate header had been received at that URI. This can be used to "preload" <parameter>manager</parameter> 's auth cache, to avoid an extra HTTP round trip in the case where you know ahead of time that a 401 response will be returned.</para> <para>This is only useful for authentication types where the initial Authorization header does not depend on any additional information from the server. (Eg, Basic or NTLM, but not Digest.)</para> <refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>manager</para></entry> <entry><para>a <type>SoupAuthManager</type></para></entry> <entry></entry></row> <row><entry><para>uri</para></entry> <entry><para>the <type>GUri</type> under which <parameter>auth</parameter> is to be used</para></entry> <entry></entry></row> <row><entry><para>auth</para></entry> <entry><para>the <type>SoupAuth</type> to use</para></entry> <entry></entry></row> </tbody></tgroup></informaltable> </refsect3></refsect2>
<refsect2> <title>soup_auth_manager_clear_cached_credentials ()</title> <programlisting><returnvalue>void</returnvalue> soup_auth_manager_clear_cached_credentials (<parameter><type>SoupAuthManager</type> *manager</parameter>);</programlisting> <para>Clear all credentials cached by <parameter>manager</parameter> </para> <refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>manager</para></entry> <entry><para>a <type>SoupAuthManager</type></para></entry> <entry></entry></row> </tbody></tgroup></informaltable> </refsect3></refsect2> </refsect1> <refsect1> <title>Types and Values</title> <refsect2> <title>SoupAuthManager</title> <programlisting>typedef struct _SoupAuthManager SoupAuthManager;</programlisting> <para>Class for managing client-side HTTP authentication.</para> </refsect2>
<refsect2> <title>SOUP_TYPE_AUTH_MANAGER</title> <programlisting>#define SOUP_TYPE_AUTH_MANAGER (soup_auth_manager_get_type ()) </programlisting> <para>The <type>GType</type> of <type>SoupAuthManager</type>; you can use this with <function>soup_session_remove_feature_by_type()</function> or <function>soup_message_disable_feature()</function>.</para> <para>(Although this type has only been publicly visible since libsoup 2.42, it has always existed in the background, and you can use <literal><code>g_type_from_name ("SoupAuthManager")</code></literal> to get its <type>GType</type> in earlier releases.)</para> </refsect2> </refsect1> <refsect1> <title>Signal Details</title> <refsect2><title>The <literal>“authenticate”</literal> signal</title> <programlisting><returnvalue>void</returnvalue> user_function (<type>SoupAuthManager</type> *manager, <type>SoupMessage</type> *msg, <type>SoupAuth</type> *auth, <type>gboolean</type> retrying, <type>gpointer</type> user_data)</programlisting> <para>Emitted when the manager requires the application to provide authentication credentials.</para> <para><type>SoupMessage</type> connects to this signal and emits its own <type>“authenticate”</type> signal when it is emitted, so you shouldn't need to use this signal directly.</para> <refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>manager</para></entry> <entry><para>the <type>SoupAuthManager</type></para></entry> <entry></entry></row> <row><entry><para>msg</para></entry> <entry><para>the <type>SoupMessage</type> being sent</para></entry> <entry></entry></row> <row><entry><para>auth</para></entry> <entry><para>the <type>SoupAuth</type> to authenticate</para></entry> <entry></entry></row> <row><entry><para>retrying</para></entry> <entry><para><literal>TRUE</literal> if this is the second (or later) attempt</para></entry> <entry></entry></row> <row><entry><simpara>user_data</simpara></entry> <entry><simpara>user data set when the signal handler was connected.</simpara></entry> <entry></entry></row> </tbody></tgroup></informaltable> </refsect3><para>Flags: Run First</para> </refsect2> </refsect1> <refsect1> <title>See Also</title> <para><type>SoupSession</type>, <type>SoupAuth</type></para> </refsect1> </refentry><refentry> <refmeta> <refentrytitle>SoupAuth</refentrytitle> <manvolnum>3</manvolnum> <refmiscinfo>LIBSOUP-3.0 Library</refmiscinfo> </refmeta>

<refentrytitle>SoupAuth</refentrytitle>

<refname>SoupAuth</refname> <refpurpose>HTTP client-side authentication support</refpurpose>

<refsect1> <title>Functions</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><returnvalue>SoupAuth</returnvalue> * </entry><entry>soup_auth_new <phrase>()</phrase></entry></row> <row><entry><returnvalue>gboolean</returnvalue> </entry><entry>soup_auth_update <phrase>()</phrase></entry></row> <row><entry><returnvalue>gboolean</returnvalue> </entry><entry>soup_auth_negotiate_supported <phrase>()</phrase></entry></row> <row><entry><returnvalue>gboolean</returnvalue> </entry><entry>soup_auth_is_for_proxy <phrase>()</phrase></entry></row> <row><entry>const <returnvalue>char</returnvalue> * </entry><entry>soup_auth_get_scheme_name <phrase>()</phrase></entry></row> <row><entry>const <returnvalue>char</returnvalue> * </entry><entry>soup_auth_get_authority <phrase>()</phrase></entry></row> <row><entry>const <returnvalue>char</returnvalue> * </entry><entry>soup_auth_get_realm <phrase>()</phrase></entry></row> <row><entry><returnvalue>char</returnvalue> * </entry><entry>soup_auth_get_info <phrase>()</phrase></entry></row> <row><entry><returnvalue>void</returnvalue> </entry><entry>soup_auth_authenticate <phrase>()</phrase></entry></row> <row><entry><returnvalue>gboolean</returnvalue> </entry><entry>soup_auth_can_authenticate <phrase>()</phrase></entry></row> <row><entry><returnvalue>gboolean</returnvalue> </entry><entry>soup_auth_is_authenticated <phrase>()</phrase></entry></row> <row><entry><returnvalue>gboolean</returnvalue> </entry><entry>soup_auth_is_ready <phrase>()</phrase></entry></row> <row><entry><returnvalue>void</returnvalue> </entry><entry>soup_auth_cancel <phrase>()</phrase></entry></row> <row><entry><returnvalue>gboolean</returnvalue> </entry><entry>soup_auth_is_cancelled <phrase>()</phrase></entry></row> <row><entry><returnvalue>char</returnvalue> * </entry><entry>soup_auth_get_authorization <phrase>()</phrase></entry></row> <row><entry><returnvalue>GSList</returnvalue> * </entry><entry>soup_auth_get_protection_space <phrase>()</phrase></entry></row> <row><entry><returnvalue>void</returnvalue> </entry><entry>soup_auth_free_protection_space <phrase>()</phrase></entry></row> </tbody> </tgroup> </informaltable> </refsect1> <refsect1> <title>Properties</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><type>char</type> *</entry><entry>authority</entry><entry>Read / Write</entry></row> <row><entry><type>gboolean</type></entry><entry>is-authenticated</entry><entry>Read</entry></row> <row><entry><type>gboolean</type></entry><entry>is-cancelled</entry><entry>Read</entry></row> <row><entry><type>gboolean</type></entry><entry>is-for-proxy</entry><entry>Read / Write</entry></row> <row><entry><type>char</type> *</entry><entry>realm</entry><entry>Read / Write</entry></row> <row><entry><type>char</type> *</entry><entry>scheme-name</entry><entry>Read</entry></row> </tbody> </tgroup> </informaltable> </refsect1> <anchor></anchor><anchor></anchor><anchor></anchor><anchor></anchor><refsect1> <title>Types and Values</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <tbody> <row><entry></entry><entry>SoupAuth</entry></row> <row><entry>#define</entry><entry>SOUP_TYPE_AUTH_BASIC</entry></row> <row><entry>#define</entry><entry>SOUP_TYPE_AUTH_DIGEST</entry></row> <row><entry>#define</entry><entry>SOUP_TYPE_AUTH_NTLM</entry></row> <row><entry>#define</entry><entry>SOUP_TYPE_AUTH_NEGOTIATE</entry></row> </tbody> </tgroup> </informaltable> </refsect1> <refsect1> <title>Object Hierarchy</title> <screen> GObject <phrase>╰──</phrase> SoupAuth <phrase>├──</phrase> SoupAuthBasic <phrase>├──</phrase> SoupAuthDigest <phrase>╰──</phrase> SoupConnectionAuth <phrase>├──</phrase> SoupAuthNTLM <phrase>╰──</phrase> SoupAuthNegotiate </screen> </refsect1> <refsect1><title>Includes</title><synopsis>#include <libsoup/soup.h> </synopsis></refsect1> <refsect1> <title>Description</title> <para><type>SoupAuth</type> objects store the authentication data associated with a given bit of web space. They are created automatically by <type>SoupSession</type>.</para> </refsect1> <refsect1> <title>Functions</title> <refsect2> <title>soup_auth_new ()</title> <programlisting><returnvalue>SoupAuth</returnvalue> * soup_auth_new (<parameter><type>GType</type> type</parameter>, <parameter><type>SoupMessage</type> *msg</parameter>, <parameter>const <type>char</type> *auth_header</parameter>);</programlisting> <para>Creates a new <type>SoupAuth</type> of type <parameter>type</parameter> with the information from <parameter>msg</parameter> and <parameter>auth_header</parameter> .</para> <para>This is called by <type>SoupSession</type>; you will normally not create auths yourself.</para> <para><emphasis>[constructor]</emphasis></para><refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>type</para></entry> <entry><para>the type of auth to create (a subtype of <type>SoupAuth</type>)</para></entry> <entry></entry></row> <row><entry><para>msg</para></entry> <entry><para>the <type>SoupMessage</type> the auth is being created for</para></entry> <entry></entry></row> <row><entry><para>auth_header</para></entry> <entry><para>the WWW-Authenticate/Proxy-Authenticate header</para></entry> <entry></entry></row> </tbody></tgroup></informaltable> </refsect3><refsect3> <title>Returns</title> <para>the new <type>SoupAuth</type>, or <literal>NULL</literal> if it could not be created. </para> <para><emphasis>[nullable]</emphasis></para> </refsect3></refsect2>
<refsect2> <title>soup_auth_update ()</title> <programlisting><returnvalue>gboolean</returnvalue> soup_auth_update (<parameter><type>SoupAuth</type> *auth</parameter>, <parameter><type>SoupMessage</type> *msg</parameter>, <parameter>const <type>char</type> *auth_header</parameter>);</programlisting> <para>Updates <parameter>auth</parameter> with the information from <parameter>msg</parameter> and <parameter>auth_header</parameter> , possibly un-authenticating it. As with <function>soup_auth_new()</function>, this is normally only used by <type>SoupSession</type>.</para> <refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>auth</para></entry> <entry><para>a <type>SoupAuth</type></para></entry> <entry></entry></row> <row><entry><para>msg</para></entry> <entry><para>the <type>SoupMessage</type> <parameter>auth</parameter> is being updated for</para></entry> <entry></entry></row> <row><entry><para>auth_header</para></entry> <entry><para>the WWW-Authenticate/Proxy-Authenticate header</para></entry> <entry></entry></row> </tbody></tgroup></informaltable> </refsect3><refsect3> <title>Returns</title> <para> <literal>TRUE</literal> if <parameter>auth</parameter> is still a valid (but potentially unauthenticated) <type>SoupAuth</type>. <literal>FALSE</literal> if something about <parameter>auth_params</parameter> could not be parsed or incorporated into <parameter>auth</parameter> at all.</para> </refsect3></refsect2>
<refsect2> <title>soup_auth_negotiate_supported ()</title> <programlisting><returnvalue>gboolean</returnvalue> soup_auth_negotiate_supported (<parameter><type>void</type></parameter>);</programlisting> <para>Indicates whether libsoup was built with GSSAPI support. If this is <literal>FALSE</literal>, <literal>SOUP_TYPE_AUTH_NEGOTIATE</literal> will still be defined and can still be added to a <type>SoupSession</type>, but libsoup will never attempt to actually use this auth type.</para> </refsect2>
<refsect2> <title>soup_auth_is_for_proxy ()</title> <programlisting><returnvalue>gboolean</returnvalue> soup_auth_is_for_proxy (<parameter><type>SoupAuth</type> *auth</parameter>);</programlisting> <para>Tests whether or not <parameter>auth</parameter> is associated with a proxy server rather than an "origin" server.</para> <refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>auth</para></entry> <entry><para>a <type>SoupAuth</type></para></entry> <entry></entry></row> </tbody></tgroup></informaltable> </refsect3><refsect3> <title>Returns</title> <para> <literal>TRUE</literal> or <literal>FALSE</literal></para> </refsect3></refsect2>
<refsect2> <title>soup_auth_get_scheme_name ()</title> <programlisting>const <returnvalue>char</returnvalue> * soup_auth_get_scheme_name (<parameter><type>SoupAuth</type> *auth</parameter>);</programlisting> <para>Returns <parameter>auth</parameter> 's scheme name. (Eg, "Basic", "Digest", or "NTLM")</para> <refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>auth</para></entry> <entry><para>a <type>SoupAuth</type></para></entry> <entry></entry></row> </tbody></tgroup></informaltable> </refsect3><refsect3> <title>Returns</title> <para> the scheme name</para> </refsect3></refsect2>
<refsect2> <title>soup_auth_get_authority ()</title> <programlisting>const <returnvalue>char</returnvalue> * soup_auth_get_authority (<parameter><type>SoupAuth</type> *auth</parameter>);</programlisting> <para>Returns the authority (host:port) that <parameter>auth</parameter> is associated with.</para> <refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>auth</para></entry> <entry><para>a <type>SoupAuth</type></para></entry> <entry></entry></row> </tbody></tgroup></informaltable> </refsect3><refsect3> <title>Returns</title> <para> the authority</para> </refsect3></refsect2>
<refsect2> <title>soup_auth_get_realm ()</title> <programlisting>const <returnvalue>char</returnvalue> * soup_auth_get_realm (<parameter><type>SoupAuth</type> *auth</parameter>);</programlisting> <para>Returns <parameter>auth</parameter> 's realm. This is an identifier that distinguishes separate authentication spaces on a given server, and may be some string that is meaningful to the user. (Although it is probably not localized.)</para> <refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>auth</para></entry> <entry><para>a <type>SoupAuth</type></para></entry> <entry></entry></row> </tbody></tgroup></informaltable> </refsect3><refsect3> <title>Returns</title> <para> the realm name</para> </refsect3></refsect2>
<refsect2> <title>soup_auth_get_info ()</title> <programlisting><returnvalue>char</returnvalue> * soup_auth_get_info (<parameter><type>SoupAuth</type> *auth</parameter>);</programlisting> <para>Gets an opaque identifier for <parameter>auth</parameter> , for use as a hash key or the like. <type>SoupAuth</type> objects from the same server with the same identifier refer to the same authentication domain (eg, the URLs associated with them take the same usernames and passwords).</para> <refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>auth</para></entry> <entry><para>a <type>SoupAuth</type></para></entry> <entry></entry></row> </tbody></tgroup></informaltable> </refsect3><refsect3> <title>Returns</title> <para> the identifier</para> </refsect3></refsect2>
<refsect2> <title>soup_auth_authenticate ()</title> <programlisting><returnvalue>void</returnvalue> soup_auth_authenticate (<parameter><type>SoupAuth</type> *auth</parameter>, <parameter>const <type>char</type> *username</parameter>, <parameter>const <type>char</type> *password</parameter>);</programlisting> <para>Call this on an auth to authenticate it; normally this will cause the auth's message to be requeued with the new authentication info.</para> <refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>auth</para></entry> <entry><para>a <type>SoupAuth</type></para></entry> <entry></entry></row> <row><entry><para>username</para></entry> <entry><para>the username provided by the user or client</para></entry> <entry></entry></row> <row><entry><para>password</para></entry> <entry><para>the password provided by the user or client</para></entry> <entry></entry></row> </tbody></tgroup></informaltable> </refsect3></refsect2>
<refsect2> <title>soup_auth_can_authenticate ()</title> <programlisting><returnvalue>gboolean</returnvalue> soup_auth_can_authenticate (<parameter><type>SoupAuth</type> *auth</parameter>);</programlisting> <para>Tests if <parameter>auth</parameter> is able to authenticate by providing credentials to the <function>soup_auth_authenticate()</function>.</para> <refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>auth</para></entry> <entry><para>a <type>SoupAuth</type></para></entry> <entry></entry></row> </tbody></tgroup></informaltable> </refsect3><refsect3> <title>Returns</title> <para> <literal>TRUE</literal> if <parameter>auth</parameter> is able to accept credentials.</para> </refsect3></refsect2>
<refsect2> <title>soup_auth_is_authenticated ()</title> <programlisting><returnvalue>gboolean</returnvalue> soup_auth_is_authenticated (<parameter><type>SoupAuth</type> *auth</parameter>);</programlisting> <para>Tests if <parameter>auth</parameter> has been given a username and password</para> <refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>auth</para></entry> <entry><para>a <type>SoupAuth</type></para></entry> <entry></entry></row> </tbody></tgroup></informaltable> </refsect3><refsect3> <title>Returns</title> <para> <literal>TRUE</literal> if <parameter>auth</parameter> has been given a username and password</para> </refsect3></refsect2>
<refsect2> <title>soup_auth_is_ready ()</title> <programlisting><returnvalue>gboolean</returnvalue> soup_auth_is_ready (<parameter><type>SoupAuth</type> *auth</parameter>, <parameter><type>SoupMessage</type> *msg</parameter>);</programlisting> <para>Tests if <parameter>auth</parameter> is ready to make a request for <parameter>msg</parameter> with. For most auths, this is equivalent to <function>soup_auth_is_authenticated()</function>, but for some auth types (eg, NTLM), the auth may be sendable (eg, as an authentication request) even before it is authenticated.</para> <refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>auth</para></entry> <entry><para>a <type>SoupAuth</type></para></entry> <entry></entry></row> <row><entry><para>msg</para></entry> <entry><para>a <type>SoupMessage</type></para></entry> <entry></entry></row> </tbody></tgroup></informaltable> </refsect3><refsect3> <title>Returns</title> <para> <literal>TRUE</literal> if <parameter>auth</parameter> is ready to make a request with.</para> </refsect3></refsect2>
<refsect2> <title>soup_auth_cancel ()</title> <programlisting><returnvalue>void</returnvalue> soup_auth_cancel (<parameter><type>SoupAuth</type> *auth</parameter>);</programlisting> <para>Call this on an auth to cancel it. You need to cancel an auth to complete an asynchronous authenticate operation when no credentials are provided (<function>soup_auth_authenticate()</function> is not called). The <type>SoupAuth</type> will be cancelled on dispose if it hans't been authenticated.</para> <refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>auth</para></entry> <entry><para>a <type>SoupAuth</type></para></entry> <entry></entry></row> </tbody></tgroup></informaltable> </refsect3></refsect2>
<refsect2> <title>soup_auth_is_cancelled ()</title> <programlisting><returnvalue>gboolean</returnvalue> soup_auth_is_cancelled (<parameter><type>SoupAuth</type> *auth</parameter>);</programlisting> <para>Tests if <parameter>auth</parameter> has been cancelled</para> <refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>auth</para></entry> <entry><para>a <type>SoupAuth</type></para></entry> <entry></entry></row> </tbody></tgroup></informaltable> </refsect3><refsect3> <title>Returns</title> <para> <literal>TRUE</literal> if <parameter>auth</parameter> has been cancelled</para> </refsect3></refsect2>
<refsect2> <title>soup_auth_get_authorization ()</title> <programlisting><returnvalue>char</returnvalue> * soup_auth_get_authorization (<parameter><type>SoupAuth</type> *auth</parameter>, <parameter><type>SoupMessage</type> *msg</parameter>);</programlisting> <para>Generates an appropriate "Authorization" header for <parameter>msg</parameter> . (The session will only call this if <function>soup_auth_is_authenticated()</function> returned <literal>TRUE</literal>.)</para> <refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>auth</para></entry> <entry><para>a <type>SoupAuth</type></para></entry> <entry></entry></row> <row><entry><para>msg</para></entry> <entry><para>the <type>SoupMessage</type> to be authorized</para></entry> <entry></entry></row> </tbody></tgroup></informaltable> </refsect3><refsect3> <title>Returns</title> <para> the "Authorization" header, which must be freed.</para> </refsect3></refsect2>
<refsect2> <title>soup_auth_get_protection_space ()</title> <programlisting><returnvalue>GSList</returnvalue> * soup_auth_get_protection_space (<parameter><type>SoupAuth</type> *auth</parameter>, <parameter><type>GUri</type> *source_uri</parameter>);</programlisting> <para>Returns a list of paths on the server which <parameter>auth</parameter> extends over. (All subdirectories of these paths are also assumed to be part of <parameter>auth</parameter> 's protection space, unless otherwise discovered not to be.)</para> <refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>auth</para></entry> <entry><para>a <type>SoupAuth</type></para></entry> <entry></entry></row> <row><entry><para>source_uri</para></entry> <entry><para>the URI of the request that <parameter>auth</parameter> was generated in response to.</para></entry> <entry></entry></row> </tbody></tgroup></informaltable> </refsect3><refsect3> <title>Returns</title> <para>the list of paths, which can be freed with <function>soup_auth_free_protection_space()</function>. </para> <para><emphasis>[element-type utf8][transfer full]</emphasis></para> </refsect3></refsect2>
<refsect2> <title>soup_auth_free_protection_space ()</title> <programlisting><returnvalue>void</returnvalue> soup_auth_free_protection_space (<parameter><type>SoupAuth</type> *auth</parameter>, <parameter><type>GSList</type> *space</parameter>);</programlisting> <para>Frees <parameter>space</parameter> .</para> <para><emphasis>[skip]</emphasis></para><refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>auth</para></entry> <entry><para>a <type>SoupAuth</type></para></entry> <entry></entry></row> <row><entry><para>space</para></entry> <entry><para>the return value from <function>soup_auth_get_protection_space()</function></para></entry> <entry></entry></row> </tbody></tgroup></informaltable> </refsect3></refsect2> </refsect1> <refsect1> <title>Types and Values</title> <refsect2> <title>SoupAuth</title> <programlisting>typedef struct _SoupAuth SoupAuth;</programlisting> <para>The abstract base class for handling authentication. Specific HTTP Authentication mechanisms are implemented by its subclasses, but applications never need to be aware of the specific subclasses being used.</para> </refsect2>
<refsect2> <title>SOUP_TYPE_AUTH_BASIC</title> <programlisting>#define SOUP_TYPE_AUTH_BASIC (soup_auth_basic_get_type ()) </programlisting> <para>A <type>GType</type> corresponding to HTTP "Basic" authentication. <type>SoupSessions</type> support this by default; if you want to disable support for it, call <function>soup_session_remove_feature_by_type()</function>, passing <literal>SOUP_TYPE_AUTH_BASIC</literal>.</para> </refsect2>
<refsect2> <title>SOUP_TYPE_AUTH_DIGEST</title> <programlisting>#define SOUP_TYPE_AUTH_DIGEST (soup_auth_digest_get_type ()) </programlisting> <para>A <type>GType</type> corresponding to HTTP "Digest" authentication. <type>SoupSessions</type> support this by default; if you want to disable support for it, call <function>soup_session_remove_feature_by_type()</function>, passing <literal>SOUP_TYPE_AUTH_DIGEST</literal>.</para> </refsect2>
<refsect2> <title>SOUP_TYPE_AUTH_NTLM</title> <programlisting>#define SOUP_TYPE_AUTH_NTLM (soup_auth_ntlm_get_type ()) </programlisting> <para>A <type>GType</type> corresponding to HTTP-based NTLM authentication. <type>SoupSessions</type> do not support this type by default; if you want to enable support for it, call <function>soup_session_add_feature_by_type()</function>, passing <literal>SOUP_TYPE_AUTH_NTLM</literal>.</para> </refsect2>
<refsect2> <title>SOUP_TYPE_AUTH_NEGOTIATE</title> <programlisting>#define SOUP_TYPE_AUTH_NEGOTIATE (soup_auth_negotiate_get_type ()) </programlisting> <para>A <type>GType</type> corresponding to HTTP-based GSS-Negotiate authentication. <type>SoupSessions</type> do not support this type by default; if you want to enable support for it, call <function>soup_session_add_feature_by_type()</function>, passing <literal>SOUP_TYPE_AUTH_NEGOTIATE</literal>.</para> <para>This auth type will only work if libsoup was compiled with GSSAPI support; you can check <function>soup_auth_negotiate_supported()</function> to see if it was.</para> </refsect2> </refsect1> <refsect1> <title>Property Details</title> <refsect2><title>The <literal>“authority”</literal> property</title> <programlisting> “authority” <type>char</type> *</programlisting> <para>The authority (host:port) being authenticated to.</para> <para>Owner: SoupAuth</para> <para>Flags: Read / Write</para> <para>Default value: NULL</para> </refsect2>
<refsect2><title>The <literal>“is-authenticated”</literal> property</title> <programlisting> “is-authenticated” <type>gboolean</type></programlisting> <para>Whether or not the auth has been authenticated.</para> <para>Owner: SoupAuth</para> <para>Flags: Read</para> <para>Default value: FALSE</para> </refsect2>
<refsect2><title>The <literal>“is-cancelled”</literal> property</title> <programlisting> “is-cancelled” <type>gboolean</type></programlisting> <para>An alias for the <type>“is-cancelled”</type> property. (Whether or not the auth has been cancelled.)</para> <para>Owner: SoupAuth</para> <para>Flags: Read</para> <para>Default value: FALSE</para> </refsect2>
<refsect2><title>The <literal>“is-for-proxy”</literal> property</title> <programlisting> “is-for-proxy” <type>gboolean</type></programlisting> <para>Whether or not the auth is for a proxy server.</para> <para>Owner: SoupAuth</para> <para>Flags: Read / Write</para> <para>Default value: FALSE</para> </refsect2>
<refsect2><title>The <literal>“realm”</literal> property</title> <programlisting> “realm” <type>char</type> *</programlisting> <para>The authentication realm.</para> <para>Owner: SoupAuth</para> <para>Flags: Read / Write</para> <para>Default value: NULL</para> </refsect2>
<refsect2><title>The <literal>“scheme-name”</literal> property</title> <programlisting> “scheme-name” <type>char</type> *</programlisting> <para>The authentication scheme name.</para> <para>Owner: SoupAuth</para> <para>Flags: Read</para> <para>Default value: NULL</para> </refsect2> </refsect1> <refsect1> <title>See Also</title> <para><type>SoupSession</type></para> </refsect1> </refentry><refentry> <refmeta> <refentrytitle>SoupAuthDomain</refentrytitle> <manvolnum>3</manvolnum> <refmiscinfo>LIBSOUP-3.0 Library</refmiscinfo> </refmeta>

<refentrytitle>SoupAuthDomain</refentrytitle>

<refname>SoupAuthDomain</refname> <refpurpose>Server-side authentication</refpurpose>

<refsect1> <title>Functions</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><returnvalue>gboolean</returnvalue> </entry><entry><phrase>(</phrase>*SoupAuthDomainFilter<phrase>)</phrase> <phrase>()</phrase></entry></row> <row><entry><returnvalue>void</returnvalue> </entry><entry>soup_auth_domain_set_filter <phrase>()</phrase></entry></row> <row><entry>const <returnvalue>char</returnvalue> * </entry><entry>soup_auth_domain_get_realm <phrase>()</phrase></entry></row> <row><entry><returnvalue>void</returnvalue> </entry><entry>soup_auth_domain_add_path <phrase>()</phrase></entry></row> <row><entry><returnvalue>void</returnvalue> </entry><entry>soup_auth_domain_remove_path <phrase>()</phrase></entry></row> <row><entry><returnvalue>gboolean</returnvalue> </entry><entry><phrase>(</phrase>*SoupAuthDomainGenericAuthCallback<phrase>)</phrase> <phrase>()</phrase></entry></row> <row><entry><returnvalue>void</returnvalue> </entry><entry>soup_auth_domain_set_generic_auth_callback <phrase>()</phrase></entry></row> <row><entry><returnvalue>gboolean</returnvalue> </entry><entry>soup_auth_domain_check_password <phrase>()</phrase></entry></row> <row><entry><returnvalue>gboolean</returnvalue> </entry><entry>soup_auth_domain_covers <phrase>()</phrase></entry></row> <row><entry><returnvalue>char</returnvalue> * </entry><entry>soup_auth_domain_accepts <phrase>()</phrase></entry></row> <row><entry><returnvalue>void</returnvalue> </entry><entry>soup_auth_domain_challenge <phrase>()</phrase></entry></row> </tbody> </tgroup> </informaltable> </refsect1> <refsect1> <title>Properties</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><type>gpointer</type></entry><entry>filter</entry><entry>Read / Write</entry></row> <row><entry><type>gpointer</type></entry><entry>filter-data</entry><entry>Read / Write</entry></row> <row><entry><type>gpointer</type></entry><entry>generic-auth-callback</entry><entry>Read / Write</entry></row> <row><entry><type>gpointer</type></entry><entry>generic-auth-data</entry><entry>Read / Write</entry></row> <row><entry><type>gboolean</type></entry><entry>proxy</entry><entry>Read / Write / Construct Only</entry></row> <row><entry><type>char</type> *</entry><entry>realm</entry><entry>Read / Write / Construct Only</entry></row> </tbody> </tgroup> </informaltable> </refsect1> <refsect1> <title>Types and Values</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <tbody> <row><entry></entry><entry>SoupAuthDomain</entry></row> </tbody> </tgroup> </informaltable> </refsect1> <refsect1> <title>Object Hierarchy</title> <screen> GObject <phrase>╰──</phrase> SoupAuthDomain <phrase>├──</phrase> SoupAuthDomainBasic <phrase>╰──</phrase> SoupAuthDomainDigest </screen> </refsect1> <refsect1><title>Includes</title><synopsis>#include <libsoup/soup.h> </synopsis></refsect1> <refsect1> <title>Description</title> <para>A <type>SoupAuthDomain</type> manages authentication for all or part of a <type>SoupServer</type>. To make a server require authentication, first create an appropriate subclass of <type>SoupAuthDomain</type>, and then add it to the server with <function>soup_server_add_auth_domain()</function>.</para> <para>In order for an auth domain to have any effect, you must add one or more paths to it (via <function>soup_auth_domain_add_path()</function> or the SoupAuthDomain:add-path property). To require authentication for all ordinary requests, add the path "/". (Note that this does not include the special "*" URI (eg, "OPTIONS *"), which must be added as a separate path if you want to cover it.)</para> <para>If you need greater control over which requests should and shouldn't be authenticated, add paths covering everything you <emphasis>might</emphasis> want authenticated, and then use a filter (<function>soup_auth_domain_set_filter()</function>) to bypass authentication for those requests that don't need it.</para> </refsect1> <refsect1> <title>Functions</title> <refsect2> <title>SoupAuthDomainFilter ()</title> <programlisting><returnvalue>gboolean</returnvalue> <phrase>(</phrase>*SoupAuthDomainFilter<phrase>)</phrase> (<parameter><type>SoupAuthDomain</type> *domain</parameter>, <parameter><type>SoupServerMessage</type> *msg</parameter>, <parameter><type>gpointer</type> user_data</parameter>);</programlisting> <para>The prototype for a <type>SoupAuthDomain</type> filter; see <function>soup_auth_domain_set_filter()</function> for details.</para> <refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>domain</para></entry> <entry><para>a <type>SoupAuthDomain</type></para></entry> <entry></entry></row> <row><entry><para>msg</para></entry> <entry><para>a <type>SoupServerMessage</type></para></entry> <entry></entry></row> <row><entry><para>user_data</para></entry> <entry><para>the data passed to <function>soup_auth_domain_set_filter()</function></para></entry> <entry></entry></row> </tbody></tgroup></informaltable> </refsect3><refsect3> <title>Returns</title> <para> <literal>TRUE</literal> if <parameter>msg</parameter> requires authentication, <literal>FALSE</literal> if not.</para> </refsect3></refsect2>
<refsect2> <title>soup_auth_domain_set_filter ()</title> <programlisting><returnvalue>void</returnvalue> soup_auth_domain_set_filter (<parameter><type>SoupAuthDomain</type> *domain</parameter>, <parameter><type>SoupAuthDomainFilter</type> filter</parameter>, <parameter><type>gpointer</type> filter_data</parameter>, <parameter><type>GDestroyNotify</type> dnotify</parameter>);</programlisting> <para>Adds <parameter>filter</parameter> as an authentication filter to <parameter>domain</parameter> . The filter gets a chance to bypass authentication for certain requests that would otherwise require it. Eg, it might check the message's path in some way that is too complicated to do via the other methods, or it might check the message's method, and allow GETs but not PUTs.</para> <para>The filter function returns <literal>TRUE</literal> if the request should still require authentication, or <literal>FALSE</literal> if authentication is unnecessary for this request.</para> <para>To help prevent security holes, your filter should return <literal>TRUE</literal> by default, and only return <literal>FALSE</literal> under specifically-tested circumstances, rather than the other way around. Eg, in the example above, where you want to authenticate PUTs but not GETs, you should check if the method is GET and return <literal>FALSE</literal> in that case, and then return <literal>TRUE</literal> for all other methods (rather than returning <literal>TRUE</literal> for PUT and <literal>FALSE</literal> for all other methods). This way if it turned out (now or later) that some paths supported additional methods besides GET and PUT, those methods would default to being NOT allowed for unauthenticated users.</para> <para>You can also set the filter by setting the SoupAuthDomain:filter and SoupAuthDomain:filter-data properties, which can also be used to set the filter at construct time.</para> <refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>domain</para></entry> <entry><para>a <type>SoupAuthDomain</type></para></entry> <entry></entry></row> <row><entry><para>filter</para></entry> <entry><para>the auth filter for <parameter>domain</parameter> </para></entry> <entry></entry></row> <row><entry><para>filter_data</para></entry> <entry><para>data to pass to <parameter>filter</parameter> </para></entry> <entry></entry></row> <row><entry><para>dnotify</para></entry> <entry><para>destroy notifier to free <parameter>filter_data</parameter> when <parameter>domain</parameter> is destroyed</para></entry> <entry></entry></row> </tbody></tgroup></informaltable> </refsect3></refsect2>
<refsect2> <title>soup_auth_domain_get_realm ()</title> <programlisting>const <returnvalue>char</returnvalue> * soup_auth_domain_get_realm (<parameter><type>SoupAuthDomain</type> *domain</parameter>);</programlisting> <para>Gets the realm name associated with <parameter>domain</parameter> </para> <refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>domain</para></entry> <entry><para>a <type>SoupAuthDomain</type></para></entry> <entry></entry></row> </tbody></tgroup></informaltable> </refsect3><refsect3> <title>Returns</title> <para> <parameter>domain</parameter> 's realm</para> </refsect3></refsect2>
<refsect2> <title>soup_auth_domain_add_path ()</title> <programlisting><returnvalue>void</returnvalue> soup_auth_domain_add_path (<parameter><type>SoupAuthDomain</type> *domain</parameter>, <parameter>const <type>char</type> *path</parameter>);</programlisting> <para>Adds <parameter>path</parameter> to <parameter>domain</parameter> , such that requests under <parameter>path</parameter> on <parameter>domain</parameter> 's server will require authentication (unless overridden by <function>soup_auth_domain_remove_path()</function> or <function>soup_auth_domain_set_filter()</function>).</para> <para>You can also add paths by setting the SoupAuthDomain:add-path property, which can also be used to add one or more paths at construct time.</para> <refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>domain</para></entry> <entry><para>a <type>SoupAuthDomain</type></para></entry> <entry></entry></row> <row><entry><para>path</para></entry> <entry><para>the path to add to <parameter>domain</parameter> </para></entry> <entry></entry></row> </tbody></tgroup></informaltable> </refsect3></refsect2>
<refsect2> <title>soup_auth_domain_remove_path ()</title> <programlisting><returnvalue>void</returnvalue> soup_auth_domain_remove_path (<parameter><type>SoupAuthDomain</type> *domain</parameter>, <parameter>const <type>char</type> *path</parameter>);</programlisting> <para>Removes <parameter>path</parameter> from <parameter>domain</parameter> , such that requests under <parameter>path</parameter> on <parameter>domain</parameter> 's server will NOT require authentication.</para> <para>This is not simply an undo-er for <function>soup_auth_domain_add_path()</function>; it can be used to "carve out" a subtree that does not require authentication inside a hierarchy that does. Note also that unlike with <function>soup_auth_domain_add_path()</function>, this cannot be overridden by adding a filter, as filters can only bypass authentication that would otherwise be required, not require it where it would otherwise be unnecessary.</para> <para>You can also remove paths by setting the SoupAuthDomain:remove-path property, which can also be used to remove one or more paths at construct time.</para> <refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>domain</para></entry> <entry><para>a <type>SoupAuthDomain</type></para></entry> <entry></entry></row> <row><entry><para>path</para></entry> <entry><para>the path to remove from <parameter>domain</parameter> </para></entry> <entry></entry></row> </tbody></tgroup></informaltable> </refsect3></refsect2>
<refsect2> <title>SoupAuthDomainGenericAuthCallback ()</title> <programlisting><returnvalue>gboolean</returnvalue> <phrase>(</phrase>*SoupAuthDomainGenericAuthCallback<phrase>)</phrase> (<parameter><type>SoupAuthDomain</type> *domain</parameter>, <parameter><type>SoupServerMessage</type> *msg</parameter>, <parameter>const <type>char</type> *username</parameter>, <parameter><type>gpointer</type> user_data</parameter>);</programlisting> <para>The prototype for a <type>SoupAuthDomain</type> generic authentication callback.</para> <para>The callback should look up the user's password, call <function>soup_auth_domain_check_password()</function>, and use the return value from that method as its own return value.</para> <para>In general, for security reasons, it is preferable to use the auth-domain-specific auth callbacks (eg, <type>SoupAuthDomainBasicAuthCallback</type> and <type>SoupAuthDomainDigestAuthCallback</type>), because they don't require keeping a cleartext password database. Most users will use the same password for many different sites, meaning if any site with a cleartext password database is compromised, accounts on other servers might be compromised as well. For many of the cases where <type>SoupServer</type> is used, this is not really relevant, but it may still be worth considering.</para> <refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>domain</para></entry> <entry><para>a <type>SoupAuthDomain</type></para></entry> <entry></entry></row> <row><entry><para>msg</para></entry> <entry><para>the <type>SoupServerMessage</type> being authenticated</para></entry> <entry></entry></row> <row><entry><para>username</para></entry> <entry><para>the username from <parameter>msg</parameter> </para></entry> <entry></entry></row> <row><entry><para>user_data</para></entry> <entry><para>the data passed to <function>soup_auth_domain_set_generic_auth_callback()</function></para></entry> <entry></entry></row> </tbody></tgroup></informaltable> </refsect3><refsect3> <title>Returns</title> <para> <literal>TRUE</literal> if <parameter>msg</parameter> is authenticated, <literal>FALSE</literal> if not.</para> </refsect3></refsect2>
<refsect2> <title>soup_auth_domain_set_generic_auth_callback ()</title> <programlisting><returnvalue>void</returnvalue> soup_auth_domain_set_generic_auth_callback (<parameter><type>SoupAuthDomain</type> *domain</parameter>, <parameter><type>SoupAuthDomainGenericAuthCallback</type> auth_callback</parameter>, <parameter><type>gpointer</type> auth_data</parameter>, <parameter><type>GDestroyNotify</type> dnotify</parameter>);</programlisting> <para>Sets <parameter>auth_callback</parameter> as an authentication-handling callback for <parameter>domain</parameter> . Whenever a request comes in to <parameter>domain</parameter> which cannot be authenticated via a domain-specific auth callback (eg, <type>SoupAuthDomainDigestAuthCallback</type>), the generic auth callback will be invoked. See <type>SoupAuthDomainGenericAuthCallback</type> for information on what the callback should do.</para> <refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>domain</para></entry> <entry><para>a <type>SoupAuthDomain</type></para></entry> <entry></entry></row> <row><entry><para>auth_callback</para></entry> <entry><para>the auth callback</para></entry> <entry></entry></row> <row><entry><para>auth_data</para></entry> <entry><para>data to pass to <parameter>auth_callback</parameter> </para></entry> <entry></entry></row> <row><entry><para>dnotify</para></entry> <entry><para>destroy notifier to free <parameter>auth_data</parameter> when <parameter>domain</parameter> is destroyed</para></entry> <entry></entry></row> </tbody></tgroup></informaltable> </refsect3></refsect2>
<refsect2> <title>soup_auth_domain_check_password ()</title> <programlisting><returnvalue>gboolean</returnvalue> soup_auth_domain_check_password (<parameter><type>SoupAuthDomain</type> *domain</parameter>, <parameter><type>SoupServerMessage</type> *msg</parameter>, <parameter>const <type>char</type> *username</parameter>, <parameter>const <type>char</type> *password</parameter>);</programlisting> <para>Checks if <parameter>msg</parameter> authenticates to <parameter>domain</parameter> via <parameter>username</parameter> and <parameter>password</parameter> . This would normally be called from a <type>SoupAuthDomainGenericAuthCallback</type>.</para> <refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>domain</para></entry> <entry><para>a <type>SoupAuthDomain</type></para></entry> <entry></entry></row> <row><entry><para>msg</para></entry> <entry><para>a <type>SoupServerMessage</type></para></entry> <entry></entry></row> <row><entry><para>username</para></entry> <entry><para>a username</para></entry> <entry></entry></row> <row><entry><para>password</para></entry> <entry><para>a password</para></entry> <entry></entry></row> </tbody></tgroup></informaltable> </refsect3><refsect3> <title>Returns</title> <para> whether or not the message is authenticated</para> </refsect3></refsect2>
<refsect2> <title>soup_auth_domain_covers ()</title> <programlisting><returnvalue>gboolean</returnvalue> soup_auth_domain_covers (<parameter><type>SoupAuthDomain</type> *domain</parameter>, <parameter><type>SoupServerMessage</type> *msg</parameter>);</programlisting> <para>Checks if <parameter>domain</parameter> requires <parameter>msg</parameter> to be authenticated (according to its paths and filter function). This does not actually look at whether <parameter>msg</parameter> <emphasis>is</emphasis> authenticated, merely whether or not it needs to be.</para> <para>This is used by <type>SoupServer</type> internally and is probably of no use to anyone else.</para> <refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>domain</para></entry> <entry><para>a <type>SoupAuthDomain</type></para></entry> <entry></entry></row> <row><entry><para>msg</para></entry> <entry><para>a <type>SoupServerMessage</type></para></entry> <entry></entry></row> </tbody></tgroup></informaltable> </refsect3><refsect3> <title>Returns</title> <para> <literal>TRUE</literal> if <parameter>domain</parameter> requires <parameter>msg</parameter> to be authenticated</para> </refsect3></refsect2>
<refsect2> <title>soup_auth_domain_accepts ()</title> <programlisting><returnvalue>char</returnvalue> * soup_auth_domain_accepts (<parameter><type>SoupAuthDomain</type> *domain</parameter>, <parameter><type>SoupServerMessage</type> *msg</parameter>);</programlisting> <para>Checks if <parameter>msg</parameter> contains appropriate authorization for <parameter>domain</parameter> to accept it. Mirroring <function>soup_auth_domain_covers()</function>, this does not check whether or not <parameter>domain</parameter> <emphasis>cares</emphasis> if <parameter>msg</parameter> is authorized.</para> <para>This is used by <type>SoupServer</type> internally and is probably of no use to anyone else.</para> <refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>domain</para></entry> <entry><para>a <type>SoupAuthDomain</type></para></entry> <entry></entry></row> <row><entry><para>msg</para></entry> <entry><para>a <type>SoupServerMessage</type></para></entry> <entry></entry></row> </tbody></tgroup></informaltable> </refsect3><refsect3> <title>Returns</title> <para>the username that <parameter>msg</parameter> has authenticated as, if in fact it has authenticated. <literal>NULL</literal> otherwise. </para> <para><emphasis>[nullable]</emphasis></para> </refsect3></refsect2>
<refsect2> <title>soup_auth_domain_challenge ()</title> <programlisting><returnvalue>void</returnvalue> soup_auth_domain_challenge (<parameter><type>SoupAuthDomain</type> *domain</parameter>, <parameter><type>SoupServerMessage</type> *msg</parameter>);</programlisting> <para>Adds a "WWW-Authenticate" or "Proxy-Authenticate" header to <parameter>msg</parameter> , requesting that the client authenticate, and sets <parameter>msg</parameter> 's status accordingly.</para> <para>This is used by <type>SoupServer</type> internally and is probably of no use to anyone else.</para> <para><emphasis>[virtual challenge]</emphasis></para><refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>domain</para></entry> <entry><para>a <type>SoupAuthDomain</type></para></entry> <entry></entry></row> <row><entry><para>msg</para></entry> <entry><para>a <type>SoupServerMessage</type></para></entry> <entry></entry></row> </tbody></tgroup></informaltable> </refsect3></refsect2> </refsect1> <refsect1> <title>Types and Values</title> <refsect2> <title>SoupAuthDomain</title> <programlisting>typedef struct _SoupAuthDomain SoupAuthDomain;</programlisting> <para>Class managing authentication for <type>SoupServer</type>.</para> </refsect2> </refsect1> <refsect1> <title>Property Details</title> <refsect2><title>The <literal>“filter”</literal> property</title> <programlisting> “filter” <type>gpointer</type></programlisting> <para>The <type>SoupAuthDomainFilter</type> for the domain.</para> <para><emphasis>[type SoupAuthDomainFilter]</emphasis></para><para>Owner: SoupAuthDomain</para> <para>Flags: Read / Write</para> </refsect2>
<refsect2><title>The <literal>“filter-data”</literal> property</title> <programlisting> “filter-data” <type>gpointer</type></programlisting> <para>Data to pass to the <type>SoupAuthDomainFilter</type>.</para> <para>Owner: SoupAuthDomain</para> <para>Flags: Read / Write</para> </refsect2>
<refsect2><title>The <literal>“generic-auth-callback”</literal> property</title> <programlisting> “generic-auth-callback” <type>gpointer</type></programlisting> <para>The <type>SoupAuthDomainGenericAuthCallback</type>.</para> <para><emphasis>[type SoupAuthDomainGenericAuthCallback]</emphasis></para><para>Owner: SoupAuthDomain</para> <para>Flags: Read / Write</para> </refsect2>
<refsect2><title>The <literal>“generic-auth-data”</literal> property</title> <programlisting> “generic-auth-data” <type>gpointer</type></programlisting> <para>The data to pass to the <type>SoupAuthDomainGenericAuthCallback</type>.</para> <para>Owner: SoupAuthDomain</para> <para>Flags: Read / Write</para> </refsect2>
<refsect2><title>The <literal>“proxy”</literal> property</title> <programlisting> “proxy” <type>gboolean</type></programlisting> <para>Whether or not this is a proxy auth domain.</para><para>Owner: SoupAuthDomain</para> <para>Flags: Read / Write / Construct Only</para> <para>Default value: FALSE</para> </refsect2>
<refsect2><title>The <literal>“realm”</literal> property</title> <programlisting> “realm” <type>char</type> *</programlisting> <para>The realm of this auth domain.</para><para>Owner: SoupAuthDomain</para> <para>Flags: Read / Write / Construct Only</para> <para>Default value: NULL</para> </refsect2> </refsect1> <refsect1> <title>See Also</title> <para><type>SoupServer</type></para> </refsect1> </refentry><refentry> <refmeta> <refentrytitle>SoupAuthDomainBasic</refentrytitle> <manvolnum>3</manvolnum> <refmiscinfo>LIBSOUP-3.0 Library</refmiscinfo> </refmeta>

<refentrytitle>SoupAuthDomainBasic</refentrytitle>

<refname>SoupAuthDomainBasic</refname> <refpurpose>Server-side "Basic" authentication</refpurpose>

<refsect1> <title>Functions</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><returnvalue>SoupAuthDomain</returnvalue> * </entry><entry>soup_auth_domain_basic_new <phrase>()</phrase></entry></row> <row><entry><returnvalue>gboolean</returnvalue> </entry><entry><phrase>(</phrase>*SoupAuthDomainBasicAuthCallback<phrase>)</phrase> <phrase>()</phrase></entry></row> <row><entry><returnvalue>void</returnvalue> </entry><entry>soup_auth_domain_basic_set_auth_callback <phrase>()</phrase></entry></row> </tbody> </tgroup> </informaltable> </refsect1> <refsect1> <title>Properties</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><type>gpointer</type></entry><entry>auth-callback</entry><entry>Read / Write</entry></row> <row><entry><type>gpointer</type></entry><entry>auth-data</entry><entry>Read / Write</entry></row> </tbody> </tgroup> </informaltable> </refsect1> <refsect1> <title>Types and Values</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <tbody> <row><entry></entry><entry>SoupAuthDomainBasic</entry></row> </tbody> </tgroup> </informaltable> </refsect1> <refsect1> <title>Object Hierarchy</title> <screen> GObject <phrase>╰──</phrase> SoupAuthDomain <phrase>╰──</phrase> SoupAuthDomainBasic </screen> </refsect1> <refsect1><title>Includes</title><synopsis>#include <libsoup/soup.h> </synopsis></refsect1> <refsect1> <title>Description</title> <para><type>SoupAuthDomainBasic</type> handles the server side of HTTP "Basic" (ie, cleartext password) authentication.</para> </refsect1> <refsect1> <title>Functions</title> <refsect2> <title>soup_auth_domain_basic_new ()</title> <programlisting><returnvalue>SoupAuthDomain</returnvalue> * soup_auth_domain_basic_new (<parameter>const <type>char</type> *optname1</parameter>, <parameter>...</parameter>);</programlisting> <para>Creates a <type>SoupAuthDomainBasic</type>. You must set the SoupAuthDomain:realm property, to indicate the realm name to be returned with the authentication challenge to the client. Other parameters are optional.</para> <para><emphasis>[constructor]</emphasis></para><refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>optname1</para></entry> <entry><para>name of first option, or <literal>NULL</literal></para></entry> <entry></entry></row> <row><entry><para>...</para></entry> <entry><para>option name/value pairs</para></entry> <entry></entry></row> </tbody></tgroup></informaltable> </refsect3><refsect3> <title>Returns</title> <para> the new <type>SoupAuthDomain</type></para> </refsect3></refsect2>
<refsect2> <title>SoupAuthDomainBasicAuthCallback ()</title> <programlisting><returnvalue>gboolean</returnvalue> <phrase>(</phrase>*SoupAuthDomainBasicAuthCallback<phrase>)</phrase> (<parameter><type>SoupAuthDomain</type> *domain</parameter>, <parameter><type>SoupServerMessage</type> *msg</parameter>, <parameter>const <type>char</type> *username</parameter>, <parameter>const <type>char</type> *password</parameter>, <parameter><type>gpointer</type> user_data</parameter>);</programlisting> <para>Callback used by <type>SoupAuthDomainBasic</type> for authentication purposes. The application should verify that <parameter>username</parameter> and <parameter>password</parameter> and valid and return <literal>TRUE</literal> or <literal>FALSE</literal>.</para> <para>If you are maintaining your own password database (rather than using the password to authenticate against some other system like PAM or a remote server), you should make sure you know what you are doing. In particular, don't store cleartext passwords, or easily-computed hashes of cleartext passwords, even if you don't care that much about the security of your server, because users will frequently use the same password for multiple sites, and so compromising any site with a cleartext (or easily-cracked) password database may give attackers access to other more-interesting sites as well.</para> <refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>domain</para></entry> <entry><para>the domain. </para></entry> <entry><emphasis>[type SoupAuthDomainBasic]</emphasis></entry></row> <row><entry><para>msg</para></entry> <entry><para>the message being authenticated</para></entry> <entry></entry></row> <row><entry><para>username</para></entry> <entry><para>the username provided by the client</para></entry> <entry></entry></row> <row><entry><para>password</para></entry> <entry><para>the password provided by the client</para></entry> <entry></entry></row> <row><entry><para>user_data</para></entry> <entry><para>the data passed to <function>soup_auth_domain_basic_set_auth_callback()</function></para></entry> <entry></entry></row> </tbody></tgroup></informaltable> </refsect3><refsect3> <title>Returns</title> <para> <literal>TRUE</literal> if <parameter>username</parameter> and <parameter>password</parameter> are valid</para> </refsect3></refsect2>
<refsect2> <title>soup_auth_domain_basic_set_auth_callback ()</title> <programlisting><returnvalue>void</returnvalue> soup_auth_domain_basic_set_auth_callback (<parameter><type>SoupAuthDomain</type> *domain</parameter>, <parameter><type>SoupAuthDomainBasicAuthCallback</type> callback</parameter>, <parameter><type>gpointer</type> user_data</parameter>, <parameter><type>GDestroyNotify</type> dnotify</parameter>);</programlisting> <para>Sets the callback that <parameter>domain</parameter> will use to authenticate incoming requests. For each request containing authorization, <parameter>domain</parameter> will invoke the callback, and then either accept or reject the request based on <parameter>callback</parameter> 's return value.</para> <para>You can also set the auth callback by setting the SoupAuthDomainBasic:auth-callback and SoupAuthDomainBasic:auth-data properties, which can also be used to set the callback at construct time.</para> <refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>domain</para></entry> <entry><para>the domain. </para></entry> <entry><emphasis>[type SoupAuthDomainBasic]</emphasis></entry></row> <row><entry><para>callback</para></entry> <entry><para>the callback</para></entry> <entry></entry></row> <row><entry><para>user_data</para></entry> <entry><para>data to pass to <parameter>auth_callback</parameter> </para></entry> <entry></entry></row> <row><entry><para>dnotify</para></entry> <entry><para>destroy notifier to free <parameter>user_data</parameter> when <parameter>domain</parameter> is destroyed</para></entry> <entry></entry></row> </tbody></tgroup></informaltable> </refsect3></refsect2> </refsect1> <refsect1> <title>Types and Values</title> <refsect2> <title>SoupAuthDomainBasic</title> <programlisting>typedef struct _SoupAuthDomainBasic SoupAuthDomainBasic;</programlisting> <para>Subclass of <type>SoupAuthDomain</type> for Basic authentication.</para> </refsect2> </refsect1> <refsect1> <title>Property Details</title> <refsect2><title>The <literal>“auth-callback”</literal> property</title> <programlisting> “auth-callback” <type>gpointer</type></programlisting> <para>The <type>SoupAuthDomainBasicAuthCallback</type></para> <para><emphasis>[type SoupAuthDomainBasicAuthCallback]</emphasis></para><para>Owner: SoupAuthDomainBasic</para> <para>Flags: Read / Write</para> </refsect2>
<refsect2><title>The <literal>“auth-data”</literal> property</title> <programlisting> “auth-data” <type>gpointer</type></programlisting> <para>The data to pass to the <type>SoupAuthDomainBasicAuthCallback</type></para> <para>Owner: SoupAuthDomainBasic</para> <para>Flags: Read / Write</para> </refsect2> </refsect1> </refentry><refentry> <refmeta> <refentrytitle>SoupAuthDomainDigest</refentrytitle> <manvolnum>3</manvolnum> <refmiscinfo>LIBSOUP-3.0 Library</refmiscinfo> </refmeta>

<refentrytitle>SoupAuthDomainDigest</refentrytitle>

<refname>SoupAuthDomainDigest</refname> <refpurpose>Server-side "Digest" authentication</refpurpose>

<refsect1> <title>Functions</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><returnvalue>SoupAuthDomain</returnvalue> * </entry><entry>soup_auth_domain_digest_new <phrase>()</phrase></entry></row> <row><entry><returnvalue>char</returnvalue> * </entry><entry><phrase>(</phrase>*SoupAuthDomainDigestAuthCallback<phrase>)</phrase> <phrase>()</phrase></entry></row> <row><entry><returnvalue>void</returnvalue> </entry><entry>soup_auth_domain_digest_set_auth_callback <phrase>()</phrase></entry></row> <row><entry><returnvalue>char</returnvalue> * </entry><entry>soup_auth_domain_digest_encode_password <phrase>()</phrase></entry></row> </tbody> </tgroup> </informaltable> </refsect1> <refsect1> <title>Properties</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><type>gpointer</type></entry><entry>auth-callback</entry><entry>Read / Write</entry></row> <row><entry><type>gpointer</type></entry><entry>auth-data</entry><entry>Read / Write</entry></row> </tbody> </tgroup> </informaltable> </refsect1> <refsect1> <title>Types and Values</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <tbody> <row><entry></entry><entry>SoupAuthDomainDigest</entry></row> </tbody> </tgroup> </informaltable> </refsect1> <refsect1> <title>Object Hierarchy</title> <screen> GObject <phrase>╰──</phrase> SoupAuthDomain <phrase>╰──</phrase> SoupAuthDomainDigest </screen> </refsect1> <refsect1><title>Includes</title><synopsis>#include <libsoup/soup.h> </synopsis></refsect1> <refsect1> <title>Description</title> <para><type>SoupAuthDomainDigest</type> handles the server side of HTTP "Digest" authentication.</para> </refsect1> <refsect1> <title>Functions</title> <refsect2> <title>soup_auth_domain_digest_new ()</title> <programlisting><returnvalue>SoupAuthDomain</returnvalue> * soup_auth_domain_digest_new (<parameter>const <type>char</type> *optname1</parameter>, <parameter>...</parameter>);</programlisting> <para>Creates a <type>SoupAuthDomainDigest</type>. You must set the SoupAuthDomain:realm property, to indicate the realm name to be returned with the authentication challenge to the client. Other parameters are optional.</para> <para><emphasis>[constructor]</emphasis></para><refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>optname1</para></entry> <entry><para>name of first option, or <literal>NULL</literal></para></entry> <entry></entry></row> <row><entry><para>...</para></entry> <entry><para>option name/value pairs</para></entry> <entry></entry></row> </tbody></tgroup></informaltable> </refsect3><refsect3> <title>Returns</title> <para> the new <type>SoupAuthDomain</type></para> </refsect3></refsect2>
<refsect2> <title>SoupAuthDomainDigestAuthCallback ()</title> <programlisting><returnvalue>char</returnvalue> * <phrase>(</phrase>*SoupAuthDomainDigestAuthCallback<phrase>)</phrase> (<parameter><type>SoupAuthDomain</type> *domain</parameter>, <parameter><type>SoupServerMessage</type> *msg</parameter>, <parameter>const <type>char</type> *username</parameter>, <parameter><type>gpointer</type> user_data</parameter>);</programlisting> <para>Callback used by <type>SoupAuthDomainDigest</type> for authentication purposes. The application should look up <parameter>username</parameter> in its password database, and return the corresponding encoded password (see <function>soup_auth_domain_digest_encode_password()</function>).</para> <refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>domain</para></entry> <entry><para>the domain. </para></entry> <entry><emphasis>[type SoupAuthDomainDigest]</emphasis></entry></row> <row><entry><para>msg</para></entry> <entry><para>the message being authenticated</para></entry> <entry></entry></row> <row><entry><para>username</para></entry> <entry><para>the username provided by the client</para></entry> <entry></entry></row> <row><entry><para>user_data</para></entry> <entry><para>the data passed to <function>soup_auth_domain_digest_set_auth_callback()</function></para></entry> <entry></entry></row> </tbody></tgroup></informaltable> </refsect3><refsect3> <title>Returns</title> <para>the encoded password, or <literal>NULL</literal> if <parameter>username</parameter> is not a valid user. <parameter>domain</parameter> will free the password when it is done with it. </para> <para><emphasis>[nullable]</emphasis></para> </refsect3></refsect2>
<refsect2> <title>soup_auth_domain_digest_set_auth_callback ()</title> <programlisting><returnvalue>void</returnvalue> soup_auth_domain_digest_set_auth_callback (<parameter><type>SoupAuthDomain</type> *domain</parameter>, <parameter><type>SoupAuthDomainDigestAuthCallback</type> callback</parameter>, <parameter><type>gpointer</type> user_data</parameter>, <parameter><type>GDestroyNotify</type> dnotify</parameter>);</programlisting> <para>Sets the callback that <parameter>domain</parameter> will use to authenticate incoming requests. For each request containing authorization, <parameter>domain</parameter> will invoke the callback, and then either accept or reject the request based on <parameter>callback</parameter> 's return value.</para> <para>You can also set the auth callback by setting the SoupAuthDomainDigest:auth-callback and SoupAuthDomainDigest:auth-data properties, which can also be used to set the callback at construct time.</para> <refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>domain</para></entry> <entry><para>the domain. </para></entry> <entry><emphasis>[type SoupAuthDomainDigest]</emphasis></entry></row> <row><entry><para>callback</para></entry> <entry><para>the callback</para></entry> <entry></entry></row> <row><entry><para>user_data</para></entry> <entry><para>data to pass to <parameter>auth_callback</parameter> </para></entry> <entry></entry></row> <row><entry><para>dnotify</para></entry> <entry><para>destroy notifier to free <parameter>user_data</parameter> when <parameter>domain</parameter> is destroyed</para></entry> <entry></entry></row> </tbody></tgroup></informaltable> </refsect3></refsect2>
<refsect2> <title>soup_auth_domain_digest_encode_password ()</title> <programlisting><returnvalue>char</returnvalue> * soup_auth_domain_digest_encode_password (<parameter>const <type>char</type> *username</parameter>, <parameter>const <type>char</type> *realm</parameter>, <parameter>const <type>char</type> *password</parameter>);</programlisting> <para>Encodes the username/realm/password triplet for Digest authentication. (That is, it returns a stringified MD5 hash of <parameter>username</parameter> , <parameter>realm</parameter> , and <parameter>password</parameter> concatenated together). This is the form that is needed as the return value of <type>SoupAuthDomainDigest</type>'s auth handler.</para> <para>For security reasons, you should store the encoded hash, rather than storing the cleartext password itself and calling this method only when you need to verify it. This way, if your server is compromised, the attackers will not gain access to cleartext passwords which might also be usable at other sites. (Note also that the encoded password returned by this method is identical to the encoded password stored in an Apache .htdigest file.)</para> <refsect3> <title>Parameters</title> <informaltable> <tgroup> <colspec></colspec> <colspec></colspec> <colspec></colspec> <tbody> <row><entry><para>username</para></entry> <entry><para>a username</para></entry> <entry></entry></row> <row><entry><para>realm</para></entry> <entry><para>an auth realm name</para></entry> <entry></entry></row> <row><entry><para>password</para></entry> <entry><para>the password for <parameter>username</parameter> in <parameter>realm</parameter> </para></entry> <entry></entry></row> </tbody></tgroup></informaltable> </refsect3><refsect3> <title>Returns</title> <para> the encoded password</para> </refsect3></refsect2> </refsect1> <refsect1> <title>Types and Values</title> <refsect2> <title>SoupAuthDomainDigest</title> <programlisting>typedef struct _SoupAuthDomainDigest SoupAuthDomainDigest;</programlisting> <para>Subclass of <type>SoupAuthDomain</type> for Digest authentication.</para> </refsect2> </refsect1> <refsect1> <title>Property Details</title> <refsect2><title>The <literal>“auth-callback”</literal> property</title> <programlisting> “auth-callback” <type>gpointer</type></programlisting> <para>The <type>SoupAuthDomainDigestAuthCallback</type></para> <para><emphasis>[type SoupAuthDomainDigestAuthCallback]</emphasis></para><para>Owner: SoupAuthDomainDigest</para> <para>Flags: Read / Write</para> </refsect2>
<refsect2><title>The <literal>“auth-data”</literal> property</title> <programlisting> “auth-data” <type>gpointer</type></programlisting> <para>The data to pass to the <type>SoupAuthDomainDigestAuthCallback</type></para> <para>Owner: SoupAuthDomainDigest</para> <para>Flags: Read / Write</para> </refsect2> </refsect1> </refentry>
Generated by GTK-Doc V1.33.1