From afd1b9daee050c8f127b0a747c336327d1f46e6c Mon Sep 17 00:00:00 2001 From: Dan Winship Date: Thu, 26 Aug 2004 15:33:33 +0000 Subject: [PATCH] add/fix lots of gtk-doc comments * libsoup/*: add/fix lots of gtk-doc comments * libsoup/soup-misc.c (soup_str_case_hash, soup_str_case_equal): Fix bug noticed while documenting. (We were using the locale-case-insensitive functions rather than the g_ascii_ ones.) * libsoup/soup-message.h (SoupMessageFlags): remove the (never implemented) NO_PIPELINE and NO_COOKIE flags. * docs/reference/tmpl/*.sgml: Regenerate, fill in some stuff. There are still problems here with gtk-doc not recognizing many of the objects in libsoup... --- ChangeLog | 15 ++ docs/reference/libsoup-sections.txt | 3 - docs/reference/tmpl/libsoup-unused.sgml | 13 ++ docs/reference/tmpl/soup-address.sgml | 32 ++-- docs/reference/tmpl/soup-auth-basic.sgml | 5 +- docs/reference/tmpl/soup-auth-digest.sgml | 5 +- docs/reference/tmpl/soup-auth.sgml | 13 +- docs/reference/tmpl/soup-connection.sgml | 8 +- docs/reference/tmpl/soup-dns.sgml | 2 +- docs/reference/tmpl/soup-message-private.sgml | 8 - docs/reference/tmpl/soup-message-queue.sgml | 3 +- docs/reference/tmpl/soup-message.sgml | 95 ++++++---- docs/reference/tmpl/soup-method.sgml | 11 +- docs/reference/tmpl/soup-socket.sgml | 27 +-- docs/reference/tmpl/soup-ssl.sgml | 6 +- docs/reference/tmpl/soup-status.sgml | 174 ++++++++++--------- docs/reference/tmpl/soup-uri.sgml | 7 +- libsoup/soup-address.c | 19 +- libsoup/soup-auth.c | 76 ++++++++ libsoup/soup-connection.c | 9 +- libsoup/soup-connection.h | 2 +- libsoup/soup-dns.c | 59 ++++++- libsoup/soup-gnutls.c | 55 ++++++ libsoup/soup-message-client-io.c | 11 ++ libsoup/soup-message-handlers.c | 70 +++++++- libsoup/soup-message-io.c | 43 +++++ libsoup/soup-message-private.h | 1 - libsoup/soup-message-queue.c | 13 +- libsoup/soup-message-server-io.c | 7 + libsoup/soup-message.c | 238 ++++++++++++++++++++++++-- libsoup/soup-message.h | 14 -- libsoup/soup-method.c | 11 +- libsoup/soup-misc.c | 23 ++- libsoup/soup-soap-message.c | 12 +- libsoup/soup-socket.c | 36 +++- libsoup/soup-status.c | 8 + libsoup/soup-status.h | 12 +- libsoup/soup-uri.c | 44 +++++ 38 files changed, 948 insertions(+), 242 deletions(-) diff --git a/ChangeLog b/ChangeLog index 3fe2d48..28f1978 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,18 @@ +2004-08-26 Dan Winship + + * libsoup/*: add/fix lots of gtk-doc comments + + * libsoup/soup-misc.c (soup_str_case_hash, soup_str_case_equal): + Fix bug noticed while documenting. (We were using the + locale-case-insensitive functions rather than the g_ascii_ ones.) + + * libsoup/soup-message.h (SoupMessageFlags): remove the (never + implemented) NO_PIPELINE and NO_COOKIE flags. + + * docs/reference/tmpl/*.sgml: Regenerate, fill in some stuff. + There are still problems here with gtk-doc not recognizing many of + the objects in libsoup... + 2004-08-13 JP Rosevear * configure.in: bump version, libtool number diff --git a/docs/reference/libsoup-sections.txt b/docs/reference/libsoup-sections.txt index 3abb918..e382c95 100644 --- a/docs/reference/libsoup-sections.txt +++ b/docs/reference/libsoup-sections.txt @@ -11,7 +11,6 @@ soup_message_new soup_message_new_from_uri soup_message_set_request soup_message_set_response -soup_message_cancel soup_message_add_header soup_message_get_header soup_message_get_header_list @@ -206,8 +205,6 @@ SOUP_SESSION_MAX_CONNS SOUP_SESSION_MAX_CONNS_PER_HOST SOUP_SESSION_USE_NTLM SOUP_SESSION_SSL_CA_FILE -soup_session_new -soup_session_new_with_options soup_session_queue_message soup_session_requeue_message soup_session_send_message diff --git a/docs/reference/tmpl/libsoup-unused.sgml b/docs/reference/tmpl/libsoup-unused.sgml index 4d49f3c..ab933b6 100644 --- a/docs/reference/tmpl/libsoup-unused.sgml +++ b/docs/reference/tmpl/libsoup-unused.sgml @@ -89,6 +89,12 @@ soup @i: @parent: + + + + + + @@ -157,6 +163,13 @@ soup @msg: @req: + + + + + +@req: + diff --git a/docs/reference/tmpl/soup-address.sgml b/docs/reference/tmpl/soup-address.sgml index b4f7b8a..edc6944 100644 --- a/docs/reference/tmpl/soup-address.sgml +++ b/docs/reference/tmpl/soup-address.sgml @@ -2,11 +2,18 @@ SoupAddress - +Higher-level IP address object +#SoupAddress represents the address of a TCP connection endpoint; both +the IP address and the port. (It is somewhat like an object-oriented +version of struct #sockaddr.) + + +If libsoup was built with IPv6 support, #SoupAddress will allow both +IPv4 and IPv6 addresses. @@ -16,15 +23,19 @@ SoupAddress - +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: -@SOUP_ADDRESS_FAMILY_IPV6: +@SOUP_ADDRESS_FAMILY_IPV4: an IPv4 address +@SOUP_ADDRESS_FAMILY_IPV6: an IPv6 address - +This can be passed to any #SoupAddress method that expects a port to +indicate that you don't care what port is used. @@ -61,12 +72,12 @@ SoupAddress - +The callback function passed to soup_address_resolve_async(). -@addr: -@status: -@data: +@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() @@ -77,9 +88,6 @@ SoupAddress @addr: @callback: @user_data: - -@cb: -@data: diff --git a/docs/reference/tmpl/soup-auth-basic.sgml b/docs/reference/tmpl/soup-auth-basic.sgml index 7dc91b1..5beb539 100644 --- a/docs/reference/tmpl/soup-auth-basic.sgml +++ b/docs/reference/tmpl/soup-auth-basic.sgml @@ -2,11 +2,12 @@ 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 index 16cf820..af0f0c1 100644 --- a/docs/reference/tmpl/soup-auth-digest.sgml +++ b/docs/reference/tmpl/soup-auth-digest.sgml @@ -2,11 +2,12 @@ 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 7283fe5..5fb0bd9 100644 --- a/docs/reference/tmpl/soup-auth.sgml +++ b/docs/reference/tmpl/soup-auth.sgml @@ -2,16 +2,25 @@ SoupAuth - +HTTP Authentication support +#SoupAuth objects store the authentication data associated with a +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.) - +SoupAuthBasic, SoupAuthDigest, SoupSession, SoupConnectionNTLM diff --git a/docs/reference/tmpl/soup-connection.sgml b/docs/reference/tmpl/soup-connection.sgml index 7c3b6eb..9cb5e6c 100644 --- a/docs/reference/tmpl/soup-connection.sgml +++ b/docs/reference/tmpl/soup-connection.sgml @@ -47,12 +47,12 @@ SoupConnection - +The callback function passed to soup_connection_connect_async(). -@sock: -@status: -@data: +@conn: the #SoupConnection +@status: an HTTP status code indicating success or failure +@data: the data passed to soup_connection_connect_async() diff --git a/docs/reference/tmpl/soup-dns.sgml b/docs/reference/tmpl/soup-dns.sgml index b98bc00..8bef2e9 100644 --- a/docs/reference/tmpl/soup-dns.sgml +++ b/docs/reference/tmpl/soup-dns.sgml @@ -2,7 +2,7 @@ soup-dns - +Low-level DNS routines diff --git a/docs/reference/tmpl/soup-message-private.sgml b/docs/reference/tmpl/soup-message-private.sgml index 04e16f8..581531f 100644 --- a/docs/reference/tmpl/soup-message-private.sgml +++ b/docs/reference/tmpl/soup-message-private.sgml @@ -23,14 +23,6 @@ soup-message-private @phase: - - - - - -@req: - - diff --git a/docs/reference/tmpl/soup-message-queue.sgml b/docs/reference/tmpl/soup-message-queue.sgml index efc18ce..0abe873 100644 --- a/docs/reference/tmpl/soup-message-queue.sgml +++ b/docs/reference/tmpl/soup-message-queue.sgml @@ -16,7 +16,8 @@ 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 32357ec..97706bd 100644 --- a/docs/reference/tmpl/soup-message.sgml +++ b/docs/reference/tmpl/soup-message.sgml @@ -16,57 +16,68 @@ SoupMessage - +Enum indicating the lifecycle of a #SoupMessage. -@SOUP_MESSAGE_STATUS_IDLE: -@SOUP_MESSAGE_STATUS_QUEUED: -@SOUP_MESSAGE_STATUS_CONNECTING: -@SOUP_MESSAGE_STATUS_RUNNING: -@SOUP_MESSAGE_STATUS_FINISHED: +@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). - + +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: +@msg: a #SoupMessage +@Returns: %TRUE if @msg is waiting to be sent. - +How the length of a request or response is to be encoded. -@SOUP_TRANSFER_UNKNOWN: -@SOUP_TRANSFER_CHUNKED: -@SOUP_TRANSFER_CONTENT_LENGTH: +@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 - +Used by #SoupDataBuffer (and several functions) to indicate the +ownership of a buffer. -@SOUP_BUFFER_SYSTEM_OWNED: -@SOUP_BUFFER_USER_OWNED: -@SOUP_BUFFER_STATIC: +@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. - +A data buffer used in several places. -@owner: -@body: -@length: +@owner: the ownership of the data +@body: the data itself +@length: length of @body - +A callback function used by many #SoupMessage methods. -@req: -@user_data: +@req: the #SoupMessage in question +@user_data: user data @@ -178,11 +189,11 @@ SoupMessage - +Indicates the HTTP protocol version being used. -@SOUP_HTTP_1_0: -@SOUP_HTTP_1_1: +@SOUP_HTTP_1_0: HTTP 1.0 (RFC 1945) +@SOUP_HTTP_1_1: HTTP 1.1 (RFC 2616) @@ -231,14 +242,19 @@ SoupMessage - +Various flags that can be set on a #SoupMessage to alter its behavior. -@SOUP_MESSAGE_NO_PIPELINE: -@SOUP_MESSAGE_NO_REDIRECT: -@SOUP_MESSAGE_NO_COOKIE: -@SOUP_MESSAGE_OVERWRITE_CHUNKS: -@SOUP_MESSAGE_EXPECT_CONTINUE: +@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. @@ -260,13 +276,18 @@ SoupMessage - +Indicates when a handler added with soup_message_add_handler() or the +like will be run. -@SOUP_HANDLER_POST_REQUEST: -@SOUP_HANDLER_PRE_BODY: -@SOUP_HANDLER_BODY_CHUNK: -@SOUP_HANDLER_POST_BODY: +@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. diff --git a/docs/reference/tmpl/soup-method.sgml b/docs/reference/tmpl/soup-method.sgml index f4c39d8..e6c6bb3 100644 --- a/docs/reference/tmpl/soup-method.sgml +++ b/docs/reference/tmpl/soup-method.sgml @@ -2,11 +2,14 @@ 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. @@ -128,7 +131,9 @@ soup-method - +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: diff --git a/docs/reference/tmpl/soup-socket.sgml b/docs/reference/tmpl/soup-socket.sgml index e5716db..8a6389a 100644 --- a/docs/reference/tmpl/soup-socket.sgml +++ b/docs/reference/tmpl/soup-socket.sgml @@ -109,22 +109,25 @@ SoupSocket - +The callback function passed to soup_socket_client_new_async(). -@sock: -@status: +@sock: the #SoupSocket +@status: an HTTP status code indicating success or failure @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: -@sock: -@user_data: +@listener: the listening #SoupSocket +@sock: the newly-received #SoupSocket +@user_data: the data passed to soup_socket_server_new(). @@ -188,13 +191,13 @@ SoupSocket - +Return value from the #SoupSocket IO methods. -@SOUP_SOCKET_OK: -@SOUP_SOCKET_WOULD_BLOCK: -@SOUP_SOCKET_EOF: -@SOUP_SOCKET_ERROR: +@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 diff --git a/docs/reference/tmpl/soup-ssl.sgml b/docs/reference/tmpl/soup-ssl.sgml index e2e9b9a..c8cedf7 100644 --- a/docs/reference/tmpl/soup-ssl.sgml +++ b/docs/reference/tmpl/soup-ssl.sgml @@ -16,11 +16,11 @@ soup-ssl - +What kind of SSL connection this is. -@SOUP_SSL_TYPE_CLIENT: -@SOUP_SSL_TYPE_SERVER: +@SOUP_SSL_TYPE_CLIENT: the client side of an SSL connection +@SOUP_SSL_TYPE_SERVER: the server side of an SSL connection diff --git a/docs/reference/tmpl/soup-status.sgml b/docs/reference/tmpl/soup-status.sgml index 4d45ea4..374a820 100644 --- a/docs/reference/tmpl/soup-status.sgml +++ b/docs/reference/tmpl/soup-status.sgml @@ -2,7 +2,7 @@ soup-status - +HTTP and Soup status codes @@ -16,122 +16,136 @@ soup-status - +The classes of HTTP and Soup status codes -@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: +@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 - +Tests if @status is an Informational (1xx) response. -@x: +@status: an HTTP status code +@Returns: %TRUE if @status is an Information (1xx) response. - +Tests if @status is a Successful (2xx) response. -@x: +@status: an HTTP status code +@Returns: %TRUE if @status is a Successful (2xx) response. - +Tests if @status is a Redirection (3xx) response. -@x: +@status: an HTTP status code +@Returns: %TRUE if @status is a Redirection (3xx) response. - +Tests if @status is a Client Error (4xx) response. -@x: +@status: an HTTP status code +@Returns: %TRUE if @status is a Client Error (4xx) response. - +Tests if @status is a Server Error (5xx) response. -@x: +@status: an HTTP status code +@Returns: %TRUE if @status is a Server Error (5xx) response. - +These represent the known HTTP status code values, plus various +network and internal errors. -@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: +@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) diff --git a/docs/reference/tmpl/soup-uri.sgml b/docs/reference/tmpl/soup-uri.sgml index c344f58..5058ce6 100644 --- a/docs/reference/tmpl/soup-uri.sgml +++ b/docs/reference/tmpl/soup-uri.sgml @@ -16,20 +16,21 @@ soup-uri - +#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 4450fb2..c4d42ac 100644 --- a/libsoup/soup-address.c +++ b/libsoup/soup-address.c @@ -200,8 +200,10 @@ soup_address_new (const char *name, guint port) * @sa: a pointer to a sockaddr * @len: size of @sa * - * Return value: a #SoupAddress equivalent to @sa (or %NULL if @sa's + * Returns a #SoupAddress equivalent to @sa (or %NULL if @sa's * address family isn't supported) + * + * Return value: the new #SoupAddress **/ SoupAddress * soup_address_new_from_sockaddr (struct sockaddr *sa, int len) @@ -221,11 +223,13 @@ soup_address_new_from_sockaddr (struct sockaddr *sa, int len) /** * soup_address_new_any: * @family: the address family - * @port: the port number (usually 0, meaning "any port") + * @port: the port number (usually %SOUP_ADDRESS_ANY_PORT) * - * Return value: a #SoupAddress corresponding to the "any" address + * Returns a #SoupAddress corresponding to the "any" address * for @family (or %NULL if @family isn't supported), suitable for * passing to soup_socket_server_new(). + * + * Return value: the new #SoupAddress **/ SoupAddress * soup_address_new_any (SoupAddressFamily family, guint port) @@ -250,8 +254,9 @@ soup_address_new_any (SoupAddressFamily family, guint port) * soup_address_get_name: * @addr: a #SoupAddress * - * Return value: the hostname associated with @addr, or %NULL if - * it is not known. + * Returns the hostname associated with @addr. + * + * Return value: the hostname, or %NULL if it is not known. **/ const char * soup_address_get_name (SoupAddress *addr) @@ -312,7 +317,9 @@ soup_address_get_physical (SoupAddress *addr) * soup_address_get_port: * @addr: a #SoupAddress * - * Return value: the port associated with @addr + * Returns the port associated with @addr. + * + * Return value: the port **/ guint soup_address_get_port (SoupAddress *addr) diff --git a/libsoup/soup-auth.c b/libsoup/soup-auth.c index 245c4a6..ba80a2f 100644 --- a/libsoup/soup-auth.c +++ b/libsoup/soup-auth.c @@ -39,6 +39,17 @@ static AuthScheme known_auth_schemes [] = { { NULL } }; +/* FIXME: it should be possible to register new auth schemes! */ + +/** + * soup_auth_new_from_header_list: + * @vals: a list of WWW-Authenticate headers from a server response + * + * Creates a #SoupAuth value based on the strongest available + * supported auth type in @vals. + * + * Return value: the new #SoupAuth, or %NULL if none could be created. + **/ SoupAuth * soup_auth_new_from_header_list (const GSList *vals) { @@ -78,6 +89,16 @@ soup_auth_new_from_header_list (const GSList *vals) return auth; } +/** + * soup_auth_authenticate: + * @auth: a #SoupAuth + * @username: the username provided by the user or client + * @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 + * and do whatever scheme-specific processing is needed. + **/ void soup_auth_authenticate (SoupAuth *auth, const char *username, const char *password) { @@ -88,6 +109,14 @@ soup_auth_authenticate (SoupAuth *auth, const char *username, const char *passwo SOUP_AUTH_GET_CLASS (auth)->authenticate (auth, username, password); } +/** + * soup_auth_get_scheme_name: + * @auth: a #SoupAuth + * + * Returns @auth's scheme name. (Eg, "Basic") + * + * Return value: the scheme name + **/ const char * soup_auth_get_scheme_name (SoupAuth *auth) { @@ -96,6 +125,14 @@ soup_auth_get_scheme_name (SoupAuth *auth) return SOUP_AUTH_GET_CLASS (auth)->scheme_name; } +/** + * soup_auth_get_realm: + * @auth: a #SoupAuth + * + * Returns @auth's realm, if any. + * + * Return value: the realm name + **/ const char * soup_auth_get_realm (SoupAuth *auth) { @@ -104,6 +141,14 @@ soup_auth_get_realm (SoupAuth *auth) return SOUP_AUTH_GET_CLASS (auth)->get_realm (auth); } +/** + * soup_auth_is_authenticated: + * @auth: a #SoupAuth + * + * Tests if @auth has been given a username and password + * + * Return value: %TRUE if @auth has been given a username and password + **/ gboolean soup_auth_is_authenticated (SoupAuth *auth) { @@ -112,6 +157,16 @@ soup_auth_is_authenticated (SoupAuth *auth) return SOUP_AUTH_GET_CLASS (auth)->is_authenticated (auth); } +/** + * soup_auth_get_authorization: + * @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.) + * + * Return value: the "Authorization" header, which must be freed. + **/ char * soup_auth_get_authorization (SoupAuth *auth, SoupMessage *msg) { @@ -121,6 +176,20 @@ soup_auth_get_authorization (SoupAuth *auth, SoupMessage *msg) return SOUP_AUTH_GET_CLASS (auth)->get_authorization (auth, msg); } +/** + * soup_auth_get_protection_space: + * @auth: a #SoupAuth + * @source_uri: the URI of the request that @auth was generated in + * response to. + * + * Returns a list of paths on the server which @auth extends over. + * (All subdirectories of these paths are also assumed to be part + * of @auth's protection space, unless otherwise discovered not to + * be.) + * + * Return value: the list of paths, which must be freed with + * soup_auth_free_protection_space(). + **/ GSList * soup_auth_get_protection_space (SoupAuth *auth, const SoupUri *source_uri) { @@ -130,6 +199,13 @@ soup_auth_get_protection_space (SoupAuth *auth, const SoupUri *source_uri) return SOUP_AUTH_GET_CLASS (auth)->get_protection_space (auth, source_uri); } +/** + * soup_auth_free_protection_space: + * @auth: a #SoupAuth + * @space: the return value from soup_auth_get_protection_space() + * + * Frees @space. + **/ void soup_auth_free_protection_space (SoupAuth *auth, GSList *space) { diff --git a/libsoup/soup-connection.c b/libsoup/soup-connection.c index 4246a88..3129bb7 100644 --- a/libsoup/soup-connection.c +++ b/libsoup/soup-connection.c @@ -604,7 +604,10 @@ soup_connection_disconnect (SoupConnection *conn) * soup_connection_is_in_use: * @conn: a connection * - * Return value: whether or not @conn is being used. + * Tests whether or not @conn is in use. + * + * Return value: %TRUE if there is currently a request being processed + * on @conn. **/ gboolean soup_connection_is_in_use (SoupConnection *conn) @@ -618,6 +621,8 @@ soup_connection_is_in_use (SoupConnection *conn) * soup_connection_last_used: * @conn: a #SoupConnection. * + * Returns the last time a response was received on @conn. + * * Return value: the last time a response was received on @conn, or 0 * if @conn has not been used yet. */ @@ -748,7 +753,7 @@ soup_connection_authenticate (SoupConnection *conn, SoupMessage *msg, } /** - * soup_connection_authenticate: + * soup_connection_reauthenticate: * @conn: a #SoupConnection * @msg: the message to authenticate * @auth_type: type of authentication to use diff --git a/libsoup/soup-connection.h b/libsoup/soup-connection.h index 92583b4..959bceb 100644 --- a/libsoup/soup-connection.h +++ b/libsoup/soup-connection.h @@ -54,7 +54,7 @@ GType soup_connection_get_type (void); SoupConnection *soup_connection_new (const char *propname1, ...); -typedef void (*SoupConnectionCallback) (SoupConnection *sock, +typedef void (*SoupConnectionCallback) (SoupConnection *conn, guint status, gpointer data); diff --git a/libsoup/soup-dns.c b/libsoup/soup-dns.c index 8cbc370..050327d 100644 --- a/libsoup/soup-dns.c +++ b/libsoup/soup-dns.c @@ -59,6 +59,13 @@ copy_hostent (struct hostent *h) h->h_length, h->h_addr_list[0]); } +/** + * soup_dns_free_hostent: + * @h: a #hostent + * + * Frees @h. Use this to free the return value from + * soup_dns_entry_get_hostent(). + **/ void soup_dns_free_hostent (struct hostent *h) { @@ -119,6 +126,17 @@ new_hostent_from_phys (const char *addr) return NULL; } +/** + * soup_dns_ntop: + * @addr: pointer to address data (eg, an #in_addr_t) + * @family: address family of @addr + * + * Converts @addr into textual form (eg, "141.213.8.59"), like the + * standard library function inet_ntop(), except that the returned + * string must be freed. + * + * Return value: the text form or @addr, which must be freed. + **/ char * soup_dns_ntop (gconstpointer addr, int family) { @@ -423,9 +441,9 @@ soup_dns_lookup_entry (const char *name) * (eg, 141.213.8.59). * * Begins asynchronous resolution of @name. The caller should - * periodically call soup_entry_check_lookup() to see if it is done, - * and call soup_entry_get_hostent() when soup_entry_check_lookup() - * returns %TRUE. + * periodically call soup_dns_entry_check_lookup() to see if it is + * done, and call soup_dns_entry_get_hostent() when + * soup_dns_entry_check_lookup() returns %TRUE. * * Currently, this routine forks and does the lookup, which can cause * some problems. In general, this will work ok for most programs most @@ -433,7 +451,7 @@ soup_dns_lookup_entry (const char *name) * systems that copy the entire process when forking. * * Returns: a #SoupDNSEntry, which will be freed when you call - * soup_entry_get_hostent() or soup_entry_cancel_lookup(). + * soup_dns_entry_get_hostent() or soup_dns_entry_cancel_lookup(). **/ SoupDNSEntry * soup_dns_entry_from_name (const char *name) @@ -517,9 +535,9 @@ soup_dns_entry_from_name (const char *name) * @family: address family of @addr * * Begins asynchronous resolution of @addr. The caller should - * periodically call soup_entry_check_lookup() to see if it is done, - * and call soup_entry_get_hostent() when soup_entry_check_lookup() - * returns %TRUE. + * periodically call soup_dns_entry_check_lookup() to see if it is + * done, and call soup_dns_entry_get_hostent() when + * soup_dns_entry_check_lookup() returns %TRUE. * * Currently, this routine forks and does the lookup, which can cause * some problems. In general, this will work ok for most programs most @@ -527,7 +545,7 @@ soup_dns_entry_from_name (const char *name) * systems that copy the entire process when forking. * * Returns: a #SoupDNSEntry, which will be freed when you call - * soup_entry_get_hostent() or soup_entry_cancel_lookup(). + * soup_dns_entry_get_hostent() or soup_dns_entry_cancel_lookup(). **/ SoupDNSEntry * soup_dns_entry_from_addr (gconstpointer addr, int family) @@ -663,6 +681,15 @@ check_hostent (SoupDNSEntry *entry, gboolean block) soup_dns_unlock (); } +/** + * soup_dns_entry_check_lookup: + * @entry: a #SoupDNSEntry + * + * Checks if @entry has finished resolving + * + * Return value: %TRUE if @entry has finished resolving (either + * successfully or not) + **/ gboolean soup_dns_entry_check_lookup (SoupDNSEntry *entry) { @@ -674,6 +701,16 @@ soup_dns_entry_check_lookup (SoupDNSEntry *entry) return entry->resolved; } +/** + * soup_dns_entry_get_hostent: + * @entry: a #SoupDNSEntry + * + * Extracts a #hostent from @entry. If @entry had not already finished + * resolving, soup_dns_entry_get_hostent() will block until it does. + * + * Return value: the #hostent (which must be freed with + * soup_dns_free_hostent()), or %NULL if it couldn't be resolved. + **/ struct hostent * soup_dns_entry_get_hostent (SoupDNSEntry *entry) { @@ -686,6 +723,12 @@ soup_dns_entry_get_hostent (SoupDNSEntry *entry) return h; } +/** + * soup_dns_entry_cancel_lookup: + * @entry: a #SoupDNSEntry + * + * Cancels the lookup for @entry. + **/ void soup_dns_entry_cancel_lookup (SoupDNSEntry *entry) { diff --git a/libsoup/soup-gnutls.c b/libsoup/soup-gnutls.c index b895f95..4a0aa58 100644 --- a/libsoup/soup-gnutls.c +++ b/libsoup/soup-gnutls.c @@ -331,6 +331,19 @@ THROW_CREATE_ERROR: return FALSE; } +/** + * 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 + * + * This attempts to wrap a new #GIOChannel around @sock that + * will SSL-encrypt/decrypt all traffic through it. + * + * Return value: an SSL-encrypting #GIOChannel, or %NULL on + * failure. + **/ GIOChannel * soup_ssl_wrap_iochannel (GIOChannel *sock, SoupSSLType type, const char *hostname, gpointer cred_pointer) @@ -393,6 +406,21 @@ soup_ssl_wrap_iochannel (GIOChannel *sock, SoupSSLType type, return NULL; } +/** + * soup_ssl_get_client_credentials: + * @ca_file: path to a file containing X509-encoded Certificate + * Authority certificates. + * + * Creates an opaque client credentials object which can later be + * passed to soup_ssl_wrap_iochannel(). + * + * If @ca_file is non-%NULL, any certificate received from a server + * must be signed by one of the CAs in the file, or an error will + * be returned. + * + * Return value: the client credentials, which must be freed with + * soup_ssl_free_client_credentials(). + **/ gpointer soup_ssl_get_client_credentials (const char *ca_file) { @@ -422,6 +450,13 @@ soup_ssl_get_client_credentials (const char *ca_file) return cred; } +/** + * soup_ssl_free_client_credentials: + * @client_creds: a client credentials structure returned by + * soup_ssl_get_client_credentials(). + * + * Frees @client_creds. + **/ void soup_ssl_free_client_credentials (gpointer client_creds) { @@ -431,6 +466,19 @@ soup_ssl_free_client_credentials (gpointer client_creds) g_free (cred); } +/** + * soup_ssl_get_server_credentials: + * @cert_file: path to a file containing an X509-encoded server + * certificate + * @key_file: path to a file containing an X509-encoded key for + * @cert_file. + * + * Creates an opaque server credentials object which can later be + * passed to soup_ssl_wrap_iochannel(). + * + * Return value: the server credentials, which must be freed with + * soup_ssl_free_server_credentials(). + **/ gpointer soup_ssl_get_server_credentials (const char *cert_file, const char *key_file) { @@ -458,6 +506,13 @@ soup_ssl_get_server_credentials (const char *cert_file, const char *key_file) return cred; } +/** + * soup_ssl_free_server_credentials: + * @server_creds: a server credentials structure returned by + * soup_ssl_get_server_credentials(). + * + * Frees @server_creds. + **/ void soup_ssl_free_server_credentials (gpointer server_creds) { diff --git a/libsoup/soup-message-client-io.c b/libsoup/soup-message-client-io.c index 8dd171a..fdc6429 100644 --- a/libsoup/soup-message-client-io.c +++ b/libsoup/soup-message-client-io.c @@ -157,6 +157,17 @@ get_request_headers (SoupMessage *req, GString *header, req->priv->msg_flags |= SOUP_MESSAGE_EXPECT_CONTINUE; } +/** + * soup_message_send_request: + * @req: a #SoupMessage + * @sock: the #SoupSocket to send @req on + * @is_via_proxy: %TRUE if @sock is a connection to a proxy server + * rather than a direct connection to the desired HTTP server + * + * Begins the process of sending @msg across @sock. (If @sock is + * synchronous, then soup_message_send_request() won't return until + * the response has been received.) + **/ void soup_message_send_request (SoupMessage *req, SoupSocket *sock, gboolean is_via_proxy) diff --git a/libsoup/soup-message-handlers.c b/libsoup/soup-message-handlers.c index e128dd8..89ccbf8 100644 --- a/libsoup/soup-message-handlers.c +++ b/libsoup/soup-message-handlers.c @@ -61,12 +61,13 @@ run_handler (SoupMessage *msg, (*data->handler_cb) (msg, data->user_data); } -/* - * Run each handler with matching criteria. If a handler requeues a - * message, we stop processing and terminate the current request. +/** + * soup_message_run_handlers: + * @msg: a #SoupMessage + * @invoke_phase: which group of handlers to run * - * After running all handlers, if there is an error set or the invoke - * phase was post_body, issue the final callback. + * Run each @invoke_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) @@ -126,6 +127,17 @@ add_handler (SoupMessage *msg, g_slist_append (msg->priv->content_handlers, data); } +/** + * soup_message_add_header_handler: + * @msg: a #SoupMessage + * @header: HTTP response header to match against + * @phase: processing phase to run the handler in + * @handler_cb: the handler + * @user_data: data to pass to @handler_cb + * + * Adds a handler to @msg for messages containing the given response + * header. + **/ void soup_message_add_header_handler (SoupMessage *msg, const char *header, @@ -142,6 +154,17 @@ soup_message_add_header_handler (SoupMessage *msg, header, 0, 0); } +/** + * soup_message_add_status_code_handler: + * @msg: a #SoupMessage + * @status_code: HTTP status code to match against + * @phase: processing phase to run the handler in + * @handler_cb: the handler + * @user_data: data to pass to @handler_cb + * + * Adds a handler to @msg for messages receiving the given status + * code. + **/ void soup_message_add_status_code_handler (SoupMessage *msg, guint status_code, @@ -158,6 +181,17 @@ soup_message_add_status_code_handler (SoupMessage *msg, NULL, status_code, 0); } +/** + * soup_message_add_status_class_handler: + * @msg: a #SoupMessage + * @status_class: HTTP status code class to match against + * @phase: processing phase to run the handler in + * @handler_cb: the handler + * @user_data: data to pass to @handler_cb + * + * Adds a handler to @msg for messages receiving a status code in + * the given class. + **/ void soup_message_add_status_class_handler (SoupMessage *msg, SoupStatusClass status_class, @@ -174,11 +208,20 @@ soup_message_add_status_class_handler (SoupMessage *msg, NULL, 0, status_class); } +/** + * soup_message_add_handler: + * @msg: a #SoupMessage + * @phase: processing phase to run the handler in + * @handler_cb: the handler + * @user_data: data to pass to @handler_cb + * + * Adds a handler to @msg for all messages + **/ void -soup_message_add_handler (SoupMessage *msg, - SoupHandlerPhase phase, - SoupMessageCallbackFn handler_cb, - gpointer user_data) +soup_message_add_handler (SoupMessage *msg, + SoupHandlerPhase phase, + SoupMessageCallbackFn handler_cb, + gpointer user_data) { g_return_if_fail (SOUP_IS_MESSAGE (msg)); g_return_if_fail (handler_cb != NULL); @@ -186,6 +229,15 @@ soup_message_add_handler (SoupMessage *msg, add_handler (msg, phase, handler_cb, user_data, 0, NULL, 0, 0); } +/** + * soup_message_remove_handler: + * @msg: a #SoupMessage + * @phase: processing phase to run the handler in + * @handler_cb: the handler + * @user_data: data to pass to @handler_cb + * + * Removes all matching handlers from @msg + **/ void soup_message_remove_handler (SoupMessage *msg, SoupHandlerPhase phase, diff --git a/libsoup/soup-message-io.c b/libsoup/soup-message-io.c index ae0168d..a8ea957 100644 --- a/libsoup/soup-message-io.c +++ b/libsoup/soup-message-io.c @@ -91,6 +91,13 @@ io_cleanup (SoupMessage *msg) msg->priv->io_data = NULL; } +/** + * soup_message_io_stop: + * @msg: a #SoupMessage + * + * Immediately stops I/O on msg; if the connection would be left in an + * inconsistent state, it will be closed. + **/ void soup_message_io_stop (SoupMessage *msg) { @@ -676,6 +683,18 @@ new_iostate (SoupMessage *msg, SoupSocket *sock, SoupMessageIOMode mode, return io; } +/** + * soup_message_io_client: + * @msg: a #SoupMessage + * @sock: socket to send @msg across + * @get_headers_cb: callback function to generate request headers + * @parse_headers_cb: callback function to parse response headers + * @user_data: data to pass to the callbacks + * + * Begins the process of sending @msg across @sock. + * + * Don't call this. Use soup_message_send_request(). + **/ void soup_message_io_client (SoupMessage *msg, SoupSocket *sock, SoupMessageGetHeadersFn get_headers_cb, @@ -694,6 +713,18 @@ soup_message_io_client (SoupMessage *msg, SoupSocket *sock, io_write (sock, msg); } +/** + * soup_message_io_server: + * @msg: an empty #SoupServerMessage + * @sock: socket to receive a request on + * @get_headers_cb: callback function to generate response headers + * @parse_headers_cb: callback function to parse request headers + * @user_data: data to pass to the callbacks + * + * Begins the process of receiving a request from @sock into @msg. + * + * Don't use this. Use soup_message_receive_request() instead. + **/ void soup_message_io_server (SoupMessage *msg, SoupSocket *sock, SoupMessageGetHeadersFn get_headers_cb, @@ -712,6 +743,12 @@ soup_message_io_server (SoupMessage *msg, SoupSocket *sock, io_read (sock, msg); } +/** + * soup_message_io_pause: + * @msg: a #SoupMessage + * + * Pauses I/O on @msg. + **/ void soup_message_io_pause (SoupMessage *msg) { @@ -729,6 +766,12 @@ soup_message_io_pause (SoupMessage *msg) } } +/** + * soup_message_io_unpause: + * @msg: a #SoupMessage + * + * Resumes I/O on @msg. + **/ void soup_message_io_unpause (SoupMessage *msg) { diff --git a/libsoup/soup-message-private.h b/libsoup/soup-message-private.h index 1488867..c17bc78 100644 --- a/libsoup/soup-message-private.h +++ b/libsoup/soup-message-private.h @@ -25,7 +25,6 @@ struct SoupMessagePrivate { void soup_message_run_handlers (SoupMessage *msg, SoupHandlerPhase phase); -void soup_message_cleanup (SoupMessage *req); void soup_message_cleanup_response (SoupMessage *req); diff --git a/libsoup/soup-message-queue.c b/libsoup/soup-message-queue.c index 9b89381..d730dc3 100644 --- a/libsoup/soup-message-queue.c +++ b/libsoup/soup-message-queue.c @@ -21,6 +21,8 @@ struct SoupMessageQueue { /** * soup_message_queue_new: * + * Creates a new #SoupMessageQueue + * * Return value: a new #SoupMessageQueue object **/ SoupMessageQueue * @@ -145,7 +147,9 @@ queue_remove_internal (SoupMessageQueue *queue, SoupMessageQueueIter *iter) * @queue: a queue * @iter: pointer to an initialized #SoupMessageQueueIter * - * Return value: the next element of @queue, or %NULL if there are no more. + * Returns the next element of @queue + * + * Return value: the next element, or %NULL if there are no more. **/ SoupMessage * soup_message_queue_next (SoupMessageQueue *queue, SoupMessageQueueIter *iter) @@ -196,6 +200,13 @@ soup_message_queue_remove (SoupMessageQueue *queue, SoupMessageQueueIter *iter) return msg; } +/** + * soup_message_queue_remove_message: + * @queue: a queue + * @msg: a #SoupMessage + * + * Removes the indicated message from @queue. + **/ void soup_message_queue_remove_message (SoupMessageQueue *queue, SoupMessage *msg) { diff --git a/libsoup/soup-message-server-io.c b/libsoup/soup-message-server-io.c index 8a11442..96d8dc8 100644 --- a/libsoup/soup-message-server-io.c +++ b/libsoup/soup-message-server-io.c @@ -147,6 +147,13 @@ get_response_headers (SoupMessage *msg, GString *headers, g_string_append (headers, "\r\n"); } +/** + * soup_message_read_request: + * @req: an empty #SoupServerMessage + * @sock: socket to receive the request on + * + * Begins the process of receiving a request from @sock into @req. + **/ void soup_message_read_request (SoupMessage *req, SoupSocket *sock) { diff --git a/libsoup/soup-message.c b/libsoup/soup-message.c index aa256df..2960f74 100644 --- a/libsoup/soup-message.c +++ b/libsoup/soup-message.c @@ -309,18 +309,39 @@ soup_message_set_response (SoupMessage *msg, msg->response.length = resp_length; } +/** + * soup_message_wrote_informational: + * @msg: a #SoupMessage + * + * Emits the %wrote_informational signal, indicating that the IO layer + * finished writing an informational (1xx) response for @msg. + **/ void soup_message_wrote_informational (SoupMessage *msg) { g_signal_emit (msg, signals[WROTE_INFORMATIONAL], 0); } +/** + * soup_message_wrote_headers: + * @msg: a #SoupMessage + * + * Emits the %wrote_headers signal, indicating that the IO layer + * finished writing the (non-informational) headers for @msg. + **/ void soup_message_wrote_headers (SoupMessage *msg) { g_signal_emit (msg, signals[WROTE_HEADERS], 0); } +/** + * soup_message_wrote_chunk: + * @msg: a #SoupMessage + * + * Emits the %wrote_chunk signal, indicating that the IO layer + * finished writing a chunk of @msg's body. + **/ void soup_message_wrote_chunk (SoupMessage *msg) { @@ -335,12 +356,26 @@ wrote_body (SoupMessage *req) g_object_unref (req); } +/** + * soup_message_wrote_body: + * @msg: a #SoupMessage + * + * Emits the %wrote_body signal, indicating that the IO layer finished + * writing the body for @msg. + **/ void soup_message_wrote_body (SoupMessage *msg) { g_signal_emit (msg, signals[WROTE_BODY], 0); } +/** + * soup_message_got_informational: + * @msg: a #SoupMessage + * + * Emits the %got_informational signal, indicating that the IO layer + * read a complete informational (1xx) response for @msg. + **/ void soup_message_got_informational (SoupMessage *msg) { @@ -357,6 +392,13 @@ got_headers (SoupMessage *req) g_object_unref (req); } +/** + * soup_message_got_headers: + * @msg: a #SoupMessage + * + * Emits the %got_headers signal, indicating that the IO layer + * finished reading the (non-informational) headers for @msg. + **/ void soup_message_got_headers (SoupMessage *msg) { @@ -373,6 +415,13 @@ got_chunk (SoupMessage *req) g_object_unref (req); } +/** + * soup_message_got_chunk: + * @msg: a #SoupMessage + * + * Emits the %got_chunk signal, indicating that the IO layer finished + * reading a chunk of @msg's body. + **/ void soup_message_got_chunk (SoupMessage *msg) { @@ -389,6 +438,13 @@ got_body (SoupMessage *req) g_object_unref (req); } +/** + * soup_message_got_body: + * @msg: a #SoupMessage + * + * Emits the %got_body signal, indicating that the IO layer finished + * reading the body for @msg. + **/ void soup_message_got_body (SoupMessage *msg) { @@ -401,6 +457,13 @@ restarted (SoupMessage *req) soup_message_io_stop (req); } +/** + * soup_message_restarted: + * @msg: a #SoupMessage + * + * Emits the %restarted signal, indicating that @msg should be + * requeued. + **/ void soup_message_restarted (SoupMessage *msg) { @@ -414,6 +477,13 @@ finished (SoupMessage *req) req->status = SOUP_MESSAGE_STATUS_FINISHED; } +/** + * soup_message_finished: + * @msg: a #SoupMessage + * + * Emits the %finished signal, indicating that @msg has been completely + * processed. + **/ void soup_message_finished (SoupMessage *msg) { @@ -430,6 +500,13 @@ free_header_list (gpointer name, gpointer vals, gpointer user_data) return TRUE; } +/** + * soup_message_clear_headers: + * @hash: a header table (the %request_headers or %response_headers + * field of a #SoupMessage) + * + * Clears @hash. + **/ void soup_message_clear_headers (GHashTable *hash) { @@ -438,6 +515,15 @@ soup_message_clear_headers (GHashTable *hash) g_hash_table_foreach_remove (hash, free_header_list, NULL); } +/** + * soup_message_remove_header: + * @hash: a header table (the %request_headers or %response_headers + * field of a #SoupMessage) + * @name: the header name to remove + * + * Removes @name from @hash. If there are multiple values for @name, + * they are all removed. + **/ void soup_message_remove_header (GHashTable *hash, const char *name) { @@ -452,6 +538,17 @@ soup_message_remove_header (GHashTable *hash, const char *name) } } +/** + * soup_message_add_header: + * @hash: a header table (the %request_headers or %response_headers + * field of a #SoupMessage) + * @name: the header name to add + * @value: the value of the new header + * + * Adds a header with name @name and value @value to @hash. If there + * was already a header with name @name, this one does not replace it, + * it is merely added to it. + **/ void soup_message_add_header (GHashTable *hash, const char *name, const char *value) { @@ -473,14 +570,14 @@ soup_message_add_header (GHashTable *hash, const char *name, const char *value) /** * soup_message_get_header: - * @hash: a header hash table + * @hash: a header table (the %request_headers or %response_headers + * field of a #SoupMessage) * @name: header name. * - * Lookup the first transport header in @hash with a key equal to - * @name. + * Finds the first header in @hash with name @name. * * Return value: the header's value or %NULL if not found. - */ + **/ const char * soup_message_get_header (GHashTable *hash, const char *name) { @@ -498,15 +595,15 @@ soup_message_get_header (GHashTable *hash, const char *name) /** * soup_message_get_header_list: - * @hash: a header hash table + * @hash: a header table (the %request_headers or %response_headers + * field of a #SoupMessage) * @name: header name. * - * Lookup the all transport request headers in @hash with a key equal - * to @name. + * Finds all headers in @hash with name @name. * - * Return value: a const pointer to a #GSList of header values or - * %NULL if not found. - */ + * Return value: a (possibly empty) list of values of headers with + * name @name. The caller should not modify or free this list. + **/ const GSList * soup_message_get_header_list (GHashTable *hash, const char *name) { @@ -533,6 +630,17 @@ foreach_value_in_list (gpointer name, gpointer value, gpointer user_data) } } +/** + * soup_message_foreach_header: + * @hash: a header table (the %request_headers or %response_headers + * field of a #SoupMessage) + * @func: callback function to run for each header + * @user_data: data to pass to @func + * + * Calls @func once for each header value in @hash. (If there are + * headers will multiple values, @func will be called once on each + * value.) + **/ void soup_message_foreach_header (GHashTable *hash, GHFunc func, gpointer user_data) { @@ -546,6 +654,14 @@ soup_message_foreach_header (GHashTable *hash, GHFunc func, gpointer user_data) g_hash_table_foreach (hash, foreach_value_in_list, &data); } +/** + * soup_message_cleanup_response: + * @req: a #SoupMessage + * + * Cleans up all response data on @req, so that the request can be sent + * again and receive a new response. (Eg, as a result of a redirect or + * authorization request.) + **/ void soup_message_cleanup_response (SoupMessage *req) { @@ -567,6 +683,13 @@ soup_message_cleanup_response (SoupMessage *req) } } +/** + * soup_message_set_flags: + * @msg: a #SoupMessage + * @flags: a set of #SoupMessageFlags values + * + * Sets the specified flags on @msg. + **/ void soup_message_set_flags (SoupMessage *msg, guint flags) { @@ -575,6 +698,14 @@ soup_message_set_flags (SoupMessage *msg, guint flags) msg->priv->msg_flags = flags; } +/** + * soup_message_get_flags: + * @msg: a #SoupMessage + * + * Gets the flags on @msg + * + * Return value: the flags + **/ guint soup_message_get_flags (SoupMessage *msg) { @@ -583,6 +714,15 @@ soup_message_get_flags (SoupMessage *msg) return msg->priv->msg_flags; } +/** + * soup_message_set_http_version: + * @msg: a #SoupMessage + * @version: the HTTP version + * + * Sets the HTTP version on @msg. The default version is + * %SOUP_HTTP_1_1. Setting it to %SOUP_HTTP_1_0 will prevent certain + * functionality from being used. + **/ void soup_message_set_http_version (SoupMessage *msg, SoupHttpVersion version) { @@ -591,6 +731,15 @@ soup_message_set_http_version (SoupMessage *msg, SoupHttpVersion version) msg->priv->http_version = version; } +/** + * soup_message_get_http_version: + * @msg: a #SoupMessage + * + * Gets the HTTP version of @msg. This is the minimum of the + * version from the request and the version from the response. + * + * Return value: the HTTP version + **/ SoupHttpVersion soup_message_get_http_version (SoupMessage *msg) { @@ -599,6 +748,15 @@ soup_message_get_http_version (SoupMessage *msg) return msg->priv->http_version; } +/** + * soup_message_is_keepalive: + * @msg: a #SoupMessage + * + * Determines whether or not @msg's connection can be kept alive for + * further requests after processing @msg. + * + * Return value: %TRUE or %FALSE. + **/ gboolean soup_message_is_keepalive (SoupMessage *msg) { @@ -635,6 +793,14 @@ soup_message_is_keepalive (SoupMessage *msg) } } +/** + * soup_message_set_uri: + * @msg: a #SoupMessage + * @new_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) { @@ -651,6 +817,14 @@ soup_message_set_uri (SoupMessage *msg, const SoupUri *new_uri) msg->priv->uri = soup_uri_copy (new_uri); } +/** + * soup_message_get_uri: + * @msg: a #SoupMessage + * + * Gets @msg's URI + * + * Return value: the URI @msg is targeted for. + **/ const SoupUri * soup_message_get_uri (SoupMessage *msg) { @@ -659,6 +833,14 @@ soup_message_get_uri (SoupMessage *msg) return msg->priv->uri; } +/** + * soup_message_set_status: + * @msg: a #SoupMessage + * @status_code: an HTTP status code + * + * Sets @msg's status code to @status_code. If @status_code is a + * known value, it will also set @msg's reason_phrase. + **/ void soup_message_set_status (SoupMessage *msg, guint status_code) { @@ -671,6 +853,14 @@ soup_message_set_status (SoupMessage *msg, guint status_code) msg->reason_phrase = g_strdup (soup_status_get_phrase (status_code)); } +/** + * soup_message_set_status_full: + * @msg: a #SoupMessage + * @status_code: an HTTP status code + * @reason_phrase: a description of the status + * + * Sets @msg's status code and reason phrase. + **/ void soup_message_set_status_full (SoupMessage *msg, guint status_code, @@ -687,6 +877,16 @@ soup_message_set_status_full (SoupMessage *msg, } +/** + * soup_message_add_chunk: + * @msg: a #SoupMessage + * @owner: the ownership of @body + * @body: body data + * @length: length of @body + * + * Adds a chunk of response data to @body. (Note that currently + * there is no way to send a request using chunked encoding.) + **/ void soup_message_add_chunk (SoupMessage *msg, SoupOwnership owner, @@ -717,12 +917,30 @@ soup_message_add_chunk (SoupMessage *msg, } } +/** + * soup_message_add_final_chunk: + * @msg: a #SoupMessage + * + * Adds a final, empty chunk of response data to @body. This must + * be called after adding the last real chunk, to indicate that + * there is no more data. + **/ void soup_message_add_final_chunk (SoupMessage *msg) { soup_message_add_chunk (msg, SOUP_BUFFER_STATIC, NULL, 0); } +/** + * soup_message_pop_chunk: + * @msg: a #SoupMessage + * + * Pops a chunk of response data from @msg's chunk list. The caller + * must free @chunk itself, and must handle the data in @chunk + * according to its %ownership. + * + * Return value: the chunk, or %NULL if there are no chunks left. + **/ SoupDataBuffer * soup_message_pop_chunk (SoupMessage *msg) { diff --git a/libsoup/soup-message.h b/libsoup/soup-message.h index a248e43..af2b28d 100644 --- a/libsoup/soup-message.h +++ b/libsoup/soup-message.h @@ -138,26 +138,12 @@ void soup_message_set_uri (SoupMessage *msg, typedef enum { /* - * SOUP_MESSAGE_NO_PIPELINE: - * Use a currently unused connection or establish a new - * connection when issuing this request. - */ - SOUP_MESSAGE_NO_PIPELINE = (1 << 0), - - /* * SOUP_MESSAGE_NO_REDIRECT: * Do not follow redirection responses. */ SOUP_MESSAGE_NO_REDIRECT = (1 << 1), /* - * SOUP_MESSAGE_NO_COOKIE: - * Do not send cookie information with request, and do not - * store cookie information from the response. - */ - SOUP_MESSAGE_NO_COOKIE = (1 << 2), - - /* * 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 diff --git a/libsoup/soup-method.c b/libsoup/soup-method.c index 74af5f0..7f9d33d 100644 --- a/libsoup/soup-method.c +++ b/libsoup/soup-method.c @@ -9,8 +9,17 @@ #include "soup-method.h" +/** + * soup_method_get_id: + * @method: an HTTP method + * + * Converts @method into a corresponding #SoupMethodId (possibly + * %SOUP_METHOD_ID_UNKNOWN). + * + * Return value: the #SoupMethodId + **/ SoupMethodId -soup_method_get_id (const gchar *method) +soup_method_get_id (const char *method) { g_return_val_if_fail (method != NULL, SOUP_METHOD_ID_UNKNOWN); diff --git a/libsoup/soup-misc.c b/libsoup/soup-misc.c index add473f..500caad 100644 --- a/libsoup/soup-misc.c +++ b/libsoup/soup-misc.c @@ -10,19 +10,36 @@ #include "soup-misc.h" +/** + * soup_str_case_hash: + * @key: ASCII string to hash + * + * Hashes @key in a case-insensitive manner. + * + * Return value: the hash code. + **/ guint soup_str_case_hash (gconstpointer key) { const char *p = key; - guint h = toupper(*p); + guint h = g_ascii_toupper(*p); if (h) for (p += 1; *p != '\0'; p++) - h = (h << 5) - h + toupper(*p); + h = (h << 5) - h + g_ascii_toupper(*p); return h; } +/** + * soup_str_case_equal: + * @v1: an ASCII string + * @v2: another ASCII string + * + * Compares @v1 and @v2 in a case-insensitive manner + * + * Return value: %TRUE if they are equal (modulo case) + **/ gboolean soup_str_case_equal (gconstpointer v1, gconstpointer v2) @@ -30,7 +47,7 @@ soup_str_case_equal (gconstpointer v1, const char *string1 = v1; const char *string2 = v2; - return g_strcasecmp (string1, string2) == 0; + return g_ascii_strcasecmp (string1, string2) == 0; } /* Base64 utils (straight from camel-mime-utils.c) */ diff --git a/libsoup/soup-soap-message.c b/libsoup/soup-soap-message.c index 6439744..3d552ac 100644 --- a/libsoup/soup-soap-message.c +++ b/libsoup/soup-soap-message.c @@ -238,7 +238,7 @@ soup_soap_message_start_body (SoupSoapMessage *msg) } /** - * soup_soap_end_body: + * soup_soap_message_end_body: * @msg: the %SoupSoapMessage. * * Closes the SOAP Body element. @@ -613,7 +613,7 @@ soup_soap_message_add_namespace (SoupSoapMessage *msg, const char *prefix, const } /** - * soup_soap_set_default_namespace: + * soup_soap_message_set_default_namespace: * @msg: the %SoupSoapMessage. * @ns_uri: the namespace URI. * @@ -699,9 +699,11 @@ soup_soap_message_persist (SoupSoapMessage *msg) * @msg: the %SoupSoapMessage. * @ns_uri: the namespace URI. * - * Return value: The namespace prefix for @ns_uri or an empty string if @ns_uri - * is set to the default namespace. If no namespace exists for the URI given, - * NULL is returned. + * Returns the namespace prefix for @ns_uri (or an empty string if + * @ns_uri is set to the default namespace) + * + * Return value: The namespace prefix, or %NULL if no namespace exists + * for the URI given. */ const char * soup_soap_message_get_namespace_prefix (SoupSoapMessage *msg, const char *ns_uri) diff --git a/libsoup/soup-socket.c b/libsoup/soup-socket.c index 2e05a64..1d1aaf4 100644 --- a/libsoup/soup-socket.c +++ b/libsoup/soup-socket.c @@ -319,7 +319,9 @@ get_property (GObject *object, guint prop_id, * @optname1: name of first property to set (or %NULL) * @...: value of @optname1, followed by additional property/value pairs * - * Return value: a new (disconnected) socket + * Creates a new (disconnected) socket + * + * Return value: the new socket **/ SoupSocket * soup_socket_new (const char *optname1, ...) @@ -727,6 +729,13 @@ soup_socket_server_new (SoupAddress *local_addr, gpointer ssl_creds, } +/** + * soup_socket_disconnect: + * @sock: a #SoupSocket + * + * Disconnects @sock. Any further read or write attempts on it will + * fail. + **/ void soup_socket_disconnect (SoupSocket *sock) { @@ -771,6 +780,14 @@ soup_socket_disconnect (SoupSocket *sock) g_signal_emit (sock, signals[DISCONNECTED], 0); } +/** + * soup_socket_is_connected: + * @sock: a #SoupSocket + * + * Tests if @sock is connected to another host + * + * Return value: %TRUE or %FALSE. + **/ gboolean soup_socket_is_connected (SoupSocket *sock) { @@ -779,7 +796,14 @@ soup_socket_is_connected (SoupSocket *sock) return sock->priv->iochannel != NULL; } - +/** + * soup_socket_get_local_address: + * @sock: a #SoupSocket + * + * Returns the #SoupAddress corresponding to the local end of @sock. + * + * Return value: the #SoupAddress + **/ SoupAddress * soup_socket_get_local_address (SoupSocket *sock) { @@ -799,6 +823,14 @@ soup_socket_get_local_address (SoupSocket *sock) return sock->priv->local_addr; } +/** + * soup_socket_get_remote_address: + * @sock: a #SoupSocket + * + * Returns the #SoupAddress corresponding to the remote end of @sock. + * + * Return value: the #SoupAddress + **/ SoupAddress * soup_socket_get_remote_address (SoupSocket *sock) { diff --git a/libsoup/soup-status.c b/libsoup/soup-status.c index 83b5bad..48f8f11 100644 --- a/libsoup/soup-status.c +++ b/libsoup/soup-status.c @@ -84,6 +84,14 @@ struct { { 0 } }; +/** + * soup_status_get_phrase: + * @status_code: an HTTP status code + * + * Looks up the stock HTTP description of @status_code. + * + * Return value: the (English) description of @status_code + **/ const char * soup_status_get_phrase (guint status_code) { diff --git a/libsoup/soup-status.h b/libsoup/soup-status.h index f0154ab..3a72704 100644 --- a/libsoup/soup-status.h +++ b/libsoup/soup-status.h @@ -17,12 +17,12 @@ typedef enum { SOUP_STATUS_CLASS_SERVER_ERROR } SoupStatusClass; -#define SOUP_STATUS_IS_TRANSPORT_ERROR(x) ((x) > 0 && (x) < 100) -#define SOUP_STATUS_IS_INFORMATIONAL(x) ((x) >= 100 && (x) < 200) -#define SOUP_STATUS_IS_SUCCESSFUL(x) ((x) >= 200 && (x) < 300) -#define SOUP_STATUS_IS_REDIRECTION(x) ((x) >= 300 && (x) < 400) -#define SOUP_STATUS_IS_CLIENT_ERROR(x) ((x) >= 400 && (x) < 500) -#define SOUP_STATUS_IS_SERVER_ERROR(x) ((x) >= 500 && (x) < 600) +#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) +#define SOUP_STATUS_IS_REDIRECTION(status) ((status) >= 300 && (status) < 400) +#define SOUP_STATUS_IS_CLIENT_ERROR(status) ((status) >= 400 && (status) < 500) +#define SOUP_STATUS_IS_SERVER_ERROR(status) ((status) >= 500 && (status) < 600) typedef enum { SOUP_STATUS_NONE, diff --git a/libsoup/soup-uri.c b/libsoup/soup-uri.c index 8e57f51..2cfeb3a 100644 --- a/libsoup/soup-uri.c +++ b/libsoup/soup-uri.c @@ -271,6 +271,8 @@ append_uri (GString *str, const char *in, const char *extra_enc_chars, * @uri: a #SoupUri * @just_path: if %TRUE, output just the path and query portions * + * Returns a string representing @uri. + * * Return value: a string representing @uri, which the caller must free. **/ char * @@ -321,6 +323,14 @@ soup_uri_to_string (const SoupUri *uri, gboolean just_path) return return_result; } +/** + * soup_uri_copy: + * @uri: a #SoupUri + * + * Copies @uri + * + * Return value: a copy of @uri, which must be freed with soup_uri_free() + **/ SoupUri * soup_uri_copy (const SoupUri *uri) { @@ -343,6 +353,16 @@ soup_uri_copy (const SoupUri *uri) return dup; } +/** + * soup_uri_copy_root: + * @uri: a #SoupUri + * + * Copies the protocol, host, and port of @uri into a new #SoupUri + * (all other fields in the new URI will be empty.) + * + * Return value: a partial copy of @uri, which must be freed with + * soup_uri_free() + **/ SoupUri * soup_uri_copy_root (const SoupUri *uri) { @@ -368,6 +388,15 @@ parts_equal (const char *one, const char *two) return !strcmp (one, two); } +/** + * soup_uri_equal: + * @u1: a #SoupUri + * @u2: another #SoupUri + * + * Tests whether or not @u1 and @u2 are equal in all parts + * + * Return value: %TRUE or %FALSE + **/ gboolean soup_uri_equal (const SoupUri *u1, const SoupUri *u2) { @@ -384,6 +413,12 @@ soup_uri_equal (const SoupUri *u1, const SoupUri *u2) return TRUE; } +/** + * soup_uri_free: + * @uri: a #SoupUri + * + * Frees @uri. + **/ void soup_uri_free (SoupUri *uri) { @@ -483,6 +518,15 @@ soup_uri_decode (char *part) } while (*s++); } +/** + * soup_uri_uses_default_port: + * @uri: a #SoupUri + * + * Tests if @uri uses the default port for its protocol. (Eg, 80 for + * http.) + * + * Return value: %TRUE or %FALSE + **/ gboolean soup_uri_uses_default_port (const SoupUri *uri) { -- 2.7.4