diff options
| author | Dan Winship <danw@gnome.org> | 2011-09-22 14:17:47 -0400 |
|---|---|---|
| committer | Dan Winship <danw@gnome.org> | 2011-09-22 14:17:47 -0400 |
| commit | 8bc27529eb2c87a5c27e1ffd388a274d4c1ae44e (patch) | |
| tree | 7bf1f5010f886b5e85e1f5c3258b09b331ded881 | |
| parent | 27b306cb9e8cc0b91e2188cc820c7c511f64b69c (diff) | |
| download | libsoup-8bc27529eb2c87a5c27e1ffd388a274d4c1ae44e.tar.gz | |
Lots of gtk-doc fixes (no code changes)
31 files changed, 688 insertions, 1038 deletions
diff --git a/docs/reference/Makefile.am b/docs/reference/Makefile.am index 765d27c2..5de89357 100644 --- a/docs/reference/Makefile.am +++ b/docs/reference/Makefile.am @@ -36,7 +36,9 @@ IGNORE_HFILES= soup.h soup-marshal.h soup-enum-types.h \ 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 = @@ -45,8 +47,7 @@ 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 = diff --git a/docs/reference/client-howto.xml b/docs/reference/client-howto.xml index e87f9019..a53f2ac3 100644 --- a/docs/reference/client-howto.xml +++ b/docs/reference/client-howto.xml @@ -58,7 +58,7 @@ you can specify various additional options: <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 @@ -68,7 +68,7 @@ you can specify various additional options: </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 @@ -76,7 +76,7 @@ you can specify various additional options: </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 @@ -89,7 +89,7 @@ you can specify various additional options: </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 @@ -99,7 +99,7 @@ you can specify various additional options: </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> @@ -110,7 +110,7 @@ you can specify various additional options: </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 @@ -136,9 +136,9 @@ which take no arguments. 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 @@ -172,7 +172,7 @@ And in <application>libsoup-gnome</application>: <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. @@ -190,7 +190,7 @@ And in <application>libsoup-gnome</application>: <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 @@ -249,9 +249,9 @@ request headers and body of the message: <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> @@ -260,7 +260,7 @@ linkend="soup-message-set-flags"><function>soup_message_set_flags</function></li 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> @@ -286,7 +286,7 @@ it will run the main loop itself until the message is complete.) <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 @@ -344,7 +344,7 @@ linkend="soup-session-queue-message"><function>soup_session_queue_message</funct 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> @@ -527,7 +527,7 @@ A few sample programs are available in the <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.) diff --git a/docs/reference/libsoup-2.4-docs.sgml b/docs/reference/libsoup-2.4-docs.sgml index c52208f2..ec6fa0dd 100644 --- a/docs/reference/libsoup-2.4-docs.sgml +++ b/docs/reference/libsoup-2.4-docs.sgml @@ -11,7 +11,6 @@ <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> @@ -38,11 +37,13 @@ <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> @@ -64,6 +65,16 @@ <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> diff --git a/docs/reference/libsoup-2.4-sections.txt b/docs/reference/libsoup-2.4-sections.txt index 3980677d..30613519 100644 --- a/docs/reference/libsoup-2.4-sections.txt +++ b/docs/reference/libsoup-2.4-sections.txt @@ -19,6 +19,10 @@ soup_message_get_address 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 @@ -38,6 +42,13 @@ SOUP_MESSAGE_FLAGS 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 @@ -94,6 +105,7 @@ soup_message_headers_append 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 @@ -141,7 +153,9 @@ SoupMemoryUse 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> @@ -154,6 +168,7 @@ soup_message_body_get_accumulate <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 @@ -196,6 +211,7 @@ soup_server_get_listener soup_server_run soup_server_run_async soup_server_quit +soup_server_disconnect soup_server_get_async_context <SUBSECTION> SoupServerCallback @@ -337,6 +353,7 @@ soup_address_is_resolved <SUBSECTION> soup_address_get_name soup_address_get_sockaddr +soup_address_get_gsockaddr soup_address_get_physical soup_address_get_port <SUBSECTION> @@ -359,8 +376,6 @@ SOUP_ADDRESS_CLASS SOUP_IS_ADDRESS_CLASS SOUP_ADDRESS_GET_CLASS SoupAddressClass -<SUBSECTION Private> -AF_INET6 </SECTION> <SECTION> @@ -373,6 +388,7 @@ soup_session_queue_message 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 @@ -400,6 +416,9 @@ SOUP_SESSION_USER_AGENT 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 @@ -409,6 +428,11 @@ SOUP_SESSION_GET_CLASS SOUP_TYPE_SESSION SoupSessionClass soup_session_get_type +<SUBSECTION Private> +SoupConnection +SoupConnectionState +SoupMessageQueue +SoupMessageQueueItem </SECTION> <SECTION> @@ -461,6 +485,9 @@ SOUP_TYPE_SESSION_FEATURE <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> @@ -470,6 +497,10 @@ SoupAuth 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 @@ -497,6 +528,14 @@ SOUP_AUTH_CLASS 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> @@ -536,6 +575,11 @@ SOUP_SOCKET_IS_SERVER 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 @@ -547,6 +591,9 @@ SOUP_SOCKET_GET_CLASS SoupSocketClass <SUBSECTION Private> soup_ssl_error_quark +soup_socket_get_fd +soup_socket_handshake_async +soup_socket_handshake_sync </SECTION> <SECTION> @@ -558,7 +605,10 @@ soup_uri_new 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 @@ -567,22 +617,35 @@ soup_uri_normalize <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> @@ -598,6 +661,14 @@ soup_date_to_string 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 @@ -613,6 +684,7 @@ soup_header_parse_param_list 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 @@ -627,13 +699,20 @@ soup_ssl_supported 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 @@ -648,6 +727,10 @@ soup_form_request_new 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> @@ -666,12 +749,12 @@ soup_xmlrpc_build_fault 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> @@ -736,23 +819,30 @@ SoupCookie 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 @@ -766,6 +856,8 @@ soup_cookies_free <SUBSECTION Standard> SOUP_TYPE_COOKIE soup_cookie_get_type +<SUBSECTION Private> +soup_cookie_equal </SECTION> <SECTION> @@ -773,15 +865,20 @@ soup_cookie_get_type <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 @@ -791,6 +888,7 @@ SOUP_IS_COOKIE_JAR SOUP_IS_COOKIE_JAR_CLASS SOUP_TYPE_COOKIE_JAR soup_cookie_jar_get_type +soup_cookie_jar_save </SECTION> <SECTION> @@ -875,6 +973,8 @@ SOUP_TYPE_PROXY_RESOLVER_GNOME <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> @@ -894,3 +994,167 @@ SoupContentSnifferClass 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> + diff --git a/docs/reference/porting-2.2-2.4.xml b/docs/reference/porting-2.2-2.4.xml deleted file mode 100644 index 37632bfc..00000000 --- a/docs/reference/porting-2.2-2.4.xml +++ /dev/null @@ -1,878 +0,0 @@ -<?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> diff --git a/docs/reference/server-howto.xml b/docs/reference/server-howto.xml index 0a9a53d9..76c19182 100644 --- a/docs/reference/server-howto.xml +++ b/docs/reference/server-howto.xml @@ -30,7 +30,7 @@ various additional options: <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 @@ -39,7 +39,7 @@ various additional options: </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 @@ -48,7 +48,7 @@ various additional options: </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 @@ -56,7 +56,7 @@ various additional options: </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 @@ -64,7 +64,7 @@ various additional options: </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 @@ -73,7 +73,7 @@ various additional options: </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 diff --git a/libsoup/soup-address.c b/libsoup/soup-address.c index 0e5e8cd7..42b777d3 100644 --- a/libsoup/soup-address.c +++ b/libsoup/soup-address.c @@ -406,7 +406,7 @@ soup_address_new_from_sockaddr (struct sockaddr *sa, int len) * * 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 **/ @@ -1013,7 +1013,7 @@ soup_address_hash_by_ip (gconstpointer addr) * 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 diff --git a/libsoup/soup-auth-domain.c b/libsoup/soup-auth-domain.c index c8ce96b7..dd47dff8 100644 --- a/libsoup/soup-auth-domain.c +++ b/libsoup/soup-auth-domain.c @@ -193,7 +193,7 @@ soup_auth_domain_class_init (SoupAuthDomainClass *auth_domain_class) /** * 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 ( @@ -205,7 +205,7 @@ soup_auth_domain_class_init (SoupAuthDomainClass *auth_domain_class) /** * 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 ( diff --git a/libsoup/soup-auth.c b/libsoup/soup-auth.c index 0b045a5e..e6d103d2 100644 --- a/libsoup/soup-auth.c +++ b/libsoup/soup-auth.c @@ -126,7 +126,7 @@ soup_auth_class_init (SoupAuthClass *auth_class) /** * 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 ( diff --git a/libsoup/soup-cache.c b/libsoup/soup-cache.c index 652ec66a..e970bcb0 100644 --- a/libsoup/soup-cache.c +++ b/libsoup/soup-cache.c @@ -1250,6 +1250,17 @@ soup_cache_class_init (SoupCacheClass *cache_class) } /** + * 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 diff --git a/libsoup/soup-cookie-jar.c b/libsoup/soup-cookie-jar.c index 13bf238d..2abb165f 100644 --- a/libsoup/soup-cookie-jar.c +++ b/libsoup/soup-cookie-jar.c @@ -252,6 +252,14 @@ soup_cookie_jar_new (void) 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) { @@ -716,7 +724,9 @@ soup_cookie_jar_delete_cookie (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 diff --git a/libsoup/soup-cookie.c b/libsoup/soup-cookie.c index 5e500438..b10eba80 100644 --- a/libsoup/soup-cookie.c +++ b/libsoup/soup-cookie.c @@ -1069,6 +1069,18 @@ soup_cookie_applies_to_uri (SoupCookie *cookie, SoupURI *uri) 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) { diff --git a/libsoup/soup-gnome-features.c b/libsoup/soup-gnome-features.c index 22a426bb..798712a2 100644 --- a/libsoup/soup-gnome-features.c +++ b/libsoup/soup-gnome-features.c @@ -14,7 +14,7 @@ /** * 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. diff --git a/libsoup/soup-headers.c b/libsoup/soup-headers.c index 6baf70b4..58d53a66 100644 --- a/libsoup/soup-headers.c +++ b/libsoup/soup-headers.c @@ -327,7 +327,7 @@ soup_headers_parse_status_line (const char *status_line, * 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 diff --git a/libsoup/soup-logger.c b/libsoup/soup-logger.c index 7cdf2ed2..ac901fc4 100644 --- a/libsoup/soup-logger.c +++ b/libsoup/soup-logger.c @@ -35,8 +35,8 @@ * 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 @@ -310,7 +310,7 @@ soup_logger_set_response_filter (SoupLogger *logger, * @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, diff --git a/libsoup/soup-message-body.c b/libsoup/soup-message-body.c index a1d78f86..daf9d1ec 100644 --- a/libsoup/soup-message-body.c +++ b/libsoup/soup-message-body.c @@ -121,8 +121,8 @@ soup_buffer_new (SoupMemoryUse use, gconstpointer data, gsize length) * * 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) @@ -384,25 +384,25 @@ soup_message_body_new (void) * @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. @@ -483,12 +483,12 @@ soup_message_body_append (SoupMessageBody *body, SoupMemoryUse use, * * 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, diff --git a/libsoup/soup-message-headers.c b/libsoup/soup-message-headers.c index 195a3b0d..9a2c22ec 100644 --- a/libsoup/soup-message-headers.c +++ b/libsoup/soup-message-headers.c @@ -22,6 +22,12 @@ **/ /** + * SoupMessageHeaders: + * + * The HTTP message headers associated with a request or response. + */ + +/** * SoupMessageHeadersType: * @SOUP_MESSAGE_HEADERS_REQUEST: request headers * @SOUP_MESSAGE_HEADERS_RESPONSE: response headers @@ -839,17 +845,17 @@ soup_message_headers_set_expectations (SoupMessageHeaders *hdrs, * 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 **/ diff --git a/libsoup/soup-message-queue.c b/libsoup/soup-message-queue.c index 58fea589..59c5c5c4 100644 --- a/libsoup/soup-message-queue.c +++ b/libsoup/soup-message-queue.c @@ -13,10 +13,7 @@ #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. * diff --git a/libsoup/soup-message.c b/libsoup/soup-message.c index 5cd4ac88..4efba5cf 100644 --- a/libsoup/soup-message.c +++ b/libsoup/soup-message.c @@ -64,11 +64,12 @@ * 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, @@ -352,7 +353,7 @@ soup_message_class_init (SoupMessageClass *message_class) * (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] = @@ -422,24 +423,25 @@ soup_message_class_init (SoupMessageClass *message_class) * @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 **/ @@ -1006,8 +1008,8 @@ soup_message_wrote_body (SoupMessage *msg) * 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) @@ -1019,8 +1021,8 @@ 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) @@ -1033,8 +1035,8 @@ 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) @@ -1061,8 +1063,8 @@ got_body (SoupMessage *req) * 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) @@ -1080,7 +1082,7 @@ 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) @@ -1422,7 +1424,8 @@ soup_message_cleanup_response (SoupMessage *req) * 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 @@ -1730,25 +1733,27 @@ soup_message_set_status_full (SoupMessage *msg, * 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, @@ -1778,7 +1783,7 @@ 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. @@ -1823,6 +1828,8 @@ soup_message_disables_feature (SoupMessage *msg, gpointer feature) /** * soup_message_get_first_party: * @msg: a #SoupMessage + * + * Gets @msg's first-party #SoupURI * * Returns: (transfer none): the @msg's first party #SoupURI * diff --git a/libsoup/soup-request-file.c b/libsoup/soup-request-file.c index d49d374e..85b9bf63 100644 --- a/libsoup/soup-request-file.c +++ b/libsoup/soup-request-file.c @@ -250,6 +250,16 @@ soup_request_file_class_init (SoupRequestFileClass *request_file_class) 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) { diff --git a/libsoup/soup-request.c b/libsoup/soup-request.c index ac856153..98087ee9 100644 --- a/libsoup/soup-request.c +++ b/libsoup/soup-request.c @@ -38,13 +38,14 @@ * 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 */ @@ -194,6 +195,20 @@ soup_request_default_send_finish (SoupRequest *request, 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, @@ -203,16 +218,41 @@ soup_request_send (SoupRequest *request, 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, @@ -259,24 +299,66 @@ soup_request_initable_interface_init (GInitableIface *initable_interface) 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) { diff --git a/libsoup/soup-requester.c b/libsoup/soup-requester.c index 3375a7a2..d71d447a 100644 --- a/libsoup/soup-requester.c +++ b/libsoup/soup-requester.c @@ -178,12 +178,35 @@ soup_requester_session_feature_init (SoupSessionFeatureInterface *feature_interf 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) @@ -203,6 +226,19 @@ soup_requester_request (SoupRequester *requester, const char *uri_string, 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) @@ -225,6 +261,25 @@ soup_requester_request_uri (SoupRequester *requester, SoupURI *uri, 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) { diff --git a/libsoup/soup-server.c b/libsoup/soup-server.c index 92bcc507..aa735808 100644 --- a/libsoup/soup-server.c +++ b/libsoup/soup-server.c @@ -429,7 +429,7 @@ soup_server_class_init (SoupServerClass *server_class) * 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. @@ -1206,8 +1206,9 @@ soup_client_context_get_auth_user (SoupClientContext *client) * @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, @@ -1243,7 +1244,7 @@ soup_client_context_get_auth_user (SoupClientContext *client) * * 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 diff --git a/libsoup/soup-session-feature.c b/libsoup/soup-session-feature.c index 97061ad6..f572a3a0 100644 --- a/libsoup/soup-session-feature.c +++ b/libsoup/soup-session-feature.c @@ -42,6 +42,9 @@ * @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. * diff --git a/libsoup/soup-session.c b/libsoup/soup-session.c index abb4ea51..3fc37fd1 100644 --- a/libsoup/soup-session.c +++ b/libsoup/soup-session.c @@ -404,6 +404,17 @@ soup_session_class_init (SoupSessionClass *session_class) 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), @@ -417,6 +428,17 @@ soup_session_class_init (SoupSessionClass *session_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), @@ -535,11 +557,11 @@ soup_session_class_init (SoupSessionClass *session_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 **/ @@ -598,7 +620,7 @@ soup_session_class_init (SoupSessionClass *session_class) * 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. @@ -1732,10 +1754,11 @@ cancel_message (SoupSession *session, SoupMessage *msg, guint status_code) * 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. @@ -1834,9 +1857,9 @@ soup_session_abort (SoupSession *session) * 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 **/ @@ -2003,7 +2026,7 @@ soup_session_remove_feature_by_type (SoupSession *session, GType feature_type) * @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): diff --git a/libsoup/soup-socket.c b/libsoup/soup-socket.c index 86388d91..8821caeb 100644 --- a/libsoup/soup-socket.c +++ b/libsoup/soup-socket.c @@ -343,7 +343,7 @@ soup_socket_class_init (SoupSocketClass *socket_class) /** * 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 ( @@ -815,7 +815,7 @@ listen_watch (GObject *pollable, gpointer data) * 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. **/ diff --git a/libsoup/soup-ssl.c b/libsoup/soup-ssl.c index c63110cf..2e0b5fca 100644 --- a/libsoup/soup-ssl.c +++ b/libsoup/soup-ssl.c @@ -143,6 +143,7 @@ soup_ssl_error_quark (void) * 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. **/ diff --git a/libsoup/soup-status.c b/libsoup/soup-status.c index 11fe51bb..2590a3d3 100644 --- a/libsoup/soup-status.c +++ b/libsoup/soup-status.c @@ -257,13 +257,13 @@ static const struct { * * <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 **/ diff --git a/libsoup/soup-uri.c b/libsoup/soup-uri.c index b5c247d1..1aa801b9 100644 --- a/libsoup/soup-uri.c +++ b/libsoup/soup-uri.c @@ -1050,11 +1050,11 @@ soup_uri_set_fragment (SoupURI *uri, const char *fragment) /** * 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 **/ diff --git a/libsoup/soup-xmlrpc.c b/libsoup/soup-xmlrpc.c index 71bf2702..2a4d4272 100644 --- a/libsoup/soup-xmlrpc.c +++ b/libsoup/soup-xmlrpc.c @@ -128,12 +128,13 @@ insert_value (xmlNode *parent, GValue *value) * @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: * @@ -782,6 +783,43 @@ soup_xmlrpc_error_quark (void) 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) { diff --git a/libsoup/soup-xmlrpc.h b/libsoup/soup-xmlrpc.h index 380a31e4..d25e3804 100644 --- a/libsoup/soup-xmlrpc.h +++ b/libsoup/soup-xmlrpc.h @@ -61,10 +61,6 @@ typedef enum { #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, |