soup-dns.h soup-auth-manager.h soup-auth-manager-ntlm.h \
soup-message-queue.h soup-path-map.h soup-ssl.h \
soup-proxy-resolver.h soup-proxy-resolver-gnome.h \
- soup-proxy-resolver-static.h
+ soup-proxy-resolver-static.h soup-directory-input-stream.h \
+ soup-http-input-stream.h soup-password-manager.h \
+ soup-password-manager-gnome.h
# Images to copy into HTML directory.
HTML_IMAGES =
content_files = \
build-howto.xml \
client-howto.xml \
- server-howto.xml \
- porting-2.2-2.4.xml
+ server-howto.xml
# Other files to distribute.
extra_files =
<variablelist>
<varlistentry>
- <term><link linkend="SOUP-SESSION-MAX-CONNS--CAPS"><literal>SOUP_SESSION_MAX_CONNS</literal></link></term>
+ <term><link linkend="SOUP-SESSION-MAX-CONNS:CAPS"><literal>SOUP_SESSION_MAX_CONNS</literal></link></term>
<listitem><para>
Allows you to set the maximum total number of connections
the session will have open at one time. (Once it reaches
</para></listitem>
</varlistentry>
<varlistentry>
- <term><link linkend="SOUP-SESSION-MAX-CONNS-PER-HOST--CAPS"><literal>SOUP_SESSION_MAX_CONNS_PER_HOST</literal></link></term>
+ <term><link linkend="SOUP-SESSION-MAX-CONNS-PER-HOST:CAPS"><literal>SOUP_SESSION_MAX_CONNS_PER_HOST</literal></link></term>
<listitem><para>
Allows you to set the maximum total number of connections
the session will have open <emphasis>to a single
</para></listitem>
</varlistentry>
<varlistentry>
- <term><link linkend="SOUP-SESSION-USE-NTLM--CAPS"><literal>SOUP_SESSION_USE_NTLM</literal></link></term>
+ <term><link linkend="SOUP-SESSION-USE-NTLM:CAPS"><literal>SOUP_SESSION_USE_NTLM</literal></link></term>
<listitem><para>
If <literal>TRUE</literal>, then Microsoft NTLM
authentication will be used if available (and will be
</para></listitem>
</varlistentry>
<varlistentry>
- <term><link linkend="SOUP-SESSION-SSL-CA-FILE--CAPS"><literal>SOUP_SESSION_SSL_CA_FILE</literal></link></term>
+ <term><link linkend="SOUP-SESSION-SSL-CA-FILE:CAPS"><literal>SOUP_SESSION_SSL_CA_FILE</literal></link></term>
<listitem><para>
Points to a file containing certificates for recognized
SSL Certificate Authorities. If this is set, then HTTPS
</para></listitem>
</varlistentry>
<varlistentry>
- <term><link linkend="SOUP-SESSION-ASYNC-CONTEXT--CAPS"><literal>SOUP_SESSION_ASYNC_CONTEXT</literal></link></term>
+ <term><link linkend="SOUP-SESSION-ASYNC-CONTEXT:CAPS"><literal>SOUP_SESSION_ASYNC_CONTEXT</literal></link></term>
<listitem><para>
A <link
linkend="GMainContext"><type>GMainContext</type></link>
</para></listitem>
</varlistentry>
<varlistentry>
- <term><link linkend="SOUP-SESSION-ADD-FEATURE--CAPS"><literal>SOUP_SESSION_ADD_FEATURE</literal></link> and <link linkend="SOUP-SESSION-ADD-FEATURE-BY-TYPE--CAPS"><literal>SOUP_SESSION_ADD_FEATURE_BY_TYPE</literal></link></term>
+ <term><link linkend="SOUP-SESSION-ADD-FEATURE:CAPS"><literal>SOUP_SESSION_ADD_FEATURE</literal></link> and <link linkend="SOUP-SESSION-ADD-FEATURE-BY-TYPE:CAPS"><literal>SOUP_SESSION_ADD_FEATURE_BY_TYPE</literal></link></term>
<listitem><para>
These allow you to specify <link
linkend="SoupSessionFeature"><type>SoupSessionFeature</type></link>s
Additional session functionality is provided as <link
linkend="SoupSessionFeature"><type>SoupSessionFeature</type></link>s,
which can be added to a session, via the <link
-linkend="SOUP-SESSION-ADD-FEATURE--CAPS"><literal>SOUP_SESSION_ADD_FEATURE</literal></link>
+linkend="SOUP-SESSION-ADD-FEATURE:CAPS"><literal>SOUP_SESSION_ADD_FEATURE</literal></link>
and <link
-linkend="SOUP-SESSION-ADD-FEATURE-BY-TYPE--CAPS"><literal>SOUP_SESSION_ADD_FEATURE_BY_TYPE</literal></link>
+linkend="SOUP-SESSION-ADD-FEATURE-BY-TYPE:CAPS"><literal>SOUP_SESSION_ADD_FEATURE_BY_TYPE</literal></link>
options at session-construction-time, or afterward via the <link
linkend="soup-session-add-feature"><function>soup_session_add_feature</function></link>
and <link
<variablelist>
<varlistentry>
- <term><link linkend="SOUP-TYPE-PROXY-RESOLVER-GNOME--CAPS"><type>SoupProxyResolverGNOME</type></link></term>
+ <term><link linkend="SOUP-TYPE-PROXY-RESOLVER-GNOME:CAPS"><type>SoupProxyResolverGNOME</type></link></term>
<listitem><para>
A feature that automatically determines the correct HTTP
proxy to use for requests.
<para>
Use the "add_feature_by_type" property/function to add features that
don't require any configuration (such as <link
-linkend="SOUP-TYPE-PROXY-RESOLVER-GNOME--CAPS"><type>SoupProxyResolverGNOME</type></link>),
+linkend="SOUP-TYPE-PROXY-RESOLVER-GNOME:CAPS"><type>SoupProxyResolverGNOME</type></link>),
and the "add_feature" property/function to add features that must be
constructed first (such as <link
linkend="SoupLogger"><type>SoupLogger</type></link>). For example, an
<para>
(Although this is a bad example, because
<application>libsoup</application> actually has convenience methods
-for dealing with <link linkend="libsoup-24-HTML-Form-Support">HTML
+for dealing with <link linkend="libsoup-2.4-HTML-Form-Support">HTML
forms</link>, as well as <link
-linkend="libsoup-24-XMLRPC-Support">XML-RPC</link>.)
+linkend="libsoup-2.4-XMLRPC-Support">XML-RPC</link>.)
</para>
<para>
to change some default behaviors. For example, by default,
<type>SoupSession</type> automatically handles responses from the
server that redirect to another URL. If you would like to handle these
-yourself, you can set the <link linkend="SOUP-MESSAGE-NO-REDIRECT--CAPS"><literal>SOUP_MESSAGE_NO_REDIRECT</literal></link>
+yourself, you can set the <link linkend="SOUP-MESSAGE-NO-REDIRECT:CAPS"><literal>SOUP_MESSAGE_NO_REDIRECT</literal></link>
flag.
</para>
<para>
The return value from <function>soup_session_send_message</function>
-is a <link linkend="soup-status">libsoup status code</link>,
+is a <link linkend="libsoup-2.4-soup-status">libsoup status code</link>,
indicating either a transport error that prevented the message from
being sent, or the HTTP status that was returned by the server in
response to the message. (The status is also available as
with a <link
linkend="SoupSessionSync"><type>SoupSessionSync</type></link>, the
message will be sent in another thread, with the callback eventually
-being invoked in the session's <link linkend="SOUP-SESSION-ASYNC-CONTEXT--CAPS"><literal>SOUP_SESSION_ASYNC_CONTEXT</literal></link>.)
+being invoked in the session's <link linkend="SOUP-SESSION-ASYNC-CONTEXT:CAPS"><literal>SOUP_SESSION_ASYNC_CONTEXT</literal></link>.)
</para>
</refsect3>
<listitem><para>
<emphasis role="bold"><literal>getbug</literal></emphasis> is a trivial
demonstration of the <link
- linkend="libsoup-XMLRPC-Support">XMLRPC</link> interface.
+ linkend="libsoup-2.4-XMLRPC-Support">XMLRPC</link> interface.
(<emphasis
role="bold"><literal>xmlrpc-test</literal></emphasis> provides
a slightly more complicated example.)
<xi:include href="build-howto.xml"/>
<xi:include href="client-howto.xml"/>
<xi:include href="server-howto.xml"/>
- <xi:include href="porting-2.2-2.4.xml"/>
</chapter>
<chapter>
<chapter>
<title>Additional Features</title>
<xi:include href="xml/soup-session-feature.xml"/>
+ <xi:include href="xml/soup-content-decoder.xml"/>
<xi:include href="xml/soup-content-sniffer.xml"/>
<xi:include href="xml/soup-cookie-jar.xml"/>
<xi:include href="xml/soup-cookie-jar-text.xml"/>
<xi:include href="xml/soup-logger.xml"/>
<xi:include href="xml/soup-proxy-uri-resolver.xml"/>
+ <xi:include href="xml/soup-proxy-resolver-default.xml"/>
</chapter>
<chapter>
<xi:include href="xml/soup-socket.xml"/>
</chapter>
+ <chapter>
+ <title>Experimental streaming API</title>
+ <xi:include href="xml/soup-requester.xml"/>
+ <xi:include href="xml/soup-request.xml"/>
+ <xi:include href="xml/soup-request-http.xml"/>
+ <xi:include href="xml/soup-request-file.xml"/>
+ <xi:include href="xml/soup-request-data.xml"/>
+ <xi:include href="xml/soup-cache.xml"/>
+ </chapter>
+
<index>
<title>Index</title>
</index>
soup_message_set_status
soup_message_set_status_full
soup_message_is_keepalive
+soup_message_get_https_status
+<SUBSECTION>
+soup_message_set_first_party
+soup_message_get_first_party
<SUBSECTION>
soup_message_add_header_handler
soup_message_add_status_code_handler
SOUP_MESSAGE_STATUS_CODE
SOUP_MESSAGE_REASON_PHRASE
SOUP_MESSAGE_SERVER_SIDE
+SOUP_MESSAGE_FIRST_PARTY
+SOUP_MESSAGE_REQUEST_BODY
+SOUP_MESSAGE_REQUEST_HEADERS
+SOUP_MESSAGE_RESPONSE_BODY
+SOUP_MESSAGE_RESPONSE_HEADERS
+SOUP_MESSAGE_TLS_CERTIFICATE
+SOUP_MESSAGE_TLS_ERRORS
<SUBSECTION Standard>
SOUP_MESSAGE
SOUP_IS_MESSAGE
soup_message_headers_replace
soup_message_headers_remove
soup_message_headers_clear
+soup_message_headers_clean_connection_headers
soup_message_headers_get_one
soup_message_headers_get_list
soup_message_headers_get
soup_buffer_new
soup_buffer_new_subbuffer
soup_buffer_new_with_owner
+soup_buffer_new_take
soup_buffer_get_owner
+soup_buffer_get_data
soup_buffer_copy
soup_buffer_free
<SUBSECTION>
<SUBSECTION>
soup_message_body_append
soup_message_body_append_buffer
+soup_message_body_append_take
soup_message_body_truncate
soup_message_body_complete
soup_message_body_flatten
soup_server_run
soup_server_run_async
soup_server_quit
+soup_server_disconnect
soup_server_get_async_context
<SUBSECTION>
SoupServerCallback
<SUBSECTION>
soup_address_get_name
soup_address_get_sockaddr
+soup_address_get_gsockaddr
soup_address_get_physical
soup_address_get_port
<SUBSECTION>
SOUP_IS_ADDRESS_CLASS
SOUP_ADDRESS_GET_CLASS
SoupAddressClass
-<SUBSECTION Private>
-AF_INET6
</SECTION>
<SECTION>
soup_session_requeue_message
soup_session_send_message
soup_session_cancel_message
+soup_session_prepare_for_uri
soup_session_abort
<SUBSECTION>
soup_session_pause_message
SOUP_SESSION_ADD_FEATURE
SOUP_SESSION_ADD_FEATURE_BY_TYPE
SOUP_SESSION_REMOVE_FEATURE_BY_TYPE
+SOUP_SESSION_ACCEPT_LANGUAGE
+SOUP_SESSION_ACCEPT_LANGUAGE_AUTO
+SOUP_SESSION_SSL_STRICT
<SUBSECTION Standard>
SOUP_IS_SESSION
SOUP_IS_SESSION_CLASS
SOUP_TYPE_SESSION
SoupSessionClass
soup_session_get_type
+<SUBSECTION Private>
+SoupConnection
+SoupConnectionState
+SoupMessageQueue
+SoupMessageQueueItem
</SECTION>
<SECTION>
<SUBSECTION Private>
soup_session_feature_attach
soup_session_feature_detach
+soup_session_feature_add_feature
+soup_session_feature_has_feature
+soup_session_feature_remove_feature
</SECTION>
<SECTION>
soup_auth_new
soup_auth_update
<SUBSECTION>
+SOUP_TYPE_AUTH_BASIC
+SOUP_TYPE_AUTH_DIGEST
+SOUP_TYPE_AUTH_NTLM
+<SUBSECTION>
soup_auth_is_for_proxy
soup_auth_get_scheme_name
soup_auth_get_host
SOUP_IS_AUTH_CLASS
SOUP_AUTH_GET_CLASS
SoupAuthClass
+soup_auth_basic_get_type
+soup_auth_digest_get_type
+soup_auth_ntlm_get_type
+<SUBSECTION Private>
+soup_auth_get_saved_password
+soup_auth_get_saved_users
+soup_auth_has_saved_password
+soup_auth_save_password
</SECTION>
<SECTION>
SOUP_SOCKET_SSL_CREDENTIALS
SOUP_SOCKET_ASYNC_CONTEXT
SOUP_SOCKET_TIMEOUT
+SOUP_SOCKET_SSL_FALLBACK
+SOUP_SOCKET_SSL_STRICT
+SOUP_SOCKET_TLS_CERTIFICATE
+SOUP_SOCKET_TLS_ERRORS
+SOUP_SOCKET_TRUSTED_CERTIFICATE
<SUBSECTION Standard>
SOUP_SOCKET
SOUP_IS_SOCKET
SoupSocketClass
<SUBSECTION Private>
soup_ssl_error_quark
+soup_socket_get_fd
+soup_socket_handshake_async
+soup_socket_handshake_sync
</SECTION>
<SECTION>
soup_uri_to_string
<SUBSECTION>
soup_uri_copy
+soup_uri_copy_host
soup_uri_equal
+soup_uri_host_equal
+soup_uri_host_hash
soup_uri_free
<SUBSECTION>
soup_uri_encode
<SUBSECTION>
SOUP_URI_SCHEME_HTTP
SOUP_URI_SCHEME_HTTPS
+SOUP_URI_SCHEME_DATA
+SOUP_URI_SCHEME_FILE
+SOUP_URI_SCHEME_FTP
soup_uri_uses_default_port
SOUP_URI_VALID_FOR_HTTP
<SUBSECTION>
soup_uri_set_scheme
+soup_uri_get_scheme
soup_uri_set_user
+soup_uri_get_user
soup_uri_set_password
+soup_uri_get_password
soup_uri_set_host
+soup_uri_get_host
soup_uri_set_port
+soup_uri_get_port
soup_uri_set_path
+soup_uri_get_path
soup_uri_set_query
soup_uri_set_query_from_form
soup_uri_set_query_from_fields
+soup_uri_get_query
soup_uri_set_fragment
+soup_uri_get_fragment
<SUBSECTION Standard>
SOUP_TYPE_URI
soup_uri_get_type
+<SUBSECTION Private>
+uri_decoded_copy
</SECTION>
<SECTION>
soup_date_to_time_t
soup_date_to_timeval
soup_date_is_past
+soup_date_get_day
+soup_date_get_hour
+soup_date_get_minute
+soup_date_get_month
+soup_date_get_offset
+soup_date_get_second
+soup_date_get_utc
+soup_date_get_year
soup_date_free
<SUBSECTION>
soup_headers_parse_request
soup_header_parse_semi_param_list
soup_header_free_param_list
soup_header_g_string_append_param
+soup_header_g_string_append_param_quoted
<SUBSECTION>
soup_str_case_equal
soup_str_case_hash
soup_date_copy
SOUP_TYPE_DATE
soup_date_get_type
-soup_form_decode_urlencoded
-soup_form_encode_urlencoded
-soup_form_encode_urlencoded_list
+soup_char_is_token
+soup_char_is_uri_gen_delims
+soup_char_is_uri_percent_encoded
+soup_char_is_uri_sub_delims
+soup_char_is_uri_unreserved
+SOUP_CHAR_HTTP_CTL
+SOUP_CHAR_HTTP_SEPARATOR
+SOUP_CHAR_URI_GEN_DELIMS
+SOUP_CHAR_URI_PERCENT_ENCODED
+SOUP_CHAR_URI_SUB_DELIMS
</SECTION>
<SECTION>
-<FILE>soup-forms</FILE>
+<FILE>soup-form</FILE>
<TITLE>HTML Form Support</TITLE>
<SUBSECTION>
SOUP_FORM_MIME_TYPE_MULTIPART
soup_form_request_new_from_datalist
soup_form_request_new_from_hash
soup_form_request_new_from_multipart
+<SUBSECTION Private>
+soup_form_decode_urlencoded
+soup_form_encode_urlencoded
+soup_form_encode_urlencoded_list
</SECTION>
<SECTION>
soup_xmlrpc_set_response
soup_xmlrpc_set_fault
<SUBSECTION>
-SOUP_XMLRPC_ERROR
-SoupXMLRPCError
SOUP_XMLRPC_FAULT
SoupXMLRPCFault
<SUBSECTION Private>
soup_xmlrpc_error_quark
+SOUP_XMLRPC_ERROR
+SoupXMLRPCError
soup_xmlrpc_fault_quark
</SECTION>
soup_cookie_new
soup_cookie_parse
soup_cookie_copy
-soup_cookie_equal
soup_cookie_free
<SUBSECTION>
soup_cookie_set_name
+soup_cookie_get_name
soup_cookie_set_value
+soup_cookie_get_value
soup_cookie_set_domain
+soup_cookie_get_domain
soup_cookie_set_path
+soup_cookie_get_path
soup_cookie_set_max_age
SOUP_COOKIE_MAX_AGE_ONE_HOUR
SOUP_COOKIE_MAX_AGE_ONE_DAY
SOUP_COOKIE_MAX_AGE_ONE_WEEK
SOUP_COOKIE_MAX_AGE_ONE_YEAR
soup_cookie_set_expires
+soup_cookie_get_expires
soup_cookie_set_secure
+soup_cookie_get_secure
soup_cookie_set_http_only
+soup_cookie_get_http_only
<SUBSECTION>
soup_cookie_applies_to_uri
+soup_cookie_domain_matches
<SUBSECTION>
soup_cookie_to_cookie_header
soup_cookie_to_set_cookie_header
<SUBSECTION Standard>
SOUP_TYPE_COOKIE
soup_cookie_get_type
+<SUBSECTION Private>
+soup_cookie_equal
</SECTION>
<SECTION>
<TITLE>SoupCookieJar</TITLE>
SoupCookieJar
soup_cookie_jar_new
-soup_cookie_jar_save
soup_cookie_jar_get_cookies
soup_cookie_jar_set_cookie
+soup_cookie_jar_set_cookie_with_first_party
<SUBSECTION>
soup_cookie_jar_add_cookie
soup_cookie_jar_delete_cookie
soup_cookie_jar_all_cookies
<SUBSECTION>
+SoupCookieJarAcceptPolicy
+soup_cookie_jar_get_accept_policy
+soup_cookie_jar_set_accept_policy
+<SUBSECTION>
SOUP_COOKIE_JAR_READ_ONLY
+SOUP_COOKIE_JAR_ACCEPT_POLICY
<SUBSECTION Standard>
SoupCookieJarClass
SOUP_COOKIE_JAR
SOUP_IS_COOKIE_JAR_CLASS
SOUP_TYPE_COOKIE_JAR
soup_cookie_jar_get_type
+soup_cookie_jar_save
</SECTION>
<SECTION>
<SUBSECTION Standard>
soup_proxy_resolver_gnome_get_type
soup_gnome_features_2_26_get_type
+SOUP_TYPE_PASSWORD_MANAGER_GNOME
+soup_password_manager_gnome_get_type
</SECTION>
<SECTION>
SoupContentSnifferPrivate
soup_content_sniffer_get_type
</SECTION>
+
+<SECTION>
+<FILE>soup-cache</FILE>
+<TITLE>SoupCache</TITLE>
+SoupCache
+SoupCacheType
+soup_cache_new
+soup_cache_flush
+soup_cache_clear
+soup_cache_dump
+soup_cache_load
+soup_cache_get_max_size
+soup_cache_set_max_size
+<SUBSECTION Standard>
+SOUP_TYPE_CACHE
+SOUP_IS_CACHE
+SOUP_IS_CACHE_CLASS
+SOUP_CACHE
+SOUP_CACHE_CLASS
+SOUP_CACHE_GET_CLASS
+SoupCacheClass
+SoupCachePrivate
+<SUBSECTION Private>
+soup_cache_generate_conditional_request
+soup_cache_get_cacheability
+soup_cache_get_type
+soup_cache_has_response
+soup_cache_send_response
+SoupCacheResponse
+SoupCacheability
+</SECTION>
+
+<SECTION>
+<FILE>soup-content-decoder</FILE>
+<TITLE>SoupContentDecoder</TITLE>
+SoupContentDecoder
+<SUBSECTION Standard>
+SOUP_TYPE_CONTENT_DECODER
+SOUP_IS_CONTENT_DECODER
+SOUP_IS_CONTENT_DECODER_CLASS
+SOUP_CONTENT_DECODER
+SOUP_CONTENT_DECODER_CLASS
+SOUP_CONTENT_DECODER_GET_CLASS
+SoupContentDecoderClass
+SoupContentDecoderPrivate
+soup_content_decoder_get_type
+</SECTION>
+
+<SECTION>
+<FILE>soup-proxy-resolver-default</FILE>
+<TITLE>SoupProxyResolverDefault</TITLE>
+SoupProxyResolverDefault
+<SUBSECTION Standard>
+soup_proxy_resolver_default_get_type
+SoupProxyResolverDefaultClass
+SOUP_TYPE_PROXY_RESOLVER_DEFAULT
+SOUP_PROXY_RESOLVER_DEFAULT
+SOUP_PROXY_RESOLVER_DEFAULT_CLASS
+SOUP_PROXY_RESOLVER_DEFAULT_GET_CLASS
+SOUP_IS_PROXY_RESOLVER_DEFAULT
+SOUP_IS_PROXY_RESOLVER_DEFAULT_CLASS
+</SECTION>
+
+<SECTION>
+<FILE>soup-requester</FILE>
+<TITLE>SoupRequester</TITLE>
+SoupRequester
+soup_requester_new
+soup_requester_request
+soup_requester_request_uri
+<SUBSECTION>
+SoupRequesterError
+SOUP_REQUESTER_ERROR
+<SUBSECTION Standard>
+soup_requester_get_type
+SoupRequesterClass
+SoupRequesterPrivate
+SOUP_TYPE_REQUESTER
+SOUP_REQUESTER
+SOUP_REQUESTER_CLASS
+SOUP_REQUESTER_GET_CLASS
+SOUP_IS_REQUESTER
+SOUP_IS_REQUESTER_CLASS
+<SUBSECTION Private>
+soup_requester_error_quark
+</SECTION>
+
+<SECTION>
+<FILE>soup-request</FILE>
+<TITLE>SoupRequest</TITLE>
+SoupRequest
+soup_request_send
+soup_request_send_async
+soup_request_send_finish
+<SUBSECTION>
+soup_request_get_content_length
+soup_request_get_content_type
+soup_request_get_session
+soup_request_get_uri
+<SUBSECTION>
+SOUP_REQUEST_SESSION
+SOUP_REQUEST_URI
+<SUBSECTION Standard>
+SOUP_IS_REQUEST
+SOUP_IS_REQUEST_CLASS
+SOUP_REQUEST
+SOUP_REQUEST_CLASS
+SOUP_REQUEST_GET_CLASS
+SOUP_TYPE_REQUEST
+SoupRequestClass
+SoupRequestPrivate
+soup_request_get_type
+</SECTION>
+
+<SECTION>
+<FILE>soup-request-data</FILE>
+<TITLE>SoupRequestData</TITLE>
+SoupRequestData
+<SUBSECTION Standard>
+SOUP_IS_REQUEST_DATA
+SOUP_IS_REQUEST_DATA_CLASS
+SOUP_REQUEST_DATA
+SOUP_REQUEST_DATA_CLASS
+SOUP_REQUEST_DATA_GET_CLASS
+SOUP_TYPE_REQUEST_DATA
+SoupRequestDataClass
+SoupRequestDataPrivate
+soup_request_data_get_type
+</SECTION>
+
+<SECTION>
+<FILE>soup-request-file</FILE>
+<TITLE>SoupRequestFile</TITLE>
+SoupRequestFile
+soup_request_file_get_file
+<SUBSECTION Standard>
+SOUP_IS_REQUEST_FILE
+SOUP_IS_REQUEST_FILE_CLASS
+SOUP_REQUEST_FILE
+SOUP_REQUEST_FILE_CLASS
+SOUP_REQUEST_FILE_GET_CLASS
+SOUP_TYPE_REQUEST_FILE
+SoupRequestFileClass
+SoupRequestFilePrivate
+soup_request_file_get_type
+</SECTION>
+
+<SECTION>
+<FILE>soup-request-http</FILE>
+<TITLE>SoupRequestHTTP</TITLE>
+SoupRequestHTTP
+soup_request_http_get_message
+<SUBSECTION Standard>
+SOUP_IS_REQUEST_HTTP
+SOUP_IS_REQUEST_HTTP_CLASS
+SOUP_REQUEST_HTTP
+SOUP_REQUEST_HTTP_CLASS
+SOUP_REQUEST_HTTP_GET_CLASS
+SOUP_TYPE_REQUEST_HTTP
+SoupRequestHTTPClass
+SoupRequestHTTPPrivate
+soup_request_http_get_type
+</SECTION>
+
+++ /dev/null
-<?xml version="1.0"?>
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
-<refentry id="libsoup-porting-2.2-2.4">
-<refmeta>
-<refentrytitle>libsoup 2.2 to 2.4 porting notes</refentrytitle>
-<manvolnum>3</manvolnum>
-<refmiscinfo>LIBSOUP Library</refmiscinfo>
-</refmeta>
-
-<refnamediv>
-<refname>Porting notes</refname><refpurpose>Notes on porting from libsoup 2.2 to 2.4</refpurpose>
-</refnamediv>
-
-<refsect2>
-<title>Overview</title>
-
-<para>
-After many API-compatible releases in the 2.2 series,
-<application>libsoup</application> has now changed its API and bumped
-its version number to 2.4. Changes were made for a variety of reasons:
-</para>
-
-<itemizedlist>
- <listitem><para>
- To fix bugs and add features that couldn't be done ABI-compatibly.
- </para></listitem>
-
- <listitem><para>
- To make it easier to generate bindings for libsoup for
- languages other than C.
- </para></listitem>
-
- <listitem><para>
- To clean up ugly/confusing old APIs
- </para></listitem>
-
- <listitem><para>
- To be more glib/gobject/gtk-like in general.
- </para></listitem>
-</itemizedlist>
-
-</refsect2>
-
-<refsect2>
-<title>SoupMessage</title>
-
-<para>
-<link linkend="SoupMessage"><type>SoupMessage</type></link> has had a
-number of API changes made, mostly to increase its
-language-bindability.
-</para>
-
-<refsect3>
-<title>SoupMessageHeaders</title>
-
-<para>
- <type>SoupMessage</type>'s
- <structfield>request_headers</structfield> and
- <structfield>response_headers</structfield> fields are now an
- opaque type (<link
- linkend="SoupMessageHeaders"><type>SoupMessageHeaders</type></link>)
- rather than being <type>GHashTables</type>. The method names have
- changed slightly to reflect this:
-</para>
-
-<variablelist>
- <varlistentry>
- <term><function>soup_message_add_header</function></term>
- <listitem><para>
- → <link linkend="soup-message-headers-append"><function>soup_message_headers_append</function></link>
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term><function>soup_message_get_header</function></term>
- <listitem><para>
- → <link linkend="soup-message-headers-get"><function>soup_message_headers_get</function></link>
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term><function>soup_message_foreach_header</function></term>
- <listitem><para>
- → <link linkend="soup-message-headers-foreach"><function>soup_message_headers_foreach</function></link>
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term><function>soup_message_remove_header</function></term>
- <listitem><para>
- → <link linkend="soup-message-headers-remove"><function>soup_message_headers_remove</function></link>
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term><function>soup_message_clear_headers</function></term>
- <listitem><para>
- → <link linkend="soup-message-headers-clear"><function>soup_message_headers_clear</function></link>
- </para></listitem>
- </varlistentry>
-</variablelist>
-
-<para>
- <function>soup_message_get_header_list</function> has no equivalent;
- if multiple copies of a header are present,
- <function>soup_message_headers_get</function> will return all of
- them, concatenated together and separated by commas; RFC 2616 says
- that the two forms (multiple headers, and a single header with
- comma-separated values) are equivalent; this change to libsoup
- ensures that applications will treat them as equivalent.
-</para>
-
-<para>
- In addition, certain important header fields now have
- dedicated get/set methods:
-</para>
-
-<itemizedlist>
- <listitem><para>
- <link linkend="soup-message-headers-get-encoding"><function>soup_message_headers_get_encoding</function></link> / <link linkend="soup-message-headers-set-encoding"><function>soup_message_headers_set_encoding</function></link>
- </para></listitem>
-
- <listitem><para>
- <link linkend="soup-message-headers-get-content-length"><function>soup_message_headers_get_content_length</function></link> / <link linkend="soup-message-headers-set-content-length"><function>soup_message_headers_set_content_length</function></link>
- </para></listitem>
-
- <listitem><para>
- <link linkend="soup-message-headers-get-expectations"><function>soup_message_headers_get_expectations</function></link> / <link linkend="soup-message-headers-set-expectations"><function>soup_message_headers_set_expectations</function></link>
- </para></listitem>
-</itemizedlist>
-
-<para>
- (<literal>soup_message_headers_set_expectation(msg, SOUP_EXPECTATION_CONTINUE)</literal>
- replaces the <literal>SOUP_MESSAGE_EXPECT_CONTINUE</literal>
- message flag).
-</para>
-
-</refsect3>
-
-<refsect3>
-<title>SoupMessageBody</title>
-
-<para>
- Similarly, the <structfield>request_body</structfield> and
- <structfield>response</structfield> fields (renamed from
- <structfield>request</structfield> and <structfield>response</structfield>) are
- now a new type, <link
- linkend="SoupMessageBody"><type>SoupMessageBody</type></link>,
- implemented in terms of <link
- linkend="SoupBuffer"><type>SoupBuffer</type></link>, a refcounted
- memory buffer type with clearer semantics than the old
- <type>SoupDataBuffer</type>/<type>SoupOwnership</type>.
-</para>
-
-<variablelist>
- <varlistentry>
- <term><literal>SOUP_BUFFER_STATIC</literal></term>
- <listitem><para>
- → <link
- linkend="SOUP-MEMORY-STATIC:CAPS"><literal>SOUP_MEMORY_STATIC</literal></link>
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>SOUP_BUFFER_SYSTEM_OWNED</literal></term>
- <listitem><para>
- → <link
- linkend="SOUP-MEMORY-TAKE:CAPS"><literal>SOUP_MEMORY_TAKE</literal></link>
- (meaning <application>libsoup</application>
- should take ownership of the memory from your).
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>SOUP_BUFFER_USER_OWNED</literal></term>
- <listitem><para>
- → <link
- linkend="SOUP-MEMORY-COPY:CAPS"><literal>SOUP_MEMORY_COPY</literal></link>
- (meaning <application>libsoup</application>
- should make a copy of the memory, because you
- can't make any guarantees about how long it will
- last.)
- </para></listitem>
- </varlistentry>
-</variablelist>
-
-<para>
- A fourth <type>SoupMemoryUse</type> value is also available: <link
- linkend="SOUP-MEMORY-TEMPORARY:CAPS"><literal>SOUP_MEMORY_TEMPORARY</literal></link>,
- which helps to avoid extra copies in some cases.
- <literal>SOUP_MEMORY_TEMPORARY</literal> means that the memory
- will last at least as long as the object you are handing it to (a
- <type>SoupBuffer</type>, <type>SoupMessageBody</type>, or
- <type>SoupMessage</type>), and so doesn't need to be copied right
- away, but that if anyone makes a copy of the buffer,
- <application>libsoup</application> needs to make a new copy of the
- memory for them at that point, since the original pointer may not
- remain valid for the lifetime of the new copy.
-</para>
-
-<para>
- (In the future, there may be additional <type>SoupBuffer</type>
- and <type>SoupMessageBody</type> methods to work directly with
- mmapped memory, splicing to file descriptors, etc.)
-</para>
-
-<para>
- <link
- linkend="soup-message-set-request"><function>soup_message_set_request</function></link>
- and <link
- linkend="soup-message-set-response"><function>soup_message_set_response</function></link>
- still work roughly like they used to.
-</para>
-
-<para>
- Unlike the old <structfield>request</structfield> and
- <structfield>response</structfield> fields, the new
- <structfield>request_body</structfield> and
- <structfield>response_body</structfield> fields are not guaranteed
- to be filled in at all times. (In particular, the
- <structfield>response_body</structfield> is not filled in until it
- has been fully read, although you can use <link
- linkend="soup-message-body-get-chunk"><function>soup_message_body_get_chunk</function></link>
- to iterate through the chunks before that point if you need to.)
-</para>
-
-<para>
- When <structfield>request_body</structfield> and
- <structfield>response_body</structfield> <emphasis>are</emphasis>
- filled in, they are <literal>'\0'</literal>-terminated for your
- processing convenience. (The terminating 0 byte is not included in
- their length.)
-</para>
-
-</refsect3>
-
-<refsect3>
-<title>Chunked encoding</title>
-
-<para>
- The prototype of the <link
- linkend="SoupMessage-got-chunk"><literal>SoupMessage::got_chunk</literal></link>
- signal has been changed; it now includes the chunk as a
- <type>SoupBuffer</type> parameter (rather than storing the chunk
- data in <literal>msg->response</literal> as in 2.2). <link
- linkend="SoupMessageFlags"><literal>SOUP_MESSAGE_OVERWRITE_CHUNKS</literal></link>
- is now somewhat poorly named, but still has essentially the same
- semantics: if you set it, each chunk will be discarded after it is
- read, and <literal>msg->response_body</literal> will not be filled
- in with the complete response at the end of message processing.
-</para>
-
-<para>
- The API for sending chunked responses from a
- <type>SoupServer</type> is also slightly different now:
-</para>
-
-<variablelist>
- <varlistentry>
- <term><function>soup_server_message_set_encoding</function></term>
- <listitem><para>
- → <link
- linkend="soup-message-headers-set-encoding"><function>soup_message_headers_set_encoding</function></link>
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term><function>soup_message_add_chunk</function></term>
- <listitem><para>
- → <link
- linkend="soup-message-body-append"><function>soup_message_body_append</function></link>
- or <link
- linkend="soup-message-body-append-buffer"><function>soup_message_body_append_buffer</function></link>
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term><function>soup_message_add_final_chunk</function></term>
- <listitem><para>
- → <link
- linkend="soup-message-body-complete"><function>soup_message_body_complete</function></link>
- </para></listitem>
- </varlistentry>
-</variablelist>
-
-<para>
- Since the new chunk-sending APIs require you to explicitly pass
- the
- <structfield>request_headers</structfield>/<structfield>request_body</structfield>
- fields, rather than just assuming you're talking about the
- response body, in theory it is now possible to use chunked
- encoding with the request as well. As of the 2.3.0 release this
- has not yet been tested.
-</para>
-
-</refsect3>
-
-<refsect3>
-<title>Methods</title>
-
-<para>
- <type>SoupMessage</type>'s
- <structfield>method</structfield> field is now an interned
- string, and you can compare the method directly against
- the defines such as <link
- linkend="SOUP-METHOD-GET:CAPS"><literal>SOUP_METHOD_GET</literal></link>
- (eg, in a <type>SoupServer</type> request handler).
- <function>soup_method_get_id</function> and the
- <literal>SOUP_METHOD_ID_*</literal> macros are now gone.
-</para>
-</refsect3>
-
-<refsect3>
-<title>Handlers</title>
-
-<para>
- <link
- linkend="soup-message-add-header-handler"><function>soup_message_add_header_handler</function></link>
- and <link
- linkend="soup-message-add-status-code-handler"><function>soup_message_add_status_code_handler</function></link>
- are now just clever wrappers around
- <function>g_signal_connect</function>. In particular, you now pass
- a signal name to them rather than a <type>SoupHandlerPhase</type>,
- and you remove them with the normal signal handler remove methods.
- However, they still retain the special behavior that if the
- message has been cancelled or requeued when the time comes for the
- handler to run, then the handler will be skipped. (Use plain
- <function>g_signal_connect</function> if you don't want that
- behavior.)
-</para>
-</refsect3>
-
-<refsect3>
-<title>I/O-related <type>SoupMessage</type> methods</title>
-
-<para>
- <function>soup_message_io_pause</function> and
- <function>soup_message_io_unpause</function> have been moved to
- <type>SoupSession</type> and <type>SoupServer</type>, to better
- reflect the fact that the session/server control the I/O, and
- <type>SoupMessage</type> is merely acted-upon by them.
-</para>
-
-<variablelist>
- <varlistentry>
- <term><function>soup_message_io_pause</function></term>
- <listitem><para>
- → <link linkend="soup-session-pause-message"><function>soup_session_pause_message</function></link> / <link linkend="soup-server-pause-message"><function>soup_server_pause_message</function></link>
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term><function>soup_message_io_unpause</function></term>
- <listitem><para>
- → <link linkend="soup-session-unpause-message"><function>soup_session_unpause_message</function></link> / <link linkend="soup-server-unpause-message"><function>soup_server_unpause_message</function></link>
- </para></listitem>
- </varlistentry>
-</variablelist>
-
-<para>
- <literal>msg->status</literal> (the I/O status) is now
- gone as well, because (a) it's really an internal state of
- <type>SoupSession</type>, and (b) it's too easy to confuse
- with <literal>msg->status_code</literal> (the HTTP status)
- anyway. Code that used to check if status was
- <literal>SOUP_MESSAGE_STATUS_FINISHED</literal> needs to
- be rewritten to track whether or not the <link
- linkend="SoupMessage-finished"><literal>finished</literal></link>
- signal has been emitted.
-</para>
-
-</refsect3>
-
-<refsect3>
-<title>HTTP-Version</title>
-
-<para>
- <type>SoupHttpVersion</type> is now <link
- linkend="SoupHTTPVersion"><type>SoupHTTPVersion</type></link>
-</para>
-</refsect3>
-
-</refsect2>
-
-<refsect2>
-<title>SoupSession</title>
-
-<refsect3>
-<title><function>soup_session_queue_message</function> callback</title>
-
-<para>
- <link
- linkend="soup-session-queue-message"><function>soup_session_queue_message</function></link>'s
- callback parameter now includes the <type>SoupSession</type> as a
- parameter, reflecting the fact that it is a
- <type>SoupSession</type> callback, not a <type>SoupMessage</type>
- callback. (It has also been renamed, from
- <type>SoupMessageCallbackFn</type> to <link
- linkend="SoupSessionCallback"><type>SoupSessionCallback</type></link>.)
-</para>
-</refsect3>
-
-<refsect3>
-<title>Authentication</title>
-
-<para>
- <type>SoupSession</type>'s <literal>authenticate</literal> and
- <literal>reauthenticate</literal> signals have been merged into a
- single <link
- linkend="SoupSession-authenticate"><literal>authenticate</literal></link>
- signal with a <parameter>retrying</parameter> parameter to indicate if
- it's the second (or later) try. Also, the signal now includes a
- <link linkend="SoupAuth"><type>SoupAuth</type></link> directly,
- and you authenticate by calling <link
- linkend="soup-auth-authenticate"><function>soup_auth_authenticate</function></link>
- on the auth (rather than passing back a username and password from
- the signal handler).
-</para>
-</refsect3>
-
-<refsect3>
-<title><type>SoupLogger</type></title>
-
-<para>
-<link linkend="libsoup-SoupLogger"><type>SoupLogger</type></link> is a
-new object that copies the behavior of
-<application>evolution-exchange</application>'s
-<literal>E2K_DEBUG</literal> and its clones. That is, it causes a
-<type>SoupSession</type> to start logging some or all of its HTTP
-traffic to stdout, for debugging purposes.
-</para>
-</refsect3>
-
-<refsect3>
-<title><type>SoupMessageFilter</type></title>
-
-<para>
- <type>SoupMessageFilter</type> is gone; code that used to use it
- can now connect to the <link
- linkend="SoupSession-request-started"><literal>SoupSession::request-started</literal></link>
- signal to get a chance to act on each message as it is sent.
- (This is how <type>SoupLogger</type> works.)
-</para>
-</refsect3>
-
-<refsect3>
-<title>Internal types</title>
-
-<para>
- The <type>SoupConnection</type> and <type>SoupMessageQueue</type>
- types (which should always have been internal to
- <type>SoupSession</type>) have been removed from the public API.
-</para>
-</refsect3>
-
-</refsect2>
-
-<refsect2>
-<title>SoupURI</title>
-
-<type>SoupUri</type> has been renamed <link
-linkend="SoupURI"><type>SoupURI</type></link>, and its behavior has
-changed in a few ways:
-
-<itemizedlist>
- <listitem>
- <para>
- It no longer fully-decodes %-encoded URI components. This
- is necessary to ensure that complicated URIs (eg, URIs
- that include other URIs as query parameters) can be
- round-tripped correctly. This corresponds to the old
- <structfield>broken_encoding</structfield> behavior, but
- that flag no longer exists, since it is the default and
- there's no way to turn it off.
- </para>
-
- <para>
- In theory, this is an ABI-breaking change, especially for
- <link
- linkend="SoupServer"><type>SoupServer</type></link>s.
- However, it is unlikely to actually break anything. (And
- in the <type>SoupServer</type> case, servers now
- fully-decode the <structfield>path</structfield> component
- themselves unless you set the <link
- linkend="SOUP-SERVER-RAW-PATHS:CAPS"><literal>SOUP_SERVER_RAW_PATHS</literal></link>
- flag on the server, so the behavior should still be the
- same.
- </para>
- </listitem>
-
- <listitem><para>
- It uses the RFC3986 parsing rules, including support for IPv6 literal
- addresses.
- </para></listitem>
-
- <listitem>
- <para>
- The field formerly called
- <structfield>protocol</structfield> is now
- <structfield>scheme</structfield>, to match the spec, and
- it's an interned string rather than a quark. The names of
- the predefined values have changed to match:
- </para>
-
- <variablelist>
- <varlistentry>
- <term><function>SOUP_PROTOCOL_HTTP</function></term>
- <listitem><para>
- → <link linkend="SOUP-URI-SCHEME-HTTP:CAPS"><literal>SOUP_URI_SCHEME_HTTP</literal></link>
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term><function>SOUP_PROTOCOL_HTTPS</function></term>
- <listitem><para>
- → <link linkend="SOUP-URI-SCHEME-HTTPS:CAPS"><literal>SOUP_URI_SCHEME_HTTPS</literal></link>
- </para></listitem>
- </varlistentry>
- </variablelist>
- </listitem>
-</itemizedlist>
-
-<para>
-<link linkend="soup-uri-decode"><function>soup_uri_decode</function></link>
-now returns a new string rather than modifying its input string in
-place. The new method <link
-linkend="soup-uri-normalize"><function>soup_uri_normalize</function></link>,
-which removes some, but not all, %-encoding, behaves similarly.
-</para>
-
-<para>
-Finally, <type>SoupURI</type> (as well as most other struct types in
-<application>libsoup</application>) now uses the glib "slice"
-allocator, so any code that uses <link
-linkend="g-new"><function>g_new</function></link> to create
-<type>SoupURI</type>s is wrong. If you want to create a URI "by hand",
-you can call <link
-linkend="soup-uri-new"><function>soup_uri_new</function></link>,
-passing <literal>NULL</literal>, and you will get back an empty
-<type>SoupURI</type>. There are also now methods that can be used to
-set its fields (eg, <link
-linkend="soup-uri-set-scheme"><function>soup_uri_set_scheme</function></link>,
-<link
-linkend="soup-uri-set-path"><function>soup_uri_set_path</function></link>,
-etc) rather than mucking with the fields directly.
-</para>
-
-<refsect3>
-<title>Forms</title>
-
-<para>
-Related to <type>SoupURI</type>, there are some new helper methods for
-dealing with HTML forms. <link
-linkend="soup-form-decode-urlencoded">soup_form_decode_urlencoded</link>
-decodes a URI <structfield>query</structfield> component (or an
-<literal>application/x-www-form-urlencoded</literal> request body)
-into a <type>GHashTable</type>. <link
-linkend="soup-form-encode-urlencoded">soup_form_encode_urlencoded</link>
-reverses the process, allowing you to fill in a
-<literal>uri->query</literal> with a properly-encoded form dataset.
-(<type>SoupURI</type> also provides <link
-linkend="soup-uri-set-query-from-form"><function>soup_uri_set_query_from_form</function></link>
-to help with this.)
-</para>
-</refsect3>
-
-</refsect2>
-
-
-<refsect2>
-<title>XML-RPC and SOAP</title>
-
-<refsect3>
-<title>SOAP</title>
-<para>
-SOAP support has been removed; the existing methods covered only a
-teeny tiny subset of SOAP, which was really only useful to a single
-application. (The code that was formerly in libsoup has been moved to
-that application.). If you were using this code, you can resurrect a
-libsoup-2.4-compatible version of it from revision 1016 of libsoup
-svn.
-</para>
-</refsect3>
-
-<refsect3>
-<title>XML-RPC</title>
-<para>
-The XML-RPC code has been completely rewritten to make it simpler to
-implement XML-RPC clients and servers. (Note: the server-side code has
-not been heavily tested yet.) The <link
-linkend="libsoup-XMLRPC-Support">new XML-RPC API</link> makes use of
-<type>GValue</type>s, with the following type mappings:
-</para>
-
-<variablelist>
- <varlistentry>
- <term><literal>int</literal></term>
- <listitem><para>
- → <type>int</type> (<link linkend="G-TYPE-INT:CAPS"><literal>G_TYPE_INT</literal></link>)
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>boolean</literal></term>
- <listitem><para>
- → <type>gboolean</type> (<link linkend="G-TYPE-BOOLEAN:CAPS"><literal>G_TYPE_BOOLEAN</literal></link>)
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>string</literal></term>
- <listitem><para>
- → <type>char *</type> (<link linkend="G-TYPE-STRING:CAPS"><literal>G_TYPE_STRING</literal></link>)
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>double</literal></term>
- <listitem><para>
- → <type>double</type> (<link linkend="G-TYPE-DOUBLE:CAPS"><literal>G_TYPE_DOUBLE</literal></link>)
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>dateTime.iso8601</literal></term>
- <listitem><para>
- → <link linkend="SoupDate"><type>SoupDate</type></link> (<link linkend="SOUP-TYPE-DATE:CAPS"><literal>SOUP_TYPE_DATE</literal></link>)
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>base64</literal></term>
- <listitem><para>
- → <type>GByteArray</type> (<link linkend="SOUP-TYPE-BYTE-ARRAY:CAPS"><literal>SOUP_TYPE_BYTE_ARRAY</literal></link>)
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>struct</literal></term>
- <listitem><para>
- → <type>GHashTable</type> (<link linkend="G-TYPE-HASH-TABLE:CAPS"><literal>G_TYPE_HASH_TABLE</literal></link>)
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>array</literal></term>
- <listitem><para>
- → <type>GValueArray</type> (<link linkend="G-TYPE-VALUE-ARRAY:CAPS"><literal>G_TYPE_VALUE_ARRAY</literal></link>)
- </para></listitem>
- </varlistentry>
-</variablelist>
-
-<para>
-<type>SoupDate</type> is discussed below.
-<literal>SOUP_TYPE_BYTE_ARRAY</literal> is just a new
-<type>GType</type> value defined by <application>libsoup</application>
-to represent <type>GByteArray</type>s, which glib does not define a
-<type>GType</type> for.
-</para>
-
-<para>
-<application>libsoup</application> provides some additional <link
-linkend="libsoup-GValue-Support"><type>GValue</type> support
-methods</link> for working with
-<type>GValueArray</type>s, and <type>GHashTable</type>s of
-<type>GValue</type>s, for the XML-RPC <literal>struct</literal> and
-<literal>array</literal> types. Eg, you can use <link
-linkend="soup-value-hash-new"><function>soup_value_hash_new</function></link>
-to create a <type>GHashTable</type> to use with the XML-RPC methods,
-and <link
-linkend="soup-value-hash-insert"><function>soup_value_hash_insert</function></link>
-to add values to it without needing to muck with <type>GValue</type>s
-directly.
-</para>
-
-<para>
-The <literal>getbug</literal> and <literal>xmlrpc-test</literal>
-programs in the <application>libsoup</application> sources provide
-examples of how to use the new API. (Beware that
-<literal>xmlrpc-test</literal>'s use of the API is a little
-complicated because of the way it sends all calls through a single
-<literal>do_xmlrpc</literal> method.)
-</para>
-
-</refsect3>
-</refsect2>
-
-<refsect2>
-<title>SoupServer</title>
-
-<refsect3>
-<title>SoupServer handlers</title>
-
-<para>
- The prototypes for <link
- linkend="soup-server-add-handler"><function>soup_server_add_handler</function></link>,
- and for the <link
- linkend="SoupServerCallback"><type>SoupServer</type>
- handlers</link> themselves have changed:
-</para>
-
-<informalexample><programlisting>
-typedef void (*SoupServerCallback) (SoupServer *server,
- SoupMessage *msg,
- const char *path,
- GHashTable *query,
- SoupClientContext *client,
- gpointer user_data);
-
-void soup_server_add_handler (SoupServer *server,
- const char *path,
- SoupServerCallback callback,
- gpointer data,
- GDestroyNotify destroy);
-</programlisting></informalexample>
-
-<para>
- <function>soup_server_add_handler</function> no longer takes a
- <type>SoupServerAuthContext</type> (see the discussion of server
- authentication below), and the order of the final two arguments
- has been swapped. (Additionally, <type>SoupServerCallbackFn</type>
- has been renamed to <type>SoupServerCallback</type>, and the old
- <parameter>unregister</parameter> parameter of type
- <type>SoupServerUnregisterFn</type> is now a standard
- <type>GDestroyNotify</type>. The change to
- <type>GDestroyNotify</type> and the swapping of the final two
- arguments is to make the method conform to standard glib/gtk
- practices.)
-</para>
-
-<para>
- In <type>SoupServerCallback</type>, several bits of data that used
- to be part of the <parameter>context</parameter> argument are now
- provided directly, and <parameter>context</parameter> specifically
- only contains more specifically-client-related information (such
- as the <type>SoupSocket</type> that the request arrived on, and
- information about authentication).
-</para>
-
-<para>
- <parameter>path</parameter> is the fully %-decoded path component
- of <parameter>msg</parameter>'s URI, and
- <parameter>query</parameter> is a hash table containing
- <parameter>msg</parameter>'s URI's
- <structfield>query</structfield> component decoded with <link
- linkend="soup-form-decode-urlencoded">soup_form_decode_urlencoded</link>.
- These are provided for your convenience; if you need the raw
- query, you can get it out of <parameter>msg</parameter>'s URI
- directly. If you need the raw path, you'll need to set the <link
- linkend="SOUP-SERVER-RAW-PATHS:CAPS"><literal>SOUP_SERVER_RAW_PATHS</literal></link>
- property on the server, which actually changes the behavior of the
- server with respect to how paths are matched; see the
- documentation for details.
-</para>
-</refsect3>
-
-<refsect3>
-<title>Server-side authentication</title>
-
-<para>
- <type>SoupServer</type> authentication has been completely
- rewritten, with <type>SoupServerAuthContext</type> being replaced
- with <link
- linkend="SoupAuthDomain"><type>SoupAuthDomain</type></link>. Among
- other improvements, you no longer need to have the cleartext
- password available to check against. See the
- <type>SoupAuthDomain</type> documentation, the <link
- linkend="libsoup-server-howto">server tutorial</link>, and
- <literal>tests/server-auth-test.c</literal>.
-</para>
-</refsect3>
-
-<refsect3>
-<title><literal>Expect: 100-continue</literal> and other early <type>SoupMessage</type> processing</title>
-
-<para>
- <type>SoupServer</type> now handles
- "<literal>Expect: 100-continue</literal>" correctly. In
- particular, if the client passes that header, and your server
- requires authentication, then authentication will be checked
- before reading the request body.
-</para>
-
-<para>
- If you want to do additional pre-request-body handling, you can
- connect to <type>SoupServer</type>'s <link
- linkend="SoupServer-request-started"><literal>request_started</literal></link>
- signal, and connect to the request's <link
- linkend="SoupMessage-got-headers"><literal>got_headers</literal></link>
- signal from there. (See the description of
- <literal>request_started</literal> for information about other
- related <type>SoupServer</type> signals.)
-</para>
-</refsect3>
-
-<refsect3>
-<title>Date header</title>
-
-<para>
- <type>SoupServer</type> now automatically sets the
- <literal>Date</literal> header on all responses, as required by
- RFC 2616.
-</para>
-</refsect3>
-
-<refsect3>
-<title>SoupServerMessage</title>
-
-<para>
- <type>SoupServerMessage</type> is now merged into
- <type>SoupMessage</type>.
- <function>soup_server_message_set_encoding</function> is replaced
- with <link
- linkend="soup-message-headers-set-encoding"><function>soup_message_headers_set_encoding</function></link>
- as described in the section on <type>SoupMessage</type> above.
-</para>
-</refsect3>
-
-<refsect3>
-<title><function>soup_server_run</function> / <function>soup_server_quit</function></title>
-
-<para>
- <link
- linkend="soup-server-run"><function>soup_server_run</function></link>
- and <link
- linkend="soup-server-run-async"><function>soup_server_run_async</function></link>
- no longer <function>g_object_ref</function> the server, and
- <link
- linkend="soup-server-quit"><function>soup_server_quit</function></link>
- no longer unrefs it.
-</para>
-</refsect3>
-
-</refsect2>
-
-<refsect2>
-<title>Miscellaneous</title>
-
-<refsect3>
-<title>SoupDate</title>
-
-<para>
- The new <link linkend="SoupDate"><type>SoupDate</type></link> type
- replaces the old <function>soup_date_*</function> methods, and has
- an improved (more liberal) date parser.
-</para>
-</refsect3>
-
-<refsect3>
-<title>Header parsing</title>
-
-<para>
- <literal>soup-headers.h</literal> now has a few additional methods
- for parsing list-type headers.
-</para>
-</refsect3>
-
-<refsect3>
-<title>SoupAddress, SoupSocket</title>
-
-<para>
- <type>SoupSocket</type> has had various simplifications made to
- reflect the fact that this is specifically libsoup's socket
- implementation, not some random generic socket API.
-</para>
-
-<para>
- Various <type>SoupAddress</type> and <type>SoupSocket</type>
- methods now take arguments of the new <link
- linkend="GCancellable"><type>GCancellable</type></link> type, from
- libgio. When porting old code, you can just pass
- <literal>NULL</literal> for these. (<link
- linkend="soup-address-resolve-async"><function>soup_address_resolve_async</function></link>
- also takes another new argument, a <link
- linkend="GMainContext"><type>GMainContext</type></link> that
- you'll want to pass <literal>NULL</literal> for.) If you pass a
- <type>GCancellable</type>, you can use it to cleanly cancel the
- address resolution / socket operation.
-</para>
-
-</refsect3>
-
-<refsect3>
-<title>Base64 methods</title>
-
-<para>
- The deprecated base64 methods are now gone; use glib's base64
- methods instead.
-</para>
-</refsect3>
-
-</refsect2>
-
-</refentry>
<variablelist>
<varlistentry>
- <term><link linkend="SOUP-SERVER-PORT--CAPS"><literal>SOUP_SERVER_PORT</literal></link></term>
+ <term><link linkend="SOUP-SERVER-PORT:CAPS"><literal>SOUP_SERVER_PORT</literal></link></term>
<listitem><para>
The TCP port to listen on. If <literal>0</literal> (or
left unspecified), some unused port will be selected for
</para></listitem>
</varlistentry>
<varlistentry>
- <term><link linkend="SOUP-SERVER-INTERFACE--CAPS"><literal>SOUP_SERVER_INTERFACE</literal></link></term>
+ <term><link linkend="SOUP-SERVER-INTERFACE:CAPS"><literal>SOUP_SERVER_INTERFACE</literal></link></term>
<listitem><para>
A <link linkend="SoupAddress"><type>SoupAddress</type></link>,
specifying the IP address of the network interface to run
</para></listitem>
</varlistentry>
<varlistentry>
- <term><link linkend="SOUP-SERVER-SSL-CERT-FILE--CAPS"><literal>SOUP_SERVER_SSL_CERT_FILE</literal></link></term>
+ <term><link linkend="SOUP-SERVER-SSL-CERT-FILE:CAPS"><literal>SOUP_SERVER_SSL_CERT_FILE</literal></link></term>
<listitem><para>
Points to a file containing an SSL certificate to use. If
this is set, then the server will speak HTTPS; otherwise
</para></listitem>
</varlistentry>
<varlistentry>
- <term><link linkend="SOUP-SERVER-SSL-KEY-FILE--CAPS"><literal>SOUP_SERVER_SSL_KEY_FILE</literal></link></term>
+ <term><link linkend="SOUP-SERVER-SSL-KEY-FILE:CAPS"><literal>SOUP_SERVER_SSL_KEY_FILE</literal></link></term>
<listitem><para>
Points to a file containing the private key for the
<literal>SOUP_SERVER_SSL_CERT_FILE</literal>. (It may
</para></listitem>
</varlistentry>
<varlistentry>
- <term><link linkend="SOUP-SERVER-ASYNC-CONTEXT--CAPS"><literal>SOUP_SERVER_ASYNC_CONTEXT</literal></link></term>
+ <term><link linkend="SOUP-SERVER-ASYNC-CONTEXT:CAPS"><literal>SOUP_SERVER_ASYNC_CONTEXT</literal></link></term>
<listitem><para>
A <link linkend="GMainContext"><type>GMainContext</type></link> which
the server will use for asynchronous operations. This can
</para></listitem>
</varlistentry>
<varlistentry>
- <term><link linkend="SOUP-SERVER-RAW-PATHS--CAPS"><literal>SOUP_SERVER_RAW_PATHS</literal></link></term>
+ <term><link linkend="SOUP-SERVER-RAW-PATHS:CAPS"><literal>SOUP_SERVER_RAW_PATHS</literal></link></term>
<listitem><para>
Set this to <literal>TRUE</literal> if you don't want
<application>libsoup</application> to decode %-encoding
*
* Returns a #SoupAddress corresponding to the "any" address
* for @family (or %NULL if @family isn't supported), suitable for
- * passing to soup_socket_server_new().
+ * using as a listening #SoupSocket.
*
* Return value: (allow-none): the new #SoupAddress
**/
* This would be used to distinguish hosts in situations where
* different virtual hosts on the same IP address should be considered
* the same. Eg, if "www.example.com" and "www.example.net" have the
- * same IP address, then a single #SoupConnection can be used to talk
+ * same IP address, then a single connection can be used to talk
* to either of them.
*
* See also soup_address_equal_by_name(), which compares by name
/**
* SOUP_AUTH_DOMAIN_GENERIC_AUTH_CALLBACK:
*
- * Alias for the #SoupAuthDomain:auth-callback property.
+ * Alias for the #SoupAuthDomain:generic-auth-callback property.
* (The #SoupAuthDomainGenericAuthCallback.)
**/
g_object_class_install_property (
/**
* SOUP_AUTH_DOMAIN_GENERIC_AUTH_DATA:
*
- * Alias for the #SoupAuthDomain:auth-data property.
+ * Alias for the #SoupAuthDomain:generic-auth-data property.
* (The data to pass to the #SoupAuthDomainGenericAuthCallback.)
**/
g_object_class_install_property (
/**
* SOUP_AUTH_SCHEME_NAME:
*
- * An alias for the #SoupAuth:scheme property. (The
+ * An alias for the #SoupAuth:scheme-name property. (The
* authentication scheme name.)
**/
g_object_class_install_property (
}
/**
+ * SoupCacheType:
+ * @SOUP_CACHE_SINGLE_USER: a single-user cache
+ * @SOUP_CACHE_SHARED: a shared cache
+ *
+ * The type of cache; this affects what kinds of responses will be
+ * saved.
+ *
+ * Since: 2.34
+ */
+
+/**
* soup_cache_new:
* @cache_dir: the directory to store the cached data, or %NULL to use the default one
* @cache_type: the #SoupCacheType of the cache
return g_object_new (SOUP_TYPE_COOKIE_JAR, NULL);
}
+/**
+ * soup_cookie_jar_save:
+ * @jar: a #SoupCookieJar
+ *
+ * This function exists for backward compatibility, but does not do
+ * anything any more; cookie jars are saved automatically when they
+ * are changed.
+ */
void
soup_cookie_jar_save (SoupCookieJar *jar)
{
/**
* soup_cookie_jar_get_accept_policy:
* @jar: a #SoupCookieJar
- *
+ *
+ * Gets @jar's #SoupCookieJarAcceptPolicy
+ *
* Returns: the #SoupCookieJarAcceptPolicy set in the @jar
*
* Since: 2.30
return TRUE;
}
+/**
+ * soup_cookie_equal:
+ * @cookie1: a #SoupCookie
+ * @cookie2: a #SoupCookie
+ *
+ * Tests if @cookie1 and @cookie2 are equal.
+ *
+ * Note that currently, this does not check that the cookie domains
+ * match. This may change in the future.
+ *
+ * Return value: whether the cookies are equal.
+ */
gboolean
soup_cookie_equal (SoupCookie *cookie1, SoupCookie *cookie2)
{
/**
* SOUP_TYPE_PROXY_RESOLVER_GNOME:
*
- * This returns the #GType of a #SoupProxyResolver that can be used to
+ * This returns the #GType of a #SoupProxyURIResolver that can be used to
* resolve HTTP proxies for GNOME applications. You can add this to
* a session using soup_session_add_feature_by_type() or by using the
* %SOUP_SESSION_ADD_FEATURE_BY_TYPE construct-time property.
* soup_headers_parse_response:
* @str: the header string (including the trailing blank line)
* @len: length of @str up to (but not including) the terminating blank line.
- * @headers: #SoupMessageheaders to store the header values in
+ * @headers: #SoupMessageHeaders to store the header values in
* @ver: (out) (allow-none): if non-%NULL, will be filled in with the HTTP
* version
* @status_code: (out) (allow-none): if non-%NULL, will be filled in with
* and then attach it to a session (or multiple sessions) with
* soup_session_add_feature().
*
- * By default, the debugging output is sent to %stdout, and looks
- * something like:
+ * By default, the debugging output is sent to
+ * <literal>stdout</literal>, and looks something like:
*
* <informalexample><screen>
* > POST /unauth HTTP/1.1
* @destroy: a #GDestroyNotify to free @printer_data
*
* Sets up an alternate log printing routine, if you don't want
- * the log to go to %stdout.
+ * the log to go to <literal>stdout</literal>.
**/
void
soup_logger_set_printer (SoupLogger *logger,
*
* Return value: the new #SoupBuffer.
*
- * Since: 2.32
* Rename to: soup_buffer_new
+ * Since: 2.32
**/
SoupBuffer *
soup_buffer_new_take (guchar *data, gsize length)
* @body may be discarded when they are no longer needed.
*
* In particular, if you set this flag to %FALSE on an "incoming"
- * message body (that is, the %response_body of a client-side message,
- * or %request_body of a server-side message), this will cause each
- * chunk of the body to be discarded after its corresponding
- * #SoupMessage::got_chunk signal is emitted. (This is equivalent to
- * setting the deprecated %SOUP_MESSAGE_OVERWRITE_CHUNKS flag on the
- * message.)
- *
- * If you set this flag to %FALSE on the %response_body of a
- * server-side message, it will cause each chunk of the body to be
+ * message body (that is, the #SoupMessage:response_body of a
+ * client-side message, or #SoupMessage:request_body of a server-side
+ * message), this will cause each chunk of the body to be discarded
+ * after its corresponding #SoupMessage::got_chunk signal is emitted.
+ * (This is equivalent to setting the deprecated
+ * %SOUP_MESSAGE_OVERWRITE_CHUNKS flag on the message.)
+ *
+ * If you set this flag to %FALSE on the #SoupMessage:response_body of
+ * a server-side message, it will cause each chunk of the body to be
* discarded after its corresponding #SoupMessage::wrote_chunk signal
* is emitted.
*
- * If you set the flag to %FALSE on the %request_body of a client-side
- * message, it will block the accumulation of chunks into @body's
- * %data field, but it will not normally cause the chunks to be
- * discarded after being written like in the server-side
- * %response_body case, because the request body needs to be kept
- * around in case the request needs to be sent a second time due to
- * redirection or authentication. However, if you set the
+ * If you set the flag to %FALSE on the #SoupMessage:request_body of a
+ * client-side message, it will block the accumulation of chunks into
+ * @body's %data field, but it will not normally cause the chunks to
+ * be discarded after being written like in the server-side
+ * #SoupMessage:response_body case, because the request body needs to
+ * be kept around in case the request needs to be sent a second time
+ * due to redirection or authentication. However, if you set the
* %SOUP_MESSAGE_CAN_REBUILD flag on the message, then the chunks will
* be discarded, and you will be responsible for recreating the
* request body after the #SoupMessage::restarted signal is emitted.
*
* Appends @length bytes from @data to @body.
*
- * This function is exactly equivalent to soup_message_body_apppend()
+ * This function is exactly equivalent to soup_message_body_append()
* with %SOUP_MEMORY_TAKE as second argument; it exists mainly for
* convenience and simplifying language bindings.
*
- * Since: 2.32
* Rename to: soup_message_body_append
+ * Since: 2.32
**/
void
soup_message_body_append_take (SoupMessageBody *body,
**/
/**
+ * SoupMessageHeaders:
+ *
+ * The HTTP message headers associated with a request or response.
+ */
+
+/**
* SoupMessageHeadersType:
* @SOUP_MESSAGE_HEADERS_REQUEST: request headers
* @SOUP_MESSAGE_HEADERS_RESPONSE: response headers
* Represents a byte range as used in the Range header.
*
* If @end is non-negative, then @start and @end represent the bounds
- * of of the range, counting from %0. (Eg, the first 500 bytes would be
- * represented as @start = %0 and @end = %499.)
+ * of of the range, counting from 0. (Eg, the first 500 bytes would be
+ * represented as @start = 0 and @end = 499.)
*
- * If @end is %-1 and @start is non-negative, then this represents a
+ * If @end is -1 and @start is non-negative, then this represents a
* range starting at @start and ending with the last byte of the
* requested resource body. (Eg, all but the first 500 bytes would be
- * @start = %500, and @end = %-1.)
+ * @start = 500, and @end = -1.)
*
- * If @end is %-1 and @start is negative, then it represents a "suffix
+ * If @end is -1 and @start is negative, then it represents a "suffix
* range", referring to the last -@start bytes of the resource body.
- * (Eg, the last 500 bytes would be @start = %-500 and @end = %-1.)
+ * (Eg, the last 500 bytes would be @start = -500 and @end = -1.)
*
* Since: 2.26
**/
#include "soup-message-queue.h"
#include "soup-uri.h"
-/**
- * SECTION:soup-message-queue
- *
- * This is an internal structure used by #SoupSession and its
+/* This is an internal structure used by #SoupSession and its
* subclasses to keep track of the status of messages currently being
* processed.
*
* trying to do.
*
* As described in the #SoupMessageBody documentation, the
- * @request_body and @response_body %data fields will not necessarily
- * be filled in at all times. When they are filled in, they will be
- * terminated with a '\0' byte (which is not included in the %length),
- * so you can use them as ordinary C strings (assuming that you know
- * that the body doesn't have any other '\0' bytes).
+ * @request_body and @response_body <literal>data</literal> fields
+ * will not necessarily be filled in at all times. When they are
+ * filled in, they will be terminated with a '\0' byte (which is not
+ * included in the <literal>length</literal>), so you can use them as
+ * ordinary C strings (assuming that you know that the body doesn't
+ * have any other '\0' bytes).
*
* For a client-side #SoupMessage, @request_body's %data is usually
* filled in right before libsoup writes the request to the network,
* (If you need to requeue a message--eg, after handling
* authentication or redirection--it is usually better to
* requeue it from a #SoupMessage::got_body handler rather
- * than a #SoupMessage::got_header handler, so that the
+ * than a #SoupMessage::got_headers handler, so that the
* existing HTTP connection can be reused.)
**/
signals[GOT_HEADERS] =
* @type: the content type that we got from sniffing
* @params: (element-type utf8 utf8): a #GHashTable with the parameters
*
- * This signal is emitted after %got-headers, and before the
- * first %got-chunk. If content sniffing is disabled, or no
- * content sniffing will be performed, due to the sniffer
- * deciding to trust the Content-Type sent by the server, this
- * signal is emitted immediately after %got_headers, and @type
- * is %NULL.
+ * This signal is emitted after #SoupMessage::got-headers, and
+ * before the first #SoupMessage::got-chunk. If content
+ * sniffing is disabled, or no content sniffing will be
+ * performed, due to the sniffer deciding to trust the
+ * Content-Type sent by the server, this signal is emitted
+ * immediately after #SoupMessage::got-headers, and @type is
+ * %NULL.
*
* If the #SoupContentSniffer feature is enabled, and the
- * sniffer decided to perform sniffing, the first %got_chunk
- * emission may be delayed, so that the sniffer has enough
- * data to correctly sniff the content. It notified the
- * library user that the content has been sniffed, and allows
- * it to change the header contents in the message, if
- * desired.
+ * sniffer decided to perform sniffing, the first
+ * #SoupMessage::got-chunk emission may be delayed, so that the
+ * sniffer has enough data to correctly sniff the content. It
+ * notified the library user that the content has been
+ * sniffed, and allows it to change the header contents in the
+ * message, if desired.
*
* After this signal is emitted, the data that was spooled so
* that sniffing could be done is delivered on the first
- * emission of %got_chunk.
+ * emission of #SoupMessage::got-chunk.
*
* Since: 2.27.3
**/
* soup_message_got_informational:
* @msg: a #SoupMessage
*
- * Emits the %got_informational signal, indicating that the IO layer
- * read a complete informational (1xx) response for @msg.
+ * Emits the #SoupMessage::got_informational signal, indicating that
+ * the IO layer read a complete informational (1xx) response for @msg.
**/
void
soup_message_got_informational (SoupMessage *msg)
* soup_message_got_headers:
* @msg: a #SoupMessage
*
- * Emits the %got_headers signal, indicating that the IO layer
- * finished reading the (non-informational) headers for @msg.
+ * Emits the #SoupMessage::got_headers signal, indicating that the IO
+ * layer finished reading the (non-informational) headers for @msg.
**/
void
soup_message_got_headers (SoupMessage *msg)
* @msg: a #SoupMessage
* @chunk: the newly-read chunk
*
- * Emits the %got_chunk signal, indicating that the IO layer finished
- * reading a chunk of @msg's body.
+ * Emits the #SoupMessage::got_chunk signal, indicating that the IO
+ * layer finished reading a chunk of @msg's body.
**/
void
soup_message_got_chunk (SoupMessage *msg, SoupBuffer *chunk)
* soup_message_got_body:
* @msg: a #SoupMessage
*
- * Emits the %got_body signal, indicating that the IO layer finished
- * reading the body for @msg.
+ * Emits the #SoupMessage::got_body signal, indicating that the IO
+ * layer finished reading the body for @msg.
**/
void
soup_message_got_body (SoupMessage *msg)
* finished sniffing the content type for @msg. If content sniffing
* will not be performed, due to the sniffer deciding to trust the
* Content-Type sent by the server, this signal is emitted immediately
- * after %got_headers, with %NULL as @content_type.
+ * after #SoupMessage::got_headers, with %NULL as @content_type.
**/
void
soup_message_content_sniffed (SoupMessage *msg, const char *content_type, GHashTable *params)
* soup_message_body_set_accumulate() for more details.
* @SOUP_MESSAGE_OVERWRITE_CHUNKS: Deprecated: equivalent to calling
* soup_message_body_set_accumulate() on the incoming message body
- * (ie, %response_body for a client-side request), passing %FALSE.
+ * (ie, #SoupMessage:response_body for a client-side request),
+ * passing %FALSE.
* @SOUP_MESSAGE_CONTENT_DECODED: Set by #SoupContentDecoder to
* indicate that it has removed the Content-Encoding on a message (and
* so headers such as Content-Length may no longer accurately describe
* call @allocator, which should return a #SoupBuffer. (See
* #SoupChunkAllocator for additional details.) Libsoup will then read
* data from the network into that buffer, and update the buffer's
- * %length to indicate how much data it read.
+ * <literal>length</literal> to indicate how much data it read.
*
* Generally, a custom chunk allocator would be used in conjunction
* with soup_message_body_set_accumulate() %FALSE and
* #SoupMessage::got_chunk, as part of a strategy to avoid unnecessary
* copying of data. However, you cannot assume that every call to the
- * allocator will be followed by a call to your %got_chunk handler; if
- * an I/O error occurs, then the buffer will be unreffed without ever
- * having been used. If your buffer-allocation strategy requires
- * special cleanup, use soup_buffer_new_with_owner() rather than doing
- * the cleanup from the %got_chunk handler.
+ * allocator will be followed by a call to your
+ * #SoupMessage::got_chunk handler; if an I/O error occurs, then the
+ * buffer will be unreffed without ever having been used. If your
+ * buffer-allocation strategy requires special cleanup, use
+ * soup_buffer_new_with_owner() rather than doing the cleanup from the
+ * #SoupMessage::got_chunk handler.
*
* The other thing to remember when using non-accumulating message
- * bodies is that the buffer passed to the %got_chunk handler will be
- * unreffed after the handler returns, just as it would be in the
- * non-custom-allocated case. If you want to hand the chunk data off
- * to some other part of your program to use later, you'll need to ref
- * the #SoupBuffer (or its owner, in the soup_buffer_new_with_owner()
- * case) to ensure that the data remains valid.
+ * bodies is that the buffer passed to the #SoupMessage::got_chunk
+ * handler will be unreffed after the handler returns, just as it
+ * would be in the non-custom-allocated case. If you want to hand the
+ * chunk data off to some other part of your program to use later,
+ * you'll need to ref the #SoupBuffer (or its owner, in the
+ * soup_buffer_new_with_owner() case) to ensure that the data remains
+ * valid.
**/
void
soup_message_set_chunk_allocator (SoupMessage *msg,
* This disables the actions of #SoupSessionFeature<!-- -->s with the
* given @feature_type (or a subclass of that type) on @msg, so that
* @msg is processed as though the feature(s) hadn't been added to the
- * session. Eg, passing #SOUP_TYPE_PROXY_RESOLVER for @feature_type
+ * session. Eg, passing #SOUP_TYPE_PROXY_URI_RESOLVER for @feature_type
* will disable proxy handling and cause @msg to be sent directly to
* the indicated origin server, regardless of system proxy
* configuration.
/**
* soup_message_get_first_party:
* @msg: a #SoupMessage
+ *
+ * Gets @msg's first-party #SoupURI
*
* Returns: (transfer none): the @msg's first party #SoupURI
*
request_class->get_content_type = soup_request_file_get_content_type;
}
+/**
+ * soup_request_file_get_file:
+ * @file: a #SoupRequestFile
+ *
+ * Gets a #GFile corresponding to @file's URI
+ *
+ * Return value: (transfer full): a #GFile corresponding to @file
+ *
+ * Since: 2.34
+ */
GFile *
soup_request_file_get_file (SoupRequestFile *file)
{
* SECTION:soup-request
* @short_description: Protocol-independent streaming request interface
*
- * FIXME
+ * A #SoupRequest is created by #SoupRequester, and represents a
+ * request to retrieve a particular URI.
*/
/**
* SoupRequest:
*
- * FIXME
+ * A request to retrieve a particular URI.
*
* Since: 2.34
*/
return soup_request_send (request, NULL, error);
}
+/**
+ * soup_request_send:
+ * @request: a #SoupRequest
+ * @cancellable: a #GCancellable or %NULL
+ * @error: return location for a #GError, or %NULL
+ *
+ * Synchronously requests the URI pointed to by @request, and returns
+ * a #GInputStream that can be used to read its contents.
+ *
+ * Return value: (transfer full): a #GInputStream that can be used to
+ * read from the URI pointed to by @request.
+ *
+ * Since: 2.34
+ */
GInputStream *
soup_request_send (SoupRequest *request,
GCancellable *cancellable,
send (request, cancellable, error);
}
+/**
+ * soup_request_send_async:
+ * @request: a #SoupRequest
+ * @cancellable: a #GCancellable or %NULL
+ * @callback: a #GAsyncReadyCallback
+ * @user_data: user data passed to @callback
+ *
+ * Begins an asynchronously request for the URI pointed to by
+ * @request.
+ *
+ * Since: 2.34
+ */
void
-soup_request_send_async (SoupRequest *request,
- GCancellable *cancellable,
- GAsyncReadyCallback callback,
- gpointer user_data)
+soup_request_send_async (SoupRequest *request,
+ GCancellable *cancellable,
+ GAsyncReadyCallback callback,
+ gpointer user_data)
{
SOUP_REQUEST_GET_CLASS (request)->
send_async (request, cancellable, callback, user_data);
}
+/**
+ * soup_request_send_finish:
+ * @request: a #SoupRequest
+ * @result: the #GAsyncResult
+ * @error: return location for a #GError, or %NULL
+ *
+ * Gets the result of a soup_request_send_async().
+ *
+ * Return value: (transfer full): a #GInputStream that can be used to
+ * read from the URI pointed to by @request.
+ *
+ * Since: 2.34
+ */
GInputStream *
soup_request_send_finish (SoupRequest *request,
GAsyncResult *result,
initable_interface->init = soup_request_initable_init;
}
+/**
+ * soup_request_get_uri:
+ * @request: a #SoupRequest
+ *
+ * Gets @request's URI
+ *
+ * Return value: (transfer none): @request's URI
+ *
+ * Since: 2.34
+ */
SoupURI *
soup_request_get_uri (SoupRequest *request)
{
return request->priv->uri;
}
+/**
+ * soup_request_get_session:
+ * @request: a #SoupRequest
+ *
+ * Gets @request's #SoupSession
+ *
+ * Return value: (transfer none): @request's #SoupSession
+ *
+ * Since: 2.34
+ */
SoupSession *
soup_request_get_session (SoupRequest *request)
{
return request->priv->session;
}
+/**
+ * soup_request_get_content_length:
+ * @request: a #SoupRequest
+ *
+ * Gets the length of the data represented by @request.
+ *
+ * Return value: the length of the data represented by @request,
+ * or -1 if not known.
+ *
+ * Since: 2.34
+ */
goffset
soup_request_get_content_length (SoupRequest *request)
{
return SOUP_REQUEST_GET_CLASS (request)->get_content_length (request);
}
+/**
+ * soup_request_get_content_type:
+ * @request: a #SoupRequest
+ *
+ * Gets the type of the data represented by @request.
+ *
+ * Return value: the type of the data represented by @request,
+ * or %NULL if not known.
+ *
+ * Since: 2.34
+ */
const char *
soup_request_get_content_type (SoupRequest *request)
{
feature_interface->has_feature = has_feature;
}
+/**
+ * soup_requester_new:
+ *
+ * Creates a new #SoupRequester object, which can be added to
+ * a #SoupSession with soup_session_add_feature().
+ *
+ * Return value: the new #SoupRequester
+ *
+ * Since: 2.34
+ */
SoupRequester *
soup_requester_new (void)
{
return g_object_new (SOUP_TYPE_REQUESTER, NULL);
}
+/**
+ * soup_requester_request:
+ * @requester: a #SoupRequester
+ * @uri_string: a URI, in string form
+ * @error: return location for a #GError, or %NULL
+ *
+ * Creates a #SoupRequest for retrieving @uri_string.
+ *
+ * Return value: (transfer full): a new #SoupRequest, or
+ * %NULL on error.
+ *
+ * Since: 2.34
+ */
SoupRequest *
soup_requester_request (SoupRequester *requester, const char *uri_string,
GError **error)
return req;
}
+/**
+ * soup_requester_request_uri:
+ * @requester: a #SoupRequester
+ * @uri: a #SoupURI representing the URI to retrieve
+ * @error: return location for a #GError, or %NULL
+ *
+ * Creates a #SoupRequest for retrieving @uri.
+ *
+ * Return value: (transfer full): a new #SoupRequest, or
+ * %NULL on error.
+ *
+ * Since: 2.34
+ */
SoupRequest *
soup_requester_request_uri (SoupRequester *requester, SoupURI *uri,
GError **error)
NULL);
}
+/**
+ * SOUP_REQUESTER_ERROR:
+ *
+ * A #GError domain for #SoupRequester errors. Used with
+ * #SoupRequesterError.
+ *
+ * Since: 2.34
+ */
+/**
+ * SoupRequesterError:
+ * @SOUP_REQUESTER_ERROR_BAD_URI: the URI could not be parsed
+ * @SOUP_REQUESTER_ERROR_UNSUPPORTED_URI_SCHEME: the URI scheme is not
+ * supported by this #SoupRequester
+ *
+ * A #SoupRequester error.
+ *
+ * Since: 2.34
+ */
+
GQuark
soup_requester_error_quark (void)
{
* holes.
*
* As with #SoupSession:user_agent, if you set a
- * %server_header property that has trailing whitespace,
+ * #SoupServer:server_header property that has trailing whitespace,
* #SoupServer will append its own product token (eg,
* "<literal>libsoup/2.3.2</literal>") to the end of the
* header for you.
* @user_data: the data passed to @soup_server_add_handler
*
* A callback used to handle requests to a #SoupServer. The callback
- * will be invoked after receiving the request body; @msg's %method,
- * %request_headers, and %request_body fields will be filled in.
+ * will be invoked after receiving the request body; @msg's
+ * #SoupMessage:method, #SoupMessage:request_headers, and
+ * #SoupMessage:request_body fields will be filled in.
*
* @path and @query contain the likewise-named components of the
* Request-URI, subject to certain assumptions. By default,
*
* To send the response body a bit at a time using "chunked" encoding,
* first call soup_message_headers_set_encoding() to set
- * %SOUP_ENCODING_CHUNKED on the %response_headers. Then call
+ * %SOUP_ENCODING_CHUNKED on the #SoupMessage:response_headers. Then call
* soup_message_body_append() (or soup_message_body_append_buffer())
* to append each chunk as it becomes ready, and
* soup_server_unpause_message() to make sure it's running. (The
* @request_queued: Proxies the session's #SoupSession::request_queued signal
* @request_started: Proxies the session's #SoupSession::request_started signal
* @request_unqueued: Proxies the session's #SoupSession::request_unqueued signal
+ * @add_feature: adds a sub-feature to the main feature
+ * @remove_feature: removes a sub-feature from the main feature
+ * @has_feature: tests if the feature includes a sub-feature
*
* The interface implemented by #SoupSessionFeature<!-- -->s.
*
SOUP_TYPE_AUTH,
G_TYPE_BOOLEAN);
+ /**
+ * SoupSession::connection-created:
+ * @session: the #SoupSession
+ * @connection: the connection
+ *
+ * Emitted when a new connection is created. This is an
+ * internal signal intended only to be used for debugging
+ * purposes, and may go away in the future.
+ *
+ * Since: 2.30
+ */
signals[CONNECTION_CREATED] =
g_signal_new ("connection-created",
G_OBJECT_CLASS_TYPE (object_class),
*/
G_TYPE_OBJECT);
+ /**
+ * SoupSession::tunneling:
+ * @session: the #SoupSession
+ * @connection: the connection
+ *
+ * Emitted when an SSL tunnel is being created on a proxy
+ * connection. This is an internal signal intended only to be
+ * used for debugging purposes, and may go away in the future.
+ *
+ * Since: 2.30
+ */
signals[TUNNELING] =
g_signal_new ("tunneling",
G_OBJECT_CLASS_TYPE (object_class),
/**
* SOUP_SESSION_SSL_STRICT:
*
- * Alias for the #SoupSession:ignore-ssl-cert-errors
- * property. By default, when validating certificates against
- * a CA file, Soup will consider invalid certificates as a
- * connection error. Setting this property to %TRUE makes soup
- * ignore the errors, and make the connection.
+ * Alias for the #SoupSession:ssl-strict property. By default,
+ * when validating certificates against a CA file, Soup will
+ * consider invalid certificates as a connection error.
+ * Setting this property to %TRUE makes soup ignore the
+ * errors, and make the connection.
*
* Since: 2.30
**/
* followed by a version string. You may also put comments,
* enclosed in parentheses, between or after the tokens.
*
- * If you set a %user_agent property that has trailing
+ * If you set a #SoupSession:user_agent property that has trailing
* whitespace, #SoupSession will append its own product token
* (eg, "<literal>libsoup/2.3.2</literal>") to the end of the
* header for you.
* may call this at any time after handing @msg off to @session; if
* @session has started sending the request but has not yet received
* the complete response, then it will close the request's connection.
- * Note that with non-idempotent requests (eg, %POST, %PUT, %DELETE)
- * it is possible that you might cancel the request after the server
- * acts on it, but before it returns a response, leaving the remote
- * resource in an unknown state.
+ * Note that with non-idempotent requests (eg,
+ * <literal>POST</literal>, <literal>PUT</literal>,
+ * <literal>DELETE</literal>) it is possible that you might cancel the
+ * request after the server acts on it, but before it returns a
+ * response, leaving the remote resource in an unknown state.
*
* If the message is cancelled while its response body is being read,
* then the response body in @msg will be left partially-filled-in.
* proxy address, etc.) in order to work more quickly once the URI is
* actually requested.
*
-* This method acts asynchronously, in @session's %async_context.
-* If you are using #SoupSessionSync and do not have a main loop running,
-* then you can't use this method.
+* This method acts asynchronously, in @session's
+* #SoupSession:async_context. If you are using #SoupSessionSync and do
+* not have a main loop running, then you can't use this method.
*
* Since: 2.30
**/
* @feature_type: the #GType of the class of features to get
*
* Generates a list of @session's features of type @feature_type. (If
- * you want to see all features, you can pass %G_TYPE_SESSION_FEATURE
+ * you want to see all features, you can pass %SOUP_TYPE_SESSION_FEATURE
* for @feature_type.)
*
* Return value: (transfer container) (element-type Soup.SessionFeature):
/**
* SOUP_SOCKET_SSL_CREDENTIALS:
*
- * Alias for the #SoupSocket:ssl-credentials property.
+ * Alias for the #SoupSocket:ssl-creds property.
* (SSL credential information.)
**/
g_object_class_install_property (
* listening)
*
* Makes @sock start listening on its local address. When connections
- * come in, @sock will emit %new_connection.
+ * come in, @sock will emit #SoupSocket::new_connection.
*
* Return value: whether or not @sock is now listening.
**/
* outside of libsoup.
* @SOUP_SSL_ERROR_CERTIFICATE: Indicates an error validating an SSL
* certificate
+ * @SOUP_SSL_ERROR_HANDSHAKE_FAILED: Unused
*
* SSL-related I/O errors.
**/
*
* <emphasis>There is no reason for you to ever use this
* function.</emphasis> If you wanted the textual description for the
- * %status_code of a given #SoupMessage, you should just look at the
- * message's %reason_phrase. However, you should only do that for use
- * in debugging messages; HTTP reason phrases are not localized, and
- * are not generally very descriptive anyway, and so they should never
- * be presented to the user directly. Instead, you should create you
- * own error messages based on the status code, and on what you were
- * trying to do.
+ * #SoupMessage:status_code of a given #SoupMessage, you should just
+ * look at the message's #SoupMessage:reason_phrase. However, you
+ * should only do that for use in debugging messages; HTTP reason
+ * phrases are not localized, and are not generally very descriptive
+ * anyway, and so they should never be presented to the user directly.
+ * Instead, you should create you own error messages based on the
+ * status code, and on what you were trying to do.
*
* Return value: the (terse, English) description of @status_code
**/
/**
* soup_uri_copy_host:
- * @uri: a #SoupUri
+ * @uri: a #SoupURI
*
* Makes a copy of @uri, considering only the protocol, host, and port
*
- * Return value: the new #SoupUri
+ * Return value: the new #SoupURI
*
* Since: 2.26.3
**/
* @n_params: length of @params
*
* This creates an XML-RPC methodCall and returns it as a string.
- * This is the low-level method that soup_xmlrpc_request_new() and
- * soup_xmlrpc_call() are built on.
+ * This is the low-level method that soup_xmlrpc_request_new() is
+ * built on.
*
* @params is an array of #GValue representing the parameters to
* @method. (It is *not* a #GValueArray, although if you have a
- * #GValueArray, you can just pass its %values and %n_values fields.)
+ * #GValueArray, you can just pass its <literal>values</literal>f and
+ * <literal>n_values</literal> fields.)
*
* The correspondence between glib types and XML-RPC types is:
*
return error;
}
+/**
+ * SOUP_XMLRPC_FAULT:
+ *
+ * A #GError domain representing an XML-RPC fault code. Used with
+ * #SoupXMLRPCFault (although servers may also return fault codes not
+ * in that enumeration).
+ */
+
+/**
+ * SoupXMLRPCFault:
+ * @SOUP_XMLRPC_FAULT_PARSE_ERROR_NOT_WELL_FORMED: request was not
+ * well-formed
+ * @SOUP_XMLRPC_FAULT_PARSE_ERROR_UNSUPPORTED_ENCODING: request was in
+ * an unsupported encoding
+ * @SOUP_XMLRPC_FAULT_PARSE_ERROR_INVALID_CHARACTER_FOR_ENCODING:
+ * request contained an invalid character
+ * @SOUP_XMLRPC_FAULT_SERVER_ERROR_INVALID_XML_RPC: request was not
+ * valid XML-RPC
+ * @SOUP_XMLRPC_FAULT_SERVER_ERROR_REQUESTED_METHOD_NOT_FOUND: method
+ * not found
+ * @SOUP_XMLRPC_FAULT_SERVER_ERROR_INVALID_METHOD_PARAMETERS: invalid
+ * parameters
+ * @SOUP_XMLRPC_FAULT_SERVER_ERROR_INTERNAL_XML_RPC_ERROR: internal
+ * error
+ * @SOUP_XMLRPC_FAULT_APPLICATION_ERROR: start of reserved range for
+ * application error codes
+ * @SOUP_XMLRPC_FAULT_SYSTEM_ERROR: start of reserved range for
+ * system error codes
+ * @SOUP_XMLRPC_FAULT_TRANSPORT_ERROR: start of reserved range for
+ * transport error codes
+ *
+ * Pre-defined XML-RPC fault codes from <ulink
+ * url="http://xmlrpc-epi.sourceforge.net/specs/rfc.fault_codes.php">http://xmlrpc-epi.sourceforge.net/specs/rfc.fault_codes.php</ulink>.
+ * These are an extension, not part of the XML-RPC spec; you can't
+ * assume servers will use them.
+ */
+
GQuark
soup_xmlrpc_fault_quark (void)
{
#define SOUP_XMLRPC_FAULT soup_xmlrpc_fault_quark()
GQuark soup_xmlrpc_fault_quark (void);
-/* From http://xmlrpc-epi.sourceforge.net/specs/rfc.fault_codes.php.
- * These are an extension, not part of the XML-RPC spec; you can't
- * assume servers will use them.
- */
typedef enum {
SOUP_XMLRPC_FAULT_PARSE_ERROR_NOT_WELL_FORMED = -32700,
SOUP_XMLRPC_FAULT_PARSE_ERROR_UNSUPPORTED_ENCODING = -32701,
projects / platform / upstream / libsoup.git / commitdiff