2008-02-09 Dan Winship <danw@gnome.org>
+ * Misc gtk-doc fix-ups
+
+2008-02-09 Dan Winship <danw@gnome.org>
+
* libsoup/soup-misc.h: remove prototype for
soup_signal_connect_once, which is only used by soup-connection
now, and will go away once that code is rewritten.
soup-types.h soup-enum-types.h \
soup-auth-basic.h soup-auth-digest.h soup-auth-ntlm.h \
soup-connection.h soup-connection-ntlm.h \
- soup-dns.h soup-auth-manager.h soup-md5-utils.h \
+ soup-dns.h soup-auth-manager.h soup-auth-manager-ntlm.h \
soup-message-queue.h soup-path-map.h soup-ssl.h
# Images to copy into HTML directory.
soup_message_get_http_version
soup_message_get_uri
soup_message_set_uri
-SoupMessageFlags
-soup_message_set_flags
-soup_message_get_flags
<SUBSECTION>
soup_message_set_status
soup_message_set_status_full
soup_message_add_header_handler
soup_message_add_status_code_handler
<SUBSECTION>
+SoupMessageFlags
+soup_message_set_flags
+soup_message_get_flags
+SoupChunkAllocator
+soup_message_set_chunk_allocator
+<SUBSECTION>
SOUP_MESSAGE_METHOD
SOUP_MESSAGE_URI
SOUP_MESSAGE_HTTP_VERSION
SOUP_METHOD_DELETE
SOUP_METHOD_TRACE
SOUP_METHOD_CONNECT
+<SUBSECTION>
SOUP_METHOD_PROPFIND
SOUP_METHOD_PROPPATCH
SOUP_METHOD_MKCOL
SOUP_METHOD_MOVE
SOUP_METHOD_LOCK
SOUP_METHOD_UNLOCK
-SOUP_METHOD_PATCH
</SECTION>
<SECTION>
soup_message_headers_remove
soup_message_headers_clear
soup_message_headers_get
+<SUBSECTION>
SoupMessageHeadersForeachFunc
soup_message_headers_foreach
<SUBSECTION>
+SoupMessageHeadersIter
+soup_message_headers_iter_init
+soup_message_headers_iter_next
+<SUBSECTION>
SoupEncoding
soup_message_headers_get_encoding
soup_message_headers_set_encoding
SoupExpectation
soup_message_headers_get_expectations
soup_message_headers_set_expectations
+<SUBSECTION Standard>
+SOUP_TYPE_MESSAGE_HEADERS
+soup_message_headers_get_type
</SECTION>
<SECTION>
SoupMemoryUse
soup_buffer_new
soup_buffer_new_subbuffer
+soup_buffer_new_with_owner
+soup_buffer_get_owner
soup_buffer_copy
soup_buffer_free
<SUBSECTION>
<SUBSECTION Standard>
SOUP_TYPE_BUFFER
soup_buffer_get_type
+SOUP_TYPE_MESSAGE_BODY
+soup_message_body_get_type
</SECTION>
<SECTION>
SOUP_SERVER_SSL_KEY_FILE
SOUP_SERVER_ASYNC_CONTEXT
SOUP_SERVER_RAW_PATHS
+SOUP_SERVER_SERVER_HEADER
<SUBSECTION Standard>
SOUP_SERVER
SOUP_IS_SERVER
soup_auth_domain_set_filter
soup_auth_domain_get_realm
<SUBSECTION>
+SoupAuthDomainGenericAuthCallback
+soup_auth_domain_set_generic_auth_callback
+soup_auth_domain_check_password
+<SUBSECTION>
soup_auth_domain_covers
soup_auth_domain_accepts
soup_auth_domain_challenge
SOUP_AUTH_DOMAIN_REMOVE_PATH
SOUP_AUTH_DOMAIN_FILTER
SOUP_AUTH_DOMAIN_FILTER_DATA
+SOUP_AUTH_DOMAIN_GENERIC_AUTH_CALLBACK
+SOUP_AUTH_DOMAIN_GENERIC_AUTH_DATA
+<SUBSECTION Private>
+soup_auth_domain_try_generic_auth_callback
<SUBSECTION Standard>
SOUP_AUTH_DOMAIN
SOUP_IS_AUTH_DOMAIN
soup_auth_domain_digest_set_auth_callback
soup_auth_domain_digest_encode_password
<SUBSECTION>
-soup_auth_domain_digest_evil_check_password
-<SUBSECTION>
SOUP_AUTH_DOMAIN_DIGEST_AUTH_CALLBACK
SOUP_AUTH_DOMAIN_DIGEST_AUTH_DATA
<SUBSECTION Standard>
soup_address_get_sockaddr
soup_address_get_physical
soup_address_get_port
+<SUBSECTION>
+SOUP_ADDRESS_FAMILY
+SOUP_ADDRESS_NAME
+SOUP_ADDRESS_PHYSICAL
+SOUP_ADDRESS_PORT
+SOUP_ADDRESS_SOCKADDR
<SUBSECTION Standard>
SOUP_ADDRESS
SOUP_IS_ADDRESS
SOUP_SESSION_SSL_CA_FILE
SOUP_SESSION_ASYNC_CONTEXT
SOUP_SESSION_TIMEOUT
+SOUP_SESSION_USER_AGENT
<SUBSECTION Standard>
SOUP_IS_SESSION
SOUP_IS_SESSION_CLASS
soup_uri_set_path
soup_uri_set_query
soup_uri_set_query_from_form
+soup_uri_set_query_from_fields
soup_uri_set_fragment
<SUBSECTION Standard>
SOUP_TYPE_URI
soup_date_new_from_time_t
soup_date_new_from_now
soup_date_to_string
+soup_date_to_time_t
soup_date_free
<SUBSECTION>
-soup_form_decode_urlencoded
-soup_form_encode_urlencoded
-soup_form_encode_urlencoded_list
+soup_form_decode
+soup_form_encode
+soup_form_encode_datalist
+soup_form_encode_hash
+soup_form_encode_valist
+soup_form_request_new
+soup_form_request_new_from_datalist
+soup_form_request_new_from_hash
<SUBSECTION>
soup_headers_parse_request
soup_headers_parse_response
soup_ssl_supported
<SUBSECTION Private>
soup_date_copy
-soup_signal_connect_once
SOUP_TYPE_DATE
soup_date_get_type
+soup_form_decode_urlencoded
+soup_form_encode_urlencoded
+soup_form_encode_urlencoded_list
</SECTION>
<SECTION>
SOUP_XMLRPC_ERROR
SoupXMLRPCError
SOUP_XMLRPC_FAULT
+SoupXMLRPCFault
<SUBSECTION Private>
soup_xmlrpc_error_quark
soup_xmlrpc_fault_quark
<FILE>soup-value-utils</FILE>
<TITLE>GValue Support</TITLE>
soup_value_hash_new
+soup_value_hash_new_with_vals
soup_value_hash_insert_value
soup_value_hash_insert
+soup_value_hash_insert_vals
soup_value_hash_lookup
+soup_value_hash_lookup_vals
<SUBSECTION>
soup_value_array_from_args
soup_value_array_to_args
+soup_value_array_new
+soup_value_array_new_with_vals
soup_value_array_insert
soup_value_array_append
+soup_value_array_append_vals
soup_value_array_get_nth
<SUBSECTION>
SOUP_VALUE_SETV
* SECTION:soup-address
* @short_description: DNS support
*
- * #SoupAddress represents the address of a TCP connection endpoint;
+ * #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.)
*
/**
* SoupAddressFamily:
+ * @SOUP_ADDRESS_FAMILY_INVALID: an invalid %SoupAddress
* @SOUP_ADDRESS_FAMILY_IPV4: an IPv4 address
* @SOUP_ADDRESS_FAMILY_IPV6: an IPv6 address
*
* @callback: callback to call with the result
* @user_data: data for @callback
*
- * Asynchronously resolves the missing half of @addr. (Its IP address
+ * Asynchronously resolves the missing half of @addr (its IP address
* if it was created with soup_address_new(), or its hostname if it
* was created with soup_address_new_from_sockaddr() or
* soup_address_new_any().)
* If you need finer control over what message parts are and aren't
* logged, use soup_logger_set_request_filter() and
* soup_logger_set_response_filter().
+ *
+ * Returns: a new #SoupLogger
**/
SoupLogger *
soup_logger_new (SoupLoggerLogLevel level, int max_body_size)
#define SOUP_IS_LOGGER_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((obj), SOUP_TYPE_LOGGER))
#define SOUP_LOGGER_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), SOUP_TYPE_LOGGER, SoupLoggerClass))
-typedef struct SoupLogger SoupLogger;
-typedef struct SoupLoggerClass SoupLoggerClass;
-
typedef enum {
SOUP_LOGGER_LOG_NONE,
SOUP_LOGGER_LOG_MINIMAL,
SOUP_LOGGER_LOG_BODY
} SoupLoggerLogLevel;
-typedef SoupLoggerLogLevel (*SoupLoggerFilter) (SoupLogger *logger,
- SoupMessage *msg,
- gpointer user_data);
-
-typedef void (*SoupLoggerPrinter) (SoupLogger *logger,
- SoupLoggerLogLevel level,
- char direction,
- const char *data,
- gpointer user_data);
-
-struct SoupLogger {
+typedef struct {
GObject parent;
-};
+} SoupLogger;
-struct SoupLoggerClass {
+typedef struct {
GObjectClass parent_class;
/* Padding for future expansion */
void (*_libsoup_reserved2) (void);
void (*_libsoup_reserved3) (void);
void (*_libsoup_reserved4) (void);
-};
+} SoupLoggerClass;
+
+typedef SoupLoggerLogLevel (*SoupLoggerFilter) (SoupLogger *logger,
+ SoupMessage *msg,
+ gpointer user_data);
+
+typedef void (*SoupLoggerPrinter) (SoupLogger *logger,
+ SoupLoggerLogLevel level,
+ char direction,
+ const char *data,
+ gpointer user_data);
GType soup_logger_get_type (void);
return body;
}
+/**
+ * soup_message_body_free:
+ * @body: a #SoupMessageBody
+ *
+ * Frees @body. You will not normally need to use this, as
+ * #SoupMessage frees its associated message bodies automatically.
+ **/
void
soup_message_body_free (SoupMessageBody *body)
{
* with a request or response.
**/
+/**
+ * SoupMessageHeadersType:
+ * @SOUP_MESSAGE_HEADERS_REQUEST: request headers
+ * @SOUP_MESSAGE_HEADERS_RESPONSE: response headers
+ *
+ * Value passed to soup_message_headers_new() to set certain default
+ * behaviors.
+ **/
+
typedef void (*SoupHeaderSetter) (SoupMessageHeaders *, const char *);
static const char *intern_header_name (const char *name, SoupHeaderSetter *setter);
}
/**
+ * SoupExpectation:
+ * @SOUP_EXPECTATION_CONTINUE: "100-continue"
+ * @SOUP_EXPECTATION_UNRECOGNIZED: any unrecognized expectation
+ *
+ * Represents the parsed value of the "Expect" header.
+ **/
+
+/**
* soup_message_headers_get_expectations:
* @hdrs: a #SoupMessageHeaders
*
* large message body (eg, via POST or PUT), and want to give the
* server a chance to reject the request after seeing just the headers
* (eg, because it will require authentication before allowing you to
- * post). This saves you from having to transmit the large request
- * body when the server is just going to ignore it anyway.
+ * post, or because you're POSTing to a URL that doesn't exist). This
+ * saves you from having to transmit the large request body when the
+ * server is just going to ignore it anyway.
**/
void
soup_message_headers_set_expectations (SoupMessageHeaders *hdrs,
gpointer user_data);
typedef struct {
+ /*< private >*/
gpointer dummy[3];
} SoupMessageHeadersIter;
* @short_description: An HTTP request and response.
* @see_also: #SoupMessageHeaders, #SoupMessageBody
*
+ * A #SoupMessage represents an HTTP message that is being sent or
+ * received.
+ *
+ * For client-side usage, you would create a #SoupMessage with
+ * soup_message_new() or soup_message_new_from_uri(), set up its
+ * fields appropriate, and send it via a #SoupSession.
+ *
+ * For server-side usage, #SoupServer will create #SoupMessage<!--
+ * -->s automatically for incoming requests, which your application
+ * will receive via handlers.
+ *
+ * Note that libsoup's terminology here does not quite match the HTTP
+ * specification: in RFC 2616, an "HTTP-message" is
+ * <emphasis>either</emphasis> a Request, <emphasis>or</emphasis> a
+ * Response. In libsoup, a #SoupMessage combines both the request and
+ * the response.
**/
/**
* @...: value of @optname1, followed by additional property/value pairs
*
* Creates a new #SoupServer.
+ *
+ * Return value: a new #SoupServer
**/
SoupServer *
soup_server_new (const char *optname1, ...)
/**
* SECTION:soup-session-sync
- * @short_description: Soup session for blocking I/O in multithreaded programs.
+ * @short_description: 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.
+ *
+ * You can use #SoupSessionSync from multiple threads concurrently.
+ * Eg, you can send a #SoupMessage in one thread, and then while
+ * waiting for the response, send another #SoupMessage from another
+ * thread. You can also send a message from one thread and then call
+ * soup_session_cancel_message() on it from any other thread (although
+ * you need to be careful to avoid race conditions, where the message
+ * finishes and is then unreffed by the sending thread just before you
+ * cancel it).
+ *
+ * However, the majority of other types and methods in libsoup are not
+ * MT-safe. In particular, you <emphasis>cannot</emphasis> modify or
+ * examine a #SoupMessage while it is being transmitted by
+ * #SoupSessionSync in another thread. Once a message has been handed
+ * off to #SoupSessionSync, it can only be manipulated from its signal
+ * handler callbacks, until I/O is complete.
**/
typedef struct {
* SECTION:soup-session
* @short_description: Soup session state object
*
+ * #SoupSession is the object that controls client-side HTTP. A
+ * #SoupSession encapsulates all of the state that libsoup is keeping
+ * on behalf of your program; cached HTTP connections, authentication
+ * information, etc.
+ *
+ * Most applications will only need a single #SoupSession; the primary
+ * reason you might need multiple sessions is if you need to have
+ * multiple independent authentication contexts. (Eg, you are
+ * connecting to a server and authenticating as two different users at
+ * different times; the easiest way to ensure that each #SoupMessage
+ * is sent with the authentication information you intended is to use
+ * one session for the first user, and a second session for the other
+ * user.)
+ *
+ * #SoupSession itself is an abstract class, with two subclasses. If
+ * you are using the glib main loop, you will generally want to use
+ * #SoupSessionAsync, which uses non-blocking I/O and callbacks. On
+ * the other hand, if your application is threaded and you want to do
+ * synchronous I/O in a separate thread from the UI, use
+ * #SoupSessionSync.
**/
typedef struct {
}
/**
+ * SoupSessionCallback:
+ * @session: the session
+ * @msg: the message that has finished
+ * @user_data: the data passed to soup_session_queue_message
+ *
+ * Prototype for the callback passed to soup_session_queue_message(),
+ * qv.
+ **/
+
+/**
* soup_session_queue_message:
* @session: a #SoupSession
* @msg: the message to queue
* SECTION:soup-socket
* @short_description: A network socket
*
+ * #SoupSocket is libsoup's TCP socket type. While it is primarily
+ * intended for internal use, #SoupSocket<!-- -->s are exposed in the
+ * API in various places, and some of their methods (eg,
+ * soup_socket_get_remote_address()) may be useful to applications.
**/
G_DEFINE_TYPE (SoupSocket, soup_socket, G_TYPE_OBJECT)
return TRUE;
}
+/**
+ * soup_socket_is_ssl:
+ * @sock: a #SoupSocket
+ *
+ * Tests if @sock is set up to do SSL. Note that this simply means
+ * that the %SOUP_SOCKET_SSL_CREDENTIALS property has been set; it
+ * does not mean that soup_socket_start_ssl() has been called.
+ *
+ * Return value: %TRUE if @sock has SSL credentials set
+ **/
gboolean
soup_socket_is_ssl (SoupSocket *sock)
{
* SECTION:soup-value-utils
* @short_description: #GValue utilities
*
+ * These methods are useful for manipulating #GValue<!-- -->s, and in
+ * particular, arrays and hash tables of #GValue<!-- -->s, in a
+ * slightly nicer way than the standard #GValue API.
+ *
+ * They are written for use with soup-xmlrpc, but they also work with
+ * types not used by XML-RPC.
**/
/**
*
* Creates a #GHashTable whose keys are strings and whose values
* are #GValue.
+ *
+ * Return value: a new empty #GHashTable
**/
GHashTable *
soup_value_hash_new (void)
* are #GValue, and initializes it with the provided data. As
* with soup_value_hash_insert(), the keys and values are copied
* rather than being inserted directly.
+ *
+ * Return value: a new #GHashTable, initialized with the given values
**/
GHashTable *
soup_value_hash_new_with_vals (const char *first_key, ...)
}
/**
- * soup_value_array_append_values:
+ * soup_value_array_append_vals:
* @array: a #GValueArray
* @first_type: the type of the first value to add
* @...: the first value to add, followed by other type/value
g_byte_array_free (ba, TRUE);
}
+/**
+ * SOUP_TYPE_BYTE_ARRAY:
+ *
+ * glib does not define a #GType for #GByteArray, so libsoup
+ * defines this one itself.
+ **/
GType
soup_byte_array_get_type (void)
{
if (g_once_init_enter (&type_volatile)) {
GType type = g_boxed_type_register_static (
- g_intern_static_string ("GByteArray"),
+ g_intern_static_string ("SoupByteArray"),
(GBoxedCopyFunc) soup_byte_array_copy,
(GBoxedFreeFunc) soup_byte_array_free);
g_once_init_leave (&type_volatile, type);