+2008-10-01 Dan Winship <danw@gnome.org>
+
+ * libsoup/soup-cookie-jar.c:
+ * libsoup/soup-cookie.c:
+ * libsoup/soup-cookie.h:
+ * libsoup/soup-headers.c:
+ * libsoup/soup-logger.c:
+ * libsoup/soup-session-feature.c:
+ * libsoup/soup-session-feature.h:
+ * libsoup/soup-session.c: doc fixups
+
+ * docs/reference/libsoup-2.4-docs.sgml:
+ * docs/reference/libsoup-2.4-sections.txt:
+ * docs/reference/libsoup-2.4.types: Add missing bits
+
2008-09-30 Dan Winship <danw@gnome.org>
* libsoup/soup-xmlrpc.c (parse_value):
<xi:include href="xml/soup-auth-domain.xml"/>
<xi:include href="xml/soup-auth-domain-basic.xml"/>
<xi:include href="xml/soup-auth-domain-digest.xml"/>
+ <xi:include href="xml/soup-cookie.xml"/>
+ <xi:include href="xml/soup-cookie-jar.xml"/>
<xi:include href="xml/soup-logger.xml"/>
<xi:include href="xml/soup-message.xml"/>
<xi:include href="xml/soup-message-headers.xml"/>
<SUBSECTION>
soup_session_get_async_context
<SUBSECTION>
+SoupSessionFeature
+soup_session_add_feature
+soup_session_add_feature_by_type
+soup_session_remove_feature
+soup_session_remove_feature_by_type
+<SUBSECTION>
SOUP_SESSION_PROXY_URI
SOUP_SESSION_MAX_CONNS
SOUP_SESSION_MAX_CONNS_PER_HOST
SOUP_SESSION_TIMEOUT
SOUP_SESSION_IDLE_TIMEOUT
SOUP_SESSION_USER_AGENT
+SOUP_SESSION_ADD_FEATURE
+SOUP_SESSION_ADD_FEATURE_BY_TYPE
+SOUP_SESSION_REMOVE_FEATURE_BY_TYPE
<SUBSECTION Standard>
SOUP_IS_SESSION
SOUP_IS_SESSION_CLASS
SOUP_TYPE_SESSION
SoupSessionClass
soup_session_get_type
+<SUBSECTION Private>
+soup_session_feature_attach
+soup_session_feature_detach
+SoupSessionFeatureInterface
+soup_session_feature_get_type
+SOUP_SESSION_FEATURE
+SOUP_SESSION_FEATURE_CLASS
+SOUP_SESSION_FEATURE_GET_CLASS
+SOUP_IS_SESSION_FEATURE
+SOUP_IS_SESSION_FEATURE_CLASS
+SOUP_TYPE_SESSION_FEATURE
</SECTION>
<SECTION>
SOUP_URI_SCHEME_HTTP
SOUP_URI_SCHEME_HTTPS
soup_uri_uses_default_port
+SOUP_URI_VALID_FOR_HTTP
<SUBSECTION>
soup_uri_set_scheme
soup_uri_set_user
soup_date_new_from_now
soup_date_to_string
soup_date_to_time_t
+soup_date_to_timeval
+soup_date_is_past
soup_date_free
<SUBSECTION>
soup_form_decode
soup_header_free_list
soup_header_contains
soup_header_parse_param_list
+soup_header_parse_semi_param_list
soup_header_free_param_list
<SUBSECTION>
soup_str_case_equal
SOUP_LOGGER_GET_CLASS
SOUP_TYPE_LOGGER
</SECTION>
+
+<SECTION>
+<FILE>soup-cookie</FILE>
+<TITLE>SoupCookie</TITLE>
+SoupCookie
+soup_cookie_new
+soup_cookie_parse
+soup_cookie_free
+<SUBSECTION>
+soup_cookie_set_name
+soup_cookie_set_value
+soup_cookie_set_domain
+soup_cookie_set_path
+soup_cookie_set_max_age
+SOUP_COOKIE_MAX_AGE_ONE_HOUR
+SOUP_COOKIE_MAX_AGE_ONE_DAY
+SOUP_COOKIE_MAX_AGE_ONE_WEEK
+SOUP_COOKIE_MAX_AGE_ONE_YEAR
+soup_cookie_set_expires
+soup_cookie_set_secure
+soup_cookie_set_http_only
+<SUBSECTION>
+soup_cookie_applies_to_uri
+<SUBSECTION>
+soup_cookie_to_cookie_header
+soup_cookie_to_set_cookie_header
+<SUBSECTION>
+soup_cookies_from_request
+soup_cookies_from_response
+soup_cookies_to_request
+soup_cookies_to_response
+soup_cookies_to_cookie_header
+soup_cookies_free
+</SECTION>
+
+<SECTION>
+<FILE>soup-cookie-jar</FILE>
+<TITLE>SoupCookieJar</TITLE>
+SoupCookieJar
+soup_cookie_jar_new
+soup_cookie_jar_save
+soup_cookie_jar_get_cookies
+soup_cookie_jar_set_cookie
+<SUBSECTION Standard>
+SoupCookieJarClass
+SOUP_COOKIE_JAR
+SOUP_COOKIE_JAR_CLASS
+SOUP_COOKIE_JAR_GET_CLASS
+SOUP_IS_COOKIE_JAR
+SOUP_IS_COOKIE_JAR_CLASS
+SOUP_TYPE_COOKIE_JAR
+soup_cookie_jar_get_type
+</SECTION>
soup_auth_domain_get_type
soup_auth_domain_basic_get_type
soup_auth_domain_digest_get_type
+soup_cookie_jar_get_type
+soup_logger_get_type
soup_message_get_type
soup_server_get_type
soup_session_get_type
soup_session_sync_get_type
soup_session_async_get_type
+soup_session_feature_get_type
soup_socket_get_type
/**
* SECTION:soup-cookie-jar
- * @short_description:
+ * @short_description: Automatic cookie handling for #SoupSession
*
* A #SoupCookieJar stores #SoupCookie<!-- -->s and arrange for them
* to be sent with the appropriate #SoupMessage<!-- -->s.
* url="http://msdn2.microsoft.com/en-us/library/ms533046.aspx">Microsoft's
* HttpOnly extension attribute</ulink>, and observed real-world usage
* (and, in particular, based on what Firefox does).
+ *
+ * To have a #SoupSession handle cookies for your appliction
+ * automatically, use a #SoupCookieJar.
**/
/**
/**
* soup_cookie_parse:
- * @cookie: a cookie string (eg, the value of a Set-Cookie header)
+ * @header: a cookie string (eg, the value of a Set-Cookie header)
* @origin: origin of the cookie, or %NULL
*
- * Parses @cookie and returns a #SoupCookie. (If @cookie contains
+ * Parses @header and returns a #SoupCookie. (If @header contains
* multiple cookies, only the first one will be parsed.)
*
- * If @cookie does not have "path" or "domain" attributes, they will
+ * If @header does not have "path" or "domain" attributes, they will
* be defaulted from @origin. If @origin is %NULL, path will default
* to "/", but domain will be left as %NULL. Note that this is not a
* valid state for a #SoupCookie, and you will need to fill in some
}
/**
+ * SOUP_COOKIE_MAX_AGE_ONE_HOUR:
+ *
+ * A constant corresponding to 1 hour, for use with soup_cookie_new()
+ * and soup_cookie_set_max_age().
+ **/
+/**
+ * SOUP_COOKIE_MAX_AGE_ONE_DAY:
+ *
+ * A constant corresponding to 1 day, for use with soup_cookie_new()
+ * and soup_cookie_set_max_age().
+ **/
+/**
+ * SOUP_COOKIE_MAX_AGE_ONE_WEEK:
+ *
+ * A constant corresponding to 1 week, for use with soup_cookie_new()
+ * and soup_cookie_set_max_age().
+ **/
+/**
+ * SOUP_COOKIE_MAX_AGE_ONE_YEAR:
+ *
+ * A constant corresponding to 1 year, for use with soup_cookie_new()
+ * and soup_cookie_set_max_age().
+ **/
+
+/**
* soup_cookie_set_expires:
* @cookie: a #SoupCookie
* @expires: the new expiration time, or %NULL
*
* Parses @msg's Set-Cookie response headers and returns a #GSList of
* #SoupCookie<!-- -->s. Cookies that do not specify "path" or
- * "domain" attributes will have their values defaulted from @origin.
+ * "domain" attributes will have their values defaulted from @msg.
*
* Return value: a #GSList of #SoupCookie<!-- -->s, which can be freed
* with soup_cookies_free().
void soup_cookie_set_secure (SoupCookie *cookie,
gboolean secure);
void soup_cookie_set_http_only (SoupCookie *cookie,
- gboolean secure);
+ gboolean http_only);
char *soup_cookie_to_set_cookie_header (SoupCookie *cookie);
char *soup_cookie_to_cookie_header (SoupCookie *cookie);
* soup_header_parse_param_list:
* @header: a header value
*
- * Parses a header which is a comma-delimited list of something like
- *
- * token [ "=" ( token | quoted-string ) ]
+ * Parses a header which is a comma-delimited list of something like:
+ * <literal>token [ "=" ( token | quoted-string ) ]</literal>.
*
* Tokens that don't have an associated value will still be added to
* the resulting hash table, but with a %NULL value.
*
- * Return value: a #GHashTable of list elements.
+ * Return value: a #GHashTable of list elements, which can be freed
+ * with soup_header_free_param_list().
**/
GHashTable *
soup_header_parse_param_list (const char *header)
* @header: a header value
*
* Parses a header which is a semicolon-delimited list of something
- * like
- *
- * token [ "=" ( token | quoted-string ) ]
+ * like: <literal>token [ "=" ( token | quoted-string ) ]</literal>.
*
* Tokens that don't have an associated value will still be added to
* the resulting hash table, but with a %NULL value.
*
- * Return value: a #GHashTable of list elements.
+ * Return value: a #GHashTable of list elements, which can be freed
+ * with soup_header_free_param_list().
**/
GHashTable *
soup_header_parse_semi_param_list (const char *header)
/**
* soup_header_free_param_list:
* @param_list: a #GHashTable returned from soup_header_parse_param_list()
+ * or soup_header_parse_semi_param_list()
*
* Frees @param_list.
**/
* optionally configure it with soup_logger_set_request_filter(),
* soup_logger_set_response_filter(), and soup_logger_set_printer(),
* and then attach it to a session (or multiple sessions) with
- * soup_logger_attach().
+ * soup_session_add_feature().
*
* By default, the debugging output is sent to %stdout, and looks
* something like:
#include "soup-session-feature.h"
+/**
+ * SECTION:soup-session-feature
+ * @short_description: Interface for miscellaneous session features
+ *
+ * #SoupSessionFeature is the interface used by classes that extend
+ * the functionality of a #SoupSession. Some features like HTTP
+ * authentication handling are implemented internally via
+ * #SoupSessionFeature<!-- -->s. Other features can be added to the session
+ * by the application. (Eg, #SoupLogger, #SoupCookieJar.)
+ *
+ * See soup_session_add_feature(), etc, to add a feature to a session.
+ **/
+
+/**
+ * SoupSessionFeature:
+ *
+ * The interface implemented by objects that implement features for
+ * #SoupSession.
+ **/
+
static void soup_session_feature_interface_init (SoupSessionFeatureInterface *interface);
static void attach (SoupSessionFeature *feature, SoupSession *session);
}
}
-/**
- * soup_session_feature_attach:
- * @feature: a #SoupSessionFeature
- * @session: a #SoupSession
- *
- * Adds @feature to @session.
- **/
void
soup_session_feature_attach (SoupSessionFeature *feature,
SoupSession *session)
g_object_unref (feature);
}
-/**
- * soup_session_feature_detach:
- * @feature: a #SoupSessionFeature
- * @session: a #SoupSession
- *
- * Removes @feature from @session.
- *
- * Return value: success or failure
- **/
void
soup_session_feature_detach (SoupSessionFeature *feature,
SoupSession *session)
#define SOUP_IS_SESSION_FEATURE_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), SOUP_TYPE_SESSION_FEATURE))
#define SOUP_SESSION_FEATURE_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_INTERFACE ((obj), SOUP_TYPE_SESSION_FEATURE, SoupSessionFeatureInterface))
+/* dummy struct for gtk-doc */
+struct _SoupSessionFeature {};
+
typedef struct {
GTypeInterface parent;
g_slist_free (conns);
}
+/**
+ * soup_session_add_feature:
+ * @session: a #SoupSession
+ * @feature: an object that implements #SoupSessionFeature
+ *
+ * Adds @feature's functionality to @session. You can also add a
+ * feature to the session at construct time by using the
+ * %SOUP_SESSION_ADD_FEATURE property.
+ **/
void
soup_session_add_feature (SoupSession *session, SoupSessionFeature *feature)
{
soup_session_feature_attach (feature, session);
}
+/**
+ * soup_session_add_feature_by_type:
+ * @session: a #SoupSession
+ * @feature_type: the #GType of a class that implements #SoupSessionFeature
+ *
+ * Creates a new feature of type @feature_type and adds it to
+ * @session. You can use this instead of soup_session_add_feature() in
+ * the case wher you don't need to customize the new feature in any
+ * way. You can also add a feature to the session at construct time by
+ * using the %SOUP_SESSION_ADD_FEATURE_BY_TYPE property.
+ **/
void
soup_session_add_feature_by_type (SoupSession *session, GType feature_type)
{
g_object_unref (feature);
}
+/**
+ * soup_session_remove_feature:
+ * @session: a #SoupSession
+ * @feature: a feature that has previously been added to @session
+ *
+ * Removes @feature's functionality from @session.
+ **/
void
soup_session_remove_feature (SoupSession *session, SoupSessionFeature *feature)
{
}
}
+/**
+ * soup_session_remove_feature_by_type:
+ * @session: a #SoupSession
+ * @feature_type: the #GType of a class that implements #SoupSessionFeature
+ *
+ * Removes all features of type @feature_type (or any subclass of
+ * @feature_type) from @session. You can also remove standard features
+ * from the session at construct time by using the
+ * %SOUP_SESSION_REMOVE_FEATURE_BY_TYPE property.
+ **/
void
soup_session_remove_feature_by_type (SoupSession *session, GType feature_type)
{
projects / platform / upstream / libsoup.git / commitdiff