From: Dan Winship Date: Wed, 1 Oct 2008 20:09:42 +0000 (+0000) Subject: doc fixups X-Git-Tag: LIBSOUP_2_25_1~28 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=0ce1726e45c739c643b73d2de619beca329900af;p=platform%2Fupstream%2Flibsoup.git doc fixups * 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 svn path=/trunk/; revision=1170 --- diff --git a/ChangeLog b/ChangeLog index ae81b4e..d462667 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,18 @@ +2008-10-01 Dan Winship + + * 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 * libsoup/soup-xmlrpc.c (parse_value): diff --git a/docs/reference/libsoup-2.4-docs.sgml b/docs/reference/libsoup-2.4-docs.sgml index fd1d2bd..d4c3239 100644 --- a/docs/reference/libsoup-2.4-docs.sgml +++ b/docs/reference/libsoup-2.4-docs.sgml @@ -20,6 +20,8 @@ + + diff --git a/docs/reference/libsoup-2.4-sections.txt b/docs/reference/libsoup-2.4-sections.txt index 3d1f615..035bcf0 100644 --- a/docs/reference/libsoup-2.4-sections.txt +++ b/docs/reference/libsoup-2.4-sections.txt @@ -352,6 +352,12 @@ soup_session_unpause_message soup_session_get_async_context +SoupSessionFeature +soup_session_add_feature +soup_session_add_feature_by_type +soup_session_remove_feature +soup_session_remove_feature_by_type + SOUP_SESSION_PROXY_URI SOUP_SESSION_MAX_CONNS SOUP_SESSION_MAX_CONNS_PER_HOST @@ -361,6 +367,9 @@ SOUP_SESSION_ASYNC_CONTEXT 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 SOUP_IS_SESSION SOUP_IS_SESSION_CLASS @@ -370,6 +379,17 @@ SOUP_SESSION_GET_CLASS SOUP_TYPE_SESSION SoupSessionClass soup_session_get_type + +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
@@ -511,6 +531,7 @@ soup_uri_normalize SOUP_URI_SCHEME_HTTP SOUP_URI_SCHEME_HTTPS soup_uri_uses_default_port +SOUP_URI_VALID_FOR_HTTP soup_uri_set_scheme soup_uri_set_user @@ -538,6 +559,8 @@ soup_date_new_from_time_t 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 soup_form_decode @@ -558,6 +581,7 @@ soup_header_parse_quality_list soup_header_free_list soup_header_contains soup_header_parse_param_list +soup_header_parse_semi_param_list soup_header_free_param_list soup_str_case_equal @@ -656,3 +680,56 @@ SOUP_LOGGER_CLASS SOUP_LOGGER_GET_CLASS SOUP_TYPE_LOGGER
+ +
+soup-cookie +SoupCookie +SoupCookie +soup_cookie_new +soup_cookie_parse +soup_cookie_free + +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 + +soup_cookie_applies_to_uri + +soup_cookie_to_cookie_header +soup_cookie_to_set_cookie_header + +soup_cookies_from_request +soup_cookies_from_response +soup_cookies_to_request +soup_cookies_to_response +soup_cookies_to_cookie_header +soup_cookies_free +
+ +
+soup-cookie-jar +SoupCookieJar +SoupCookieJar +soup_cookie_jar_new +soup_cookie_jar_save +soup_cookie_jar_get_cookies +soup_cookie_jar_set_cookie + +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 +
diff --git a/docs/reference/libsoup-2.4.types b/docs/reference/libsoup-2.4.types index 9effee1..a342980 100644 --- a/docs/reference/libsoup-2.4.types +++ b/docs/reference/libsoup-2.4.types @@ -5,10 +5,13 @@ soup_auth_get_type 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 diff --git a/libsoup/soup-cookie-jar.c b/libsoup/soup-cookie-jar.c index fecd2c1..9b717c5 100644 --- a/libsoup/soup-cookie-jar.c +++ b/libsoup/soup-cookie-jar.c @@ -21,7 +21,7 @@ /** * SECTION:soup-cookie-jar - * @short_description: + * @short_description: Automatic cookie handling for #SoupSession * * A #SoupCookieJar stores #SoupCookies and arrange for them * to be sent with the appropriate #SoupMessages. diff --git a/libsoup/soup-cookie.c b/libsoup/soup-cookie.c index e6f364d..d095eda 100644 --- a/libsoup/soup-cookie.c +++ b/libsoup/soup-cookie.c @@ -34,6 +34,9 @@ * url="http://msdn2.microsoft.com/en-us/library/ms533046.aspx">Microsoft's * HttpOnly extension attribute, 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. **/ /** @@ -391,13 +394,13 @@ soup_cookie_new (const char *name, const char *value, /** * 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 @@ -504,6 +507,31 @@ soup_cookie_set_max_age (SoupCookie *cookie, int max_age) } /** + * 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 @@ -656,7 +684,7 @@ soup_cookie_free (SoupCookie *cookie) * * Parses @msg's Set-Cookie response headers and returns a #GSList of * #SoupCookies. 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 #SoupCookies, which can be freed * with soup_cookies_free(). diff --git a/libsoup/soup-cookie.h b/libsoup/soup-cookie.h index 84b4602..2c1bad4 100644 --- a/libsoup/soup-cookie.h +++ b/libsoup/soup-cookie.h @@ -48,7 +48,7 @@ void soup_cookie_set_expires (SoupCookie *cookie, 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); diff --git a/libsoup/soup-headers.c b/libsoup/soup-headers.c index 662404b..42ba8c4 100644 --- a/libsoup/soup-headers.c +++ b/libsoup/soup-headers.c @@ -648,14 +648,14 @@ parse_param_list (const char *header, char delim) * 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: + * token [ "=" ( token | quoted-string ) ]. * * 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) @@ -668,14 +668,13 @@ 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: token [ "=" ( token | quoted-string ) ]. * * 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) @@ -686,6 +685,7 @@ 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. **/ diff --git a/libsoup/soup-logger.c b/libsoup/soup-logger.c index 34c6360..37b9fec 100644 --- a/libsoup/soup-logger.c +++ b/libsoup/soup-logger.c @@ -32,7 +32,7 @@ * 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: diff --git a/libsoup/soup-session-feature.c b/libsoup/soup-session-feature.c index a2abb0b..71526de 100644 --- a/libsoup/soup-session-feature.c +++ b/libsoup/soup-session-feature.c @@ -11,6 +11,26 @@ #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 + * #SoupSessionFeatures. 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); @@ -93,13 +113,6 @@ 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) @@ -119,15 +132,6 @@ detach (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) diff --git a/libsoup/soup-session-feature.h b/libsoup/soup-session-feature.h index 0bdf078..f64e315 100644 --- a/libsoup/soup-session-feature.h +++ b/libsoup/soup-session-feature.h @@ -17,6 +17,9 @@ G_BEGIN_DECLS #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; diff --git a/libsoup/soup-session.c b/libsoup/soup-session.c index 41134cf..3107ad1 100644 --- a/libsoup/soup-session.c +++ b/libsoup/soup-session.c @@ -1340,6 +1340,15 @@ soup_session_abort (SoupSession *session) 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) { @@ -1353,6 +1362,17 @@ 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) { @@ -1366,6 +1386,13 @@ 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) { @@ -1381,6 +1408,16 @@ 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) {