From 5069f32c25a4a1ef85b698d9cbd283418c8a8de7 Mon Sep 17 00:00:00 2001 From: Dan Winship Date: Tue, 14 Jun 2005 15:34:22 +0000 Subject: [PATCH] add/fix gtk-doc comments, make functions match prototypes, etc * libsoup/*.[ch]: add/fix gtk-doc comments, make functions match prototypes, etc * docs/reference/*: update, fix, etc --- ChangeLog | 7 + docs/reference/libsoup-docs.sgml | 13 +- docs/reference/libsoup-overrides.txt | 11 + docs/reference/libsoup-sections.txt | 368 +++++++++------- docs/reference/libsoup.types | 8 + docs/reference/tmpl/libsoup-unused.sgml | 482 ++++++++++++++++++--- docs/reference/tmpl/soup-address.sgml | 44 +- docs/reference/tmpl/soup-auth-basic.sgml | 23 - docs/reference/tmpl/soup-auth-digest.sgml | 23 - docs/reference/tmpl/soup-auth.sgml | 24 +- docs/reference/tmpl/soup-connection-ntlm.sgml | 5 +- docs/reference/tmpl/soup-connection.sgml | 110 ++++- docs/reference/tmpl/soup-dns.sgml | 79 +++- docs/reference/tmpl/soup-headers.sgml | 92 ---- docs/reference/tmpl/soup-marshal.sgml | 78 ---- docs/reference/tmpl/soup-md5-utils.sgml | 6 +- .../{soup-types.sgml => soup-message-filter.sgml} | 11 +- docs/reference/tmpl/soup-message-queue.sgml | 14 +- docs/reference/tmpl/soup-message.sgml | 321 +++++++------- docs/reference/tmpl/soup-method.sgml | 165 ------- docs/reference/tmpl/soup-misc.sgml | 4 +- docs/reference/tmpl/soup-server-auth.sgml | 11 +- docs/reference/tmpl/soup-server-message.sgml | 8 +- docs/reference/tmpl/soup-server.sgml | 89 ++-- docs/reference/tmpl/soup-session-async.sgml | 42 ++ docs/reference/tmpl/soup-session-sync.sgml | 46 ++ docs/reference/tmpl/soup-session.sgml | 125 +++++- docs/reference/tmpl/soup-soap-message.sgml | 13 +- docs/reference/tmpl/soup-soap-response.sgml | 197 +++++++++ docs/reference/tmpl/soup-socket.sgml | 123 ++++-- docs/reference/tmpl/soup-ssl.sgml | 32 +- docs/reference/tmpl/soup-status.sgml | 177 ++++---- docs/reference/tmpl/soup-uri.sgml | 24 +- libsoup/soup-address.c | 22 +- libsoup/soup-address.h | 26 +- libsoup/soup-auth.c | 7 +- libsoup/soup-auth.h | 2 +- libsoup/soup-connection.c | 49 ++- libsoup/soup-connection.h | 17 +- libsoup/soup-dns.c | 7 + libsoup/soup-dns.h | 22 +- libsoup/soup-gnutls.c | 24 +- libsoup/soup-headers.c | 14 + libsoup/soup-md5-utils.h | 1 + libsoup/soup-message-handlers.c | 10 +- libsoup/soup-message-queue.h | 7 + libsoup/soup-message.c | 88 +++- libsoup/soup-message.h | 156 +++++-- libsoup/soup-misc.h | 7 +- libsoup/soup-session-async.c | 16 + libsoup/soup-session-sync.c | 16 + libsoup/soup-session.c | 57 ++- libsoup/soup-soap-message.c | 150 ++++--- libsoup/soup-soap-message.h | 2 +- libsoup/soup-soap-response.c | 117 +++-- libsoup/soup-socket.c | 43 ++ libsoup/soup-socket.h | 41 +- libsoup/soup-ssl.h | 7 + libsoup/soup-status.h | 144 ++++++ libsoup/soup-uri.c | 24 +- libsoup/soup-uri.h | 18 + 61 files changed, 2652 insertions(+), 1217 deletions(-) delete mode 100644 docs/reference/tmpl/soup-auth-basic.sgml delete mode 100644 docs/reference/tmpl/soup-auth-digest.sgml delete mode 100644 docs/reference/tmpl/soup-headers.sgml delete mode 100644 docs/reference/tmpl/soup-marshal.sgml rename docs/reference/tmpl/{soup-types.sgml => soup-message-filter.sgml} (69%) delete mode 100644 docs/reference/tmpl/soup-method.sgml create mode 100644 docs/reference/tmpl/soup-session-async.sgml create mode 100644 docs/reference/tmpl/soup-session-sync.sgml create mode 100644 docs/reference/tmpl/soup-soap-response.sgml diff --git a/ChangeLog b/ChangeLog index f26c60a..c4705d9 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,10 @@ +2005-06-14 Dan Winship + + * libsoup/*.[ch]: add/fix gtk-doc comments, make functions match + prototypes, etc + + * docs/reference/*: update, fix, etc + 2005-06-13 Tor Lillqvist * configure.in: Check also for inet_ntop(). Pre-cache knowledge diff --git a/docs/reference/libsoup-docs.sgml b/docs/reference/libsoup-docs.sgml index 99884f3..76d372b 100644 --- a/docs/reference/libsoup-docs.sgml +++ b/docs/reference/libsoup-docs.sgml @@ -8,24 +8,17 @@ libsoup - - - - - - - + - - - + + diff --git a/docs/reference/libsoup-overrides.txt b/docs/reference/libsoup-overrides.txt index e69de29..9828402 100644 --- a/docs/reference/libsoup-overrides.txt +++ b/docs/reference/libsoup-overrides.txt @@ -0,0 +1,11 @@ + +soup_dns_lookup_get_address +struct sockaddr * +SoupDNSLookup *lookup + + +soup_address_get_sockaddr +struct sockaddr * +SoupAddress *addr, +int *len + diff --git a/docs/reference/libsoup-sections.txt b/docs/reference/libsoup-sections.txt index e382c95..46352d9 100644 --- a/docs/reference/libsoup-sections.txt +++ b/docs/reference/libsoup-sections.txt @@ -1,56 +1,54 @@
soup-message +SoupMessage +SoupMessage SoupMessageStatus SOUP_MESSAGE_IS_STARTING SoupTransferEncoding SoupOwnership SoupDataBuffer -SoupMessage SoupMessageCallbackFn + soup_message_new soup_message_new_from_uri soup_message_set_request soup_message_set_response + soup_message_add_header soup_message_get_header soup_message_get_header_list soup_message_foreach_header soup_message_remove_header soup_message_clear_headers + SoupHttpVersion soup_message_set_http_version soup_message_get_http_version -soup_message_is_keepalive soup_message_get_uri soup_message_set_uri SoupMessageFlags soup_message_set_flags soup_message_get_flags + +soup_message_set_status +soup_message_set_status_full +soup_message_add_chunk +soup_message_add_final_chunk +soup_message_pop_chunk +soup_message_is_keepalive + SoupHandlerPhase soup_message_add_handler soup_message_add_header_handler soup_message_add_status_code_handler soup_message_add_status_class_handler soup_message_remove_handler -soup_message_set_status -soup_message_set_status_full -soup_message_add_chunk -soup_message_add_final_chunk -soup_message_pop_chunk + soup_message_send_request soup_message_read_request -soup_message_io_cancel soup_message_io_pause soup_message_io_unpause -soup_message_wrote_informational -soup_message_wrote_headers -soup_message_wrote_chunk -soup_message_wrote_body -soup_message_got_informational -soup_message_got_headers -soup_message_got_chunk -soup_message_got_body -soup_message_finished +soup_message_io_stop SOUP_MESSAGE SOUP_IS_MESSAGE @@ -60,21 +58,37 @@ SOUP_MESSAGE_CLASS SOUP_IS_MESSAGE_CLASS SOUP_MESSAGE_GET_CLASS SoupMessageClass -
- -
-soup-auth-digest -SoupAuthDigest -SoupAuthDigest - -SOUP_AUTH_DIGEST -SOUP_IS_AUTH_DIGEST -SOUP_TYPE_AUTH_DIGEST -soup_auth_digest_get_type -SOUP_AUTH_DIGEST_CLASS -SOUP_IS_AUTH_DIGEST_CLASS -SOUP_AUTH_DIGEST_GET_CLASS -SoupAuthDigestClass +SoupMessagePrivate +SOUP_MESSAGE_GET_PRIVATE + +SOUP_METHOD_OPTIONS +SOUP_METHOD_GET +SOUP_METHOD_HEAD +SOUP_METHOD_PUT +SOUP_METHOD_POST +SOUP_METHOD_DELETE +SOUP_METHOD_TRACE +SOUP_METHOD_CONNECT +SOUP_METHOD_PROPFIND +SOUP_METHOD_PROPPATCH +SOUP_METHOD_MKCOL +SOUP_METHOD_COPY +SOUP_METHOD_MOVE +SOUP_METHOD_LOCK +SOUP_METHOD_UNLOCK +SOUP_METHOD_PATCH +SoupMethodId +soup_method_get_id +soup_message_wrote_informational +soup_message_wrote_headers +soup_message_wrote_chunk +soup_message_wrote_body +soup_message_got_informational +soup_message_got_headers +soup_message_got_chunk +soup_message_got_body +soup_message_finished +soup_message_restarted
@@ -94,25 +108,27 @@ SOUP_STATUS_IS_TRANSPORT_ERROR
soup-server SoupServer +SoupServer SoupServerContext SoupServerCallbackFn SoupServerUnregisterFn -SOUP_SERVER_PORT -SOUP_SERVER_INTERFACE -SOUP_SERVER_SSL_CERT_FILE -SOUP_SERVER_SSL_KEY_FILE soup_server_new soup_server_get_protocol soup_server_get_port soup_server_run soup_server_run_async soup_server_quit +SoupServerHandler soup_server_add_handler soup_server_remove_handler soup_server_get_handler soup_server_list_handlers soup_server_context_get_client_address soup_server_context_get_client_host +SOUP_SERVER_PORT +SOUP_SERVER_INTERFACE +SOUP_SERVER_SSL_CERT_FILE +SOUP_SERVER_SSL_KEY_FILE SOUP_SERVER SOUP_IS_SERVER @@ -127,6 +143,7 @@ SoupServerClass
soup-address SoupAddress +SoupAddress SoupAddressFamily SOUP_ADDRESS_ANY_PORT soup_address_new @@ -136,6 +153,7 @@ SoupAddressCallback soup_address_resolve_async soup_address_resolve_sync soup_address_get_name +soup_address_get_sockaddr soup_address_get_physical soup_address_get_port @@ -185,45 +203,121 @@ soup_soap_message_reset soup_soap_message_persist soup_soap_message_get_namespace_prefix soup_soap_message_get_xml_doc +soup_soap_message_parse_response -SOUP_SOAP_MESSAGE SOUP_IS_SOAP_MESSAGE -SOUP_TYPE_SOAP_MESSAGE -soup_soap_message_get_type -SOUP_SOAP_MESSAGE_CLASS SOUP_IS_SOAP_MESSAGE_CLASS +SOUP_SOAP_MESSAGE +SOUP_SOAP_MESSAGE_CLASS SOUP_SOAP_MESSAGE_GET_CLASS +SOUP_TYPE_SOAP_MESSAGE SoupSoapMessageClass -SoupSoapMessagePrivate +soup_soap_message_get_type +
+ +
+soup-soap-response +SoupSoapResponse +SoupSoapResponse +SoupSoapParameter +soup_soap_response_new +soup_soap_response_new_from_string +soup_soap_response_set_method_name +soup_soap_parameter_get_first_child +soup_soap_parameter_get_first_child_by_name +soup_soap_parameter_get_int_value +soup_soap_parameter_get_name +soup_soap_parameter_get_next_child +soup_soap_parameter_get_next_child_by_name +soup_soap_parameter_get_property +soup_soap_parameter_get_string_value +soup_soap_response_from_string +soup_soap_response_get_first_parameter +soup_soap_response_get_first_parameter_by_name +soup_soap_response_get_method_name +soup_soap_response_get_next_parameter +soup_soap_response_get_next_parameter_by_name +soup_soap_response_get_parameters + +SOUP_IS_SOAP_RESPONSE +SOUP_IS_SOAP_RESPONSE_CLASS +SOUP_SOAP_RESPONSE +SOUP_SOAP_RESPONSE_CLASS +SOUP_SOAP_RESPONSE_GET_CLASS +SOUP_TYPE_SOAP_RESPONSE +SoupSoapResponseClass +soup_soap_response_get_type
soup-session SoupSession +SoupSession +soup_session_queue_message +soup_session_requeue_message +soup_session_send_message +soup_session_abort +soup_session_add_filter +soup_session_cancel_message +soup_session_get_connection +soup_session_remove_filter +soup_session_try_prune_connection SOUP_SESSION_PROXY_URI SOUP_SESSION_MAX_CONNS SOUP_SESSION_MAX_CONNS_PER_HOST SOUP_SESSION_USE_NTLM SOUP_SESSION_SSL_CA_FILE -soup_session_queue_message -soup_session_requeue_message -soup_session_send_message -soup_session_abort -SOUP_SESSION SOUP_IS_SESSION -SOUP_TYPE_SESSION -soup_session_get_type -SOUP_SESSION_CLASS SOUP_IS_SESSION_CLASS +SOUP_SESSION +SOUP_SESSION_CLASS SOUP_SESSION_GET_CLASS +SOUP_TYPE_SESSION SoupSessionClass +soup_session_get_type +
+ +
+soup-session-async +SoupSessionAsync +SoupSessionAsync +soup_session_async_new +soup_session_async_new_with_options + +SOUP_IS_SESSION_ASYNC +SOUP_IS_SESSION_ASYNC_CLASS +SOUP_SESSION_ASYNC +SOUP_SESSION_ASYNC_CLASS +SOUP_SESSION_ASYNC_GET_CLASS +SOUP_TYPE_SESSION_ASYNC +SoupSessionAsyncClass +soup_session_async_get_type +
+ +
+soup-session-sync +SoupSessionSync +SoupSessionSync +soup_session_sync_new +soup_session_sync_new_with_options + +SOUP_IS_SESSION_SYNC +SOUP_IS_SESSION_SYNC_CLASS +SOUP_SESSION_SYNC +SOUP_SESSION_SYNC_CLASS +SOUP_SESSION_SYNC_GET_CLASS +SOUP_TYPE_SESSION_SYNC +SoupSessionSyncClass +soup_session_sync_get_type
soup-auth SoupAuth SoupAuth +SoupAuthBasic +SoupAuthDigest soup_auth_new_from_header_list soup_auth_get_scheme_name soup_auth_get_realm @@ -241,20 +335,33 @@ SOUP_AUTH_CLASS SOUP_IS_AUTH_CLASS SOUP_AUTH_GET_CLASS SoupAuthClass +SOUP_AUTH_BASIC +SOUP_IS_AUTH_BASIC +SOUP_TYPE_AUTH_BASIC +soup_auth_basic_get_type +SOUP_AUTH_BASIC_CLASS +SOUP_IS_AUTH_BASIC_CLASS +SOUP_AUTH_BASIC_GET_CLASS +SoupAuthBasicClass +SOUP_AUTH_DIGEST +SOUP_IS_AUTH_DIGEST +SOUP_TYPE_AUTH_DIGEST +soup_auth_digest_get_type +SOUP_AUTH_DIGEST_CLASS +SOUP_IS_AUTH_DIGEST_CLASS +SOUP_AUTH_DIGEST_GET_CLASS +SoupAuthDigestClass
soup-socket SoupSocket -SOUP_SOCKET_FLAG_NONBLOCKING -SOUP_SOCKET_FLAG_NODELAY -SOUP_SOCKET_FLAG_REUSEADDR -SOUP_SOCKET_IS_SERVER -SOUP_SOCKET_SSL_CREDENTIALS +SoupSocket soup_socket_new soup_socket_connect soup_socket_listen soup_socket_start_ssl +soup_socket_start_proxy_ssl soup_socket_disconnect soup_socket_is_connected SoupSocketCallback @@ -268,6 +375,11 @@ SoupSocketIOStatus soup_socket_read soup_socket_read_until soup_socket_write +SOUP_SOCKET_FLAG_NONBLOCKING +SOUP_SOCKET_FLAG_NODELAY +SOUP_SOCKET_FLAG_REUSEADDR +SOUP_SOCKET_IS_SERVER +SOUP_SOCKET_SSL_CREDENTIALS SOUP_SOCKET SOUP_IS_SOCKET @@ -295,26 +407,9 @@ SoupConnectionNTLMClass
-soup-auth-basic -SoupAuthBasic -SoupAuthBasic - -SOUP_AUTH_BASIC -SOUP_IS_AUTH_BASIC -SOUP_TYPE_AUTH_BASIC -soup_auth_basic_get_type -SOUP_AUTH_BASIC_CLASS -SOUP_IS_AUTH_BASIC_CLASS -SOUP_AUTH_BASIC_GET_CLASS -SoupAuthBasicClass -
- -
soup-connection SoupConnection -SOUP_CONNECTION_ORIGIN_URI -SOUP_CONNECTION_PROXY_URI -SOUP_CONNECTION_SSL_CREDENTIALS +SoupConnection soup_connection_new SoupConnectionCallback soup_connection_connect_async @@ -325,6 +420,12 @@ soup_connection_last_used soup_connection_send_request soup_connection_authenticate soup_connection_reauthenticate +soup_connection_release +soup_connection_reserve +SOUP_CONNECTION_ORIGIN_URI +SOUP_CONNECTION_PROXY_URI +SOUP_CONNECTION_SSL_CREDENTIALS +SOUP_CONNECTION_MESSAGE_FILTER SOUP_CONNECTION SOUP_IS_CONNECTION @@ -339,6 +440,7 @@ SoupConnectionClass
soup-server-message SoupServerMessage +SoupServerMessage soup_server_message_new soup_server_message_get_server soup_server_message_set_encoding @@ -359,59 +461,19 @@ SoupServerMessageClass
-soup-message-queue -SoupMessageQueueIter -soup_message_queue_new -soup_message_queue_append -soup_message_queue_first -soup_message_queue_next -soup_message_queue_remove -soup_message_queue_free_iter -soup_message_queue_destroy -soup_message_queue_remove_message -
- -
-soup-md5-utils -SoupMD5Context -soup_md5_init -soup_md5_update -soup_md5_final -
- -
-soup-server-auth -SoupServerAuthCallbackFn -soup_server_auth_context_challenge -SoupAuthType -SoupServerAuthBasic -SoupDigestAlgorithm -SoupServerAuthDigest -soup_server_auth_new -soup_server_auth_free -soup_server_auth_get_user -soup_server_auth_check_passwd -
- -
soup-dns -soup_dns_entry_from_name -soup_dns_entry_from_addr -soup_dns_entry_check_lookup -soup_dns_entry_cancel_lookup -soup_dns_free_hostent +soup_dns_init soup_dns_ntop -
- -
-soup-headers -soup_headers_parse_request -soup_headers_parse_status_line -soup_headers_parse_response -soup_header_param_decode_token -soup_header_param_parse_list -soup_header_param_copy_token -soup_header_param_destroy_hash +SoupDNSLookup +soup_dns_lookup_name +soup_dns_lookup_address +soup_dns_lookup_resolve +SoupDNSCallback +soup_dns_lookup_resolve_async +soup_dns_lookup_cancel +soup_dns_lookup_get_hostname +soup_dns_lookup_get_address +soup_dns_lookup_free
@@ -422,10 +484,14 @@ soup_ssl_free_client_credentials soup_ssl_get_server_credentials soup_ssl_free_server_credentials soup_ssl_wrap_iochannel +SOUP_SSL_ERROR +soup_ssl_error_quark +SoupSocketError
soup-uri +SoupUri SoupProtocol SOUP_PROTOCOL_HTTP SOUP_PROTOCOL_HTTPS @@ -442,47 +508,17 @@ soup_uri_uses_default_port
-soup-message-private -soup_message_run_handlers -soup_message_cleanup -soup_message_cleanup_response -SoupMessageGetHeadersFn -SoupMessageParseHeadersFn -soup_message_io_client -soup_message_io_server -
- -
-soup-method -SOUP_METHOD_POST -SOUP_METHOD_GET -SOUP_METHOD_HEAD -SOUP_METHOD_OPTIONS -SOUP_METHOD_PUT -SOUP_METHOD_MOVE -SOUP_METHOD_COPY -SOUP_METHOD_DELETE -SOUP_METHOD_TRACE -SOUP_METHOD_CONNECT -SOUP_METHOD_MKCOL -SOUP_METHOD_PROPPATCH -SOUP_METHOD_PROPFIND -SOUP_METHOD_PATCH -SOUP_METHOD_LOCK -SOUP_METHOD_UNLOCK -SoupMethodId -soup_method_get_id -
- -
-soup-misc -soup_base64_encode -soup_base64_encode_close -soup_base64_encode_step -soup_base64_decode -soup_base64_decode_step -soup_signal_connect_once -soup_str_case_hash -soup_str_case_equal -soup_ssl_supported +soup-message-filter +SoupMessageFilter +soup_message_filter_setup_message + +SOUP_IS_MESSAGE_FILTER +SOUP_IS_MESSAGE_FILTER_CLASS +SOUP_MESSAGE_FILTER +SOUP_MESSAGE_FILTER_CLASS +SOUP_MESSAGE_FILTER_GET_CLASS +SOUP_MESSAGE_FILTER_GET_CLASS +SOUP_TYPE_MESSAGE_FILTER +SoupMessageFilterClass +soup_message_filter_get_type
diff --git a/docs/reference/libsoup.types b/docs/reference/libsoup.types index 87cf608..df628db 100644 --- a/docs/reference/libsoup.types +++ b/docs/reference/libsoup.types @@ -5,10 +5,14 @@ #include #include #include +#include #include #include #include +#include +#include #include +#include #include soup_address_get_type @@ -18,9 +22,13 @@ soup_auth_digest_get_type soup_connection_get_type soup_connection_ntlm_get_type soup_message_get_type +soup_message_filter_get_type soup_server_message_get_type soup_server_get_type soup_session_get_type +soup_session_sync_get_type +soup_session_async_get_type soup_soap_message_get_type +soup_soap_response_get_type soup_socket_get_type diff --git a/docs/reference/tmpl/libsoup-unused.sgml b/docs/reference/tmpl/libsoup-unused.sgml index ab933b6..fd309be 100644 --- a/docs/reference/tmpl/libsoup-unused.sgml +++ b/docs/reference/tmpl/libsoup-unused.sgml @@ -1,195 +1,575 @@ - + +This implements the Basic HTTP Authentication mechanism, as described +in RFC 2617. It is created automatically by #SoupSession when needed. + + + + + + + + + + +HTTP Basic Authentication + + +SoupAuthBasic + + + + +This implements the Digest HTTP Authentication mechanism, as described +in RFC 2617. It is created automatically by #SoupSession when needed. - + - + +HTTP Digest Authentication + +SoupAuthDigest - -soup-marshal + + + + + - + - + +MD5 hash utilities + + + +soup-md5-utils + + + - + + + + + + - -SoupSocketSSL + +soup-message-private - + + + +#SoupMessageQueue maintains the queue of pending messages in a +#SoupSession. + + + + - + +Message queue object + + + +soup-message-queue + + + - + + + + + + +Miscellaneous functions - -soup-types + +soup-misc - + - + - + +Server-side authentication structures + +soup-server-auth - -soup + + + + + +@SOUP_AUTH_TYPE_BASIC: +@SOUP_AUTH_TYPE_DIGEST: + + + + + + +@SOUP_ALGORITHM_MD5: +@SOUP_ALGORITHM_MD5_SESS: - + -@l: -@t: -@ci: -@i: -@parent: - + +@msg: +@headers: +@encoding: +@user_data: - + +@msg: +@headers: +@header_len: +@encoding: +@content_len: +@user_data: +@Returns: - + - + - + +@type: +@user: +@passwd: - + +@auth_ctx: +@auth: +@msg: +@data: +@Returns: - + +@types: +@callback: +@user_data: - + +@type: +@algorithm: +@integrity: +@realm: +@user: +@nonce: +@nonce_count: +@cnonce: +@digest_uri: +@digest_response: +@request_method: + + + + + - +@text: +@out_len: +@Returns: + + -@closure: -@return_value: -@n_param_values: -@param_values: -@invocation_hint: -@marshal_data: +@in: +@len: +@out: +@state: +@save: +@Returns: - + +@text: +@len: +@Returns: - + -@msg: -@req: +@in: +@inlen: +@break_lines: +@out: +@state: +@save: +@Returns: - + + + + + +@in: +@len: +@break_lines: +@out: +@state: +@save: +@Returns: + + + + + + +@ctx: +@digest: + + + + + + +@ctx: + + + + + + +@ctx: +@buf: +@len: + + @req: - + + + + + +@msg: + + + + + + +@msg: + + + + + + +@msg: + + + + + + +@msg: + + @msg: - + + + + + +@msg: +@sock: +@get_headers_cb: +@parse_headers_cb: +@user_data: + + + + + + +@msg: +@sock: +@get_headers_cb: +@parse_headers_cb: +@user_data: + + + + + + +@queue: +@msg: + + + + + + +@queue: + + + + + + +@queue: +@iter: +@Returns: + + + + + + +@queue: +@iter: + + + + + + +@Returns: + + + + + + +@queue: +@iter: +@Returns: + + + + + + +@queue: +@iter: +@Returns: + + + + + + +@queue: +@msg: + + + + + + +@msg: + + + + + + +@msg: +@phase: + + + + + + +@msg: + + + + + + +@msg: + + + + + + +@msg: + + + + + + +@msg: + + + + + + +@auth: +@passwd: +@Returns: + + + + + + +@auth_ctx: +@msg: +@header_name: + + + + + + +@auth: + + + + + + +@auth: +@Returns: + + + + + + +@auth_ctx: +@auth_hdrs: +@msg: +@Returns: + + + + + + +@instance: +@detailed_signal: +@c_handler: +@data: +@Returns: + + + + + + + + +@v1: +@v2: @Returns: - + -@optname1: -@Varargs: +@key: @Returns: diff --git a/docs/reference/tmpl/soup-address.sgml b/docs/reference/tmpl/soup-address.sgml index edc6944..0db6ca9 100644 --- a/docs/reference/tmpl/soup-address.sgml +++ b/docs/reference/tmpl/soup-address.sgml @@ -21,21 +21,31 @@ IPv4 and IPv6 addresses. + + + + + + + + + + + +@addr: +@status: + -The supported address families. Note that the -%SOUP_ADDRESS_FAMILY_IPV6 constant is available even if libsoup was -built without IPv6 support, but attempting to create an IPv6 address -will fail in that case. + -@SOUP_ADDRESS_FAMILY_IPV4: an IPv4 address -@SOUP_ADDRESS_FAMILY_IPV6: an IPv6 address +@SOUP_ADDRESS_FAMILY_IPV4: +@SOUP_ADDRESS_FAMILY_IPV6: -This can be passed to any #SoupAddress method that expects a port to -indicate that you don't care what port is used. + @@ -72,12 +82,12 @@ indicate that you don't care what port is used. -The callback function passed to soup_address_resolve_async(). + -@addr: the #SoupAddress that was resolved -@status: %SOUP_STATUS_OK or %SOUP_STATUS_CANT_RESOLVE -@data: the user data that was passed to soup_address_resolve_async() +@addr: +@status: +@data: @@ -108,6 +118,16 @@ The callback function passed to soup_address_resolve_async(). @Returns: + + + + + +@addr: +@len: +@Returns: + + diff --git a/docs/reference/tmpl/soup-auth-basic.sgml b/docs/reference/tmpl/soup-auth-basic.sgml deleted file mode 100644 index 5beb539..0000000 --- a/docs/reference/tmpl/soup-auth-basic.sgml +++ /dev/null @@ -1,23 +0,0 @@ - -SoupAuthBasic - - -HTTP Basic Authentication - - - -This implements the Basic HTTP Authentication mechanism, as described -in RFC 2617. - - - - - - - - - - - - - diff --git a/docs/reference/tmpl/soup-auth-digest.sgml b/docs/reference/tmpl/soup-auth-digest.sgml deleted file mode 100644 index af0f0c1..0000000 --- a/docs/reference/tmpl/soup-auth-digest.sgml +++ /dev/null @@ -1,23 +0,0 @@ - -SoupAuthDigest - - -HTTP Digest Authentication - - - -This implements the Digest HTTP Authentication mechanism, as described -in RFC 2617. - - - - - - - - - - - - - diff --git a/docs/reference/tmpl/soup-auth.sgml b/docs/reference/tmpl/soup-auth.sgml index 5fb0bd9..6108b77 100644 --- a/docs/reference/tmpl/soup-auth.sgml +++ b/docs/reference/tmpl/soup-auth.sgml @@ -11,21 +11,29 @@ given bit of webspace. They are created and maintained automatically by #SoupSession. + -#SoupAuth itself is an abstract class. Specific HTTP Authentication -mechanisms are implemented by its subclasses. (NTLM authentication, -which works quite differently from normal HTTP authentication, is -handled by #SoupConnectionNTLM.) +#SoupSession, #SoupConnectionNTLM - + -SoupAuthBasic, SoupAuthDigest, SoupSession, SoupConnectionNTLM +The abstract base class for handling authentication. Specific HTTP +Authentication mechanisms are implemented by its subclasses. (NTLM +authentication, which works quite differently from normal HTTP +authentication, is handled by #SoupConnectionNTLM.) - + + +An object representing Basic HTTP authentication. + + + + +An object representing Digest HTTP authentication. @@ -34,7 +42,7 @@ SoupAuthBasic, SoupAuthDigest, SoupSession, SoupConnectionNTLM -@header: +@vals: @Returns: diff --git a/docs/reference/tmpl/soup-connection-ntlm.sgml b/docs/reference/tmpl/soup-connection-ntlm.sgml index b4e9794..7c749fc 100644 --- a/docs/reference/tmpl/soup-connection-ntlm.sgml +++ b/docs/reference/tmpl/soup-connection-ntlm.sgml @@ -2,11 +2,12 @@ SoupConnectionNTLM - +NTLM-authenticated connection - +#SoupSession automatically creates #SoupConnectionNTLM rather than +#SoupConnection if you set the %SOUP_SESSION_USE_NTLM flag. diff --git a/docs/reference/tmpl/soup-connection.sgml b/docs/reference/tmpl/soup-connection.sgml index 9cb5e6c..cfcfb89 100644 --- a/docs/reference/tmpl/soup-connection.sgml +++ b/docs/reference/tmpl/soup-connection.sgml @@ -2,11 +2,13 @@ SoupConnection - +a single possibly-persistent HTTP connection - +#SoupConnection represents a single connection to an HTTP server +(possibly via a proxy). Connection objects are created and destroyed +automatically by #SoupSession. @@ -14,26 +16,70 @@ SoupConnection - + + + - + + +@conn: +@msg: +@auth_type: +@auth_realm: +@username: +@password: + + +@conn: +@status: + + + + - +@conn: + + +@conn: +@msg: +@auth_type: +@auth_realm: +@username: +@password: + + + + + + + + + + + + + + + + + + + @@ -47,12 +93,12 @@ SoupConnection -The callback function passed to soup_connection_connect_async(). + -@conn: the #SoupConnection -@status: an HTTP status code indicating success or failure -@data: the data passed to soup_connection_connect_async() +@conn: +@status: +@data: @@ -63,8 +109,6 @@ The callback function passed to soup_connection_connect_async(). @conn: @callback: @user_data: - -@Param2: @@ -137,3 +181,47 @@ The callback function passed to soup_connection_connect_async(). @password: + + + + + +@conn: + + + + + + + +@conn: + + + + +An alias for the "origin-uri" property. + + + + + + +An alias for the "proxy-uri" property. + + + + + + +An alias for the "ssl-creds" property. + + + + + + +An alias for the "message-filter" property. + + + + diff --git a/docs/reference/tmpl/soup-dns.sgml b/docs/reference/tmpl/soup-dns.sgml index 8bef2e9..db9d9c7 100644 --- a/docs/reference/tmpl/soup-dns.sgml +++ b/docs/reference/tmpl/soup-dns.sgml @@ -14,7 +14,31 @@ Low-level DNS routines - + + + + + + + + + + + + +@sa: +@Returns: + +@address: + + + + + + + + + @@ -23,48 +47,77 @@ Low-level DNS routines @Returns: - + -@addr: -@family: +@sockaddr: @Returns: + +@address: - + -@entry: +@lookup: @Returns: - + -@entry: +@lookup: +@success: +@user_data: - + -@h: +@lookup: +@callback: +@user_data: - + -@addr: -@family: +@lookup: + + + + + + + +@lookup: @Returns: + + + + + +@lookup: +@Returns: + + + + + + + +@lookup: + + diff --git a/docs/reference/tmpl/soup-headers.sgml b/docs/reference/tmpl/soup-headers.sgml deleted file mode 100644 index cec103b..0000000 --- a/docs/reference/tmpl/soup-headers.sgml +++ /dev/null @@ -1,92 +0,0 @@ - -soup-headers - - - - - - - - - - - - - - - - - - - -@str: -@len: -@dest: -@req_method: -@req_path: -@ver: -@Returns: - - - - - - - -@status_line: -@ver: -@status_code: -@status_phrase: -@Returns: - - - - - - - -@str: -@len: -@dest: -@ver: -@status_code: -@status_phrase: -@Returns: - - - - - - - -@in: -@Returns: - - - - - - - -@header: -@Returns: - - - - - - - -@tokens: -@t: -@Returns: - - - - - - - -@table: - - diff --git a/docs/reference/tmpl/soup-marshal.sgml b/docs/reference/tmpl/soup-marshal.sgml deleted file mode 100644 index ba76427..0000000 --- a/docs/reference/tmpl/soup-marshal.sgml +++ /dev/null @@ -1,78 +0,0 @@ - -soup-marshal - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@closure: -@return_value: -@n_param_values: -@param_values: -@invocation_hint: -@marshal_data: - - - - - - - - - diff --git a/docs/reference/tmpl/soup-md5-utils.sgml b/docs/reference/tmpl/soup-md5-utils.sgml index 7fd75d0..afb42b2 100644 --- a/docs/reference/tmpl/soup-md5-utils.sgml +++ b/docs/reference/tmpl/soup-md5-utils.sgml @@ -2,7 +2,7 @@ soup-md5-utils - +MD5 hash utilities @@ -19,10 +19,6 @@ soup-md5-utils -@buf: -@bits: -@in: -@doByteReverse: diff --git a/docs/reference/tmpl/soup-types.sgml b/docs/reference/tmpl/soup-message-filter.sgml similarity index 69% rename from docs/reference/tmpl/soup-types.sgml rename to docs/reference/tmpl/soup-message-filter.sgml index 02ad055..c1bbe1b 100644 --- a/docs/reference/tmpl/soup-types.sgml +++ b/docs/reference/tmpl/soup-message-filter.sgml @@ -1,5 +1,5 @@ -soup-types +SoupMessageFilter @@ -14,15 +14,12 @@ soup-types - + -@l: -@t: -@ci: -@i: -@parent: +@filter: +@msg: diff --git a/docs/reference/tmpl/soup-message-queue.sgml b/docs/reference/tmpl/soup-message-queue.sgml index 0abe873..468f0d6 100644 --- a/docs/reference/tmpl/soup-message-queue.sgml +++ b/docs/reference/tmpl/soup-message-queue.sgml @@ -2,11 +2,12 @@ soup-message-queue - +Message queue object - +#SoupMessageQueue maintains the queue of pending messages in a +#SoupSession. @@ -14,10 +15,15 @@ soup-message-queue + + + + + + -An opaque data structure used to iterate the elements of a -#SoupMessageQueue. + diff --git a/docs/reference/tmpl/soup-message.sgml b/docs/reference/tmpl/soup-message.sgml index 97706bd..33b6ed3 100644 --- a/docs/reference/tmpl/soup-message.sgml +++ b/docs/reference/tmpl/soup-message.sgml @@ -2,7 +2,7 @@ SoupMessage - +An HTTP request and response. @@ -14,70 +14,145 @@ SoupMessage + + + + + +@method: +@status_code: +@reason_phrase: +@request: +@request_headers: +@response: +@response_headers: +@status: + + + + + + +@msg: + + + + + + +@msg: + + + + + + +@msg: + + + + + + +@msg: + + + + + + +@msg: + + + + + + +@msg: + + + + + + +@msg: + + + + + + +@msg: + + + + + + +@msg: + + + + + + +@msg: + -Enum indicating the lifecycle of a #SoupMessage. + -@SOUP_MESSAGE_STATUS_IDLE: The message has not yet been queued. -@SOUP_MESSAGE_STATUS_QUEUED: The message has been queued, but is -waiting for a connection to be available. -@SOUP_MESSAGE_STATUS_CONNECTING: The message is waiting for a specific -connection to finish connecting. -@SOUP_MESSAGE_STATUS_RUNNING: The message is being processed. -@SOUP_MESSAGE_STATUS_FINISHED: The message is complete (request and -response both processed). +@SOUP_MESSAGE_STATUS_IDLE: +@SOUP_MESSAGE_STATUS_QUEUED: +@SOUP_MESSAGE_STATUS_CONNECTING: +@SOUP_MESSAGE_STATUS_RUNNING: +@SOUP_MESSAGE_STATUS_FINISHED: -Tests if @msg is in a "starting" state, waiting to be sent. (More -commonly used to test if a message has been requeued after its first -attempt.) + -@msg: a #SoupMessage -@Returns: %TRUE if @msg is waiting to be sent. +@msg: +@Returns: -How the length of a request or response is to be encoded. + -@SOUP_TRANSFER_UNKNOWN: HTTP 1.0-style (content ends when the -connection is closed) -@SOUP_TRANSFER_CHUNKED: chunked encoding (only supported for response) -@SOUP_TRANSFER_CONTENT_LENGTH: Content-Length +@SOUP_TRANSFER_UNKNOWN: +@SOUP_TRANSFER_CHUNKED: +@SOUP_TRANSFER_CONTENT_LENGTH: -Used by #SoupDataBuffer (and several functions) to indicate the -ownership of a buffer. + -@SOUP_BUFFER_SYSTEM_OWNED: The data is owned by soup and it can free -it when it is done with it. -@SOUP_BUFFER_USER_OWNED: The data is owned by the user, who is -responsible for freeing it at the right point -@SOUP_BUFFER_STATIC: The data should not be freed. +@SOUP_BUFFER_SYSTEM_OWNED: +@SOUP_BUFFER_USER_OWNED: +@SOUP_BUFFER_STATIC: -A data buffer used in several places. + -@owner: the ownership of the data -@body: the data itself -@length: length of @body +@owner: +@body: +@length: -A callback function used by many #SoupMessage methods. + -@req: the #SoupMessage in question -@user_data: user data +@req: +@user_data: @@ -88,8 +163,6 @@ A callback function used by many #SoupMessage methods. @method: @uri_string: @Returns: - -@uri: @@ -112,8 +185,6 @@ A callback function used by many #SoupMessage methods. @req_owner: @req_body: @req_length: - -@req_len: @@ -126,8 +197,6 @@ A callback function used by many #SoupMessage methods. @resp_owner: @resp_body: @resp_length: - -@resp_len: @@ -189,11 +258,11 @@ A callback function used by many #SoupMessage methods. -Indicates the HTTP protocol version being used. + -@SOUP_HTTP_1_0: HTTP 1.0 (RFC 1945) -@SOUP_HTTP_1_1: HTTP 1.1 (RFC 2616) +@SOUP_HTTP_1_0: +@SOUP_HTTP_1_1: @@ -213,15 +282,6 @@ Indicates the HTTP protocol version being used. @Returns: - - - - - -@msg: -@Returns: - - @@ -242,19 +302,12 @@ Indicates the HTTP protocol version being used. -Various flags that can be set on a #SoupMessage to alter its behavior. + -@SOUP_MESSAGE_NO_REDIRECT: The session should not follow redirect -(3xx) responses received by this message. -@SOUP_MESSAGE_OVERWRITE_CHUNKS: Rather than building up the response -body in %response, each new chunk should overwrite the previous one. -(This can be used if you are connecting to the %got_chunk signal or -have installed a %SOUP_MESSAGE_BODY_CHUNK handler.) -@SOUP_MESSAGE_EXPECT_CONTINUE: This will cause an "Expect: -100-continue" header to be added to the outgoing request, giving the -server the opportunity to reject the message (eg, with a 401 -Unauthorized) before the full request body is sent. +@SOUP_MESSAGE_NO_REDIRECT: +@SOUP_MESSAGE_OVERWRITE_CHUNKS: +@SOUP_MESSAGE_EXPECT_CONTINUE: @@ -274,79 +327,6 @@ Unauthorized) before the full request body is sent. @Returns: - - -Indicates when a handler added with soup_message_add_handler() or the -like will be run. - - -@SOUP_HANDLER_POST_REQUEST: The handler should run immediately after -sending the request body -@SOUP_HANDLER_PRE_BODY: The handler should run before reading the -response body (after reading the headers). -@SOUP_HANDLER_BODY_CHUNK: The handler should run after every body -chunk is read. (See also %SOUP_MESSAGE_OVERWRITE_CHUNKS.) -@SOUP_HANDLER_POST_BODY: The handler should run after the entire -message body has been read. - - - - - - -@msg: -@type: -@handler_cb: -@user_data: - - - - - - - -@msg: -@header: -@type: -@Param4: -@user_data: - - - - - - - -@msg: -@status_code: -@type: -@Param4: -@user_data: - - - - - - - -@msg: -@status_class: -@type: -@Param4: -@user_data: - - - - - - - -@msg: -@type: -@Param3: -@user_data: - - @@ -394,90 +374,103 @@ message body has been read. @Returns: - - - - - -@req: -@sock: -@via_proxy: - - - + -@req: -@sock: +@msg: +@Returns: - + -@msg: - +@SOUP_HANDLER_POST_REQUEST: +@SOUP_HANDLER_PRE_BODY: +@SOUP_HANDLER_BODY_CHUNK: +@SOUP_HANDLER_POST_BODY: - + @msg: +@phase: +@handler_cb: +@user_data: - + @msg: +@header: +@phase: +@handler_cb: +@user_data: - + @msg: +@status_code: +@phase: +@handler_cb: +@user_data: - + @msg: +@status_class: +@phase: +@handler_cb: +@user_data: - + @msg: +@phase: +@handler_cb: +@user_data: - + -@msg: +@req: +@sock: +@is_via_proxy: - + -@msg: +@req: +@sock: - + @@ -485,7 +478,7 @@ message body has been read. @msg: - + @@ -493,7 +486,7 @@ message body has been read. @msg: - + diff --git a/docs/reference/tmpl/soup-method.sgml b/docs/reference/tmpl/soup-method.sgml deleted file mode 100644 index e6c6bb3..0000000 --- a/docs/reference/tmpl/soup-method.sgml +++ /dev/null @@ -1,165 +0,0 @@ - -soup-method - - -HTTP method-related defines. - - - -These can be used if you don't want to specify the HTTP method to -soup_message_new() as an explicit string. This is purely a stylistic -consideration. There is no difference between using the define and -the string itself. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -This enumeration is used internally by routines that need to check the -HTTP method in a #SoupMessage against several different possibilities, -to avoid repeated strcmp()s. - - -@SOUP_METHOD_ID_UNKNOWN: -@SOUP_METHOD_ID_POST: -@SOUP_METHOD_ID_GET: -@SOUP_METHOD_ID_HEAD: -@SOUP_METHOD_ID_OPTIONS: -@SOUP_METHOD_ID_PUT: -@SOUP_METHOD_ID_MOVE: -@SOUP_METHOD_ID_COPY: -@SOUP_METHOD_ID_DELETE: -@SOUP_METHOD_ID_TRACE: -@SOUP_METHOD_ID_CONNECT: -@SOUP_METHOD_ID_MKCOL: -@SOUP_METHOD_ID_PROPPATCH: -@SOUP_METHOD_ID_PROPFIND: -@SOUP_METHOD_ID_PATCH: -@SOUP_METHOD_ID_LOCK: -@SOUP_METHOD_ID_UNLOCK: - - - - - - -@method: -@Returns: - - diff --git a/docs/reference/tmpl/soup-misc.sgml b/docs/reference/tmpl/soup-misc.sgml index c7fb37c..8bb7f42 100644 --- a/docs/reference/tmpl/soup-misc.sgml +++ b/docs/reference/tmpl/soup-misc.sgml @@ -2,7 +2,7 @@ soup-misc - +Miscellaneous functions @@ -85,8 +85,6 @@ soup-misc @c_handler: @data: @Returns: - -@signal: diff --git a/docs/reference/tmpl/soup-server-auth.sgml b/docs/reference/tmpl/soup-server-auth.sgml index 2497ce4..cbe22e3 100644 --- a/docs/reference/tmpl/soup-server-auth.sgml +++ b/docs/reference/tmpl/soup-server-auth.sgml @@ -2,7 +2,7 @@ soup-server-auth - +Server-side authentication structures @@ -14,6 +14,15 @@ soup-server-auth + + + + + +@types: +@callback: +@user_data: + diff --git a/docs/reference/tmpl/soup-server-message.sgml b/docs/reference/tmpl/soup-server-message.sgml index 09bb7b8..ec03fde 100644 --- a/docs/reference/tmpl/soup-server-message.sgml +++ b/docs/reference/tmpl/soup-server-message.sgml @@ -2,7 +2,7 @@ SoupServerMessage - +Server-side #SoupMessage @@ -14,6 +14,12 @@ SoupServerMessage + + + + + + diff --git a/docs/reference/tmpl/soup-server.sgml b/docs/reference/tmpl/soup-server.sgml index 11436c1..0f6ecb2 100644 --- a/docs/reference/tmpl/soup-server.sgml +++ b/docs/reference/tmpl/soup-server.sgml @@ -2,11 +2,16 @@ SoupServer - +HTTP server +#SoupServer implements a simple HTTP server. + + +This API is less stable than the soup client API, and will most likely +change in the next release. @@ -14,65 +19,63 @@ SoupServer - + -@msg: -@path: -@method_id: -@auth: -@server: -@handler: -@sock: - + -@context: -@msg: -@user_data: - - - + -@server: -@handler: -@user_data: - - - + + + + - + +@msg: +@path: +@method_id: +@auth: +@server: +@handler: +@sock: - - + +@context: +@msg: +@user_data: - + +@server: +@handler: +@user_data: @@ -127,6 +130,12 @@ SoupServer @serv: + + + + + + @@ -186,3 +195,31 @@ SoupServer @Returns: + + +An alias for the "port" property. + + + + + + +An alias for the "interface" property. + + + + + + +An alias for the "ssl-cert-file" property. + + + + + + +An alias for the "ssl-key-file" property. + + + + diff --git a/docs/reference/tmpl/soup-session-async.sgml b/docs/reference/tmpl/soup-session-async.sgml new file mode 100644 index 0000000..05a9076 --- /dev/null +++ b/docs/reference/tmpl/soup-session-async.sgml @@ -0,0 +1,42 @@ + +SoupSessionAsync + + +Soup session for asynchronous (main-loop-based) I/O. + + + +#SoupSessionASync is an implementation of #SoupSession that uses +non-blocking I/O via the glib main loop. It is intended for use in +single-threaded programs. + + + + + + + + + + + + + + + + + + +@Returns: + + + + + + + +@optname1: +@Varargs: +@Returns: + + diff --git a/docs/reference/tmpl/soup-session-sync.sgml b/docs/reference/tmpl/soup-session-sync.sgml new file mode 100644 index 0000000..65398c1 --- /dev/null +++ b/docs/reference/tmpl/soup-session-sync.sgml @@ -0,0 +1,46 @@ + +SoupSessionSync + + +Soup session for blocking I/O in multithreaded programs. + + + +#SoupSessionSync is an implementation of #SoupSession that uses +synchronous I/O, intended for use in multi-threaded programs. + + + +Note that you cannot use soup_session_queue_message() with a +synchronous session. You can only use soup_session_send_message(). + + + + + + + + + + + + + + + + + + +@Returns: + + + + + + + +@optname1: +@Varargs: +@Returns: + + diff --git a/docs/reference/tmpl/soup-session.sgml b/docs/reference/tmpl/soup-session.sgml index 1f6c9b1..eb71603 100644 --- a/docs/reference/tmpl/soup-session.sgml +++ b/docs/reference/tmpl/soup-session.sgml @@ -2,7 +2,7 @@ SoupSession - +Soup session state object @@ -14,40 +14,60 @@ SoupSession - + - - + +@session: +@msg: +@auth_type: +@auth_realm: +@username: +@password: - - + +@session: +@msg: +@auth_type: +@auth_realm: +@username: +@password: + + + + - + + + + - + + + + @@ -58,8 +78,6 @@ SoupSession @msg: @callback: @user_data: - -@req: @@ -69,8 +87,6 @@ SoupSession @session: @msg: - -@req: @@ -81,8 +97,6 @@ SoupSession @session: @msg: @Returns: - -@req: @@ -93,3 +107,86 @@ SoupSession @session: + + + + + +@session: +@filter: + + + + + + + +@session: +@msg: + + + + + + + +@session: +@msg: +@try_pruning: +@is_new: +@Returns: + + + + + + + +@session: +@filter: + + + + + + + +@session: +@Returns: + + + + +An alias for the "proxy-uri" property. + + + + + + +An alias for the "max-conns" property. + + + + + + +An alias for the "max-conns-per-host" property. + + + + + + +An alias for the "use-ntlm" property. + + + + + + +An alias for the "ssl-ca-file" property. + + + + diff --git a/docs/reference/tmpl/soup-soap-message.sgml b/docs/reference/tmpl/soup-soap-message.sgml index f6f3666..48493a3 100644 --- a/docs/reference/tmpl/soup-soap-message.sgml +++ b/docs/reference/tmpl/soup-soap-message.sgml @@ -2,7 +2,7 @@ SoupSoapMessage - +A SOAP request/response @@ -177,6 +177,8 @@ SoupSoapMessage @msg: +@i: + @Param2: @@ -319,3 +321,12 @@ SoupSoapMessage @Returns: + + + + + +@msg: +@Returns: + + diff --git a/docs/reference/tmpl/soup-soap-response.sgml b/docs/reference/tmpl/soup-soap-response.sgml new file mode 100644 index 0000000..d4cbbaa --- /dev/null +++ b/docs/reference/tmpl/soup-soap-response.sgml @@ -0,0 +1,197 @@ + +SoupSoapResponse + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +@Returns: + + + + + + + +@xmlstr: +@Returns: + + + + + + + +@response: +@method_name: + + + + + + + +@param: +@Returns: + + + + + + + +@param: +@name: +@Returns: + + + + + + + +@param: +@Returns: + + + + + + + +@param: +@Returns: + + + + + + + +@param: +@Returns: + + + + + + + +@param: +@name: +@Returns: + + + + + + + +@param: +@prop_name: +@Returns: + + + + + + + +@param: +@Returns: + + + + + + + +@response: +@xmlstr: +@Returns: + + + + + + + +@response: +@Returns: + + + + + + + +@response: +@name: +@Returns: + + + + + + + +@response: +@Returns: + + + + + + + +@response: +@from: +@Returns: + + + + + + + +@response: +@from: +@name: +@Returns: + + + + + + + +@response: +@Returns: + + diff --git a/docs/reference/tmpl/soup-socket.sgml b/docs/reference/tmpl/soup-socket.sgml index 8a6389a..78ea20c 100644 --- a/docs/reference/tmpl/soup-socket.sgml +++ b/docs/reference/tmpl/soup-socket.sgml @@ -2,7 +2,7 @@ SoupSocket - +a network socket @@ -14,40 +14,73 @@ SoupSocket - + + + - + + +@sock: +@status: + + +@sock: + + + + - +@sock: +@new: + + +@sock: + + - + + +@sock: + + + + + - + + + + + + + + + @@ -67,8 +100,6 @@ SoupSocket @sock: @remote_addr: @Returns: - -@rem_addr: @@ -90,6 +121,16 @@ SoupSocket @Returns: + + + + + +@sock: +@ssl_host: +@Returns: + + @@ -109,25 +150,22 @@ SoupSocket -The callback function passed to soup_socket_client_new_async(). + -@sock: the #SoupSocket -@status: an HTTP status code indicating success or failure +@sock: +@status: @user_data: - -@data: the data passed to soup_socket_client_new_async() -The callback function passed to soup_socket_server_new(), which -receives new connections. + -@listener: the listening #SoupSocket -@sock: the newly-received #SoupSocket -@user_data: the data passed to soup_socket_server_new(). +@listener: +@sock: +@user_data: @@ -153,8 +191,6 @@ receives new connections. @ssl_creds: @status_ret: @Returns: - -@status: @@ -167,8 +203,6 @@ receives new connections. @callback: @user_data: @Returns: - -@Param3: @@ -191,13 +225,13 @@ receives new connections. -Return value from the #SoupSocket IO methods. + -@SOUP_SOCKET_OK: Success -@SOUP_SOCKET_WOULD_BLOCK: Cannot read/write any more at this time -@SOUP_SOCKET_EOF: End of file -@SOUP_SOCKET_ERROR: Other error +@SOUP_SOCKET_OK: +@SOUP_SOCKET_WOULD_BLOCK: +@SOUP_SOCKET_EOF: +@SOUP_SOCKET_ERROR: @@ -238,3 +272,38 @@ Return value from the #SoupSocket IO methods. @Returns: + + +An alias for the "non-blocking" property. + + + + + + +An alias for the "nodelay" property. + + + + + + +An alias for the "reuseaddr" property. + + + + + + +An alias for the "is-server" property. + + + + + + +An alias for the "ssl-creds" property. + + + + diff --git a/docs/reference/tmpl/soup-ssl.sgml b/docs/reference/tmpl/soup-ssl.sgml index c8cedf7..d837f0c 100644 --- a/docs/reference/tmpl/soup-ssl.sgml +++ b/docs/reference/tmpl/soup-ssl.sgml @@ -2,7 +2,7 @@ soup-ssl - +SSL/TLS handling @@ -16,11 +16,11 @@ soup-ssl -What kind of SSL connection this is. + -@SOUP_SSL_TYPE_CLIENT: the client side of an SSL connection -@SOUP_SSL_TYPE_SERVER: the server side of an SSL connection +@SOUP_SSL_TYPE_CLIENT: +@SOUP_SSL_TYPE_SERVER: @@ -69,3 +69,27 @@ What kind of SSL connection this is. @Returns: + + + + + + + + + + + + +@Returns: + + + + + + + +@SOUP_SSL_ERROR_HANDSHAKE_NEEDS_READ: +@SOUP_SSL_ERROR_HANDSHAKE_NEEDS_WRITE: +@SOUP_SSL_ERROR_CERTIFICATE: + diff --git a/docs/reference/tmpl/soup-status.sgml b/docs/reference/tmpl/soup-status.sgml index 374a820..25f6d7f 100644 --- a/docs/reference/tmpl/soup-status.sgml +++ b/docs/reference/tmpl/soup-status.sgml @@ -16,136 +16,127 @@ HTTP and Soup status codes -The classes of HTTP and Soup status codes + -@SOUP_STATUS_CLASS_TRANSPORT_ERROR: Network or Soup-level error -@SOUP_STATUS_CLASS_INFORMATIONAL: HTTP 1xx response providing partial -information about the state of a request -@SOUP_STATUS_CLASS_SUCCESS: HTTP 2xx successful response -@SOUP_STATUS_CLASS_REDIRECT: HTTP 3xx redirection response -@SOUP_STATUS_CLASS_CLIENT_ERROR: HTTP 4xx client error response -@SOUP_STATUS_CLASS_SERVER_ERROR: HTTP 5xx server error response +@SOUP_STATUS_CLASS_TRANSPORT_ERROR: +@SOUP_STATUS_CLASS_INFORMATIONAL: +@SOUP_STATUS_CLASS_SUCCESS: +@SOUP_STATUS_CLASS_REDIRECT: +@SOUP_STATUS_CLASS_CLIENT_ERROR: +@SOUP_STATUS_CLASS_SERVER_ERROR: -Tests if @status is an Informational (1xx) response. + -@status: an HTTP status code -@Returns: %TRUE if @status is an Information (1xx) response. +@status: +@Returns: -Tests if @status is a Successful (2xx) response. + -@status: an HTTP status code -@Returns: %TRUE if @status is a Successful (2xx) response. +@status: +@Returns: -Tests if @status is a Redirection (3xx) response. + -@status: an HTTP status code -@Returns: %TRUE if @status is a Redirection (3xx) response. +@status: +@Returns: -Tests if @status is a Client Error (4xx) response. + -@status: an HTTP status code -@Returns: %TRUE if @status is a Client Error (4xx) response. +@status: +@Returns: -Tests if @status is a Server Error (5xx) response. + -@status: an HTTP status code -@Returns: %TRUE if @status is a Server Error (5xx) response. +@status: +@Returns: -These represent the known HTTP status code values, plus various -network and internal errors. + -@SOUP_STATUS_NONE: No status available. (Eg, the message has not been -sent yet) -@SOUP_STATUS_CANCELLED: Message was cancelled locally -@SOUP_STATUS_CANT_RESOLVE: Unable to resolve destination host name -@SOUP_STATUS_CANT_RESOLVE_PROXY: Unable to resolve proxy host name -@SOUP_STATUS_CANT_CONNECT: Unable to connect to remote host -@SOUP_STATUS_CANT_CONNECT_PROXY: Unable to connect to proxy -@SOUP_STATUS_SSL_FAILED: SSL negotiation failed -@SOUP_STATUS_IO_ERROR: A network error occurred, or the other end -closed the connection unexpectedly -@SOUP_STATUS_MALFORMED: Malformed data (usually a programmer error) -@SOUP_STATUS_TRY_AGAIN: Try again. (Only returned in certain -specifically documented cases) -@SOUP_STATUS_CONTINUE: 100 Continue (HTTP) -@SOUP_STATUS_SWITCHING_PROTOCOLS: 101 Switching Protocols (HTTP) -@SOUP_STATUS_PROCESSING: 102 Processing (WebDAV) -@SOUP_STATUS_OK: 200 Success (HTTP). Also used by many lower-level -soup routines to indicate success. -@SOUP_STATUS_CREATED: 201 Created (HTTP) -@SOUP_STATUS_ACCEPTED: 202 Accepted (HTTP) -@SOUP_STATUS_NON_AUTHORITATIVE: 203 Non-Authoritative Information (HTTP) -@SOUP_STATUS_NO_CONTENT: 204 No Content (HTTP) -@SOUP_STATUS_RESET_CONTENT: 205 Reset Content (HTTP) -@SOUP_STATUS_PARTIAL_CONTENT: 206 Partial Content (HTTP) -@SOUP_STATUS_MULTI_STATUS: 207 Multi-Status (WebDAV) -@SOUP_STATUS_MULTIPLE_CHOICES: 300 Multiple Choices (HTTP) -@SOUP_STATUS_MOVED_PERMANENTLY: 301 Moved Permanently (HTTP) -@SOUP_STATUS_FOUND: 302 Found (HTTP) -@SOUP_STATUS_MOVED_TEMPORARILY: 302 Moved Temporarily (old name, RFC 2068) -@SOUP_STATUS_SEE_OTHER: 303 See Other (HTTP) -@SOUP_STATUS_NOT_MODIFIED: 304 Not Modified (HTTP) -@SOUP_STATUS_USE_PROXY: 305 Use Proxy (HTTP) -@SOUP_STATUS_NOT_APPEARING_IN_THIS_PROTOCOL: 306 [Unused] (HTTP) -@SOUP_STATUS_TEMPORARY_REDIRECT: 307 Temporary Redirect (HTTP) -@SOUP_STATUS_BAD_REQUEST: 400 Bad Request (HTTP) -@SOUP_STATUS_UNAUTHORIZED: 401 Unauthorized (HTTP) -@SOUP_STATUS_PAYMENT_REQUIRED: 402 Payment Required (HTTP) -@SOUP_STATUS_FORBIDDEN: 403 Forbidden (HTTP) -@SOUP_STATUS_NOT_FOUND: 404 Not Found (HTTP) -@SOUP_STATUS_METHOD_NOT_ALLOWED: 405 Method Not Allowed (HTTP) -@SOUP_STATUS_NOT_ACCEPTABLE: 406 Not Acceptable (HTTP) -@SOUP_STATUS_PROXY_AUTHENTICATION_REQUIRED: 407 Proxy Authentication -Required (HTTP) -@SOUP_STATUS_PROXY_UNAUTHORIZED: shorter alias for %SOUP_STATUS_PROXY_AUTHENTICATION_REQUIRED -@SOUP_STATUS_REQUEST_TIMEOUT: 408 Request Timeout (HTTP) -@SOUP_STATUS_CONFLICT: 409 Conflict (HTTP) -@SOUP_STATUS_GONE: 410 Gone (HTTP) -@SOUP_STATUS_LENGTH_REQUIRED: 411 Length Required (HTTP) -@SOUP_STATUS_PRECONDITION_FAILED: 412 Precondition Failed (HTTP) -@SOUP_STATUS_REQUEST_ENTITY_TOO_LARGE: 413 Request Entity Too Large (HTTP) -@SOUP_STATUS_REQUEST_URI_TOO_LONG: 414 Request-URI Too Long (HTTP) -@SOUP_STATUS_UNSUPPORTED_MEDIA_TYPE: 415 Unsupported Media Type (HTTP) -@SOUP_STATUS_REQUESTED_RANGE_NOT_SATISFIABLE: 416 Requested Range Not -Satisfiable (HTTP) -@SOUP_STATUS_INVALID_RANGE: shorter alias for %SOUP_STATUS_REQUESTED_RANGE_NOT_SATISFIABLE -@SOUP_STATUS_EXPECTATION_FAILED: 417 Expectation Failed (HTTP) -@SOUP_STATUS_UNPROCESSABLE_ENTITY: 422 Unprocessable Entity (WebDAV) -@SOUP_STATUS_LOCKED: 423 Locked (WebDAV) -@SOUP_STATUS_FAILED_DEPENDENCY: 424 Failed Dependency (WebDAV) -@SOUP_STATUS_INTERNAL_SERVER_ERROR: 500 Internal Server Error (HTTP) -@SOUP_STATUS_NOT_IMPLEMENTED: 501 Not Implemented (HTTP) -@SOUP_STATUS_BAD_GATEWAY: 502 Bad Gateway (HTTP) -@SOUP_STATUS_SERVICE_UNAVAILABLE: 503 Service Unavailable (HTTP) -@SOUP_STATUS_GATEWAY_TIMEOUT: 504 Gateway Timeout (HTTP) -@SOUP_STATUS_HTTP_VERSION_NOT_SUPPORTED: 505 HTTP Version Not -Supported (HTTP) -@SOUP_STATUS_INSUFFICIENT_STORAGE: 507 Insufficient Storage (WebDAV) -@SOUP_STATUS_NOT_EXTENDED: 510 Not Extended (RFC 2774) +@SOUP_STATUS_NONE: +@SOUP_STATUS_CANCELLED: +@SOUP_STATUS_CANT_RESOLVE: +@SOUP_STATUS_CANT_RESOLVE_PROXY: +@SOUP_STATUS_CANT_CONNECT: +@SOUP_STATUS_CANT_CONNECT_PROXY: +@SOUP_STATUS_SSL_FAILED: +@SOUP_STATUS_IO_ERROR: +@SOUP_STATUS_MALFORMED: +@SOUP_STATUS_TRY_AGAIN: +@SOUP_STATUS_CONTINUE: +@SOUP_STATUS_SWITCHING_PROTOCOLS: +@SOUP_STATUS_PROCESSING: +@SOUP_STATUS_OK: +@SOUP_STATUS_CREATED: +@SOUP_STATUS_ACCEPTED: +@SOUP_STATUS_NON_AUTHORITATIVE: +@SOUP_STATUS_NO_CONTENT: +@SOUP_STATUS_RESET_CONTENT: +@SOUP_STATUS_PARTIAL_CONTENT: +@SOUP_STATUS_MULTI_STATUS: +@SOUP_STATUS_MULTIPLE_CHOICES: +@SOUP_STATUS_MOVED_PERMANENTLY: +@SOUP_STATUS_FOUND: +@SOUP_STATUS_MOVED_TEMPORARILY: +@SOUP_STATUS_SEE_OTHER: +@SOUP_STATUS_NOT_MODIFIED: +@SOUP_STATUS_USE_PROXY: +@SOUP_STATUS_NOT_APPEARING_IN_THIS_PROTOCOL: +@SOUP_STATUS_TEMPORARY_REDIRECT: +@SOUP_STATUS_BAD_REQUEST: +@SOUP_STATUS_UNAUTHORIZED: +@SOUP_STATUS_PAYMENT_REQUIRED: +@SOUP_STATUS_FORBIDDEN: +@SOUP_STATUS_NOT_FOUND: +@SOUP_STATUS_METHOD_NOT_ALLOWED: +@SOUP_STATUS_NOT_ACCEPTABLE: +@SOUP_STATUS_PROXY_AUTHENTICATION_REQUIRED: +@SOUP_STATUS_PROXY_UNAUTHORIZED: +@SOUP_STATUS_REQUEST_TIMEOUT: +@SOUP_STATUS_CONFLICT: +@SOUP_STATUS_GONE: +@SOUP_STATUS_LENGTH_REQUIRED: +@SOUP_STATUS_PRECONDITION_FAILED: +@SOUP_STATUS_REQUEST_ENTITY_TOO_LARGE: +@SOUP_STATUS_REQUEST_URI_TOO_LONG: +@SOUP_STATUS_UNSUPPORTED_MEDIA_TYPE: +@SOUP_STATUS_REQUESTED_RANGE_NOT_SATISFIABLE: +@SOUP_STATUS_INVALID_RANGE: +@SOUP_STATUS_EXPECTATION_FAILED: +@SOUP_STATUS_UNPROCESSABLE_ENTITY: +@SOUP_STATUS_LOCKED: +@SOUP_STATUS_FAILED_DEPENDENCY: +@SOUP_STATUS_INTERNAL_SERVER_ERROR: +@SOUP_STATUS_NOT_IMPLEMENTED: +@SOUP_STATUS_BAD_GATEWAY: +@SOUP_STATUS_SERVICE_UNAVAILABLE: +@SOUP_STATUS_GATEWAY_TIMEOUT: +@SOUP_STATUS_HTTP_VERSION_NOT_SUPPORTED: +@SOUP_STATUS_INSUFFICIENT_STORAGE: +@SOUP_STATUS_NOT_EXTENDED: diff --git a/docs/reference/tmpl/soup-uri.sgml b/docs/reference/tmpl/soup-uri.sgml index 5058ce6..48150ed 100644 --- a/docs/reference/tmpl/soup-uri.sgml +++ b/docs/reference/tmpl/soup-uri.sgml @@ -2,7 +2,7 @@ soup-uri - +URIs @@ -14,23 +14,37 @@ soup-uri + + + + + +@protocol: +@user: +@passwd: +@host: +@port: +@path: +@query: +@fragment: +@broken_encoding: + -#GQuark is used for SoupProtocol so that the protocol of a #SoupUri -can be tested quickly. + -This returns the #SoupProtocol value for "http". + -This returns the #SoupProtocol value for "https". + diff --git a/libsoup/soup-address.c b/libsoup/soup-address.c index da88fc5..2704e17 100644 --- a/libsoup/soup-address.c +++ b/libsoup/soup-address.c @@ -147,6 +147,15 @@ soup_address_class_init (SoupAddressClass *address_class) object_class->finalize = finalize; /* signals */ + + /** + * SoupAddress::dns-result: + * @addr: the #SoupAddress + * @status: the DNS status code + * + * Emitted when an address resolution completes. (This is used + * internally by soup_address_resolve_async() itself.) + **/ signals[DNS_RESULT] = g_signal_new ("dns_result", G_OBJECT_CLASS_TYPE (object_class), @@ -228,6 +237,17 @@ soup_address_new_from_sockaddr (struct sockaddr *sa, int len) } /** + * SoupAddressFamily: + * @SOUP_ADDRESS_FAMILY_IPV4: an IPv4 address + * @SOUP_ADDRESS_FAMILY_IPV6: an IPv6 address + * + * The supported address families. Note that the + * %SOUP_ADDRESS_FAMILY_IPV6 constant is available even if libsoup was + * built without IPv6 support, but attempting to create an IPv6 + * address will fail in that case. + **/ + +/** * soup_address_new_any: * @family: the address family * @port: the port number (usually %SOUP_ADDRESS_ANY_PORT) @@ -281,7 +301,7 @@ soup_address_get_name (SoupAddress *addr) * @len: return location for sockaddr length * * Returns the sockaddr associated with @addr, with its length in - * *@len. If the sockaddr is not yet know, returns %NULL. + * *@len. If the sockaddr is not yet known, returns %NULL. * * Return value: the sockaddr, or %NULL **/ diff --git a/libsoup/soup-address.h b/libsoup/soup-address.h index 5bc88aa..b27c20d 100644 --- a/libsoup/soup-address.h +++ b/libsoup/soup-address.h @@ -45,8 +45,27 @@ typedef enum { } SoupAddressFamily; #endif +/** + * SOUP_ADDRESS_ANY_PORT: + * + * This can be passed to any #SoupAddress method that expects a port, + * to indicate that you don't care what port is used. + **/ #define SOUP_ADDRESS_ANY_PORT 0 +/** + * SoupAddressCallback: + * @addr: the #SoupAddress that was resolved + * @status: %SOUP_STATUS_OK or %SOUP_STATUS_CANT_RESOLVE + * @data: the user data that was passed to + * soup_address_resolve_async() + * + * The callback function passed to soup_address_resolve_async(). + **/ +typedef void (*SoupAddressCallback) (SoupAddress *addr, + guint status, + gpointer data); + GType soup_address_get_type (void); SoupAddress *soup_address_new (const char *name, @@ -56,18 +75,15 @@ SoupAddress *soup_address_new_from_sockaddr (struct sockaddr *sa, SoupAddress *soup_address_new_any (SoupAddressFamily family, guint port); -typedef void (*SoupAddressCallback) (SoupAddress *addr, - guint status, - gpointer data); void soup_address_resolve_async (SoupAddress *addr, SoupAddressCallback callback, gpointer user_data); guint soup_address_resolve_sync (SoupAddress *addr); const char *soup_address_get_name (SoupAddress *addr); -struct sockaddr *soup_address_get_sockaddr (SoupAddress *addr, - int *len); const char *soup_address_get_physical (SoupAddress *addr); guint soup_address_get_port (SoupAddress *addr); +struct sockaddr *soup_address_get_sockaddr (SoupAddress *addr, + int *len); #endif /* SOUP_ADDRESS_H */ diff --git a/libsoup/soup-auth.c b/libsoup/soup-auth.c index fdc9f7d..166f350 100644 --- a/libsoup/soup-auth.c +++ b/libsoup/soup-auth.c @@ -96,7 +96,7 @@ soup_auth_new_from_header_list (const GSList *vals) * @password: the password provided by the user or client * * This is called by the session after requesting a username and - * password from the application. @auth should take the information + * password from the application. @auth will take the information * and do whatever scheme-specific processing is needed. **/ void @@ -162,8 +162,9 @@ soup_auth_is_authenticated (SoupAuth *auth) * @auth: a #SoupAuth * @msg: the #SoupMessage to be authorized * - * Generates an appropriate "Authorization" header for @msg. (This - * will only be called if soup_auth_is_authenticated() returns %TRUE.) + * Generates an appropriate "Authorization" header for @msg. (The + * session will only call this if soup_auth_is_authenticated() + * returned %TRUE.) * * Return value: the "Authorization" header, which must be freed. **/ diff --git a/libsoup/soup-auth.h b/libsoup/soup-auth.h index c385dba..be49573 100644 --- a/libsoup/soup-auth.h +++ b/libsoup/soup-auth.h @@ -45,7 +45,7 @@ typedef struct { GType soup_auth_get_type (void); -SoupAuth *soup_auth_new_from_header_list (const GSList *header); +SoupAuth *soup_auth_new_from_header_list (const GSList *vals); const char *soup_auth_get_scheme_name (SoupAuth *auth); const char *soup_auth_get_realm (SoupAuth *auth); diff --git a/libsoup/soup-connection.c b/libsoup/soup-connection.c index 09f7a75..a38f05b 100644 --- a/libsoup/soup-connection.c +++ b/libsoup/soup-connection.c @@ -129,6 +129,15 @@ soup_connection_class_init (SoupConnectionClass *connection_class) object_class->get_property = get_property; /* signals */ + + /** + * SoupConnection::connect-result: + * @conn: the connection + * @status: the status + * + * Emitted when a connection attempt succeeds or fails. This + * is used internally by soup_connection_connect_async(). + **/ signals[CONNECT_RESULT] = g_signal_new ("connect_result", G_OBJECT_CLASS_TYPE (object_class), @@ -138,6 +147,14 @@ soup_connection_class_init (SoupConnectionClass *connection_class) soup_marshal_NONE__INT, G_TYPE_NONE, 1, G_TYPE_INT); + + /** + * SoupConnection::disconnected: + * @conn: the connection + * + * Emitted when the connection's socket is disconnected, for + * whatever reason. + **/ signals[DISCONNECTED] = g_signal_new ("disconnected", G_OBJECT_CLASS_TYPE (object_class), @@ -146,6 +163,21 @@ soup_connection_class_init (SoupConnectionClass *connection_class) NULL, NULL, soup_marshal_NONE__NONE, G_TYPE_NONE, 0); + + /** + * SoupConnection::authenticate: + * @conn: the connection + * @msg: the #SoupMessage being sent + * @auth_type: the authentication type + * @auth_realm: the realm being authenticated to + * @username: the signal handler should set this to point to + * the provided username + * @password: the signal handler should set this to point to + * the provided password + * + * Emitted when the connection requires authentication. + * (#SoupConnectionNTLM makes use of this.) + **/ signals[AUTHENTICATE] = g_signal_new ("authenticate", G_OBJECT_CLASS_TYPE (object_class), @@ -159,6 +191,21 @@ soup_connection_class_init (SoupConnectionClass *connection_class) G_TYPE_STRING, G_TYPE_POINTER, G_TYPE_POINTER); + + /** + * SoupConnection::reauthenticate: + * @conn: the connection + * @msg: the #SoupMessage being sent + * @auth_type: the authentication type + * @auth_realm: the realm being authenticated to + * @username: the signal handler should set this to point to + * the provided username + * @password: the signal handler should set this to point to + * the provided password + * + * Emitted when the authentication data acquired by a previous + * %authenticate or %reauthenticate signal fails. + **/ signals[REAUTHENTICATE] = g_signal_new ("reauthenticate", G_OBJECT_CLASS_TYPE (object_class), @@ -735,7 +782,7 @@ soup_connection_reserve (SoupConnection *conn) * @conn: a #SoupConnection * * Marks @conn as not "in use". This can be used to cancel the effect - * of a soup_session_reserve(). It is not necessary to call this + * of a soup_connection_reserve(). It is not necessary to call this * after soup_connection_send_request(). **/ void diff --git a/libsoup/soup-connection.h b/libsoup/soup-connection.h index f3c056c..ca6f5d1 100644 --- a/libsoup/soup-connection.h +++ b/libsoup/soup-connection.h @@ -43,6 +43,19 @@ typedef struct { GType soup_connection_get_type (void); +/** + * SoupConnectionCallback: + * @conn: the #SoupConnection + * @status: an HTTP status code indicating success or failure + * @data: the data passed to soup_connection_connect_async() + * + * The callback function passed to soup_connection_connect_async(). + **/ +typedef void (*SoupConnectionCallback) (SoupConnection *conn, + guint status, + gpointer data); + + #define SOUP_CONNECTION_ORIGIN_URI "origin-uri" #define SOUP_CONNECTION_PROXY_URI "proxy-uri" #define SOUP_CONNECTION_SSL_CREDENTIALS "ssl-creds" @@ -51,10 +64,6 @@ GType soup_connection_get_type (void); SoupConnection *soup_connection_new (const char *propname1, ...); -typedef void (*SoupConnectionCallback) (SoupConnection *conn, - guint status, - gpointer data); - void soup_connection_connect_async (SoupConnection *conn, SoupConnectionCallback callback, gpointer user_data); diff --git a/libsoup/soup-dns.c b/libsoup/soup-dns.c index 876ea43..d7ba077 100644 --- a/libsoup/soup-dns.c +++ b/libsoup/soup-dns.c @@ -143,6 +143,13 @@ static GCond *soup_dns_cond; static GMutex *soup_gethost_lock; #endif +/** + * soup_dns_init: + * + * Initializes the libsoup DNS system. Must be called before any other + * soup_dns method is called. Normally this gets called automatically + * by #SoupAddress's class_init function. + **/ void soup_dns_init (void) { diff --git a/libsoup/soup-dns.h b/libsoup/soup-dns.h index 1bd2c54..13443d9 100644 --- a/libsoup/soup-dns.h +++ b/libsoup/soup-dns.h @@ -12,12 +12,27 @@ #include void soup_dns_init (void); +char *soup_dns_ntop (struct sockaddr *sa); +/** + * SoupDNSLookup: + * + * An opaque type that represents a DNS lookup operation. + **/ typedef struct SoupDNSLookup SoupDNSLookup; SoupDNSLookup *soup_dns_lookup_name (const char *name); -SoupDNSLookup *soup_dns_lookup_address (struct sockaddr *address); +SoupDNSLookup *soup_dns_lookup_address (struct sockaddr *sockaddr); +void soup_dns_lookup_free (SoupDNSLookup *lookup); +/** + * SoupDNSCallback: + * @lookup: the completed lookup + * @success: %TRUE if @lookup completed successfully, %FALSE if it failed + * @user_data: the data passed to soup_dns_lookup_resolve_async() + * + * The callback function passed to soup_dns_lookup_resolve_async(). + **/ typedef void (*SoupDNSCallback) (SoupDNSLookup *lookup, gboolean success, gpointer user_data); gboolean soup_dns_lookup_resolve (SoupDNSLookup *lookup); @@ -29,10 +44,5 @@ void soup_dns_lookup_cancel (SoupDNSLookup *lookup); char *soup_dns_lookup_get_hostname (SoupDNSLookup *lookup); struct sockaddr *soup_dns_lookup_get_address (SoupDNSLookup *lookup); -void soup_dns_lookup_free (SoupDNSLookup *lookup); - - -char *soup_dns_ntop (struct sockaddr *address); - #endif /* SOUP_DNS_H */ diff --git a/libsoup/soup-gnutls.c b/libsoup/soup-gnutls.c index 4d41b59..8b1d8be 100644 --- a/libsoup/soup-gnutls.c +++ b/libsoup/soup-gnutls.c @@ -350,8 +350,8 @@ THROW_CREATE_ERROR: * soup_ssl_wrap_iochannel: * @sock: a #GIOChannel wrapping a TCP socket. * @type: whether this is a client or server socket - * @hostname: the hostname of the remote machine - * @cred_pointer: a client or server credentials structure + * @remote_host: the hostname of the remote machine + * @credentials: a client or server credentials structure * * This attempts to wrap a new #GIOChannel around @sock that * will SSL-encrypt/decrypt all traffic through it. @@ -361,17 +361,17 @@ THROW_CREATE_ERROR: **/ GIOChannel * soup_ssl_wrap_iochannel (GIOChannel *sock, SoupSSLType type, - const char *hostname, gpointer cred_pointer) + const char *remote_host, gpointer credentials) { SoupGNUTLSChannel *chan = NULL; GIOChannel *gchan = NULL; gnutls_session session = NULL; - SoupGNUTLSCred *cred = cred_pointer; + SoupGNUTLSCred *cred = credentials; int sockfd; int ret; g_return_val_if_fail (sock != NULL, NULL); - g_return_val_if_fail (cred_pointer != NULL, NULL); + g_return_val_if_fail (credentials != NULL, NULL); sockfd = g_io_channel_unix_get_fd (sock); if (!sockfd) { @@ -402,7 +402,7 @@ soup_ssl_wrap_iochannel (GIOChannel *sock, SoupSSLType type, chan->real_sock = sock; chan->session = session; chan->cred = cred; - chan->hostname = g_strdup (hostname); + chan->hostname = g_strdup (remote_host); chan->type = type; g_io_channel_ref (sock); @@ -484,15 +484,15 @@ soup_ssl_get_client_credentials (const char *ca_file) /** * soup_ssl_free_client_credentials: - * @client_creds: a client credentials structure returned by + * @creds: a client credentials structure returned by * soup_ssl_get_client_credentials(). * * Frees @client_creds. **/ void -soup_ssl_free_client_credentials (gpointer client_creds) +soup_ssl_free_client_credentials (gpointer creds) { - SoupGNUTLSCred *cred = client_creds; + SoupGNUTLSCred *cred = creds; gnutls_certificate_free_credentials (cred->cred); g_free (cred); @@ -541,15 +541,15 @@ soup_ssl_get_server_credentials (const char *cert_file, const char *key_file) /** * soup_ssl_free_server_credentials: - * @server_creds: a server credentials structure returned by + * @creds: a server credentials structure returned by * soup_ssl_get_server_credentials(). * * Frees @server_creds. **/ void -soup_ssl_free_server_credentials (gpointer server_creds) +soup_ssl_free_server_credentials (gpointer creds) { - SoupGNUTLSCred *cred = server_creds; + SoupGNUTLSCred *cred = creds; gnutls_certificate_free_credentials (cred->cred); g_free (cred); diff --git a/libsoup/soup-headers.c b/libsoup/soup-headers.c index ee03aa9..552a7b6 100644 --- a/libsoup/soup-headers.c +++ b/libsoup/soup-headers.c @@ -175,6 +175,20 @@ soup_headers_parse_status_line (const char *status_line, return TRUE; } +/** + * soup_headers_parse_response: + * @str: the header string (including the trailing blank line) + * @len: length of @str + * @dest: #GHashTable to store the header values in + * @ver: on return, will contain the HTTP version + * @status_code: on return, will contain the HTTP status code + * @status_pharse: on return, will contain the status phrase + * + * Parses the headers of an HTTP response in @str and stores the + * results in @ver, @status_code, @status_phrase, and @dest. + * + * Return value: success or failure. + **/ gboolean soup_headers_parse_response (char *str, int len, diff --git a/libsoup/soup-md5-utils.h b/libsoup/soup-md5-utils.h index 5295a61..161c0d3 100644 --- a/libsoup/soup-md5-utils.h +++ b/libsoup/soup-md5-utils.h @@ -29,6 +29,7 @@ #include typedef struct { + /*< private >*/ guint32 buf[4]; guint32 bits[2]; guchar in[64]; diff --git a/libsoup/soup-message-handlers.c b/libsoup/soup-message-handlers.c index 20553e3..3d59821 100644 --- a/libsoup/soup-message-handlers.c +++ b/libsoup/soup-message-handlers.c @@ -64,13 +64,13 @@ run_handler (SoupMessage *msg, /** * soup_message_run_handlers: * @msg: a #SoupMessage - * @invoke_phase: which group of handlers to run + * @phase: which group of handlers to run * - * Run each @invoke_phase handler on @msg. If a handler requeues the - * message, we stop processing at that point. + * Run each @phase handler on @msg. If a handler requeues the message, + * we stop processing at that point. */ void -soup_message_run_handlers (SoupMessage *msg, SoupHandlerPhase invoke_phase) +soup_message_run_handlers (SoupMessage *msg, SoupHandlerPhase phase) { SoupMessagePrivate *priv = SOUP_MESSAGE_GET_PRIVATE (msg); GSList *copy, *list; @@ -83,7 +83,7 @@ soup_message_run_handlers (SoupMessage *msg, SoupHandlerPhase invoke_phase) for (list = copy; list; list = list->next) { if (!g_slist_find (priv->content_handlers, list->data)) continue; - run_handler (msg, invoke_phase, list->data); + run_handler (msg, phase, list->data); if (SOUP_MESSAGE_IS_STARTING (msg)) break; diff --git a/libsoup/soup-message-queue.h b/libsoup/soup-message-queue.h index fcd8248..ed01c4e 100644 --- a/libsoup/soup-message-queue.h +++ b/libsoup/soup-message-queue.h @@ -11,7 +11,14 @@ typedef struct SoupMessageQueue SoupMessageQueue; +/** + * SoupMessageQueueIter: + * + * An opaque data structure used to iterate the elements of a + * #SoupMessageQueue. + **/ typedef struct { + /*< private >*/ GList *cur, *next; } SoupMessageQueueIter; diff --git a/libsoup/soup-message.c b/libsoup/soup-message.c index 50afe93..c0b4643 100644 --- a/libsoup/soup-message.c +++ b/libsoup/soup-message.c @@ -107,6 +107,14 @@ soup_message_class_init (SoupMessageClass *message_class) object_class->finalize = finalize; /* signals */ + + /** + * SoupMessage::wrote-informational: + * @msg: the message + * + * Emitted immediately after writing a 1xx (Informational) + * response for a message. + **/ signals[WROTE_INFORMATIONAL] = g_signal_new ("wrote_informational", G_OBJECT_CLASS_TYPE (object_class), @@ -115,6 +123,13 @@ soup_message_class_init (SoupMessageClass *message_class) NULL, NULL, soup_marshal_NONE__NONE, G_TYPE_NONE, 0); + + /** + * SoupMessage::wrote-headers: + * @msg: the message + * + * Emitted immediately after writing the headers for a message. + **/ signals[WROTE_HEADERS] = g_signal_new ("wrote_headers", G_OBJECT_CLASS_TYPE (object_class), @@ -123,6 +138,14 @@ soup_message_class_init (SoupMessageClass *message_class) NULL, NULL, soup_marshal_NONE__NONE, G_TYPE_NONE, 0); + + /** + * SoupMessage::wrote-chunk: + * @msg: the message + * + * Emitted immediately after writing a body chunk for a message. + * (This is + **/ signals[WROTE_CHUNK] = g_signal_new ("wrote_chunk", G_OBJECT_CLASS_TYPE (object_class), @@ -131,6 +154,13 @@ soup_message_class_init (SoupMessageClass *message_class) NULL, NULL, soup_marshal_NONE__NONE, G_TYPE_NONE, 0); + + /** + * SoupMessage::wrote-body: + * @msg: the message + * + * Emitted immediately after writing the complete body for a message. + **/ signals[WROTE_BODY] = g_signal_new ("wrote_body", G_OBJECT_CLASS_TYPE (object_class), @@ -140,6 +170,13 @@ soup_message_class_init (SoupMessageClass *message_class) soup_marshal_NONE__NONE, G_TYPE_NONE, 0); + /** + * SoupMessage::got-informational: + * @msg: the message + * + * Emitted after receiving a 1xx (Informational) response for + * a message. + **/ signals[GOT_INFORMATIONAL] = g_signal_new ("got_informational", G_OBJECT_CLASS_TYPE (object_class), @@ -148,6 +185,13 @@ soup_message_class_init (SoupMessageClass *message_class) NULL, NULL, soup_marshal_NONE__NONE, G_TYPE_NONE, 0); + + /** + * SoupMessage::got-headers: + * @msg: the message + * + * Emitted after receiving all message headers for a message. + **/ signals[GOT_HEADERS] = g_signal_new ("got_headers", G_OBJECT_CLASS_TYPE (object_class), @@ -156,6 +200,16 @@ soup_message_class_init (SoupMessageClass *message_class) NULL, NULL, soup_marshal_NONE__NONE, G_TYPE_NONE, 0); + + /** + * SoupMessage::got-chunk: + * @msg: the message + * + * Emitted after receiving a chunk of a message body. Note + * that "chunk" in this context means any subpiece of the + * body, not necessarily the specific HTTP 1.1 chunks sent by + * the other side. + **/ signals[GOT_CHUNK] = g_signal_new ("got_chunk", G_OBJECT_CLASS_TYPE (object_class), @@ -164,6 +218,13 @@ soup_message_class_init (SoupMessageClass *message_class) NULL, NULL, soup_marshal_NONE__NONE, G_TYPE_NONE, 0); + + /** + * SoupMessage::got-body: + * @msg: the message + * + * Emitted after receiving the complete message body. + **/ signals[GOT_BODY] = g_signal_new ("got_body", G_OBJECT_CLASS_TYPE (object_class), @@ -173,6 +234,12 @@ soup_message_class_init (SoupMessageClass *message_class) soup_marshal_NONE__NONE, G_TYPE_NONE, 0); + /** + * SoupMessage::restarted: + * @msg: the message + * + * Emitted when a message is about to be re-queued. + **/ signals[RESTARTED] = g_signal_new ("restarted", G_OBJECT_CLASS_TYPE (object_class), @@ -181,6 +248,15 @@ soup_message_class_init (SoupMessageClass *message_class) NULL, NULL, soup_marshal_NONE__NONE, G_TYPE_NONE, 0); + + /** + * SoupMessage::finished: + * @msg: the message + * + * Emitted when all HTTP processing is finished for a message. + * (After #read-body for client-side code, or after + * #wrote-body for server-side code.) + **/ signals[FINISHED] = g_signal_new ("finished", G_OBJECT_CLASS_TYPE (object_class), @@ -788,28 +864,28 @@ soup_message_is_keepalive (SoupMessage *msg) /** * soup_message_set_uri: * @msg: a #SoupMessage - * @new_uri: the new #SoupUri + * @uri: the new #SoupUri * * Changes the URI that @msg is directed to (generally as a result * of a redirect). **/ void -soup_message_set_uri (SoupMessage *msg, const SoupUri *new_uri) +soup_message_set_uri (SoupMessage *msg, const SoupUri *uri) { SoupMessagePrivate *priv; g_return_if_fail (SOUP_IS_MESSAGE (msg)); priv = SOUP_MESSAGE_GET_PRIVATE (msg); - if (priv->uri && new_uri) { - if (strcmp (priv->uri->host, new_uri->host) != 0) + if (priv->uri && uri) { + if (strcmp (priv->uri->host, uri->host) != 0) soup_message_io_stop (msg); - } else if (!new_uri) + } else if (!uri) soup_message_io_stop (msg); if (priv->uri) soup_uri_free (priv->uri); - priv->uri = soup_uri_copy (new_uri); + priv->uri = soup_uri_copy (uri); } /** diff --git a/libsoup/soup-message.h b/libsoup/soup-message.h index e47da72..7d6b841 100644 --- a/libsoup/soup-message.h +++ b/libsoup/soup-message.h @@ -16,6 +16,19 @@ #define SOUP_IS_MESSAGE_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((obj), SOUP_TYPE_MESSAGE)) #define SOUP_MESSAGE_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), SOUP_TYPE_MESSAGE, SoupMessageClass)) +/** + * SoupMessageStatus: + * @SOUP_MESSAGE_STATUS_IDLE: The message has not yet been queued. + * @SOUP_MESSAGE_STATUS_QUEUED: The message has been queued, but is + * waiting for a connection to be available. + * @SOUP_MESSAGE_STATUS_CONNECTING: The message is waiting for a + * specific connection to finish connecting. + * @SOUP_MESSAGE_STATUS_RUNNING: The message is being processed. + * @SOUP_MESSAGE_STATUS_FINISHED: The message is complete (request and + * response both processed). + * + * Enum indicating the lifecycle of a #SoupMessage. + **/ typedef enum { SOUP_MESSAGE_STATUS_IDLE, SOUP_MESSAGE_STATUS_QUEUED, @@ -24,29 +37,82 @@ typedef enum { SOUP_MESSAGE_STATUS_FINISHED } SoupMessageStatus; +/** + * SOUP_MESSAGE_IS_STARTING: + * @msg: a #SoupMessage + * + * Tests if @msg is in a "starting" state, waiting to be sent. (More + * commonly used to test if a message has been requeued after its + * first attempt.) + * + * Return value: %TRUE if @msg is waiting to be sent. + **/ #define SOUP_MESSAGE_IS_STARTING(msg) (msg->status == SOUP_MESSAGE_STATUS_QUEUED || msg->status == SOUP_MESSAGE_STATUS_CONNECTING) +/** + * SoupTransferEncoding: + * @SOUP_TRANSFER_UNKNOWN: HTTP 1.0-style (content ends when the + * connection is closed) + * @SOUP_TRANSFER_CHUNKED: chunked encoding (only supported for + * response) + * @SOUP_TRANSFER_CONTENT_LENGTH: Content-Length + * + * How the length of a request or response is to be encoded. + **/ typedef enum { SOUP_TRANSFER_UNKNOWN = 0, SOUP_TRANSFER_CHUNKED, SOUP_TRANSFER_CONTENT_LENGTH } SoupTransferEncoding; +/** + * SoupOwnership: + * @SOUP_BUFFER_SYSTEM_OWNED: The data is owned by soup and it can + * free it when it is done with it. + * @SOUP_BUFFER_USER_OWNED: The data is owned by the user, who is + * responsible for freeing it at the right point + * @SOUP_BUFFER_STATIC: The data should not be freed. + * + * Used by #SoupDataBuffer (and several functions) to indicate the + * ownership of a buffer. + **/ typedef enum { SOUP_BUFFER_SYSTEM_OWNED = 0, SOUP_BUFFER_USER_OWNED, SOUP_BUFFER_STATIC } SoupOwnership; +/** + * SoupDataBuffer: + * @owner: the ownership of the data + * @body: the data itself + * @length: length of @body + * + * A data buffer used in several places. + **/ typedef struct { SoupOwnership owner; char *body; guint length; } SoupDataBuffer; +/** + * SoupMessage: + * @method: the HTTP method + * @status_code: the HTTP status code + * @reason_phrase: the status phrase associated with @status_code + * @request: the request buffer + * @request_headers: the request headers + * @response: the response buffer + * @response_headers: the response headers + * @status: the processing status of the message + * + * Represents an HTTP message being sent or received. + **/ struct SoupMessage { GObject parent; + /*< public >*/ const char *method; guint status_code; @@ -79,6 +145,13 @@ typedef struct { GType soup_message_get_type (void); +/** + * SoupMessageCallbackFn: + * @req: the #SoupMessage in question + * @user_data: user data + * + * A callback function used by many #SoupMessage methods. + **/ typedef void (*SoupMessageCallbackFn) (SoupMessage *req, gpointer user_data); SoupMessage *soup_message_new (const char *method, @@ -117,6 +190,13 @@ void soup_message_remove_header (GHashTable *hash, void soup_message_clear_headers (GHashTable *hash); +/** + * SoupHttpVersion: + * @SOUP_HTTP_1_0: HTTP 1.0 (RFC 1945) + * @SOUP_HTTP_1_1: HTTP 1.1 (RFC 2616) + * + * Indicates the HTTP protocol version being used. + **/ typedef enum { SOUP_HTTP_1_0 = 0, SOUP_HTTP_1_1 = 1 @@ -132,32 +212,27 @@ const SoupUri *soup_message_get_uri (SoupMessage *msg); void soup_message_set_uri (SoupMessage *msg, const SoupUri *uri); +/** + * SoupMessageFlags: + * @SOUP_MESSAGE_NO_REDIRECT: The session should not follow redirect + * (3xx) responses received by this message. + * @SOUP_MESSAGE_OVERWRITE_CHUNKS: Rather than building up the + * response body in %response, each new chunk should overwrite the + * previous one. (This can be used if you are connecting to the + * %got_chunk signal or have installed a %SOUP_MESSAGE_BODY_CHUNK + * handler. + * @SOUP_MESSAGE_EXPECT_CONTINUE: This will cause an "Expect: + * 100-continue" header to be added to the outgoing request, giving + * the server the opportunity to reject the message (eg, with a 401 + * Unauthorized) before the full request body is sent. + * + * Various flags that can be set on a #SoupMessage to alter its + * behavior. + **/ typedef enum { - /* - * SOUP_MESSAGE_NO_REDIRECT: - * Do not follow redirection responses. - */ SOUP_MESSAGE_NO_REDIRECT = (1 << 1), - - /* - * SOUP_MESSAGE_OVERWRITE_CHUNKS: - * Downloaded data chunks should not be stored in the response - * data buffer. Instead only send data to SOUP_HANDLER_BODY_CHUNK - * handlers, then truncate the data buffer. - * - * Useful when the response is expected to be very large, and - * storage in memory is not desired. - */ SOUP_MESSAGE_OVERWRITE_CHUNKS = (1 << 3), - - /* - * SOUP_MESSAGE_EXPECT_CONTINUE: The message includes an - * "Expect: 100-continue" header, and we should not send the - * body until the Continue response has been received. (This - * is automatically set if there is an "Expect: 100-continue" - * header.) - */ - SOUP_MESSAGE_EXPECT_CONTINUE = (1 << 4) + SOUP_MESSAGE_EXPECT_CONTINUE = (1 << 4) } SoupMessageFlags; void soup_message_set_flags (SoupMessage *msg, @@ -168,6 +243,21 @@ guint soup_message_get_flags (SoupMessage *msg); /* * Handler Registration */ + +/** + * SoupHandlerPhase: + * @SOUP_HANDLER_POST_REQUEST: The handler should run immediately + * after sending the request body + * @SOUP_HANDLER_PRE_BODY: The handler should run before reading the + * response body (after reading the headers). + * @SOUP_HANDLER_BODY_CHUNK: The handler should run after every body + * chunk is read. (See also %SOUP_MESSAGE_OVERWRITE_CHUNKS.) + * @SOUP_HANDLER_POST_BODY: The handler should run after the entire + * message body has been read. + * + * Indicates when a handler added with soup_message_add_handler() or + * the like will be run. + **/ typedef enum { SOUP_HANDLER_POST_REQUEST = 1, SOUP_HANDLER_PRE_BODY, @@ -176,33 +266,33 @@ typedef enum { } SoupHandlerPhase; void soup_message_add_handler (SoupMessage *msg, - SoupHandlerPhase type, + SoupHandlerPhase phase, SoupMessageCallbackFn handler_cb, gpointer user_data); void soup_message_add_header_handler (SoupMessage *msg, const char *header, - SoupHandlerPhase type, - SoupMessageCallbackFn, + SoupHandlerPhase phase, + SoupMessageCallbackFn handler_cb, gpointer user_data); void soup_message_add_status_code_handler ( SoupMessage *msg, guint status_code, - SoupHandlerPhase type, - SoupMessageCallbackFn, + SoupHandlerPhase phase, + SoupMessageCallbackFn handler_cb, gpointer user_data); void soup_message_add_status_class_handler ( SoupMessage *msg, SoupStatusClass status_class, - SoupHandlerPhase type, - SoupMessageCallbackFn, + SoupHandlerPhase phase, + SoupMessageCallbackFn handler_cb, gpointer user_data); void soup_message_remove_handler (SoupMessage *msg, - SoupHandlerPhase type, - SoupMessageCallbackFn, + SoupHandlerPhase phase, + SoupMessageCallbackFn handler_cb, gpointer user_data); /* @@ -229,7 +319,7 @@ SoupDataBuffer*soup_message_pop_chunk (SoupMessage *msg); /* I/O */ void soup_message_send_request (SoupMessage *req, SoupSocket *sock, - gboolean via_proxy); + gboolean is_via_proxy); void soup_message_read_request (SoupMessage *req, SoupSocket *sock); void soup_message_io_stop (SoupMessage *msg); diff --git a/libsoup/soup-misc.h b/libsoup/soup-misc.h index c8b4e73..0962813 100644 --- a/libsoup/soup-misc.h +++ b/libsoup/soup-misc.h @@ -47,8 +47,11 @@ guint soup_str_case_hash (gconstpointer key); gboolean soup_str_case_equal (gconstpointer v1, gconstpointer v2); -/* SSL support */ - +/** + * soup_ssl_supported: + * + * Can be used to test if libsoup was compiled with ssl support. + **/ extern gboolean soup_ssl_supported; #endif /* SOUP_MISC_H */ diff --git a/libsoup/soup-session-async.c b/libsoup/soup-session-async.c index b35afec..f713b9c 100644 --- a/libsoup/soup-session-async.c +++ b/libsoup/soup-session-async.c @@ -37,12 +37,28 @@ soup_session_async_class_init (SoupSessionAsyncClass *soup_session_async_class) } +/** + * soup_session_async_new: + * + * Creates an asynchronous #SoupSession with the default options. + * + * Return value: the new session. + **/ SoupSession * soup_session_async_new (void) { return g_object_new (SOUP_TYPE_SESSION_ASYNC, NULL); } +/** + * soup_session_async_new_with_options: + * @optname1: name of first property to set + * @...: value of @optname1, followed by additional property/value pairs + * + * Creates an asynchronous #SoupSession with the specified options. + * + * Return value: the new session. + **/ SoupSession * soup_session_async_new_with_options (const char *optname1, ...) { diff --git a/libsoup/soup-session-sync.c b/libsoup/soup-session-sync.c index 88e700a..54ab91b 100644 --- a/libsoup/soup-session-sync.c +++ b/libsoup/soup-session-sync.c @@ -62,12 +62,28 @@ soup_session_sync_class_init (SoupSessionSyncClass *session_sync_class) } +/** + * soup_session_sync_new: + * + * Creates an synchronous #SoupSession with the default options. + * + * Return value: the new session. + **/ SoupSession * soup_session_sync_new (void) { return g_object_new (SOUP_TYPE_SESSION_SYNC, NULL); } +/** + * soup_session_sync_new_with_options: + * @optname1: name of first property to set + * @...: value of @optname1, followed by additional property/value pairs + * + * Creates an synchronous #SoupSession with the specified options. + * + * Return value: the new session. + **/ SoupSession * soup_session_sync_new_with_options (const char *optname1, ...) { diff --git a/libsoup/soup-session.c b/libsoup/soup-session.c index c1d8235..24f5c4a 100644 --- a/libsoup/soup-session.c +++ b/libsoup/soup-session.c @@ -187,6 +187,26 @@ soup_session_class_init (SoupSessionClass *session_class) object_class->get_property = get_property; /* signals */ + + /** + * SoupSession::authenticate: + * @session: the session + * @msg: the #SoupMessage being sent + * @auth_type: the authentication type + * @auth_realm: the realm being authenticated to + * @username: the signal handler should set this to point to + * the provided username + * @password: the signal handler should set this to point to + * the provided password + * + * Emitted when the session requires authentication. The + * credentials may come from the user, or from cached + * information. If no credentials are available, leave + * @username and @password unchanged. + * + * If the provided credentials fail, the #reauthenticate + * signal will be emitted. + **/ signals[AUTHENTICATE] = g_signal_new ("authenticate", G_OBJECT_CLASS_TYPE (object_class), @@ -200,6 +220,40 @@ soup_session_class_init (SoupSessionClass *session_class) G_TYPE_STRING, G_TYPE_POINTER, G_TYPE_POINTER); + + /** + * SoupSession::reauthenticate: + * @session: the session + * @msg: the #SoupMessage being sent + * @auth_type: the authentication type + * @auth_realm: the realm being authenticated to + * @username: the signal handler should set this to point to + * the provided username + * @password: the signal handler should set this to point to + * the provided password + * + * Emitted when the credentials provided by the application to + * the #authenticate signal have failed. This gives the + * application a second chance to provide authentication + * credentials. If the new credentials also fail, #SoupSession + * will emit #reauthenticate again, and will continue doing so + * until the provided credentials work, or a #reauthenticate + * signal emission "fails" (because the handler left @username + * and @password unchanged). At that point, the 401 or 407 + * error status will be returned to the caller. + * + * If your application only uses cached passwords, it should + * only connect to #authenticate, and not #reauthenticate. + * + * If your application always prompts the user for a password, + * and never uses cached information, then you can connect the + * same handler to #authenticate and #reauthenticate. + * + * To get standard web-browser behavior, return either cached + * information or a user-provided password (whichever is + * available) from the #authenticate handler, but return only + * user-provided information from the #reauthenticate handler. + **/ signals[REAUTHENTICATE] = g_signal_new ("reauthenticate", G_OBJECT_CLASS_TYPE (object_class), @@ -1001,7 +1055,8 @@ connect_result (SoupConnection *conn, guint status, gpointer user_data) * @is_new: on return, %TRUE if the returned connection is new and not * yet connected * - * Tries to find or create a connection for @msg. + * Tries to find or create a connection for @msg; this is an internal + * method for #SoupSession subclasses. * * If there is an idle connection to the relevant host available, then * that connection will be returned (with *@is_new set to %FALSE). The diff --git a/libsoup/soup-soap-message.c b/libsoup/soup-soap-message.c index 89c5907..656caf1 100644 --- a/libsoup/soup-soap-message.c +++ b/libsoup/soup-soap-message.c @@ -81,6 +81,10 @@ fetch_ns (SoupSoapMessage *msg, const char *prefix, const char *ns_uri) * soup_soap_message_new: * @method: the HTTP method for the created request. * @uri_string: the destination endpoint (as a string). + * @standalone: ??? FIXME + * @xml_encoding: ??? FIXME + * @env_prefix: ??? FIXME + * @env_uri: ??? FIXME * * Creates a new empty #SoupSoapMessage, which will connect to @uri_string. * @@ -111,8 +115,12 @@ soup_soap_message_new (const char *method, const char *uri_string, * soup_soap_message_new_from_uri: * @method: the HTTP method for the created request. * @uri: the destination endpoint (as a #SoupUri). + * @standalone: ??? FIXME + * @xml_encoding: ??? FIXME + * @env_prefix: ??? FIXME + * @env_uri: ??? FIXME * - * * Creates a new empty #SoupSoapMessage, which will connect to @uri + * Creates a new empty #SoupSoapMessage, which will connect to @uri * * Returns: the new #SoupSoapMessage */ @@ -240,23 +248,24 @@ soup_soap_message_end_body (SoupSoapMessage *msg) /** * soup_soap_message_start_element: - * @msg: the %SoupSoapMessage. + * @msg: the #SoupSoapMessage. * @name: the element name. * @prefix: the namespace prefix * @ns_uri: the namespace URI * - * Starts a new arbitrary message element, with @name as the element name, - * @prefix as the XML Namespace prefix, and @ns_uri as the XML Namespace uri for * the created element. + * Starts a new arbitrary message element, with @name as the element + * name, @prefix as the XML Namespace prefix, and @ns_uri as the XML + * Namespace uri for * the created element. * - * Passing @prefix with no @ns_uri will cause a recursive search for an - * existing namespace with the same prefix. Failing that a new ns will be - * created with an empty uri. + * Passing @prefix with no @ns_uri will cause a recursive search for + * an existing namespace with the same prefix. Failing that a new ns + * will be created with an empty uri. * - * Passing both @prefix and @ns_uri always causes new namespace attribute - * creation. + * Passing both @prefix and @ns_uri always causes new namespace + * attribute creation. * - * Passing NULL for both @prefix and @ns_uri causes no prefix to be used, and - * the element will be in the default namespace. + * Passing NULL for both @prefix and @ns_uri causes no prefix to be + * used, and the element will be in the default namespace. */ void soup_soap_message_start_element (SoupSoapMessage *msg, @@ -280,7 +289,7 @@ soup_soap_message_start_element (SoupSoapMessage *msg, /** * soup_soap_message_end_element: - * @msg: the %SoupSoapMessage. + * @msg: the #SoupSoapMessage. * * Closes the current message element. */ @@ -297,17 +306,17 @@ soup_soap_message_end_element (SoupSoapMessage *msg) /** * soup_soap_message_start_fault: - * @msg: the %SoupSoapMessage. + * @msg: the #SoupSoapMessage. * @faultcode: faultcode element value * @faultstring: faultstring element value - * @faultactor: faultactor element value + * @faultfactor: faultfactor element value * - * Starts a new SOAP Fault element, creating faultcode, faultstring, and - * faultactor child elements. + * Starts a new SOAP Fault element, creating faultcode, faultstring, + * and faultfactor child elements. * * If you wish to add the faultdetail element, use - * %soup_soap_message_start_fault_detail, and then %soup_soap_message_start_element - * to add arbitrary sub-elements. + * soup_soap_message_start_fault_detail(), and then + * soup_soap_message_start_element() to add arbitrary sub-elements. */ void soup_soap_message_start_fault (SoupSoapMessage *msg, @@ -336,7 +345,7 @@ soup_soap_message_start_fault (SoupSoapMessage *msg, /** * soup_soap_message_end_fault: - * @msg: the %SoupSoapMessage. + * @msg: the #SoupSoapMessage. * * Closes the current SOAP Fault element. */ @@ -348,10 +357,11 @@ soup_soap_message_end_fault (SoupSoapMessage *msg) /** * soup_soap_message_start_fault_detail: - * @msg: the %SoupSoapMessage. + * @msg: the #SoupSoapMessage. * - * Start the faultdetail child element of the current SOAP Fault element. The - * faultdetail element allows arbitrary data to be sent in a returned fault. + * Start the faultdetail child element of the current SOAP Fault + * element. The faultdetail element allows arbitrary data to be sent + * in a returned fault. **/ void soup_soap_message_start_fault_detail (SoupSoapMessage *msg) @@ -369,7 +379,7 @@ soup_soap_message_start_fault_detail (SoupSoapMessage *msg) /** * soup_soap_message_end_fault_detail: - * @msg: the %SoupSoapMessage. + * @msg: the #SoupSoapMessage. * * Closes the current SOAP faultdetail element. */ @@ -381,15 +391,15 @@ soup_soap_message_end_fault_detail (SoupSoapMessage *msg) /** * soup_soap_message_start_header: - * @msg: the %SoupSoapMessage. + * @msg: the #SoupSoapMessage. * * Creates a new SOAP Header element. You can call - * %soup_soap_message_start_header_element after this to add a new header child - * element. SOAP Header elements allow out-of-band data to be transferred while - * not interfering with the message body. + * soup_soap_message_start_header_element() after this to add a new + * header child element. SOAP Header elements allow out-of-band data + * to be transferred while not interfering with the message body. * - * This should be called after %soup_soap_message_start_envelope and before - * %soup_soap_message_start_body. + * This should be called after soup_soap_message_start_envelope() and + * before soup_soap_message_start_body(). */ void soup_soap_message_start_header (SoupSoapMessage *msg) @@ -405,7 +415,7 @@ soup_soap_message_start_header (SoupSoapMessage *msg) /** * soup_soap_message_end_header: - * @msg: the %SoupSoapMessage. + * @msg: the #SoupSoapMessage. * * Closes the current SOAP Header element. */ @@ -417,7 +427,7 @@ soup_soap_message_end_header (SoupSoapMessage *msg) /** * soup_soap_message_start_header_element: - * @msg: the %SoupSoapMessage. + * @msg: the #SoupSoapMessage. * @name: name of the header element * @must_understand: whether the recipient must understand the header in order * to proceed with processing the message @@ -449,7 +459,7 @@ soup_soap_message_start_header_element (SoupSoapMessage *msg, /** * soup_soap_message_end_header_element: - * @msg: the %SoupSoapMessage. + * @msg: the #SoupSoapMessage. * * Closes the current SOAP header element. */ @@ -461,13 +471,13 @@ soup_soap_message_end_header_element (SoupSoapMessage *msg) /** * soup_soap_message_write_int: - * @msg: the %SoupSoapMessage. + * @msg: the #SoupSoapMessage. * @i: the integer value to write. * - * Writes the stringified value if @i as the current element's content. + * Writes the stringified value of @i as the current element's content. */ void -soup_soap_message_write_int (SoupSoapMessage *msg, long i) +soup_soap_message_write_int (SoupSoapMessage *msg, glong i) { char *str = g_strdup_printf ("%ld", i); soup_soap_message_write_string (msg, str); @@ -476,10 +486,10 @@ soup_soap_message_write_int (SoupSoapMessage *msg, long i) /** * soup_soap_message_write_double: - * @msg: the %SoupSoapMessage. + * @msg: the #SoupSoapMessage. * @d: the double value to write. * - * Writes the stringified value if @d as the current element's content. + * Writes the stringified value of @d as the current element's content. */ void soup_soap_message_write_double (SoupSoapMessage *msg, double d) @@ -491,11 +501,13 @@ soup_soap_message_write_double (SoupSoapMessage *msg, double d) /** * soup_soap_message_write_base64: - * @msg: the %SoupSoapMessage + * @msg: the #SoupSoapMessage * @string: the binary data buffer to encode * @len: the length of data to encode * - * Writes the Base-64 encoded value of @string as the current element's content. **/ + * Writes the Base-64 encoded value of @string as the current + * element's content. + **/ void soup_soap_message_write_base64 (SoupSoapMessage *msg, const char *string, int len) { @@ -506,10 +518,11 @@ soup_soap_message_write_base64 (SoupSoapMessage *msg, const char *string, int le /** * soup_soap_message_write_time: - * @msg: the %SoupSoapMessage. + * @msg: the #SoupSoapMessage. * @timeval: pointer to a time_t to encode * - * Writes the stringified value of @timeval as the current element's content. + * Writes the stringified value of @timeval as the current element's + * content. **/ void soup_soap_message_write_time (SoupSoapMessage *msg, const time_t *timeval) @@ -520,7 +533,7 @@ soup_soap_message_write_time (SoupSoapMessage *msg, const time_t *timeval) /** * soup_soap_message_write_string: - * @msg: the %SoupSoapMessage. + * @msg: the #SoupSoapMessage. * @string: string to write. * * Writes the @string as the current element's content. @@ -538,11 +551,12 @@ soup_soap_message_write_string (SoupSoapMessage *msg, const char *string) /** * soup_soap_message_write_buffer: - * @msg: the %SoupSoapMessage. + * @msg: the #SoupSoapMessage. * @buffer: the string data buffer to write. * @len: length of @buffer. * - * Writes the string buffer pointed to by @buffer as the current element's content. + * Writes the string buffer pointed to by @buffer as the current + * element's content. */ void soup_soap_message_write_buffer (SoupSoapMessage *msg, const char *buffer, int len) @@ -557,11 +571,11 @@ soup_soap_message_write_buffer (SoupSoapMessage *msg, const char *buffer, int le /** * soup_soap_message_set_element_type: - * @msg: the %SoupSoapMessage. + * @msg: the #SoupSoapMessage. * @xsi_type: the type name for the element. * - * Sets the current element's XML schema xsi:type attribute, which specifies - * the element's type name. + * Sets the current element's XML schema xsi:type attribute, which + * specifies the element's type name. */ void soup_soap_message_set_element_type (SoupSoapMessage *msg, const char *xsi_type) @@ -576,7 +590,7 @@ soup_soap_message_set_element_type (SoupSoapMessage *msg, const char *xsi_type) /** * soup_soap_message_set_null: - * @msg: the %SoupSoapMessage. + * @msg: the #SoupSoapMessage. * * Sets the current element's XML Schema xsi:null attribute. */ @@ -593,7 +607,7 @@ soup_soap_message_set_null (SoupSoapMessage *msg) /** * soup_soap_message_add_attribute: - * @msg: the %SoupSoapMessage. + * @msg: the #SoupSoapMessage. * @name: name of the attribute * @value: value of the attribute * @prefix: the namespace prefix @@ -620,7 +634,7 @@ soup_soap_message_add_attribute (SoupSoapMessage *msg, /** * soup_soap_message_add_namespace: - * @msg: the %SoupSoapMessage. + * @msg: the #SoupSoapMessage. * @prefix: the namespace prefix * @ns_uri: the namespace URI, or NULL for empty namespace * @@ -639,12 +653,12 @@ soup_soap_message_add_namespace (SoupSoapMessage *msg, const char *prefix, const /** * soup_soap_message_set_default_namespace: - * @msg: the %SoupSoapMessage. + * @msg: the #SoupSoapMessage. * @ns_uri: the namespace URI. * - * Sets the default namespace to the URI specified in @ns_uri. The default - * namespace becomes the namespace all non-explicitly namespaced child elements - * fall into. + * Sets the default namespace to the URI specified in @ns_uri. The + * default namespace becomes the namespace all non-explicitly + * namespaced child elements fall into. */ void soup_soap_message_set_default_namespace (SoupSoapMessage *msg, const char *ns_uri) @@ -659,11 +673,11 @@ soup_soap_message_set_default_namespace (SoupSoapMessage *msg, const char *ns_ur /** * soup_soap_message_set_encoding_style: - * @msg: the %SoupSoapMessage. + * @msg: the #SoupSoapMessage. * @enc_style: the new encodingStyle value * - * Sets the encodingStyle attribute on the current element to the value of - * @enc_style. + * Sets the encodingStyle attribute on the current element to the + * value of @enc_style. */ void soup_soap_message_set_encoding_style (SoupSoapMessage *msg, const char *enc_style) @@ -678,7 +692,7 @@ soup_soap_message_set_encoding_style (SoupSoapMessage *msg, const char *enc_styl /** * soup_soap_message_reset: - * @msg: the %SoupSoapMessage. + * @msg: the #SoupSoapMessage. * * Resets the internal XML representation of the SOAP message. */ @@ -709,9 +723,9 @@ soup_soap_message_reset (SoupSoapMessage *msg) /** * soup_soap_message_persist: - * @msg: the %SoupSoapMessage. + * @msg: the #SoupSoapMessage. * - * Writes the serialized XML tree to the %SoupMessage's buffer. + * Writes the serialized XML tree to the #SoupMessage's buffer. */ void soup_soap_message_persist (SoupSoapMessage *msg) @@ -732,7 +746,7 @@ soup_soap_message_persist (SoupSoapMessage *msg) /** * soup_soap_message_get_namespace_prefix: - * @msg: the %SoupSoapMessage. + * @msg: the #SoupSoapMessage. * @ns_uri: the namespace URI. * * Returns the namespace prefix for @ns_uri (or an empty string if @@ -764,12 +778,12 @@ soup_soap_message_get_namespace_prefix (SoupSoapMessage *msg, const char *ns_uri /** * soup_soap_message_get_xml_doc: - * @msg: the %SoupSoapMessage. + * @msg: the #SoupSoapMessage. * - * Returns the internal XML representation tree of the %SoupSoapMessage pointed - * to by @msg. + * Returns the internal XML representation tree of the + * #SoupSoapMessage pointed to by @msg. * - * Return value: the xmlDocPtr representing the SOAP message. + * Return value: the #xmlDocPtr representing the SOAP message. */ xmlDocPtr soup_soap_message_get_xml_doc (SoupSoapMessage *msg) @@ -784,12 +798,12 @@ soup_soap_message_get_xml_doc (SoupSoapMessage *msg) /** * soup_soap_message_parse_response: - * @msg: the %SoupSoapMessage. + * @msg: the #SoupSoapMessage. * * Parses the response returned by the server. * - * Return value: a %SoupSoapResponse representing the response from the server, - * or %NULL if there was an error. + * Return value: a #SoupSoapResponse representing the response from + * the server, or %NULL if there was an error. */ SoupSoapResponse * soup_soap_message_parse_response (SoupSoapMessage *msg) diff --git a/libsoup/soup-soap-message.h b/libsoup/soup-soap-message.h index 055a5d6..9048d62 100644 --- a/libsoup/soup-soap-message.h +++ b/libsoup/soup-soap-message.h @@ -63,7 +63,7 @@ void soup_soap_message_start_header_element (SoupSoapMessage *msg, const char *prefix, const char *ns_uri); void soup_soap_message_end_header_element (SoupSoapMessage *msg); -void soup_soap_message_write_int (SoupSoapMessage *msg, long i); +void soup_soap_message_write_int (SoupSoapMessage *msg, glong i); void soup_soap_message_write_double (SoupSoapMessage *msg, double d); void soup_soap_message_write_base64 (SoupSoapMessage *msg, const char *string, int len); void soup_soap_message_write_time (SoupSoapMessage *msg, const time_t *timeval); diff --git a/libsoup/soup-soap-response.c b/libsoup/soup-soap-response.c index e1ad47b..6ad6af0 100644 --- a/libsoup/soup-soap-response.c +++ b/libsoup/soup-soap-response.c @@ -58,10 +58,11 @@ soup_soap_response_init (SoupSoapResponse *response) /** * soup_soap_response_new: * - * Create a new empty %SoupSoapResponse object, which can be modified with the - * accessor functions provided with this class. + * Create a new empty #SoupSoapResponse object, which can be modified + * with the accessor functions provided with this class. * - * Return value: the new %SoupSoapResponse (or %NULL if there was an error). + * Return value: the new #SoupSoapResponse (or %NULL if there was an + * error). */ SoupSoapResponse * soup_soap_response_new (void) @@ -76,10 +77,11 @@ soup_soap_response_new (void) * soup_soap_response_new_from_string: * @xmlstr: the XML string to parse. * - * Create a new %SoupSoapResponse object from the XML string contained in - * @xmlstr. + * Create a new #SoupSoapResponse object from the XML string contained + * in @xmlstr. * - * Return value: the new %SoupSoapResponse (or %NULL if there was an error). + * Return value: the new #SoupSoapResponse (or %NULL if there was an + * error). */ SoupSoapResponse * soup_soap_response_new_from_string (const char *xmlstr) @@ -115,11 +117,11 @@ parse_parameters (SoupSoapResponsePrivate *priv, xmlNodePtr xml_method) /** * soup_soap_response_from_string: - * @response: the %SoupSoapResponse object. + * @response: the #SoupSoapResponse object. * @xmlstr: XML string to parse. * - * Parses the string contained in @xmlstr and sets all properties from it in the - * @response object. + * Parses the string contained in @xmlstr and sets all properties from + * it in the @response object. * * Return value: %TRUE if successful, %FALSE otherwise. */ @@ -186,7 +188,7 @@ soup_soap_response_from_string (SoupSoapResponse *response, const char *xmlstr) /** * soup_soap_response_get_method_name: - * @response: the %SoupSoapResponse object. + * @response: the #SoupSoapResponse object. * * Gets the method name from the SOAP response. * @@ -206,10 +208,10 @@ soup_soap_response_get_method_name (SoupSoapResponse *response) /** * soup_soap_response_set_method_name: - * @response: the %SoupSoapResponse object. + * @response: the #SoupSoapResponse object. * @method_name: the method name to set. * - * Sets the method name on the given %SoupSoapResponse. + * Sets the method name on the given #SoupSoapResponse. */ void soup_soap_response_set_method_name (SoupSoapResponse *response, const char *method_name) @@ -226,6 +228,11 @@ soup_soap_response_set_method_name (SoupSoapResponse *response, const char *meth /** * soup_soap_parameter_get_name: + * @param: the parameter + * + * Returns the parameter name. + * + * Return value: the parameter name. */ const char * soup_soap_parameter_get_name (SoupSoapParameter *param) @@ -237,6 +244,11 @@ soup_soap_parameter_get_name (SoupSoapParameter *param) /** * soup_soap_parameter_get_int_value: + * @param: the parameter + * + * Returns the parameter's (integer) value. + * + * Return value: the parameter value as an integer */ int soup_soap_parameter_get_int_value (SoupSoapParameter *param) @@ -258,6 +270,12 @@ soup_soap_parameter_get_int_value (SoupSoapParameter *param) /** * soup_soap_parameter_get_string_value: + * @param: the parameter + * + * Returns the parameter's value. + * + * Return value: the parameter value as a string, which must be freed + * by the caller. */ char * soup_soap_parameter_get_string_value (SoupSoapParameter *param) @@ -274,13 +292,13 @@ soup_soap_parameter_get_string_value (SoupSoapParameter *param) /** * soup_soap_parameter_get_first_child: - * @param: A %SoupSoapParameter. + * @param: A #SoupSoapParameter. * - * Gets the first child of the given %SoupSoapParameter. This is used + * Gets the first child of the given #SoupSoapParameter. This is used * for compound data types, which can contain several parameters * themselves. * - * Return value: the first child or NULL if there are no children. + * Return value: the first child or %NULL if there are no children. */ SoupSoapParameter * soup_soap_parameter_get_first_child (SoupSoapParameter *param) @@ -292,13 +310,13 @@ soup_soap_parameter_get_first_child (SoupSoapParameter *param) /** * soup_soap_parameter_get_first_child_by_name: - * @param: A %SoupSoapParameter. + * @param: A #SoupSoapParameter. * @name: The name of the child parameter to look for. * - * Gets the first child of the given %SoupSoapParameter whose name - * is @name. + * Gets the first child of the given #SoupSoapParameter whose name is + * @name. * - * Return value: the first child with the given name or NULL if there + * Return value: the first child with the given name or %NULL if there * are no children. */ SoupSoapParameter * @@ -321,7 +339,16 @@ soup_soap_parameter_get_first_child_by_name (SoupSoapParameter *param, const cha /** * soup_soap_parameter_get_next_child: - * @param: A %SoupSoapParameter. + * @param: A #SoupSoapParameter. + * + * Gets the next sibling of the given #SoupSoapParameter. This is used + * for compound data types, which can contain several parameters + * themselves. + * + * FIXME: the name of this method is wrong + * + * Return value: the next sibling, or %NULL if there are no more + * siblings. */ SoupSoapParameter * soup_soap_parameter_get_next_child (SoupSoapParameter *param) @@ -333,6 +360,15 @@ soup_soap_parameter_get_next_child (SoupSoapParameter *param) /** * soup_soap_parameter_get_next_child_by_name: + * @param: A #SoupSoapParameter. + * @name: The name of the sibling parameter to look for. + * + * Gets the next sibling of the given #SoupSoapParameter whose name is + * @name. + * + * FIXME: the name of this method is wrong + * + * Return value: the next sibling with the given name, or %NULL */ SoupSoapParameter * soup_soap_parameter_get_next_child_by_name (SoupSoapParameter *param, @@ -355,8 +391,12 @@ soup_soap_parameter_get_next_child_by_name (SoupSoapParameter *param, /** * soup_soap_parameter_get_property: - * @param: + * @param: the parameter * @prop_name: Name of the property to retrieve. + * + * Returns the named property of @param. + * + * Return value: the property, which must be freed by the caller. */ char * soup_soap_parameter_get_property (SoupSoapParameter *param, const char *prop_name) @@ -375,13 +415,11 @@ soup_soap_parameter_get_property (SoupSoapParameter *param, const char *prop_nam /** * soup_soap_response_get_parameters: - * @response: the %SoupSoapResponse object. + * @response: the #SoupSoapResponse object. * * Returns the list of parameters received in the SOAP response. * - * Return value: the list of parameters, represented in - * SoupSoapParameter's, which is an opaque type used to - * represent a parameter in the SOAP response. + * Return value: a list of #SoupSoapParameter */ const GList * soup_soap_response_get_parameters (SoupSoapResponse *response) @@ -396,13 +434,12 @@ soup_soap_response_get_parameters (SoupSoapResponse *response) /** * soup_soap_response_get_first_parameter: - * @response: the %SoupSoapResponse object. + * @response: the #SoupSoapResponse object. * * Retrieves the first parameter contained in the SOAP response. * - * Return value: a %SoupSoapParameter representing the - * first parameter. This is an opaque type used to - * represent a parameter in the SOAP response. + * Return value: a #SoupSoapParameter representing the first + * parameter, or %NULL if there are no parameters. */ SoupSoapParameter * soup_soap_response_get_first_parameter (SoupSoapResponse *response) @@ -417,15 +454,14 @@ soup_soap_response_get_first_parameter (SoupSoapResponse *response) /** * soup_soap_response_get_first_parameter_by_name: - * @response: the %SoupSoapResponse object. + * @response: the #SoupSoapResponse object. * @name: the name of the parameter to look for. * * Retrieves the first parameter contained in the SOAP response whose * name is @name. * - * Return value: a %SoupSoapParameter representing the - * first parameter. This is an opaque type used to - * represent a parameter in the SOAP response. + * Return value: a #SoupSoapParameter representing the first parameter + * with the given name, or %NULL. */ SoupSoapParameter * soup_soap_response_get_first_parameter_by_name (SoupSoapResponse *response, @@ -450,12 +486,13 @@ soup_soap_response_get_first_parameter_by_name (SoupSoapResponse *response, /** * soup_soap_response_get_next_parameter: - * @response: the %SoupSoapResponse object. + * @response: the #SoupSoapResponse object. * @from: the parameter to start from. * - * Retrieves the parameter following @from in the %SoupSoapResponse object. + * Retrieves the parameter following @from in the #SoupSoapResponse + * object. * - * Return value: a %SoupSoapParameter representing the parameter. + * Return value: a #SoupSoapParameter representing the parameter. */ SoupSoapParameter * soup_soap_response_get_next_parameter (SoupSoapResponse *response, @@ -477,14 +514,14 @@ soup_soap_response_get_next_parameter (SoupSoapResponse *response, /** * soup_soap_response_get_next_parameter_by_name: - * @response: the %SoupSoapResponse object. + * @response: the #SoupSoapResponse object. * @from: the parameter to start from. * @name: the name of the parameter to look for. * - * Retrieves the parameter following @from in the %SoupSoapResponse object - * whose name matches @name. + * Retrieves the first parameter following @from in the + * #SoupSoapResponse object whose name matches @name. * - * Return value: a %SoupSoapParameter representing the parameter. + * Return value: a #SoupSoapParameter representing the parameter. */ SoupSoapParameter * soup_soap_response_get_next_parameter_by_name (SoupSoapResponse *response, diff --git a/libsoup/soup-socket.c b/libsoup/soup-socket.c index 5af5a37..3d5bc34 100644 --- a/libsoup/soup-socket.c +++ b/libsoup/soup-socket.c @@ -158,6 +158,15 @@ soup_socket_class_init (SoupSocketClass *socket_class) object_class->get_property = get_property; /* signals */ + + /** + * SoupSocket::connect-result: + * @sock: the socket + * @status: the status + * + * Emitted when a connection attempt succeeds or fails. This + * is used internally by soup_socket_client_new_async(). + **/ signals[CONNECT_RESULT] = g_signal_new ("connect_result", G_OBJECT_CLASS_TYPE (object_class), @@ -167,6 +176,14 @@ soup_socket_class_init (SoupSocketClass *socket_class) soup_marshal_NONE__INT, G_TYPE_NONE, 1, G_TYPE_INT); + + /** + * SoupSocket::readable: + * @sock: the socket + * + * Emitted when an async socket is readable. See + * soup_socket_read() and soup_socket_read_until(). + **/ signals[READABLE] = g_signal_new ("readable", G_OBJECT_CLASS_TYPE (object_class), @@ -175,6 +192,14 @@ soup_socket_class_init (SoupSocketClass *socket_class) NULL, NULL, soup_marshal_NONE__NONE, G_TYPE_NONE, 0); + + /** + * SoupSocket::writable: + * @sock: the socket + * + * Emitted when an async socket is writable. See + * soup_socket_write(). + **/ signals[WRITABLE] = g_signal_new ("writable", G_OBJECT_CLASS_TYPE (object_class), @@ -183,6 +208,14 @@ soup_socket_class_init (SoupSocketClass *socket_class) NULL, NULL, soup_marshal_NONE__NONE, G_TYPE_NONE, 0); + + /** + * SoupSocket::disconnected: + * @sock: the socket + * + * Emitted when the socket is disconnected, for whatever + * reason. + **/ signals[DISCONNECTED] = g_signal_new ("disconnected", G_OBJECT_CLASS_TYPE (object_class), @@ -191,6 +224,16 @@ soup_socket_class_init (SoupSocketClass *socket_class) NULL, NULL, soup_marshal_NONE__NONE, G_TYPE_NONE, 0); + + /** + * SoupSocket::new-connection: + * @sock: the socket + * @new: the new socket + * + * Emitted when a listening socket (set up with + * soup_socket_listen() or soup_socket_server_new()) receives a + * new connection. + **/ signals[NEW_CONNECTION] = g_signal_new ("new_connection", G_OBJECT_CLASS_TYPE (object_class), diff --git a/libsoup/soup-socket.h b/libsoup/soup-socket.h index bb43caa..5db2174 100644 --- a/libsoup/soup-socket.h +++ b/libsoup/soup-socket.h @@ -38,6 +38,31 @@ typedef struct { #define SOUP_SOCKET_IS_SERVER "is-server" #define SOUP_SOCKET_SSL_CREDENTIALS "ssl-creds" +/** + * SoupSocketCallback: + * @sock: the #SoupSocket + * @status: an HTTP status code indicating success or failure + * @user_data: the data passed to soup_socket_client_new_async() + * + * The callback function passed to soup_socket_client_new_async(). + **/ +typedef void (*SoupSocketCallback) (SoupSocket *sock, + guint status, + gpointer user_data); + +/** + * SoupSocketListenerCallback: + * @listener: the listening #SoupSocket + * @sock: the newly-received #SoupSocket + * @user_data: the data passed to soup_socket_server_new(). + * + * The callback function passed to soup_socket_server_new(), which + * receives new connections. + **/ +typedef void (*SoupSocketListenerCallback) (SoupSocket *listener, + SoupSocket *sock, + gpointer user_data); + GType soup_socket_get_type (void); SoupSocket *soup_socket_new (const char *optname1, @@ -54,13 +79,6 @@ gboolean soup_socket_start_proxy_ssl (SoupSocket *sock, void soup_socket_disconnect (SoupSocket *sock); gboolean soup_socket_is_connected (SoupSocket *sock); -typedef void (*SoupSocketCallback) (SoupSocket *sock, - guint status, - gpointer user_data); -typedef void (*SoupSocketListenerCallback) (SoupSocket *listener, - SoupSocket *sock, - gpointer user_data); - SoupSocket *soup_socket_client_new_async (const char *hostname, guint port, gpointer ssl_creds, @@ -79,6 +97,15 @@ SoupAddress *soup_socket_get_local_address (SoupSocket *sock); SoupAddress *soup_socket_get_remote_address (SoupSocket *sock); +/** + * SoupSocketIOStatus: + * @SOUP_SOCKET_OK: Success + * @SOUP_SOCKET_WOULD_BLOCK: Cannot read/write any more at this time + * @SOUP_SOCKET_EOF: End of file + * @SOUP_SOCKET_ERROR: Other error + * + * Return value from the #SoupSocket IO methods. + **/ typedef enum { SOUP_SOCKET_OK, SOUP_SOCKET_WOULD_BLOCK, diff --git a/libsoup/soup-ssl.h b/libsoup/soup-ssl.h index c52658a..1442543 100644 --- a/libsoup/soup-ssl.h +++ b/libsoup/soup-ssl.h @@ -8,6 +8,13 @@ #include +/** + * SoupSSLType: + * @SOUP_SSL_TYPE_CLIENT: the client side of an SSL connection + * @SOUP_SSL_TYPE_SERVER: the server side of an SSL connection + * + * What kind of SSL connection this is. + **/ typedef enum { SOUP_SSL_TYPE_CLIENT = 0, SOUP_SSL_TYPE_SERVER diff --git a/libsoup/soup-status.h b/libsoup/soup-status.h index 3a72704..6b1e2ed 100644 --- a/libsoup/soup-status.h +++ b/libsoup/soup-status.h @@ -8,6 +8,18 @@ #ifndef SOUP_STATUS_H #define SOUP_STATUS_H 1 +/** + * SoupStatusClass: + * @SOUP_STATUS_CLASS_TRANSPORT_ERROR: Network or Soup-level error + * @SOUP_STATUS_CLASS_INFORMATIONAL: HTTP 1xx response providing + * partial information about the state of a request + * @SOUP_STATUS_CLASS_SUCCESS: HTTP 2xx successful response + * @SOUP_STATUS_CLASS_REDIRECT: HTTP 3xx redirection response + * @SOUP_STATUS_CLASS_CLIENT_ERROR: HTTP 4xx client error response + * @SOUP_STATUS_CLASS_SERVER_ERROR: HTTP 5xx server error response + * + * The classes of HTTP and Soup status codes + **/ typedef enum { SOUP_STATUS_CLASS_TRANSPORT_ERROR = 0, SOUP_STATUS_CLASS_INFORMATIONAL, @@ -17,6 +29,55 @@ typedef enum { SOUP_STATUS_CLASS_SERVER_ERROR } SoupStatusClass; +/** + * SOUP_STATUS_IS_TRANSPORT_ERROR: + * @status: a status code + * + * Tests if @status is a libsoup transport error. + * + * Return value: %TRUE or %FALSE + **/ +/** + * SOUP_STATUS_IS_INFORMATIONAL: + * @status: an HTTP status code + * + * Tests if @status is an Informational (1xx) response. + * + * Return value: %TRUE or %FALSE + **/ +/** + * SOUP_STATUS_IS_SUCCESSFUL: + * @status: an HTTP status code + * + * Tests if @status is a Successful (2xx) response. + * + * Return value: %TRUE or %FALSE + **/ +/** + * SOUP_STATUS_IS_REDIRECTION: + * @status: an HTTP status code + * + * Tests if @status is a Redirection (3xx) response. + * + * Return value: %TRUE or %FALSE + **/ +/** + * SOUP_STATUS_IS_CLIENT_ERROR: + * @status: an HTTP status code + * + * Tests if @status is a Client Error (4xx) response. + * + * Return value: %TRUE or %FALSE + **/ +/** + * SOUP_STATUS_IS_SERVER_ERROR: + * @status: an HTTP status code + * + * Tests if @status is a Server Error (5xx) response. + * + * Return value: %TRUE or %FALSE + **/ + #define SOUP_STATUS_IS_TRANSPORT_ERROR(status) ((status) > 0 && (status) < 100) #define SOUP_STATUS_IS_INFORMATIONAL(status) ((status) >= 100 && (status) < 200) #define SOUP_STATUS_IS_SUCCESSFUL(status) ((status) >= 200 && (status) < 300) @@ -24,6 +85,89 @@ typedef enum { #define SOUP_STATUS_IS_CLIENT_ERROR(status) ((status) >= 400 && (status) < 500) #define SOUP_STATUS_IS_SERVER_ERROR(status) ((status) >= 500 && (status) < 600) +/** + * SoupKnownStatusCode: + * @SOUP_STATUS_NONE: No status available. (Eg, the message has not + * been sent yet) + * @SOUP_STATUS_CANCELLED: Message was cancelled locally + * @SOUP_STATUS_CANT_RESOLVE: Unable to resolve destination host name + * @SOUP_STATUS_CANT_RESOLVE_PROXY: Unable to resolve proxy host name + * @SOUP_STATUS_CANT_CONNECT: Unable to connect to remote host + * @SOUP_STATUS_CANT_CONNECT_PROXY: Unable to connect to proxy + * @SOUP_STATUS_SSL_FAILED: SSL negotiation failed + * @SOUP_STATUS_IO_ERROR: A network error occurred, or the other end + * closed the connection unexpectedly + * @SOUP_STATUS_MALFORMED: Malformed data (usually a programmer error) + * @SOUP_STATUS_TRY_AGAIN: Try again. (Only returned in certain + * specifically documented cases) + * @SOUP_STATUS_CONTINUE: 100 Continue (HTTP) + * @SOUP_STATUS_SWITCHING_PROTOCOLS: 101 Switching Protocols (HTTP) + * @SOUP_STATUS_PROCESSING: 102 Processing (WebDAV) + * @SOUP_STATUS_OK: 200 Success (HTTP). Also used by many lower-level + * soup routines to indicate success. + * @SOUP_STATUS_CREATED: 201 Created (HTTP) + * @SOUP_STATUS_ACCEPTED: 202 Accepted (HTTP) + * @SOUP_STATUS_NON_AUTHORITATIVE: 203 Non-Authoritative Information + * (HTTP) + * @SOUP_STATUS_NO_CONTENT: 204 No Content (HTTP) + * @SOUP_STATUS_RESET_CONTENT: 205 Reset Content (HTTP) + * @SOUP_STATUS_PARTIAL_CONTENT: 206 Partial Content (HTTP) + * @SOUP_STATUS_MULTI_STATUS: 207 Multi-Status (WebDAV) + * @SOUP_STATUS_MULTIPLE_CHOICES: 300 Multiple Choices (HTTP) + * @SOUP_STATUS_MOVED_PERMANENTLY: 301 Moved Permanently (HTTP) + * @SOUP_STATUS_FOUND: 302 Found (HTTP) + * @SOUP_STATUS_MOVED_TEMPORARILY: 302 Moved Temporarily (old name, + * RFC 2068) + * @SOUP_STATUS_SEE_OTHER: 303 See Other (HTTP) + * @SOUP_STATUS_NOT_MODIFIED: 304 Not Modified (HTTP) + * @SOUP_STATUS_USE_PROXY: 305 Use Proxy (HTTP) + * @SOUP_STATUS_NOT_APPEARING_IN_THIS_PROTOCOL: 306 [Unused] (HTTP) + * @SOUP_STATUS_TEMPORARY_REDIRECT: 307 Temporary Redirect (HTTP) + * @SOUP_STATUS_BAD_REQUEST: 400 Bad Request (HTTP) + * @SOUP_STATUS_UNAUTHORIZED: 401 Unauthorized (HTTP) + * @SOUP_STATUS_PAYMENT_REQUIRED: 402 Payment Required (HTTP) + * @SOUP_STATUS_FORBIDDEN: 403 Forbidden (HTTP) + * @SOUP_STATUS_NOT_FOUND: 404 Not Found (HTTP) + * @SOUP_STATUS_METHOD_NOT_ALLOWED: 405 Method Not Allowed (HTTP) + * @SOUP_STATUS_NOT_ACCEPTABLE: 406 Not Acceptable (HTTP) + * @SOUP_STATUS_PROXY_AUTHENTICATION_REQUIRED: 407 Proxy Authentication + * Required (HTTP) + * @SOUP_STATUS_PROXY_UNAUTHORIZED: shorter alias for + * %SOUP_STATUS_PROXY_AUTHENTICATION_REQUIRED + * @SOUP_STATUS_REQUEST_TIMEOUT: 408 Request Timeout (HTTP) + * @SOUP_STATUS_CONFLICT: 409 Conflict (HTTP) + * @SOUP_STATUS_GONE: 410 Gone (HTTP) + * @SOUP_STATUS_LENGTH_REQUIRED: 411 Length Required (HTTP) + * @SOUP_STATUS_PRECONDITION_FAILED: 412 Precondition Failed (HTTP) + * @SOUP_STATUS_REQUEST_ENTITY_TOO_LARGE: 413 Request Entity Too Large + * (HTTP) + * @SOUP_STATUS_REQUEST_URI_TOO_LONG: 414 Request-URI Too Long (HTTP) + * @SOUP_STATUS_UNSUPPORTED_MEDIA_TYPE: 415 Unsupported Media Type + * (HTTP) + * @SOUP_STATUS_REQUESTED_RANGE_NOT_SATISFIABLE: 416 Requested Range + * Not Satisfiable (HTTP) + * @SOUP_STATUS_INVALID_RANGE: shorter alias for + * %SOUP_STATUS_REQUESTED_RANGE_NOT_SATISFIABLE + * @SOUP_STATUS_EXPECTATION_FAILED: 417 Expectation Failed (HTTP) + * @SOUP_STATUS_UNPROCESSABLE_ENTITY: 422 Unprocessable Entity + * (WebDAV) + * @SOUP_STATUS_LOCKED: 423 Locked (WebDAV) + * @SOUP_STATUS_FAILED_DEPENDENCY: 424 Failed Dependency (WebDAV) + * @SOUP_STATUS_INTERNAL_SERVER_ERROR: 500 Internal Server Error + * (HTTP) + * @SOUP_STATUS_NOT_IMPLEMENTED: 501 Not Implemented (HTTP) + * @SOUP_STATUS_BAD_GATEWAY: 502 Bad Gateway (HTTP) + * @SOUP_STATUS_SERVICE_UNAVAILABLE: 503 Service Unavailable (HTTP) + * @SOUP_STATUS_GATEWAY_TIMEOUT: 504 Gateway Timeout (HTTP) + * @SOUP_STATUS_HTTP_VERSION_NOT_SUPPORTED: 505 HTTP Version Not + * Supported (HTTP) + * @SOUP_STATUS_INSUFFICIENT_STORAGE: 507 Insufficient Storage + * (WebDAV) + * @SOUP_STATUS_NOT_EXTENDED: 510 Not Extended (RFC 2774) + * + * These represent the known HTTP status code values, plus various + * network and internal errors. + **/ typedef enum { SOUP_STATUS_NONE, diff --git a/libsoup/soup-uri.c b/libsoup/soup-uri.c index 2cfeb3a..ae298f4 100644 --- a/libsoup/soup-uri.c +++ b/libsoup/soup-uri.c @@ -390,24 +390,24 @@ parts_equal (const char *one, const char *two) /** * soup_uri_equal: - * @u1: a #SoupUri - * @u2: another #SoupUri + * @uri1: a #SoupUri + * @uri2: another #SoupUri * - * Tests whether or not @u1 and @u2 are equal in all parts + * Tests whether or not @uri1 and @uri2 are equal in all parts * * Return value: %TRUE or %FALSE **/ gboolean -soup_uri_equal (const SoupUri *u1, const SoupUri *u2) +soup_uri_equal (const SoupUri *uri1, const SoupUri *uri2) { - if (u1->protocol != u2->protocol || - u1->port != u2->port || - !parts_equal (u1->user, u2->user) || - !parts_equal (u1->passwd, u2->passwd) || - !parts_equal (u1->host, u2->host) || - !parts_equal (u1->path, u2->path) || - !parts_equal (u1->query, u2->query) || - !parts_equal (u1->fragment, u2->fragment)) + if (uri1->protocol != uri2->protocol || + uri1->port != uri2->port || + !parts_equal (uri1->user, uri2->user) || + !parts_equal (uri1->passwd, uri2->passwd) || + !parts_equal (uri1->host, uri2->host) || + !parts_equal (uri1->path, uri2->path) || + !parts_equal (uri1->query, uri2->query) || + !parts_equal (uri1->fragment, uri2->fragment)) return FALSE; return TRUE; diff --git a/libsoup/soup-uri.h b/libsoup/soup-uri.h index 5ad6503..5aad10c 100644 --- a/libsoup/soup-uri.h +++ b/libsoup/soup-uri.h @@ -11,8 +11,26 @@ #include +/** + * SoupProtocol: + * + * #GQuark is used for SoupProtocol so that the protocol of a #SoupUri + * can be tested quickly. + **/ typedef GQuark SoupProtocol; + +/** + * SOUP_PROTOCOL_HTTP: + * + * This returns the #SoupProtocol value for "http". + **/ #define SOUP_PROTOCOL_HTTP (g_quark_from_static_string ("http")) + +/** + * SOUP_PROTOCOL_HTTPS: + * + * This returns the #SoupProtocol value for "https". +**/ #define SOUP_PROTOCOL_HTTPS (g_quark_from_static_string ("https")) struct SoupUri { -- 2.7.4