comparison src/util.h @ 11135:f2755f58a7da

[gaim-migrate @ 13196] Straighten out some comments and get rid of a warning in gtkutils.c committer: Tailor Script <[e-mail]>

11134:f78e7e982cf4

 *                pass in NULL if you're sure that you know
 *                the length of the decoded data, or if you
 *                know you'll be able to use strlen to
 *                determine the length, etc.
 *
 * @return The raw data.  Must be g'free'd when no longer needed.
 */
guint8 *gaim_quotedp_decode(const char *str, gsize *ret_len);

/*@}*/

 * according to RFC 2047.  Basically, a header is plain ASCII and can
 * contain any number of sections called "encoded-words."  The format
 * of an encoded word is =?ISO-8859-1?Q?Keld_J=F8rn_Simonsen?=
 * =? designates the beginning of the encoded-word
 * ?= designates the end of the encoded-word
 * ? segments the encoded word into three pieces.  The first piece is
 *   the character set, the second piece is the encoding, and the
 *   third piece is the encoded text.
 *
 * @param str The string to convert back.
 *
 * @return The readable string.
 */
char *gaim_mime_decode_field (const char *str);

/*@}*/


/**************************************************************************/

/**
 * Creates a string according to a time and format string
 *
 * This function just calls strftime. The only advantage to using it
 * is that gcc won't give a warning if you use %c
 */
size_t gaim_strftime(char *s, size_t max, const char *format, const struct tm *tm);

/*@}*/

/** @name Markup Functions                                                */
/**************************************************************************/
/*@{*/

/**
 * Finds a 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.
 *

 * @return True if the email address is syntactically correct.
 */
gboolean gaim_email_is_valid(const char *address);

/**
 * This function extracts a list of URIs from the a "text/uri-list" string
 * It was "borrowed" from gnome_uri_list_extract_uris
 * 
 * @param uri_list an uri-list in the standard format.
 *
 * @return a GList containing strings allocated with g_malloc that have been 
 *	splitted from uri-list.
 */
GList* gaim_uri_list_extract_uris (const gchar* uri_list);

/**
 * This function extracts a list of filenames from the a "text/uri-list" string
 * It was "borrowed" from gnome_uri_list_extract_filenames
 * 
 * @param uri_list an uri-list in the standard format.
 *
 * @return a GList containing strings allocated with g_malloc that contain the 
 * 	filenames in the uri-list. Note that unlike gaim_uri_list_extract_uris() 
 * 	function, this will discard any non-file uri from the result value.
 */
GList* gaim_uri_list_extract_filenames (const gchar* uri_list);

/*@}*/

/**************************************************************************
 * UTF8 String Functions

11135:f2755f58a7da

 *                pass in NULL if you're sure that you know
 *                the length of the decoded data, or if you
 *                know you'll be able to use strlen to
 *                determine the length, etc.
 *
 * @return The raw data.  Must be g_free'd when no longer needed.
 */
guint8 *gaim_quotedp_decode(const char *str, gsize *ret_len);

/*@}*/

 * according to RFC 2047.  Basically, a header is plain ASCII and can
 * contain any number of sections called "encoded-words."  The format
 * of an encoded word is =?ISO-8859-1?Q?Keld_J=F8rn_Simonsen?=
 * =? designates the beginning of the encoded-word
 * ?= designates the end of the encoded-word
 *
 * An encoded word is segmented into three pieces by the use of a
 * question mark.  The first piece is the character set, the second
 * piece is the encoding, and the third piece is the encoded text.
 *
 * @param str The ASCII string, possibly containing any number of
 *            encoded-word sections.
 *
 * @return The string, with any encoded-word sections decoded and
 *         converted to UTF-8.  Must be g_free'd when no longer
 *         needed.
 */
char *gaim_mime_decode_field(const char *str);

/*@}*/


/**************************************************************************/

/**
 * Creates a string according to a time and format string
 *
 * This function just calls strftime. The only advantage to using it
 * is that gcc won't give a warning if you use %c
 *
 * TODO: The warning is gone in gcc4, and this function can
 *       eventually be removed.
 */
size_t gaim_strftime(char *s, size_t max, const char *format, const struct tm *tm);

/*@}*/

/** @name Markup Functions                                                */
/**************************************************************************/
/*@{*/

/**
 * 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.
 *

 * @return True if the email address is syntactically correct.
 */
gboolean gaim_email_is_valid(const char *address);

/**
 * This function extracts a list of URIs from the a "text/uri-list"
 * string.  It was "borrowed" from gnome_uri_list_extract_uris
 *
 * @param uri_list An uri-list in the standard format.
 *
 * @return A GList containing strings allocated with g_malloc
 *         that have been splitted from uri-list.
 */
GList *gaim_uri_list_extract_uris(const gchar *uri_list);

/**
 * This function extracts a list of filenames from a
 * "text/uri-list" string.  It was "borrowed" from
 * gnome_uri_list_extract_filenames
 *
 * @param uri_list A uri-list in the standard format.
 *
 * @return A GList containing strings allocated with g_malloc that
 *         contain the filenames in the uri-list. Note that unlike
 *         gaim_uri_list_extract_uris() function, this will discard
 *         any non-file uri from the result value.
 */
GList *gaim_uri_list_extract_filenames(const gchar *uri_list);

/*@}*/

/**************************************************************************
 * UTF8 String Functions