From 8bc27529eb2c87a5c27e1ffd388a274d4c1ae44e Mon Sep 17 00:00:00 2001 From: Dan Winship Date: Thu, 22 Sep 2011 14:17:47 -0400 Subject: [PATCH] Lots of gtk-doc fixes (no code changes) --- docs/reference/Makefile.am | 7 +- docs/reference/client-howto.xml | 32 +- docs/reference/libsoup-2.4-docs.sgml | 13 +- docs/reference/libsoup-2.4-sections.txt | 284 ++++++++++- docs/reference/porting-2.2-2.4.xml | 878 -------------------------------- docs/reference/server-howto.xml | 12 +- libsoup/soup-address.c | 4 +- libsoup/soup-auth-domain.c | 4 +- libsoup/soup-auth.c | 2 +- libsoup/soup-cache.c | 11 + libsoup/soup-cookie-jar.c | 12 +- libsoup/soup-cookie.c | 12 + libsoup/soup-gnome-features.c | 2 +- libsoup/soup-headers.c | 2 +- libsoup/soup-logger.c | 6 +- libsoup/soup-message-body.c | 38 +- libsoup/soup-message-headers.c | 18 +- libsoup/soup-message-queue.c | 5 +- libsoup/soup-message.c | 91 ++-- libsoup/soup-request-file.c | 10 + libsoup/soup-request.c | 94 +++- libsoup/soup-requester.c | 55 ++ libsoup/soup-server.c | 9 +- libsoup/soup-session-feature.c | 3 + libsoup/soup-session.c | 51 +- libsoup/soup-socket.c | 4 +- libsoup/soup-ssl.c | 1 + libsoup/soup-status.c | 14 +- libsoup/soup-uri.c | 4 +- libsoup/soup-xmlrpc.c | 44 +- libsoup/soup-xmlrpc.h | 4 - 31 files changed, 688 insertions(+), 1038 deletions(-) delete mode 100644 docs/reference/porting-2.2-2.4.xml diff --git a/docs/reference/Makefile.am b/docs/reference/Makefile.am index 765d27c..5de8935 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 e87f901..a53f2ac 100644 --- a/docs/reference/client-howto.xml +++ b/docs/reference/client-howto.xml @@ -58,7 +58,7 @@ you can specify various additional options: - SOUP_SESSION_MAX_CONNS + SOUP_SESSION_MAX_CONNS 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: - SOUP_SESSION_MAX_CONNS_PER_HOST + SOUP_SESSION_MAX_CONNS_PER_HOST Allows you to set the maximum total number of connections the session will have open to a single @@ -76,7 +76,7 @@ you can specify various additional options: - SOUP_SESSION_USE_NTLM + SOUP_SESSION_USE_NTLM If TRUE, then Microsoft NTLM authentication will be used if available (and will be @@ -89,7 +89,7 @@ you can specify various additional options: - SOUP_SESSION_SSL_CA_FILE + SOUP_SESSION_SSL_CA_FILE 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: - SOUP_SESSION_ASYNC_CONTEXT + SOUP_SESSION_ASYNC_CONTEXT A GMainContext @@ -110,7 +110,7 @@ you can specify various additional options: - SOUP_SESSION_ADD_FEATURE and SOUP_SESSION_ADD_FEATURE_BY_TYPE + SOUP_SESSION_ADD_FEATURE and SOUP_SESSION_ADD_FEATURE_BY_TYPE These allow you to specify SoupSessionFeatures @@ -136,9 +136,9 @@ which take no arguments. Additional session functionality is provided as SoupSessionFeatures, which can be added to a session, via the SOUP_SESSION_ADD_FEATURE +linkend="SOUP-SESSION-ADD-FEATURE:CAPS">SOUP_SESSION_ADD_FEATURE and SOUP_SESSION_ADD_FEATURE_BY_TYPE +linkend="SOUP-SESSION-ADD-FEATURE-BY-TYPE:CAPS">SOUP_SESSION_ADD_FEATURE_BY_TYPE options at session-construction-time, or afterward via the soup_session_add_feature and libsoup-gnome: - SoupProxyResolverGNOME + SoupProxyResolverGNOME A feature that automatically determines the correct HTTP proxy to use for requests. @@ -190,7 +190,7 @@ And in libsoup-gnome: Use the "add_feature_by_type" property/function to add features that don't require any configuration (such as SoupProxyResolverGNOME), +linkend="SOUP-TYPE-PROXY-RESOLVER-GNOME:CAPS">SoupProxyResolverGNOME), and the "add_feature" property/function to add features that must be constructed first (such as SoupLogger). For example, an @@ -249,9 +249,9 @@ request headers and body of the message: (Although this is a bad example, because libsoup actually has convenience methods -for dealing with HTML +for dealing with HTML forms, as well as XML-RPC.) +linkend="libsoup-2.4-XMLRPC-Support">XML-RPC.) @@ -260,7 +260,7 @@ linkend="soup-message-set-flags">soup_message_set_flagsSoupSession automatically handles responses from the server that redirect to another URL. If you would like to handle these -yourself, you can set the SOUP_MESSAGE_NO_REDIRECT +yourself, you can set the SOUP_MESSAGE_NO_REDIRECT flag. @@ -286,7 +286,7 @@ it will run the main loop itself until the message is complete.) The return value from soup_session_send_message -is a libsoup status code, +is a libsoup status code, 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">soup_session_queue_messageSoupSessionSync, the message will be sent in another thread, with the callback eventually -being invoked in the session's SOUP_SESSION_ASYNC_CONTEXT.) +being invoked in the session's SOUP_SESSION_ASYNC_CONTEXT.) @@ -527,7 +527,7 @@ A few sample programs are available in the getbug is a trivial demonstration of the XMLRPC interface. + linkend="libsoup-2.4-XMLRPC-Support">XMLRPC interface. (xmlrpc-test 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 c52208f..ec6fa0d 100644 --- a/docs/reference/libsoup-2.4-docs.sgml +++ b/docs/reference/libsoup-2.4-docs.sgml @@ -11,7 +11,6 @@ - @@ -38,11 +37,13 @@ Additional Features + + @@ -64,6 +65,16 @@ + + Experimental streaming API + + + + + + + + Index diff --git a/docs/reference/libsoup-2.4-sections.txt b/docs/reference/libsoup-2.4-sections.txt index 3980677..3061351 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 + +soup_message_set_first_party +soup_message_get_first_party 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 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 @@ -154,6 +168,7 @@ soup_message_body_get_accumulate 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 SoupServerCallback @@ -337,6 +353,7 @@ soup_address_is_resolved soup_address_get_name soup_address_get_sockaddr +soup_address_get_gsockaddr soup_address_get_physical soup_address_get_port @@ -359,8 +376,6 @@ SOUP_ADDRESS_CLASS SOUP_IS_ADDRESS_CLASS SOUP_ADDRESS_GET_CLASS SoupAddressClass - -AF_INET6
@@ -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 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 SOUP_IS_SESSION SOUP_IS_SESSION_CLASS @@ -409,6 +428,11 @@ SOUP_SESSION_GET_CLASS SOUP_TYPE_SESSION SoupSessionClass soup_session_get_type + +SoupConnection +SoupConnectionState +SoupMessageQueue +SoupMessageQueueItem
@@ -461,6 +485,9 @@ SOUP_TYPE_SESSION_FEATURE soup_session_feature_attach soup_session_feature_detach +soup_session_feature_add_feature +soup_session_feature_has_feature +soup_session_feature_remove_feature
@@ -470,6 +497,10 @@ SoupAuth soup_auth_new soup_auth_update +SOUP_TYPE_AUTH_BASIC +SOUP_TYPE_AUTH_DIGEST +SOUP_TYPE_AUTH_NTLM + 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 + +soup_auth_get_saved_password +soup_auth_get_saved_users +soup_auth_has_saved_password +soup_auth_save_password
@@ -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 SOUP_SOCKET SOUP_IS_SOCKET @@ -547,6 +591,9 @@ SOUP_SOCKET_GET_CLASS SoupSocketClass soup_ssl_error_quark +soup_socket_get_fd +soup_socket_handshake_async +soup_socket_handshake_sync
@@ -558,7 +605,10 @@ soup_uri_new soup_uri_to_string soup_uri_copy +soup_uri_copy_host soup_uri_equal +soup_uri_host_equal +soup_uri_host_hash soup_uri_free soup_uri_encode @@ -567,22 +617,35 @@ soup_uri_normalize 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 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 SOUP_TYPE_URI soup_uri_get_type + +uri_decoded_copy
@@ -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 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 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
-soup-forms +soup-form HTML Form Support 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 + +soup_form_decode_urlencoded +soup_form_encode_urlencoded +soup_form_encode_urlencoded_list
@@ -666,12 +749,12 @@ soup_xmlrpc_build_fault soup_xmlrpc_set_response soup_xmlrpc_set_fault -SOUP_XMLRPC_ERROR -SoupXMLRPCError SOUP_XMLRPC_FAULT SoupXMLRPCFault soup_xmlrpc_error_quark +SOUP_XMLRPC_ERROR +SoupXMLRPCError soup_xmlrpc_fault_quark
@@ -736,23 +819,30 @@ SoupCookie soup_cookie_new soup_cookie_parse soup_cookie_copy -soup_cookie_equal soup_cookie_free 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 soup_cookie_applies_to_uri +soup_cookie_domain_matches soup_cookie_to_cookie_header soup_cookie_to_set_cookie_header @@ -766,6 +856,8 @@ soup_cookies_free SOUP_TYPE_COOKIE soup_cookie_get_type + +soup_cookie_equal
@@ -773,15 +865,20 @@ soup_cookie_get_type SoupCookieJar 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 soup_cookie_jar_add_cookie soup_cookie_jar_delete_cookie soup_cookie_jar_all_cookies +SoupCookieJarAcceptPolicy +soup_cookie_jar_get_accept_policy +soup_cookie_jar_set_accept_policy + SOUP_COOKIE_JAR_READ_ONLY +SOUP_COOKIE_JAR_ACCEPT_POLICY 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
@@ -875,6 +973,8 @@ SOUP_TYPE_PROXY_RESOLVER_GNOME soup_proxy_resolver_gnome_get_type soup_gnome_features_2_26_get_type +SOUP_TYPE_PASSWORD_MANAGER_GNOME +soup_password_manager_gnome_get_type
@@ -894,3 +994,167 @@ SoupContentSnifferClass SoupContentSnifferPrivate soup_content_sniffer_get_type
+ +
+soup-cache +SoupCache +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 + +SOUP_TYPE_CACHE +SOUP_IS_CACHE +SOUP_IS_CACHE_CLASS +SOUP_CACHE +SOUP_CACHE_CLASS +SOUP_CACHE_GET_CLASS +SoupCacheClass +SoupCachePrivate + +soup_cache_generate_conditional_request +soup_cache_get_cacheability +soup_cache_get_type +soup_cache_has_response +soup_cache_send_response +SoupCacheResponse +SoupCacheability +
+ +
+soup-content-decoder +SoupContentDecoder +SoupContentDecoder + +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 +
+ +
+soup-proxy-resolver-default +SoupProxyResolverDefault +SoupProxyResolverDefault + +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 +
+ +
+soup-requester +SoupRequester +SoupRequester +soup_requester_new +soup_requester_request +soup_requester_request_uri + +SoupRequesterError +SOUP_REQUESTER_ERROR + +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 + +soup_requester_error_quark +
+ +
+soup-request +SoupRequest +SoupRequest +soup_request_send +soup_request_send_async +soup_request_send_finish + +soup_request_get_content_length +soup_request_get_content_type +soup_request_get_session +soup_request_get_uri + +SOUP_REQUEST_SESSION +SOUP_REQUEST_URI + +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 +
+ +
+soup-request-data +SoupRequestData +SoupRequestData + +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 +
+ +
+soup-request-file +SoupRequestFile +SoupRequestFile +soup_request_file_get_file + +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 +
+ +
+soup-request-http +SoupRequestHTTP +SoupRequestHTTP +soup_request_http_get_message + +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 +
+ 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 37632bf..0000000 --- a/docs/reference/porting-2.2-2.4.xml +++ /dev/null @@ -1,878 +0,0 @@ - - - - -libsoup 2.2 to 2.4 porting notes -3 -LIBSOUP Library - - - -Porting notesNotes on porting from libsoup 2.2 to 2.4 - - - -Overview - - -After many API-compatible releases in the 2.2 series, -libsoup has now changed its API and bumped -its version number to 2.4. Changes were made for a variety of reasons: - - - - - To fix bugs and add features that couldn't be done ABI-compatibly. - - - - To make it easier to generate bindings for libsoup for - languages other than C. - - - - To clean up ugly/confusing old APIs - - - - To be more glib/gobject/gtk-like in general. - - - - - - -SoupMessage - - -SoupMessage has had a -number of API changes made, mostly to increase its -language-bindability. - - - -SoupMessageHeaders - - - SoupMessage's - request_headers and - response_headers fields are now an - opaque type (SoupMessageHeaders) - rather than being GHashTables. The method names have - changed slightly to reflect this: - - - - - soup_message_add_header - - → soup_message_headers_append - - - - soup_message_get_header - - → soup_message_headers_get - - - - soup_message_foreach_header - - → soup_message_headers_foreach - - - - soup_message_remove_header - - → soup_message_headers_remove - - - - soup_message_clear_headers - - → soup_message_headers_clear - - - - - - soup_message_get_header_list has no equivalent; - if multiple copies of a header are present, - soup_message_headers_get 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. - - - - In addition, certain important header fields now have - dedicated get/set methods: - - - - - soup_message_headers_get_encoding / soup_message_headers_set_encoding - - - - soup_message_headers_get_content_length / soup_message_headers_set_content_length - - - - soup_message_headers_get_expectations / soup_message_headers_set_expectations - - - - - (soup_message_headers_set_expectation(msg, SOUP_EXPECTATION_CONTINUE) - replaces the SOUP_MESSAGE_EXPECT_CONTINUE - message flag). - - - - - -SoupMessageBody - - - Similarly, the request_body and - response fields (renamed from - request and response) are - now a new type, SoupMessageBody, - implemented in terms of SoupBuffer, a refcounted - memory buffer type with clearer semantics than the old - SoupDataBuffer/SoupOwnership. - - - - - SOUP_BUFFER_STATIC - - → SOUP_MEMORY_STATIC - - - - SOUP_BUFFER_SYSTEM_OWNED - - → SOUP_MEMORY_TAKE - (meaning libsoup - should take ownership of the memory from your). - - - - SOUP_BUFFER_USER_OWNED - - → SOUP_MEMORY_COPY - (meaning libsoup - should make a copy of the memory, because you - can't make any guarantees about how long it will - last.) - - - - - - A fourth SoupMemoryUse value is also available: SOUP_MEMORY_TEMPORARY, - which helps to avoid extra copies in some cases. - SOUP_MEMORY_TEMPORARY means that the memory - will last at least as long as the object you are handing it to (a - SoupBuffer, SoupMessageBody, or - SoupMessage), and so doesn't need to be copied right - away, but that if anyone makes a copy of the buffer, - libsoup 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. - - - - (In the future, there may be additional SoupBuffer - and SoupMessageBody methods to work directly with - mmapped memory, splicing to file descriptors, etc.) - - - - soup_message_set_request - and soup_message_set_response - still work roughly like they used to. - - - - Unlike the old request and - response fields, the new - request_body and - response_body fields are not guaranteed - to be filled in at all times. (In particular, the - response_body is not filled in until it - has been fully read, although you can use soup_message_body_get_chunk - to iterate through the chunks before that point if you need to.) - - - - When request_body and - response_body are - filled in, they are '\0'-terminated for your - processing convenience. (The terminating 0 byte is not included in - their length.) - - - - - -Chunked encoding - - - The prototype of the SoupMessage::got_chunk - signal has been changed; it now includes the chunk as a - SoupBuffer parameter (rather than storing the chunk - data in msg->response as in 2.2). SOUP_MESSAGE_OVERWRITE_CHUNKS - 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 msg->response_body will not be filled - in with the complete response at the end of message processing. - - - - The API for sending chunked responses from a - SoupServer is also slightly different now: - - - - - soup_server_message_set_encoding - - → soup_message_headers_set_encoding - - - - soup_message_add_chunk - - → soup_message_body_append - or soup_message_body_append_buffer - - - - soup_message_add_final_chunk - - → soup_message_body_complete - - - - - - Since the new chunk-sending APIs require you to explicitly pass - the - request_headers/request_body - 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. - - - - - -Methods - - - SoupMessage's - method field is now an interned - string, and you can compare the method directly against - the defines such as SOUP_METHOD_GET - (eg, in a SoupServer request handler). - soup_method_get_id and the - SOUP_METHOD_ID_* macros are now gone. - - - - -Handlers - - - soup_message_add_header_handler - and soup_message_add_status_code_handler - are now just clever wrappers around - g_signal_connect. In particular, you now pass - a signal name to them rather than a SoupHandlerPhase, - 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 - g_signal_connect if you don't want that - behavior.) - - - - -I/O-related <type>SoupMessage</type> methods - - - soup_message_io_pause and - soup_message_io_unpause have been moved to - SoupSession and SoupServer, to better - reflect the fact that the session/server control the I/O, and - SoupMessage is merely acted-upon by them. - - - - - soup_message_io_pause - - → soup_session_pause_message / soup_server_pause_message - - - - soup_message_io_unpause - - → soup_session_unpause_message / soup_server_unpause_message - - - - - - msg->status (the I/O status) is now - gone as well, because (a) it's really an internal state of - SoupSession, and (b) it's too easy to confuse - with msg->status_code (the HTTP status) - anyway. Code that used to check if status was - SOUP_MESSAGE_STATUS_FINISHED needs to - be rewritten to track whether or not the finished - signal has been emitted. - - - - - -HTTP-Version - - - SoupHttpVersion is now SoupHTTPVersion - - - - - - -SoupSession - - -<function>soup_session_queue_message</function> callback - - - soup_session_queue_message's - callback parameter now includes the SoupSession as a - parameter, reflecting the fact that it is a - SoupSession callback, not a SoupMessage - callback. (It has also been renamed, from - SoupMessageCallbackFn to SoupSessionCallback.) - - - - -Authentication - - - SoupSession's authenticate and - reauthenticate signals have been merged into a - single authenticate - signal with a retrying parameter to indicate if - it's the second (or later) try. Also, the signal now includes a - SoupAuth directly, - and you authenticate by calling soup_auth_authenticate - on the auth (rather than passing back a username and password from - the signal handler). - - - - -<type>SoupLogger</type> - - -SoupLogger is a -new object that copies the behavior of -evolution-exchange's -E2K_DEBUG and its clones. That is, it causes a -SoupSession to start logging some or all of its HTTP -traffic to stdout, for debugging purposes. - - - - -<type>SoupMessageFilter</type> - - - SoupMessageFilter is gone; code that used to use it - can now connect to the SoupSession::request-started - signal to get a chance to act on each message as it is sent. - (This is how SoupLogger works.) - - - - -Internal types - - - The SoupConnection and SoupMessageQueue - types (which should always have been internal to - SoupSession) have been removed from the public API. - - - - - - -SoupURI - -SoupUri has been renamed SoupURI, and its behavior has -changed in a few ways: - - - - - 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 - broken_encoding behavior, but - that flag no longer exists, since it is the default and - there's no way to turn it off. - - - - In theory, this is an ABI-breaking change, especially for - SoupServers. - However, it is unlikely to actually break anything. (And - in the SoupServer case, servers now - fully-decode the path component - themselves unless you set the SOUP_SERVER_RAW_PATHS - flag on the server, so the behavior should still be the - same. - - - - - It uses the RFC3986 parsing rules, including support for IPv6 literal - addresses. - - - - - The field formerly called - protocol is now - scheme, to match the spec, and - it's an interned string rather than a quark. The names of - the predefined values have changed to match: - - - - - SOUP_PROTOCOL_HTTP - - → SOUP_URI_SCHEME_HTTP - - - - SOUP_PROTOCOL_HTTPS - - → SOUP_URI_SCHEME_HTTPS - - - - - - - -soup_uri_decode -now returns a new string rather than modifying its input string in -place. The new method soup_uri_normalize, -which removes some, but not all, %-encoding, behaves similarly. - - - -Finally, SoupURI (as well as most other struct types in -libsoup) now uses the glib "slice" -allocator, so any code that uses g_new to create -SoupURIs is wrong. If you want to create a URI "by hand", -you can call soup_uri_new, -passing NULL, and you will get back an empty -SoupURI. There are also now methods that can be used to -set its fields (eg, soup_uri_set_scheme, -soup_uri_set_path, -etc) rather than mucking with the fields directly. - - - -Forms - - -Related to SoupURI, there are some new helper methods for -dealing with HTML forms. soup_form_decode_urlencoded -decodes a URI query component (or an -application/x-www-form-urlencoded request body) -into a GHashTable. soup_form_encode_urlencoded -reverses the process, allowing you to fill in a -uri->query with a properly-encoded form dataset. -(SoupURI also provides soup_uri_set_query_from_form -to help with this.) - - - - - - - -XML-RPC and SOAP - - -SOAP - -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. - - - - -XML-RPC - -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 new XML-RPC API makes use of -GValues, with the following type mappings: - - - - - int - - → int (G_TYPE_INT) - - - - boolean - - → gboolean (G_TYPE_BOOLEAN) - - - - string - - → char * (G_TYPE_STRING) - - - - double - - → double (G_TYPE_DOUBLE) - - - - dateTime.iso8601 - - → SoupDate (SOUP_TYPE_DATE) - - - - base64 - - → GByteArray (SOUP_TYPE_BYTE_ARRAY) - - - - struct - - → GHashTable (G_TYPE_HASH_TABLE) - - - - array - - → GValueArray (G_TYPE_VALUE_ARRAY) - - - - - -SoupDate is discussed below. -SOUP_TYPE_BYTE_ARRAY is just a new -GType value defined by libsoup -to represent GByteArrays, which glib does not define a -GType for. - - - -libsoup provides some additional GValue support -methods for working with -GValueArrays, and GHashTables of -GValues, for the XML-RPC struct and -array types. Eg, you can use soup_value_hash_new -to create a GHashTable to use with the XML-RPC methods, -and soup_value_hash_insert -to add values to it without needing to muck with GValues -directly. - - - -The getbug and xmlrpc-test -programs in the libsoup sources provide -examples of how to use the new API. (Beware that -xmlrpc-test's use of the API is a little -complicated because of the way it sends all calls through a single -do_xmlrpc method.) - - - - - - -SoupServer - - -SoupServer handlers - - - The prototypes for soup_server_add_handler, - and for the SoupServer - handlers themselves have changed: - - - -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); - - - - soup_server_add_handler no longer takes a - SoupServerAuthContext (see the discussion of server - authentication below), and the order of the final two arguments - has been swapped. (Additionally, SoupServerCallbackFn - has been renamed to SoupServerCallback, and the old - unregister parameter of type - SoupServerUnregisterFn is now a standard - GDestroyNotify. The change to - GDestroyNotify and the swapping of the final two - arguments is to make the method conform to standard glib/gtk - practices.) - - - - In SoupServerCallback, several bits of data that used - to be part of the context argument are now - provided directly, and context specifically - only contains more specifically-client-related information (such - as the SoupSocket that the request arrived on, and - information about authentication). - - - - path is the fully %-decoded path component - of msg's URI, and - query is a hash table containing - msg's URI's - query component decoded with soup_form_decode_urlencoded. - These are provided for your convenience; if you need the raw - query, you can get it out of msg's URI - directly. If you need the raw path, you'll need to set the SOUP_SERVER_RAW_PATHS - property on the server, which actually changes the behavior of the - server with respect to how paths are matched; see the - documentation for details. - - - - -Server-side authentication - - - SoupServer authentication has been completely - rewritten, with SoupServerAuthContext being replaced - with SoupAuthDomain. Among - other improvements, you no longer need to have the cleartext - password available to check against. See the - SoupAuthDomain documentation, the server tutorial, and - tests/server-auth-test.c. - - - - -<literal>Expect: 100-continue</literal> and other early <type>SoupMessage</type> processing - - - SoupServer now handles - "Expect: 100-continue" correctly. In - particular, if the client passes that header, and your server - requires authentication, then authentication will be checked - before reading the request body. - - - - If you want to do additional pre-request-body handling, you can - connect to SoupServer's request_started - signal, and connect to the request's got_headers - signal from there. (See the description of - request_started for information about other - related SoupServer signals.) - - - - -Date header - - - SoupServer now automatically sets the - Date header on all responses, as required by - RFC 2616. - - - - -SoupServerMessage - - - SoupServerMessage is now merged into - SoupMessage. - soup_server_message_set_encoding is replaced - with soup_message_headers_set_encoding - as described in the section on SoupMessage above. - - - - -<function>soup_server_run</function> / <function>soup_server_quit</function> - - - soup_server_run - and soup_server_run_async - no longer g_object_ref the server, and - soup_server_quit - no longer unrefs it. - - - - - - -Miscellaneous - - -SoupDate - - - The new SoupDate type - replaces the old soup_date_* methods, and has - an improved (more liberal) date parser. - - - - -Header parsing - - - soup-headers.h now has a few additional methods - for parsing list-type headers. - - - - -SoupAddress, SoupSocket - - - SoupSocket has had various simplifications made to - reflect the fact that this is specifically libsoup's socket - implementation, not some random generic socket API. - - - - Various SoupAddress and SoupSocket - methods now take arguments of the new GCancellable type, from - libgio. When porting old code, you can just pass - NULL for these. (soup_address_resolve_async - also takes another new argument, a GMainContext that - you'll want to pass NULL for.) If you pass a - GCancellable, you can use it to cleanly cancel the - address resolution / socket operation. - - - - - -Base64 methods - - - The deprecated base64 methods are now gone; use glib's base64 - methods instead. - - - - - - diff --git a/docs/reference/server-howto.xml b/docs/reference/server-howto.xml index 0a9a53d..76c1918 100644 --- a/docs/reference/server-howto.xml +++ b/docs/reference/server-howto.xml @@ -30,7 +30,7 @@ various additional options: - SOUP_SERVER_PORT + SOUP_SERVER_PORT The TCP port to listen on. If 0 (or left unspecified), some unused port will be selected for @@ -39,7 +39,7 @@ various additional options: - SOUP_SERVER_INTERFACE + SOUP_SERVER_INTERFACE A SoupAddress, specifying the IP address of the network interface to run @@ -48,7 +48,7 @@ various additional options: - SOUP_SERVER_SSL_CERT_FILE + SOUP_SERVER_SSL_CERT_FILE 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: - SOUP_SERVER_SSL_KEY_FILE + SOUP_SERVER_SSL_KEY_FILE Points to a file containing the private key for the SOUP_SERVER_SSL_CERT_FILE. (It may @@ -64,7 +64,7 @@ various additional options: - SOUP_SERVER_ASYNC_CONTEXT + SOUP_SERVER_ASYNC_CONTEXT A GMainContext which the server will use for asynchronous operations. This can @@ -73,7 +73,7 @@ various additional options: - SOUP_SERVER_RAW_PATHS + SOUP_SERVER_RAW_PATHS Set this to TRUE if you don't want libsoup to decode %-encoding diff --git a/libsoup/soup-address.c b/libsoup/soup-address.c index 0e5e8cd..42b777d 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 c8ce96b..dd47dff 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 0b045a5..e6d103d 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 652ec66..e970bcb 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 13bf238..2abb165 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 5e50043..b10eba8 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 22a426b..798712a 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 6baf70b..58d53a6 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 7cdf2ed..ac901fc 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 + * stdout, and looks something like: * * * > 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 stdout. **/ void soup_logger_set_printer (SoupLogger *logger, diff --git a/libsoup/soup-message-body.c b/libsoup/soup-message-body.c index a1d78f8..daf9d1e 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 195a3b0..9a2c22e 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 58fea58..59c5c5c 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 5cd4ac8..4efba5c 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 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). * * 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. + * length 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 #SoupSessionFeatures 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 d49d374..85b9bf6 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 ac85615..98087ee 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 3375a7a..d71d447 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 92bcc50..aa73580 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, * "libsoup/2.3.2") 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 97061ad..f572a3a 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 #SoupSessionFeatures. * diff --git a/libsoup/soup-session.c b/libsoup/soup-session.c index abb4ea5..3fc37fd 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, "libsoup/2.3.2") 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, + * 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. * * 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 86388d9..8821cae 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 c63110c..2e0b5fc 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 11fe51b..2590a3d 100644 --- a/libsoup/soup-status.c +++ b/libsoup/soup-status.c @@ -257,13 +257,13 @@ static const struct { * * There is no reason for you to ever use this * function. 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 b5c247d..1aa801b 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 71bf270..2a4d427 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 valuesf and + * n_values 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 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. + */ + GQuark soup_xmlrpc_fault_quark (void) { diff --git a/libsoup/soup-xmlrpc.h b/libsoup/soup-xmlrpc.h index 380a31e..d25e380 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, -- 2.7.4