diff options
author | Ankit Vani <a@nevitus.org> | 2014-02-01 00:57:31 +0530 |
---|---|---|
committer | Ankit Vani <a@nevitus.org> | 2014-02-01 00:57:31 +0530 |
commit | af1664675ed20c97a370811256cb8219b3b2f496 (patch) | |
tree | bdd0fa8508ac34608ca90571452c3a79b194b668 /libpurple/util.h | |
parent | f20d0a8c75ff23fae0dda50c0fa0f1d5988cc2bd (diff) | |
download | pidgin-af1664675ed20c97a370811256cb8219b3b2f496.tar.gz |
Convert docs from doxygen to gtk-doc format for request.h and util.h
Diffstat (limited to 'libpurple/util.h')
-rw-r--r-- | libpurple/util.h | 674 |
1 files changed, 407 insertions, 267 deletions
diff --git a/libpurple/util.h b/libpurple/util.h index 957ab2dd77..5af6fa282d 100644 --- a/libpurple/util.h +++ b/libpurple/util.h @@ -32,13 +32,17 @@ #include <stdio.h> /** + * PurpleMenuAction: + * * A generic structure that contains information about an "action." One - * place this is is used is by PRPLs to tell the core the list of available + * place this is is used is by protocols to tell the core the list of available * right-click actions for a buddy list row. */ typedef struct _PurpleMenuAction PurpleMenuAction; /** + * PurpleKeyValuePair: + * * A key-value pair. * * This is used by, among other things, purple_gtk_combo* functions to pass in a @@ -65,131 +69,146 @@ struct _PurpleKeyValuePair G_BEGIN_DECLS /** - * Creates a new PurpleMenuAction. - * + * purple_menu_action_new: * @label: The text label to display for this action. * @callback: The function to be called when the action is used on * the selected item. * @data: Additional data to be passed to the callback. * @children: A GList of PurpleMenuActions to be added as a submenu * of the action. + * + * Creates a new PurpleMenuAction. + * * Returns: The PurpleMenuAction. */ PurpleMenuAction *purple_menu_action_new(const char *label, PurpleCallback callback, gpointer data, GList *children); /** - * Frees a PurpleMenuAction - * + * purple_menu_action_free: * @act: The PurpleMenuAction to free. + * + * Frees a PurpleMenuAction */ void purple_menu_action_free(PurpleMenuAction *act); /** - * Returns the label of the PurpleMenuAction. - * + * purple_menu_action_get_label: * @act: The PurpleMenuAction. * + * Returns the label of the PurpleMenuAction. + * * Returns: The label string. */ char * purple_menu_action_get_label(const PurpleMenuAction *act); /** - * Returns the callback of the PurpleMenuAction. - * + * purple_menu_action_get_callback: * @act: The PurpleMenuAction. * + * Returns the callback of the PurpleMenuAction. + * * Returns: The callback function. */ PurpleCallback purple_menu_action_get_callback(const PurpleMenuAction *act); /** - * Returns the data stored in the PurpleMenuAction. - * + * purple_menu_action_get_data: * @act: The PurpleMenuAction. * + * Returns the data stored in the PurpleMenuAction. + * * Returns: The data. */ gpointer purple_menu_action_get_data(const PurpleMenuAction *act); /** - * Returns the children of the PurpleMenuAction. - * + * purple_menu_action_get_children: * @act: The PurpleMenuAction. * + * Returns the children of the PurpleMenuAction. + * * Returns: The GList of children. */ GList* purple_menu_action_get_children(const PurpleMenuAction *act); /** - * Set the label to the PurpleMenuAction. - * + * purple_menu_action_set_label: * @act: The menu action. * @label: The label for the menu action. + * + * Set the label to the PurpleMenuAction. */ void purple_menu_action_set_label(PurpleMenuAction *act, char *label); /** - * Set the callback that will be used by the PurpleMenuAction. - * + * purple_menu_action_set_callback: * @act: The menu action. * @callback: The callback. + * + * Set the callback that will be used by the PurpleMenuAction. */ void purple_menu_action_set_callback(PurpleMenuAction *act, PurpleCallback callback); /** - * Set the label to the PurpleMenuAction. - * + * purple_menu_action_set_data: * @act: The menu action. * @data: The data used by this PurpleMenuAction + * + * Set the label to the PurpleMenuAction. */ void purple_menu_action_set_data(PurpleMenuAction *act, gpointer data); /** - * Set the children of the PurpleMenuAction. - * + * purple_menu_action_set_children: * @act: The menu action. * @children: The PurpleMenuAtion children + * + * Set the children of the PurpleMenuAction. */ void purple_menu_action_set_children(PurpleMenuAction *act, GList *children); /** - * Sets the icon for the PurpleMenuAction. - * + * purple_menu_action_set_stock_icon: * @act: The menu action. * @strock: The stock icon identifier. + * + * Sets the icon for the PurpleMenuAction. */ void purple_menu_action_set_stock_icon(PurpleMenuAction *act, const gchar *stock); /** - * Gets the stock icon of the PurpleMenuAction. - * + * purple_menu_action_get_stock_icon: * @act: The menu action. * + * Gets the stock icon of the PurpleMenuAction. + * * Returns: The stock icon identifier. */ const gchar * purple_menu_action_get_stock_icon(PurpleMenuAction *act); /** - * Set the appropriate presence values for the currently playing song. - * + * purple_util_set_current_song: * @title: The title of the song, %NULL to unset the value. * @artist: The artist of the song, can be %NULL. * @album: The album of the song, can be %NULL. + * + * Set the appropriate presence values for the currently playing song. */ void purple_util_set_current_song(const char *title, const char *artist, const char *album); /** - * Format song information. - * + * purple_util_format_song_info: * @title: The title of the song, %NULL to unset the value. * @artist: The artist of the song, can be %NULL. * @album: The album of the song, can be %NULL. * @unused: Currently unused, must be %NULL. * + * Format song information. + * * Returns: The formatted string. The caller must g_free the returned string. */ char * purple_util_format_song_info(const char *title, const char *artist, @@ -201,11 +220,15 @@ char * purple_util_format_song_info(const char *title, const char *artist, /*@{*/ /** + * purple_util_init: + * * Initializes the utility subsystem. */ void purple_util_init(void); /** + * purple_util_uninit: + * * Uninitializes the util subsystem. */ void purple_util_uninit(void); @@ -218,11 +241,12 @@ void purple_util_uninit(void); /*@{*/ /** - * Converts a chunk of binary data to its base-16 equivalent. - * + * purple_base16_encode: * @data: The data to convert. * @len: The length of the data. * + * Converts a chunk of binary data to its base-16 equivalent. + * * Returns: The base-16 string in the ASCII encoding. Must be * g_free'd when no longer needed. * @@ -231,9 +255,7 @@ void purple_util_uninit(void); gchar *purple_base16_encode(const guchar *data, gsize len); /** - * Converts an ASCII string of base-16 encoded data to - * the binary equivalent. - * + * purple_base16_decode: * @str: The base-16 string to convert to raw data. * @ret_len: The length of the returned data. You can * pass in NULL if you're sure that you know @@ -241,6 +263,9 @@ gchar *purple_base16_encode(const guchar *data, gsize len); * know you'll be able to use strlen to * determine the length, etc. * + * Converts an ASCII string of base-16 encoded data to + * the binary equivalent. + * * Returns: The raw data. Must be g_free'd when no longer needed. * * @see purple_base16_encode() @@ -248,14 +273,15 @@ gchar *purple_base16_encode(const guchar *data, gsize len); guchar *purple_base16_decode(const char *str, gsize *ret_len); /** + * purple_base16_encode_chunked: + * @data: The data to convert. + * @len: The length of the data. + * * Converts a chunk of binary data to a chunked base-16 representation * (handy for key fingerprints) * * Example output: 01:23:45:67:89:AB:CD:EF * - * @data: The data to convert. - * @len: The length of the data. - * * Returns: The base-16 string in the ASCII chunked encoding. Must be * g_free'd when no longer needed. */ @@ -270,11 +296,12 @@ gchar *purple_base16_encode_chunked(const guchar *data, gsize len); /*@{*/ /** - * Converts a chunk of binary data to its base-64 equivalent. - * + * purple_base64_encode: * @data: The data to convert. * @len: The length of the data. * + * Converts a chunk of binary data to its base-64 equivalent. + * * Returns: The base-64 string in the ASCII encoding. Must be * g_free'd when no longer needed. * @@ -283,9 +310,7 @@ gchar *purple_base16_encode_chunked(const guchar *data, gsize len); gchar *purple_base64_encode(const guchar *data, gsize len); /** - * Converts an ASCII string of base-64 encoded data to - * the binary equivalent. - * + * purple_base64_decode: * @str: The base-64 string to convert to raw data. * @ret_len: The length of the returned data. You can * pass in NULL if you're sure that you know @@ -293,6 +318,9 @@ gchar *purple_base64_encode(const guchar *data, gsize len); * know you'll be able to use strlen to * determine the length, etc. * + * Converts an ASCII string of base-64 encoded data to + * the binary equivalent. + * * Returns: The raw data. Must be g_free'd when no longer needed. * * @see purple_base64_encode() @@ -307,15 +335,16 @@ guchar *purple_base64_decode(const char *str, gsize *ret_len); /*@{*/ /** + * purple_quotedp_decode: + * @str: The quoted printable ASCII string to convert to raw data. + * @ret_len: The length of the returned data. + * * Converts a quoted printable string back to its readable equivalent. * What is a quoted printable string, you ask? It's an encoding used * to transmit binary data as ASCII. It's intended purpose is to send * emails containing non-ASCII characters. Wikipedia has a pretty good * explanation. Also see RFC 2045. * - * @str: The quoted printable ASCII string to convert to raw data. - * @ret_len: The length of the returned data. - * * Returns: The readable string. Must be g_free'd when no longer needed. */ guchar *purple_quotedp_decode(const char *str, gsize *ret_len); @@ -328,6 +357,10 @@ guchar *purple_quotedp_decode(const char *str, gsize *ret_len); /*@{*/ /** + * purple_mime_decode_field: + * @str: The ASCII string, possibly containing any number of + * encoded-word sections. + * * Converts a MIME header field string back to its readable equivalent * according to RFC 2047. Basically, a header is plain ASCII and can * contain any number of sections called "encoded-words." The format @@ -339,9 +372,6 @@ guchar *purple_quotedp_decode(const char *str, gsize *ret_len); * question mark. The first piece is the character set, the second * piece is the encoding, and the third piece is the encoded text. * - * @str: The ASCII string, possibly containing any number of - * encoded-word sections. - * * Returns: The string, with any encoded-word sections decoded and * converted to UTF-8. Must be g_free'd when no longer * needed. @@ -357,6 +387,10 @@ char *purple_mime_decode_field(const char *str); /*@{*/ /** + * purple_utf8_strftime: + * @format: The format string, in UTF-8 + * @tm: The time to format, or %NULL to use the current local time + * * Formats a time into the specified format. * * This is essentially strftime(), but it has a static buffer @@ -374,81 +408,82 @@ char *purple_mime_decode_field(const char *str); * abbreviation (as is the case on Unix). As with %z, conversion specifiers * should not be used. * - * @format: The format string, in UTF-8 - * @tm: The time to format, or %NULL to use the current local time + * Note: @format is required to be in UTF-8. This differs from strftime(), + * where the format is provided in the locale charset. * * Returns: The formatted time, in UTF-8. - * - * Note: @a format is required to be in UTF-8. This differs from strftime(), - * where the format is provided in the locale charset. */ const char *purple_utf8_strftime(const char *format, const struct tm *tm); /** - * Gets a string representation of the local timezone offset - * + * purple_get_tzoff_str: * @tm: The time to get the timezone for * @iso: TRUE to format the offset according to ISO-8601, FALSE to * not substitute 'Z' for 0 offset, and to not separate * hours and minutes with a colon. + * + * Gets a string representation of the local timezone offset */ const char *purple_get_tzoff_str(const struct tm *tm, gboolean iso); /** + * purple_date_format_short: + * @tm: The time to format, or %NULL to use the current local time + * * Formats a time into the user's preferred short date format. * * The returned string is stored in a static buffer, so the result * should be g_strdup()'d if it's going to be kept. * - * @tm: The time to format, or %NULL to use the current local time - * * Returns: The date, formatted as per the user's settings. In the USA this * is something like "02/18/13" */ const char *purple_date_format_short(const struct tm *tm); /** + * purple_date_format_long: + * @tm: The time to format, or %NULL to use the current local time + * * Formats a time into the user's preferred short date plus time format. * * The returned string is stored in a static buffer, so the result * should be g_strdup()'d if it's going to be kept. * - * @tm: The time to format, or %NULL to use the current local time - * * Returns: The timestamp, formatted as per the user's settings. In the USA * this is something like "02/18/13 15:26:44" */ const char *purple_date_format_long(const struct tm *tm); /** + * purple_date_format_full: + * @tm: The time to format, or %NULL to use the current local time + * * Formats a time into the user's preferred full date and time format. * * The returned string is stored in a static buffer, so the result * should be g_strdup()'d if it's going to be kept. * - * @tm: The time to format, or %NULL to use the current local time - * * Returns: The date and time, formatted as per the user's settings. In the * USA this is something like "Mon Feb 18 15:26:44 2013" */ const char *purple_date_format_full(const struct tm *tm); /** + * purple_time_format: + * @tm: The time to format, or %NULL to use the current local time + * * Formats a time into the user's preferred time format. * * The returned string is stored in a static buffer, so the result * should be g_strdup()'d if it's going to be kept. * - * @tm: The time to format, or %NULL to use the current local time - * * Returns: The time, formatted as per the user's settings. In the USA this * is something like "15:26:44" */ const char *purple_time_format(const struct tm *tm); /** - * Builds a time_t from the supplied information. - * + * purple_time_build: * @year: The year. * @month: The month. * @day: The day. @@ -456,19 +491,23 @@ const char *purple_time_format(const struct tm *tm); * @min: The minute. * @sec: The second. * + * Builds a time_t from the supplied information. + * * Returns: A time_t. */ time_t purple_time_build(int year, int month, int day, int hour, int min, int sec); -/** Used by purple_str_to_time to indicate no timezone offset was - * specified in the timestamp string. */ +/** + * PURPLE_NO_TZ_OFF: + * + * Used by purple_str_to_time to indicate no timezone offset was + * specified in the timestamp string. + */ #define PURPLE_NO_TZ_OFF -500000 /** - * Parses a timestamp in jabber, ISO8601, or MM/DD/YYYY format and returns - * a time_t. - * + * purple_str_to_time: * @timestamp: The timestamp * @utc: Assume UTC if no timezone specified * @tm: If not %NULL, the caller can get a copy of the @@ -476,12 +515,15 @@ time_t purple_time_build(int year, int month, int day, int hour, * @tz_off: If not %NULL, the caller can get a copy of the * timezone offset (from UTC) used to calculate the time_t * return value. Note: Zero is a valid offset. As such, - * the value of the macro @c PURPLE_NO_TZ_OFF indicates no + * the value of the macro PURPLE_NO_TZ_OFF indicates no * offset was specified (which means that the local * timezone was used in the calculation). * @rest: If not %NULL, the caller can get a pointer to the - * part of @a timestamp left over after parsing is - * completed, if it's not the end of @a timestamp. + * part of @timestamp left over after parsing is + * completed, if it's not the end of @timestamp. + * + * Parses a timestamp in jabber, ISO8601, or MM/DD/YYYY format and returns + * a time_t. * * Returns: A time_t. */ @@ -489,14 +531,15 @@ time_t purple_str_to_time(const char *timestamp, gboolean utc, struct tm *tm, long *tz_off, const char **rest); /** - * Formats a datetime according to a UTS-35 Date Format Pattern. - * + * purple_uts35_to_str: * @format: The formatting string, according to UTS #35 * See http://unicode.org/reports/tr35/ * (NOTE: not all formats are supported) * @len: The length of the formatting string * @tm: The time to format, or %NULL to use the current local time * + * Formats a datetime according to a UTS-35 Date Format Pattern. + * * Returns: The time, formatted as per the user's settings. */ char *purple_uts35_to_str(const char *format, size_t len, struct tm *tm); @@ -510,6 +553,8 @@ char *purple_uts35_to_str(const char *format, size_t len, struct tm *tm); /*@{*/ /** + * purple_markup_escape_text: + * * Escapes special characters in a plain-text string so they display * correctly as HTML. For example, & is replaced with & and < is * replaced with < @@ -521,18 +566,20 @@ char *purple_uts35_to_str(const char *format, size_t len, struct tm *tm); gchar *purple_markup_escape_text(const gchar *text, gssize length); /** - * Finds an HTML tag matching the given name. - * - * This locates an HTML tag's start and end, and stores its attributes - * in a GData hash table. The names of the attributes are lower-cased - * in the hash table, and the name of the tag is case insensitive. - * + * purple_markup_find_tag: * @needle: The name of the tag * @haystack: The null-delimited string to search in * @start: A pointer to the start of the tag if found * @end: A pointer to the end of the tag if found * @attributes: The attributes, if the tag was found. This should * be freed with g_datalist_clear(). + * + * Finds an HTML tag matching the given name. + * + * This locates an HTML tag's start and end, and stores its attributes + * in a GData hash table. The names of the attributes are lower-cased + * in the hash table, and the name of the tag is case insensitive. + * * Returns: TRUE if the tag was found */ gboolean purple_markup_find_tag(const char *needle, const char *haystack, @@ -540,11 +587,7 @@ gboolean purple_markup_find_tag(const char *needle, const char *haystack, GData **attributes); /** - * Extracts a field of data from HTML. - * - * This is a scary function. See protocols/msn/msn.c and - * protocols/yahoo/yahoo_profile.c for example usage. - * + * purple_markup_extract_info_field: * @str: The string to parse. * @len: The size of str. * @user_info: The destination PurpleNotifyUserInfo to which the new @@ -560,6 +603,11 @@ gboolean purple_markup_find_tag(const char *needle, const char *haystack, * @link_prefix: The prefix for the link. * @format_cb: A callback to format the value before adding it. * + * Extracts a field of data from HTML. + * + * This is a scary function. See protocols/msn/msn.c and + * protocols/yahoo/yahoo_profile.c for example usage. + * * Returns: TRUE if successful, or FALSE otherwise. */ gboolean purple_markup_extract_info_field(const char *str, int len, PurpleNotifyUserInfo *user_info, @@ -571,30 +619,33 @@ gboolean purple_markup_extract_info_field(const char *str, int len, PurpleNotify PurpleInfoFieldFormatCallback format_cb); /** - * Converts HTML markup to XHTML. - * + * purple_markup_html_to_xhtml: * @html: The HTML markup. * @dest_xhtml: The destination XHTML output. * @dest_plain: The destination plain-text output. + * + * Converts HTML markup to XHTML. */ void purple_markup_html_to_xhtml(const char *html, char **dest_xhtml, char **dest_plain); /** - * Strips HTML tags from a string. - * + * purple_markup_strip_html: * @str: The string to strip HTML from. * + * Strips HTML tags from a string. + * * Returns: The new string without HTML. You must g_free this string * when finished with it. */ char *purple_markup_strip_html(const char *str); /** - * Adds the necessary HTML code to turn URIs into HTML links in a string. - * + * purple_markup_linkify: * @str: The string to linkify. * + * Adds the necessary HTML code to turn URIs into HTML links in a string. + * * Returns: The new string with all URIs surrounded in standard * HTML <a href="whatever"></a> tags. You must g_free this * string when finished with it. @@ -602,6 +653,9 @@ char *purple_markup_strip_html(const char *str); char *purple_markup_linkify(const char *str); /** + * purple_unescape_text: + * @text: The string in which to unescape any HTML entities + * * Unescapes HTML entities to their literal characters in the text. * For example "&" is replaced by '&' and so on. Also converts * numerical entities (e.g. "&" is also '&'). @@ -611,8 +665,6 @@ char *purple_markup_linkify(const char *str); * * purple_unescape_html() is similar, but also converts "<br>" into "\n". * - * @text: The string in which to unescape any HTML entities - * * Returns: The text with HTML entities literalized. You must g_free * this string when finished with it. * @@ -621,11 +673,12 @@ char *purple_markup_linkify(const char *str); char *purple_unescape_text(const char *text); /** + * purple_unescape_html: + * @html: The string in which to unescape any HTML entities + * * Unescapes HTML entities to their literal characters and converts * "<br>" to "\n". See purple_unescape_text() for more details. * - * @html: The string in which to unescape any HTML entities - * * Returns: The text with HTML entities literalized. You must g_free * this string when finished with it. * @@ -634,6 +687,13 @@ char *purple_unescape_text(const char *text); char *purple_unescape_html(const char *html); /** + * purple_markup_slice: + * @str: The input NUL terminated, HTML, UTF-8 (or ASCII) string. + * @x: The character offset into an unformatted version of str to + * begin at. + * @y: The character offset (into an unformatted vesion of str) of + * one past the last character to include in the slice. + * * Returns a newly allocated substring of the HTML UTF-8 string "str". * The markup is preserved such that the substring will have the same * formatting as original string, even though some tags may have been @@ -646,31 +706,31 @@ char *purple_unescape_html(const char *html); * when used with other UI's. libpurple users are encouraged to report and * work out any problems encountered. * - * @str: The input NUL terminated, HTML, UTF-8 (or ASCII) string. - * @x: The character offset into an unformatted version of str to - * begin at. - * @y: The character offset (into an unformatted vesion of str) of - * one past the last character to include in the slice. - * * Returns: The HTML slice of string, with all formatting retained. */ char *purple_markup_slice(const char *str, guint x, guint y); /** + * purple_markup_get_tag_name: + * @tag: The string starting a HTML tag. + * * Returns a newly allocated string containing the name of the tag * located at "tag". Tag is expected to point to a '<', and contain * a '>' sometime after that. If there is no '>' and the string is * not NUL terminated, this function can be expected to segfault. * - * @tag: The string starting a HTML tag. * Returns: A string containing the name of the tag. */ char *purple_markup_get_tag_name(const char *tag); /** + * purple_markup_unescape_entity: + * @text: A string containing an HTML entity. + * @length: If not %NULL, the string length of the entity is stored in this location. + * * Returns a constant string of the character representation of the HTML - * entity pointed to by @a text. For example, purple_markup_unescape_entity("&") - * will return "&". The @a text variable is expected to point to an '&', + * entity pointed to by @text. For example, purple_markup_unescape_entity("&") + * will return "&". The @text variable is expected to point to an '&', * the first character of the entity. If given an unrecognized entity, the function * returns %NULL. * @@ -678,16 +738,17 @@ char *purple_markup_get_tag_name(const char *tag); * the string for the entity, does not replace the entity, and does not * return a newly allocated string. * - * @text: A string containing an HTML entity. - * @length: If not %NULL, the string length of the entity is stored in this location. - * * Returns: A constant string containing the character representation of the given entity. */ const char * purple_markup_unescape_entity(const char *text, int *length); /** + * purple_markup_get_css_property: + * @style: A string containing the inline CSS text. + * @opt: The requested CSS property. + * * Returns a newly allocated string containing the value of the CSS property specified - * in opt. The @a style argument is expected to point to a HTML inline CSS. + * in opt. The @style argument is expected to point to a HTML inline CSS. * The function will seek for the CSS property and return its value. * * For example, purple_markup_get_css_property("direction:rtl;color:#dc4d1b;", @@ -696,18 +757,16 @@ const char * purple_markup_unescape_entity(const char *text, int *length); * On error or if the requested property was not found, the function returns * %NULL. * - * @style: A string containing the inline CSS text. - * @opt: The requested CSS property. - * * Returns: The value of the requested CSS property. */ char * purple_markup_get_css_property(const gchar *style, const gchar *opt); /** - * Check if the given HTML contains RTL text. - * + * purple_markup_is_rtl: * @html: The HTML text. * + * Check if the given HTML contains RTL text. + * * Returns: TRUE if the text contains RTL text, FALSE otherwise. */ gboolean purple_markup_is_rtl(const char *html); @@ -721,6 +780,8 @@ gboolean purple_markup_is_rtl(const char *html); /*@{*/ /** + * purple_home_dir: + * * Returns the user's home directory. * * Returns: The user's home directory. @@ -730,6 +791,8 @@ gboolean purple_markup_is_rtl(const char *html); const gchar *purple_home_dir(void); /** + * purple_user_dir: + * * Returns the purple settings directory in the user's home directory. * This is usually ~/.purple * @@ -740,24 +803,33 @@ const gchar *purple_home_dir(void); const char *purple_user_dir(void); /** - * Define a custom purple settings directory, overriding the default (user's home directory/.purple) + * purple_util_set_user_dir: * @dir: The custom settings directory + * + * Define a custom purple settings directory, overriding the default (user's home directory/.purple) */ void purple_util_set_user_dir(const char *dir); /** - * Builds a complete path from the root, making any directories along - * the path which do not already exist. - * + * purple_build_dir: * @path: The path you wish to create. Note that it must start * from the root or this function will fail. * @mode: Unix-style permissions for this directory. * + * Builds a complete path from the root, making any directories along + * the path which do not already exist. + * * Returns: 0 for success, nonzero on any error. */ int purple_build_dir(const char *path, int mode); /** + * purple_util_write_data_to_file: + * @filename: The basename of the file to write in the purple_user_dir. + * @data: A null-terminated string of data to write. + * @size: The size of the data to save. If data is + * null-terminated you can pass in -1. + * * Write a string of data to a file of the given name in the Purple * user directory ($HOME/.purple by default). The data is typically * a serialized version of one of Purple's config files, such as @@ -765,26 +837,22 @@ int purple_build_dir(const char *path, int mode); * obtained using purple_xmlnode_to_formatted_str. However, this function * should work fine for saving binary files as well. * - * @filename: The basename of the file to write in the purple_user_dir. - * @data: A null-terminated string of data to write. - * @size: The size of the data to save. If data is - * null-terminated you can pass in -1. - * * Returns: TRUE if the file was written successfully. FALSE otherwise. */ gboolean purple_util_write_data_to_file(const char *filename, const char *data, gssize size); /** - * Write data to a file using the absolute path. - * - * This exists for Glib backwards compatibility reasons. - * + * purple_util_write_data_to_file_absolute: * @filename_full: Filename to write to * @data: A null-terminated string of data to write. * @size: The size of the data to save. If data is * null-terminated you can pass in -1. * + * Write data to a file using the absolute path. + * + * This exists for Glib backwards compatibility reasons. + * * Returns: TRUE if the file was written successfully. FALSE otherwise. * * @todo Remove this function (use g_file_set_contents instead) when 3.0.0 @@ -796,16 +864,17 @@ gboolean purple_util_write_data_to_file_absolute(const char *filename_full, const char *data, gssize size); /** - * Read the contents of a given file and parse the results into an - * PurpleXmlNode tree structure. This is intended to be used to read - * Purple's configuration xml files (prefs.xml, pounces.xml, etc.) - * + * purple_util_read_xml_from_file: * @filename: The basename of the file to open in the purple_user_dir. * @description: A very short description of the contents of this * file. This is used in error messages shown to the * user when the file can not be opened. For example, * "preferences," or "buddy pounces." * + * Read the contents of a given file and parse the results into an + * PurpleXmlNode tree structure. This is intended to be used to read + * Purple's configuration xml files (prefs.xml, pounces.xml, etc.) + * * Returns: An PurpleXmlNode tree of the contents of the given file. Or NULL, if * the file does not exist or there was an error reading the file. */ @@ -813,6 +882,10 @@ PurpleXmlNode *purple_util_read_xml_from_file(const char *filename, const char *description); /** + * purple_mkstemp: + * @path: The returned path to the temp file. + * @binary: Text or binary, for platforms where it matters. + * * Creates a temporary file and returns a file pointer to it. * * This is like mkstemp(), but returns a file pointer and uses a @@ -820,28 +893,28 @@ PurpleXmlNode *purple_util_read_xml_from_file(const char *filename, * directory to use and allocates the space for the file path. * * The caller is responsible for closing the file and removing it when - * done, as well as freeing the space pointed to by @a path with + * done, as well as freeing the space pointed to by @path with * g_free(). * - * @path: The returned path to the temp file. - * @binary: Text or binary, for platforms where it matters. - * * Returns: A file pointer to the temporary file, or %NULL on failure. */ FILE *purple_mkstemp(char **path, gboolean binary); /** - * Returns an extension corresponding to the image data's file type. - * + * purple_util_get_image_extension: * @data: A pointer to the image data * @len: The length of the image data * + * Returns an extension corresponding to the image data's file type. + * * Returns: The appropriate extension, or "icon" if unknown. */ const char * purple_util_get_image_extension(gconstpointer data, size_t len); /** + * purple_util_get_image_filename: + * * Returns: A hex encoded version of the SHA-1 hash of the data passed * in with the correct file extention appended. The file * extension is determined by calling @@ -859,15 +932,18 @@ char *purple_util_get_image_filename(gconstpointer image_data, size_t image_len) /*@{*/ /** - * Checks if the given program name is valid and executable. - * + * purple_program_is_valid: * @program: The file name of the application. * + * Checks if the given program name is valid and executable. + * * Returns: TRUE if the program is runable. */ gboolean purple_program_is_valid(const char *program); /** + * purple_running_gnome: + * * Check if running GNOME. * * Returns: TRUE if running GNOME, FALSE otherwise. @@ -875,6 +951,8 @@ gboolean purple_program_is_valid(const char *program); gboolean purple_running_gnome(void); /** + * purple_running_kde: + * * Check if running KDE. * * Returns: TRUE if running KDE, FALSE otherwise. @@ -882,6 +960,8 @@ gboolean purple_running_gnome(void); gboolean purple_running_kde(void); /** + * purple_running_osx: + * * Check if running OS X. * * Returns: TRUE if running OS X, FALSE otherwise. @@ -889,31 +969,35 @@ gboolean purple_running_kde(void); gboolean purple_running_osx(void); /** - * Returns the IP address from a socket file descriptor. - * + * purple_fd_get_ip: * @fd: The socket file descriptor. * + * Returns the IP address from a socket file descriptor. + * * Returns: The IP address, or %NULL on error. */ char *purple_fd_get_ip(int fd); /** - * Returns the address family of a socket. - * + * purple_socket_get_family: * @fd: The socket file descriptor. * + * Returns the address family of a socket. + * * Returns: The address family of the socket (AF_INET, AF_INET6, etc) or -1 * on error. */ int purple_socket_get_family(int fd); /** + * purple_socket_speaks_ipv4: + * @fd: The socket file descriptor + * * Returns TRUE if a socket is capable of speaking IPv4. * * This is the case for IPv4 sockets and, on some systems, IPv6 sockets * (due to the IPv4-mapped address functionality). * - * @fd: The socket file descriptor * Returns: TRUE if a socket can speak IPv4. */ gboolean purple_socket_speaks_ipv4(int fd); @@ -927,19 +1011,28 @@ gboolean purple_socket_speaks_ipv4(int fd); /*@{*/ /** + * purple_strequal: + * @left: A string + * @right: A string to compare with left + * * Tests two strings for equality. * * Unlike strcmp(), this function will not crash if one or both of the * strings are %NULL. * - * @left: A string - * @right: A string to compare with left - * * Returns: %TRUE if the strings are the same, else %FALSE. */ gboolean purple_strequal(const gchar *left, const gchar *right); /** + * purple_normalize: + * @account: The account the string belongs to, or NULL if you do + * not know the account. If you use NULL, the string + * will still be normalized, but if the protocol uses a + * custom normalization function then the string may + * not be normalized correctly. + * @str: The string to normalize. + * * Normalizes a string, so that it is suitable for comparison. * * The returned string will point to a static buffer, so if the @@ -947,117 +1040,119 @@ gboolean purple_strequal(const gchar *left, const gchar *right); * g_strdup() it. Also, calling normalize() twice in the same line * will lead to problems. * - * @account: The account the string belongs to, or NULL if you do - * not know the account. If you use NULL, the string - * will still be normalized, but if the PRPL uses a - * custom normalization function then the string may - * not be normalized correctly. - * @str: The string to normalize. - * * Returns: A pointer to the normalized version stored in a static buffer. */ const char *purple_normalize(const PurpleAccount *account, const char *str); /** + * purple_normalize_nocase: + * @account: The account the string belongs to. + * @str: The string to normalize. + * * Normalizes a string, so that it is suitable for comparison. * - * This is one possible implementation for the PRPL callback + * This is one possible implementation for the protocol callback * function "normalize." It returns a lowercase and UTF-8 * normalized version of the string. * - * @account: The account the string belongs to. - * @str: The string to normalize. - * * Returns: A pointer to the normalized version stored in a static buffer. */ const char *purple_normalize_nocase(const PurpleAccount *account, const char *str); /** - * Checks, if a string is valid. - * + * purple_validate: * @prpl: The protocol plugin the string belongs to. * @str: The string to validate. * + * Checks, if a string is valid. + * * Returns: TRUE, if string is valid, otherwise FALSE. */ gboolean purple_validate(const PurplePlugin *prpl, const char *str); /** - * Compares two strings to see if the first contains the second as - * a proper prefix. - * + * purple_str_has_prefix: * @s: The string to check. * @p: The prefix in question. * + * Compares two strings to see if the first contains the second as + * a proper prefix. + * * Returns: TRUE if p is a prefix of s, otherwise FALSE. */ gboolean purple_str_has_prefix(const char *s, const char *p); /** - * Compares two strings to see if the second is a proper suffix - * of the first. - * + * purple_str_has_suffix: * @s: The string to check. * @x: The suffix in question. * + * Compares two strings to see if the second is a proper suffix + * of the first. + * * Returns: TRUE if x is a a suffix of s, otherwise FALSE. */ gboolean purple_str_has_suffix(const char *s, const char *x); /** + * purple_strdup_withhtml: + * @src: The source string. + * * Duplicates a string and replaces all newline characters from the * source string with HTML linebreaks. * - * @src: The source string. - * * Returns: The new string. Must be g_free'd by the caller. */ gchar *purple_strdup_withhtml(const gchar *src); /** - * Ensures that all linefeeds have a matching carriage return. - * + * purple_str_add_cr: * @str: The source string. * + * Ensures that all linefeeds have a matching carriage return. + * * Returns: The string with carriage returns. */ char *purple_str_add_cr(const char *str); /** + * purple_str_strip_char: + * @str: The string to strip characters from. + * @thechar: The character to strip from the given string. + * * Strips all instances of the given character from the * given string. The string is modified in place. This * is useful for stripping new line characters, for example. * * Example usage: * purple_str_strip_char(my_dumb_string, '\n'); - * - * @str: The string to strip characters from. - * @thechar: The character to strip from the given string. */ void purple_str_strip_char(char *str, char thechar); /** - * Given a string, this replaces all instances of one character - * with another. This happens inline (the original string IS - * modified). - * + * purple_util_chrreplace: * @string: The string from which to replace stuff. * @delimiter: The character you want replaced. * @replacement: The character you want inserted in place * of the delimiting character. + * + * Given a string, this replaces all instances of one character + * with another. This happens inline (the original string IS + * modified). */ void purple_util_chrreplace(char *string, char delimiter, char replacement); /** - * Given a string, this replaces one substring with another - * and returns a newly allocated string. - * + * purple_strreplace: * @string: The string from which to replace stuff. * @delimiter: The substring you want replaced. * @replacement: The substring you want inserted in place * of the delimiting substring. * + * Given a string, this replaces one substring with another + * and returns a newly allocated string. + * * Returns: A new string, after performing the substitution. * free this with g_free(). */ @@ -1066,12 +1161,13 @@ gchar *purple_strreplace(const char *string, const char *delimiter, /** + * purple_utf8_ncr_encode: + * @in: The string which might contain utf-8 substrings + * * Given a string, this replaces any utf-8 substrings in that string with * the corresponding numerical character reference, and returns a newly * allocated string. * - * @in: The string which might contain utf-8 substrings - * * Returns: A new string, with utf-8 replaced with numerical character * references, free this with g_free() */ @@ -1079,12 +1175,13 @@ char *purple_utf8_ncr_encode(const char *in); /** + * purple_utf8_ncr_decode: + * @in: The string which might contain numerical character references. + * * Given a string, this replaces any numerical character references * in that string with the corresponding actual utf-8 substrings, * and returns a newly allocated string. * - * @in: The string which might contain numerical character references. - * * Returns: A new string, with numerical character references * replaced with actual utf-8, free this with g_free(). */ @@ -1092,14 +1189,15 @@ char *purple_utf8_ncr_decode(const char *in); /** - * Given a string, this replaces one substring with another - * ignoring case and returns a newly allocated string. - * + * purple_strcasereplace: * @string: The string from which to replace stuff. * @delimiter: The substring you want replaced. * @replacement: The substring you want inserted in place * of the delimiting substring. * + * Given a string, this replaces one substring with another + * ignoring case and returns a newly allocated string. + * * Returns: A new string, after performing the substitution. * free this with g_free(). */ @@ -1107,74 +1205,82 @@ gchar *purple_strcasereplace(const char *string, const char *delimiter, const char *replacement); /** - * This is like strstr, except that it ignores ASCII case in - * searching for the substring. - * + * purple_strcasestr: * @haystack: The string to search in. * @needle: The substring to find. * + * This is like strstr, except that it ignores ASCII case in + * searching for the substring. + * * Returns: the location of the substring if found, or NULL if not */ const char *purple_strcasestr(const char *haystack, const char *needle); /** + * purple_str_size_to_units: + * @size: The size + * * Returns a string representing a filesize in the appropriate * units (MB, KB, GB, etc.) * - * @size: The size - * * Returns: The string in units form. This must be freed. */ char *purple_str_size_to_units(goffset size); /** - * Converts seconds into a human-readable form. - * + * purple_str_seconds_to_string: * @sec: The seconds. * + * Converts seconds into a human-readable form. + * * Returns: A human-readable form, containing days, hours, minutes, and * seconds. */ char *purple_str_seconds_to_string(guint sec); /** + * purple_str_binary_to_ascii: + * @binary: A string of random data, possibly with embedded NULs + * and such. + * @len: The length in bytes of the input string. Must not be 0. + * * Converts a binary string into a NUL terminated ascii string, * replacing nonascii characters and characters below SPACE (including * NUL) into \\xyy, where yy are two hex digits. Also backslashes are * changed into two backslashes (\\\\). The returned, newly allocated * string can be outputted to the console, and must be g_free()d. * - * @binary: A string of random data, possibly with embedded NULs - * and such. - * @len: The length in bytes of the input string. Must not be 0. - * * Returns: A newly allocated ASCIIZ string. */ char *purple_str_binary_to_ascii(const unsigned char *binary, guint len); /** + * purple_utf16_size: + * @str: String to check. + * * Calculates UTF-16 string size (in bytes). * - * @str: String to check. * Returns: Number of bytes (including NUL character) that string occupies. */ size_t purple_utf16_size(const gunichar2 *str); /** + * purple_str_wipe: + * @str: A NUL-terminated string to free, or a NULL-pointer. + * * Fills a NUL-terminated string with zeros and frees it. * * It should be used to free sensitive data, like passwords. - * - * @str: A NUL-terminated string to free, or a NULL-pointer. */ void purple_str_wipe(gchar *str); /** + * purple_utf16_wipe: + * @str: A NUL-terminated string to free, or a NULL-pointer. + * * Fills a NUL-terminated UTF-16 string with zeros and frees it. * * It should be used to free sensitive data, like passwords. - * - * @str: A NUL-terminated string to free, or a NULL-pointer. */ void purple_utf16_wipe(gunichar2 *str); @@ -1189,85 +1295,93 @@ void purple_utf16_wipe(gunichar2 *str); void purple_got_protocol_handler_uri(const char *uri); /** + * purple_url_decode: + * @str: The string to translate. + * * Decodes a URL into a plain string. * * This will change hex codes and such to their ascii equivalents. * - * @str: The string to translate. - * * Returns: The resulting string. */ const char *purple_url_decode(const char *str); /** + * purple_url_encode: + * @str: The string to translate. + * * Encodes a URL into an escaped string. * * This will change non-alphanumeric characters to hex codes. * - * @str: The string to translate. - * * Returns: The resulting string. */ const char *purple_url_encode(const char *str); /** - * Checks if the given email address is syntactically valid. - * + * purple_email_is_valid: * @address: The email address to validate. * + * Checks if the given email address is syntactically valid. + * * Returns: True if the email address is syntactically correct. */ gboolean purple_email_is_valid(const char *address); /** + * purple_ip_address_is_valid: + * @ip: The IP address to validate. + * * Checks if the given IP address is a syntactically valid IPv4 or * IPv6 address. * If you specifically want to check for an IPv4 address use * purple_ipv4_address_is_valid(), or for an IPv6 address use * purple_ipv6_address_is_valid(). * - * @ip: The IP address to validate. - * * Returns: True if the IP address is syntactically correct. */ gboolean purple_ip_address_is_valid(const char *ip); /** - * Checks if the given IP address is a syntactically valid IPv4 address. - * + * purple_ipv4_address_is_valid: * @ip: The IP address to validate. * + * Checks if the given IP address is a syntactically valid IPv4 address. + * * Returns: True if the IP address is syntactically correct. */ gboolean purple_ipv4_address_is_valid(const char *ip); /** - * Checks if the given IP address is a syntactically valid IPv6 address. - * + * purple_ipv6_address_is_valid: * @ip: The IP address to validate. * + * Checks if the given IP address is a syntactically valid IPv6 address. + * * Returns: True if the IP address is syntactically correct. */ gboolean purple_ipv6_address_is_valid(const char *ip); /** + * purple_uri_list_extract_uris: + * @uri_list: An uri-list in the standard format. + * * This function extracts a list of URIs from the a "text/uri-list" * string. It was "borrowed" from gnome_uri_list_extract_uris * - * @uri_list: An uri-list in the standard format. - * * Returns: A GList containing strings allocated with g_malloc * that have been splitted from uri-list. */ GList *purple_uri_list_extract_uris(const gchar *uri_list); /** + * purple_uri_list_extract_filenames: + * @uri_list: A uri-list in the standard format. + * * This function extracts a list of filenames from a * "text/uri-list" string. It was "borrowed" from * gnome_uri_list_extract_filenames * - * @uri_list: A uri-list in the standard format. - * * Returns: A GList containing strings allocated with g_malloc that * contain the filenames in the uri-list. Note that unlike * purple_uri_list_extract_uris() function, this will discard @@ -1283,105 +1397,114 @@ GList *purple_uri_list_extract_filenames(const gchar *uri_list); /*@{*/ /** + * purple_utf8_try_convert: + * @str: The source string. + * * Attempts to convert a string to UTF-8 from an unknown encoding. * * This function checks the locale and tries sane defaults. * - * @str: The source string. - * * Returns: The UTF-8 string, or %NULL if it could not be converted. */ gchar *purple_utf8_try_convert(const char *str); /** + * purple_utf8_salvage: + * @str: The source string. + * * Salvages the valid UTF-8 characters from a string, replacing any * invalid characters with a filler character (currently hardcoded to * '?'). * - * @str: The source string. - * * Returns: A valid UTF-8 string. */ gchar *purple_utf8_salvage(const char *str); /** + * purple_utf8_strip_unprintables: + * @str: A valid UTF-8 string. + * * Removes unprintable characters from a UTF-8 string. These characters * (in particular low-ASCII characters) are invalid in XML 1.0 and thus * are not allowed in XMPP and are rejected by libxml2 by default. * * The returned string must be freed by the caller. * - * @str: A valid UTF-8 string. - * * Returns: A newly allocated UTF-8 string without the unprintable characters. */ gchar *purple_utf8_strip_unprintables(const gchar *str); /** + * purple_gai_strerror: + * @errnum: The error code. + * * Return the UTF-8 version of gai_strerror(). It calls gai_strerror() * then converts the result to UTF-8. This function is analogous to * g_strerror(). * - * @errnum: The error code. - * * Returns: The UTF-8 error message. */ const gchar *purple_gai_strerror(gint errnum); /** + * purple_utf8_strcasecmp: + * @a: The first string. + * @b: The second string. + * * Compares two UTF-8 strings case-insensitively. This comparison is * more expensive than a simple g_utf8_collate() comparison because * it calls g_utf8_casefold() on each string, which allocates new * strings. * - * @a: The first string. - * @b: The second string. - * - * Returns: -1 if @a a is less than @a b. - * 0 if @a a is equal to @a b. - * 1 if @a a is greater than @a b. + * Returns: -1 if @a is less than @b. + * 0 if @a is equal to @b. + * 1 if @a is greater than @b. */ int purple_utf8_strcasecmp(const char *a, const char *b); /** + * purple_utf8_has_word: + * @haystack: The string to search in. + * @needle: The substring to find. + * * Case insensitive search for a word in a string. The needle string * must be contained in the haystack string and not be immediately * preceded or immediately followed by another alpha-numeric character. * - * @haystack: The string to search in. - * @needle: The substring to find. - * * Returns: TRUE if haystack has the word, otherwise FALSE */ gboolean purple_utf8_has_word(const char *haystack, const char *needle); /** + * purple_print_utf8_to_console: + * @filestream: The file stream (e.g. STDOUT or STDERR) + * @message: The message to print. + * * Prints a UTF-8 message to the given file stream. The function * tries to convert the UTF-8 message to user's locale. If this * is not possible, the original UTF-8 text will be printed. - * - * @filestream: The file stream (e.g. STDOUT or STDERR) - * @message: The message to print. */ void purple_print_utf8_to_console(FILE *filestream, char *message); /** - * Checks for messages starting (post-HTML) with "/me ", including the space. - * + * purple_message_meify: * @message: The message to check * @len: The message length, or -1 * + * Checks for messages starting (post-HTML) with "/me ", including the space. + * * Returns: TRUE if it starts with "/me ", and it has been removed, otherwise * FALSE */ gboolean purple_message_meify(char *message, gssize len); /** + * purple_text_strip_mnemonic: + * @in: The string to strip + * * Removes the underscore characters from a string used identify the mnemonic * character. * - * @in: The string to strip - * * Returns: The stripped string */ char *purple_text_strip_mnemonic(const char *in); @@ -1389,46 +1512,52 @@ char *purple_text_strip_mnemonic(const char *in); /*@}*/ /** + * purple_add_eight: + * @x: The number to add 8 to. + * * Adds 8 to something. * * Blame SimGuy. * - * @x: The number to add 8 to. - * * Returns: x + 8 */ #define purple_add_eight(x) ((x)+8) /** + * purple_unescape_filename: + * @str: The string to translate. + * * Does the reverse of purple_escape_filename * * This will change hex codes and such to their ascii equivalents. * - * @str: The string to translate. - * * Returns: The resulting string. */ const char *purple_unescape_filename(const char *str); /** - * Escapes filesystem-unfriendly characters from a filename - * + * purple_escape_filename: * @str: The string to translate. * + * Escapes filesystem-unfriendly characters from a filename + * * Returns: The resulting string. */ const char *purple_escape_filename(const char *str); /** - * Escapes javascript-unfriendly substrings from a string. - * + * purple_escape_js: * @str: The string to escape. * + * Escapes javascript-unfriendly substrings from a string. + * * Returns: The javascript-safe string (must be g_free'd after use). */ gchar * purple_escape_js(const gchar *str); /** + * purple_restore_default_signal_handlers: + * * Restore default signal handlers for signals which might reasonably have * handlers. This should be called by a fork()'d child process, since child processes * inherit the handlers of the parent. @@ -1436,6 +1565,8 @@ gchar * purple_escape_js(const gchar *str); void purple_restore_default_signal_handlers(void); /** + * purple_get_host_name: + * * Gets the host name of the machine. If it not possible to determine the * host name, "localhost" is returned * @@ -1444,6 +1575,8 @@ void purple_restore_default_signal_handlers(void); const gchar *purple_get_host_name(void); /** + * purple_uuid_random: + * * Returns a type 4 (random) UUID * * Returns: A UUID, caller is responsible for freeing it @@ -1451,44 +1584,45 @@ const gchar *purple_get_host_name(void); gchar *purple_uuid_random(void); /** + * purple_callback_set_zero: + * @data: A pointer to variable, which should be set to NULL. + * * Sets given pointer to NULL. * * Function designed to be used as a GDestroyNotify callback. - * - * @data: A pointer to variable, which should be set to NULL. */ void purple_callback_set_zero(gpointer data); /** - * Creates a new GValue of the specified type. - * + * purple_value_new: * @type: The type of data to be held by the GValue * + * Creates a new GValue of the specified type. + * * Returns: The created GValue */ GValue *purple_value_new(GType type); /** - * Duplicates a GValue. - * + * purple_value_dup: * @value: The GValue to duplicate * + * Duplicates a GValue. + * * Returns: The duplicated GValue */ GValue *purple_value_dup(GValue *value); /** - * Frees a GValue. - * + * purple_value_free: * @value: The GValue to free. + * + * Frees a GValue. */ void purple_value_free(GValue *value); /** - * Calculates a session key for HTTP Digest authentation - * - * See RFC 2617 for more information. - * + * purple_http_digest_calculate_session_key: * @algorithm: The hash algorithm to use * @username: The username provided by the user * @realm: The authentication realm provided by the server @@ -1496,6 +1630,10 @@ void purple_value_free(GValue *value); * @nonce: The nonce provided by the server * @client_nonce: The nonce provided by the client * + * Calculates a session key for HTTP Digest authentation + * + * See RFC 2617 for more information. + * * Returns: The session key, or %NULL if an error occurred. */ gchar *purple_http_digest_calculate_session_key( @@ -1503,10 +1641,8 @@ gchar *purple_http_digest_calculate_session_key( const gchar *realm, const gchar *password, const gchar *nonce, const gchar *client_nonce); -/** Calculate a response for HTTP Digest authentication - * - * See RFC 2617 for more information. - * +/** + * purple_http_digest_calculate_response: * @algorithm: The hash algorithm to use * @method: The HTTP method in use * @digest_uri: The URI from the initial request @@ -1517,6 +1653,10 @@ gchar *purple_http_digest_calculate_session_key( * @client_nonce: The nonce provided by the client * @session_key: The session key from purple_cipher_http_digest_calculate_session_key() * + * Calculate a response for HTTP Digest authentication + * + * See RFC 2617 for more information. + * * Returns: The hashed response, or %NULL if an error occurred. */ gchar *purple_http_digest_calculate_response( |