[gmime] Fixed g_mime_message_set_reply_to() and updated docs for UTF-8 interfaces
- From: Jeffrey Stedfast <fejj src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gmime] Fixed g_mime_message_set_reply_to() and updated docs for UTF-8 interfaces
- Date: Mon, 12 Aug 2013 03:41:40 +0000 (UTC)
commit 5931ff36bf14c8a9b272845b377885a533399479
Author: Jeffrey Stedfast <fejj gnome org>
Date: Sun Aug 11 23:40:55 2013 -0400
Fixed g_mime_message_set_reply_to() and updated docs for UTF-8 interfaces
2013-08-11 Jeffrey Stedfast <fejj gnome org>
* gmime/gmime-message.c (g_mime_message_set_reply_to): Fixed this
function to parse the reply_to string just like
g_mime_message_set_sender() does so that the reply_to field can be
guaranteed to be in UTF-8.
* gmime/*.c: Updated API documentation for functions taking or
returning strings to clarify whether the strings should be in
UTF-8 or not.
ChangeLog | 11 +++++
TODO | 10 +++++
gmime/gmime-content-type.c | 28 ++++++++------
gmime/gmime-disposition.c | 27 ++++++++-----
gmime/gmime-header.c | 22 ++++++++++-
gmime/gmime-message.c | 91 +++++++++++++++++++++++++++++---------------
gmime/gmime-object.c | 48 +++++++++++++++++------
gmime/gmime-part.c | 14 ++++---
gmime/internet-address.c | 16 ++++++--
9 files changed, 188 insertions(+), 79 deletions(-)
---
diff --git a/ChangeLog b/ChangeLog
index 0efee8b..7e561b1 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,14 @@
+2013-08-11 Jeffrey Stedfast <fejj gnome org>
+
+ * gmime/gmime-message.c (g_mime_message_set_reply_to): Fixed this
+ function to parse the reply_to string just like
+ g_mime_message_set_sender() does so that the reply_to field can be
+ guaranteed to be in UTF-8.
+
+ * gmime/*.c: Updated API documentation for functions taking or
+ returning strings to clarify whether the strings should be in
+ UTF-8 or not.
+
2013-08-10 Jeffrey Stedfast <fejj gnome org>
* mono/GMime.metadata: Various fixups to get rid of warnings.
diff --git a/TODO b/TODO
index a6512b8..612fac1 100644
--- a/TODO
+++ b/TODO
@@ -3,6 +3,16 @@ the GMime library. This list of tasks in no way indicates priority,
that is to say that there is no rhyme or reason to the order that the
tasks are presented in.
+GMime 2.8 / 3.0 Planning:
+
+- Fix g_mime_message_[g,s]set_sender() to take/return an
+ InternetAddressList to be more consistent with the recipient
+ functions as well as being less error-prone.
+
+- Fix g_mime_message_[g,s]et_reply_to() to take/return an
+ InternetAddressList to be more consistent with the recipient
+ functions as well as being less error-prone.
+
GMime 2.6 Planning:
===================
diff --git a/gmime/gmime-content-type.c b/gmime/gmime-content-type.c
index 70acac4..31bedf7 100644
--- a/gmime/gmime-content-type.c
+++ b/gmime/gmime-content-type.c
@@ -395,25 +395,28 @@ g_mime_content_type_get_params (GMimeContentType *mime_type)
/**
* g_mime_content_type_set_parameter:
* @mime_type: MIME Content-Type
- * @attribute: parameter name (aka attribute)
+ * @name: parameter name (aka attribute)
* @value: parameter value
*
* Sets a parameter on the Content-Type.
+ *
+ * Note: The @name should be in US-ASCII while the @value should be in
+ * UTF-8.
**/
void
-g_mime_content_type_set_parameter (GMimeContentType *mime_type, const char *attribute, const char *value)
+g_mime_content_type_set_parameter (GMimeContentType *mime_type, const char *name, const char *value)
{
GMimeParam *param = NULL;
g_return_if_fail (GMIME_IS_CONTENT_TYPE (mime_type));
- g_return_if_fail (attribute != NULL);
+ g_return_if_fail (name != NULL);
g_return_if_fail (value != NULL);
- if ((param = g_hash_table_lookup (mime_type->param_hash, attribute))) {
+ if ((param = g_hash_table_lookup (mime_type->param_hash, name))) {
g_free (param->value);
param->value = g_strdup (value);
} else {
- param = g_mime_param_new (attribute, value);
+ param = g_mime_param_new (name, value);
mime_type->params = g_mime_param_append_param (mime_type->params, param);
g_hash_table_insert (mime_type->param_hash, param->name, param);
}
@@ -425,22 +428,23 @@ g_mime_content_type_set_parameter (GMimeContentType *mime_type, const char *attr
/**
* g_mime_content_type_get_parameter:
* @mime_type: a #GMimeContentType object
- * @attribute: parameter name (aka attribute)
+ * @name: parameter name (aka attribute)
*
- * Gets the parameter value specified by @attribute if it's available.
+ * Gets the parameter value specified by @name if it's available.
*
- * Returns: a const pointer to the paramer value specified by
- * @attribute or %NULL on fail.
+ * Returns: the value of the requested parameter or %NULL if the
+ * parameter is not set. If the parameter is set, the returned string
+ * will be in UTF-8.
**/
const char *
-g_mime_content_type_get_parameter (GMimeContentType *mime_type, const char *attribute)
+g_mime_content_type_get_parameter (GMimeContentType *mime_type, const char *name)
{
GMimeParam *param;
g_return_val_if_fail (GMIME_IS_CONTENT_TYPE (mime_type), NULL);
- g_return_val_if_fail (attribute != NULL, NULL);
+ g_return_val_if_fail (name != NULL, NULL);
- if (!(param = g_hash_table_lookup (mime_type->param_hash, attribute)))
+ if (!(param = g_hash_table_lookup (mime_type->param_hash, name)))
return NULL;
return param->value;
diff --git a/gmime/gmime-disposition.c b/gmime/gmime-disposition.c
index 9a13acb..943ecf7 100644
--- a/gmime/gmime-disposition.c
+++ b/gmime/gmime-disposition.c
@@ -261,25 +261,28 @@ g_mime_content_disposition_get_params (GMimeContentDisposition *disposition)
/**
* g_mime_content_disposition_set_parameter:
* @disposition: a #GMimeContentDisposition object
- * @attribute: parameter name
+ * @name: parameter name
* @value: parameter value
*
* Sets a parameter on the Content-Disposition.
+ *
+ * Note: The @name should be in US-ASCII while the @value should be in
+ * UTF-8.
**/
void
-g_mime_content_disposition_set_parameter (GMimeContentDisposition *disposition, const char *attribute, const
char *value)
+g_mime_content_disposition_set_parameter (GMimeContentDisposition *disposition, const char *name, const char
*value)
{
GMimeParam *param = NULL;
g_return_if_fail (GMIME_IS_CONTENT_DISPOSITION (disposition));
- g_return_if_fail (attribute != NULL);
+ g_return_if_fail (name != NULL);
g_return_if_fail (value != NULL);
- if ((param = g_hash_table_lookup (disposition->param_hash, attribute))) {
+ if ((param = g_hash_table_lookup (disposition->param_hash, name))) {
g_free (param->value);
param->value = g_strdup (value);
} else {
- param = g_mime_param_new (attribute, value);
+ param = g_mime_param_new (name, value);
disposition->params = g_mime_param_append_param (disposition->params, param);
g_hash_table_insert (disposition->param_hash, param->name, param);
}
@@ -291,21 +294,23 @@ g_mime_content_disposition_set_parameter (GMimeContentDisposition *disposition,
/**
* g_mime_content_disposition_get_parameter:
* @disposition: a #GMimeContentDisposition object
- * @attribute: parameter name
+ * @name: parameter name
*
- * Gets the value of the parameter @attribute, or %NULL on fail.
+ * Gets the parameter value specified by @name if it's available.
*
- * Returns: the value of the parameter of name @attribute.
+ * Returns: the value of the requested parameter or %NULL if the
+ * parameter is not set. If the parameter is set, the returned string
+ * will be in UTF-8.
**/
const char *
-g_mime_content_disposition_get_parameter (GMimeContentDisposition *disposition, const char *attribute)
+g_mime_content_disposition_get_parameter (GMimeContentDisposition *disposition, const char *name)
{
GMimeParam *param;
g_return_val_if_fail (GMIME_IS_CONTENT_DISPOSITION (disposition), NULL);
- g_return_val_if_fail (attribute != NULL, NULL);
+ g_return_val_if_fail (name != NULL, NULL);
- if (!(param = g_hash_table_lookup (disposition->param_hash, attribute)))
+ if (!(param = g_hash_table_lookup (disposition->param_hash, name)))
return NULL;
return param->value;
diff --git a/gmime/gmime-header.c b/gmime/gmime-header.c
index f2dc703..d75f2d1 100644
--- a/gmime/gmime-header.c
+++ b/gmime/gmime-header.c
@@ -415,6 +415,9 @@ g_mime_header_iter_get_name (GMimeHeaderIter *iter)
*
* Returns: %TRUE if the value was set or %FALSE otherwise (indicates
* invalid iter).
+ *
+ * Note: @value should be encoded with a function such as
+ * g_mime_utils_header_encode_text().
**/
gboolean
g_mime_header_iter_set_value (GMimeHeaderIter *iter, const char *value)
@@ -437,9 +440,12 @@ g_mime_header_iter_set_value (GMimeHeaderIter *iter, const char *value)
* g_mime_header_iter_get_value:
* @iter: a #GMimeHeaderIter
*
- * Gets the current header's name.
+ * Gets the current header's value.
*
- * Returns: the header name or %NULL if invalid.
+ * Returns: the header's raw, unprocessed value or %NULL if invalid.
+ *
+ * Note: The returned value should be decoded with a function such as
+ * g_mime_utils_header_decode_text() before displaying to the user.
**/
const char *
g_mime_header_iter_get_value (GMimeHeaderIter *iter)
@@ -633,6 +639,9 @@ g_mime_header_list_contains (const GMimeHeaderList *headers, const char *name)
* Prepends a header. If @value is %NULL, a space will be set aside
* for it (useful for setting the order of headers before values can
* be obtained for them) otherwise the header will be unset.
+ *
+ * Note: @value should be encoded with a function such as
+ * g_mime_utils_header_encode_text().
**/
void
g_mime_header_list_prepend (GMimeHeaderList *headers, const char *name, const char *value)
@@ -659,6 +668,9 @@ g_mime_header_list_prepend (GMimeHeaderList *headers, const char *name, const ch
* Appends a header. If @value is %NULL, a space will be set aside for it
* (useful for setting the order of headers before values can be
* obtained for them) otherwise the header will be unset.
+ *
+ * Note: @value should be encoded with a function such as
+ * g_mime_utils_header_encode_text().
**/
void
g_mime_header_list_append (GMimeHeaderList *headers, const char *name, const char *value)
@@ -686,6 +698,9 @@ g_mime_header_list_append (GMimeHeaderList *headers, const char *name, const cha
* Gets the value of the first header with the name requested.
*
* Returns: the value of the header requested.
+ *
+ * Note: The returned value should be decoded with a function such as
+ * g_mime_utils_header_decode_text() before displaying to the user.
**/
const char *
g_mime_header_list_get (const GMimeHeaderList *headers, const char *name)
@@ -716,6 +731,9 @@ g_mime_header_list_get (const GMimeHeaderList *headers, const char *name)
* Note: If there are multiple headers with the specified field name,
* the first instance of the header will be replaced and further
* instances will be removed.
+ *
+ * Additionally, @value should be encoded with a function such as
+ * g_mime_utils_header_encode_text().
**/
void
g_mime_header_list_set (GMimeHeaderList *headers, const char *name, const char *value)
diff --git a/gmime/gmime-message.c b/gmime/gmime-message.c
index 15334fe..1b92577 100644
--- a/gmime/gmime-message.c
+++ b/gmime/gmime-message.c
@@ -1054,11 +1054,15 @@ g_mime_message_new (gboolean pretty_headers)
/**
* g_mime_message_set_sender:
- * @message: MIME Message to change
+ * @message: A #GMimeMessage
* @sender: The name and address of the sender
*
* Set the sender's name and address on the MIME Message.
* (ex: "\"Joe Sixpack\" <joe sixpack org>")
+ *
+ * Note: The @sender string should be the raw encoded email
+ * address. It is probably best to use an #InternetAddress to
+ * construct and encode this value.
**/
void
g_mime_message_set_sender (GMimeMessage *message, const char *sender)
@@ -1089,11 +1093,13 @@ g_mime_message_set_sender (GMimeMessage *message, const char *sender)
/**
* g_mime_message_get_sender:
- * @message: MIME Message
+ * @message: A #GMimeMessage
*
* Gets the email address of the sender from @message.
*
- * Returns: the sender's name and address of the MIME Message.
+ * Returns: the sender's name and address of the @message in a form
+ * suitable for display or %NULL if no sender is set. If not %NULL,
+ * the returned string will be in UTF-8.
**/
const char *
g_mime_message_get_sender (GMimeMessage *message)
@@ -1106,21 +1112,36 @@ g_mime_message_get_sender (GMimeMessage *message)
/**
* g_mime_message_set_reply_to:
- * @message: MIME Message to change
+ * @message: A #GMimeMessage
* @reply_to: The Reply-To address
*
- * Set the sender's Reply-To address on the MIME Message.
+ * Set the sender's Reply-To address on the @message.
+ *
+ * Note: The @reply_to string should be the raw encoded email
+ * address. It is probably best to use an #InternetAddress to
+ * construct and encode this value.
**/
void
g_mime_message_set_reply_to (GMimeMessage *message, const char *reply_to)
{
+ InternetAddressList *addrlist;
+ char *encoded;
+
g_return_if_fail (GMIME_IS_MESSAGE (message));
g_return_if_fail (reply_to != NULL);
g_free (message->reply_to);
- message->reply_to = g_mime_strdup_trim (reply_to);
- g_mime_header_list_set (GMIME_OBJECT (message)->headers, "Reply-To", message->reply_to);
+ if ((addrlist = internet_address_list_parse_string (reply_to))) {
+ message->reply_to = internet_address_list_to_string (addrlist, FALSE);
+ encoded = internet_address_list_to_string (addrlist, TRUE);
+ g_mime_header_list_set (GMIME_OBJECT (message)->headers, "Reply-To", encoded);
+ g_object_unref (addrlist);
+ g_free (encoded);
+ } else {
+ g_mime_header_list_set (GMIME_OBJECT (message)->headers, "Reply-To", "");
+ message->reply_to = NULL;
+ }
if (message->mime_part)
g_mime_header_list_set_stream (message->mime_part->headers, NULL);
@@ -1129,11 +1150,13 @@ g_mime_message_set_reply_to (GMimeMessage *message, const char *reply_to)
/**
* g_mime_message_get_reply_to:
- * @message: MIME Message
+ * @message: A #GMimeMessage
*
* Gets the Reply-To address from @message.
*
- * Returns: the sender's Reply-To address from the MIME Message.
+ * Returns: the sender's Reply-To address in a form suitable for
+ * display or %NULL if no Reply-To address is set. If not %NULL, the
+ * returned string will be in UTF-8.
**/
const char *
g_mime_message_get_reply_to (GMimeMessage *message)
@@ -1187,12 +1210,14 @@ bcc_list_changed (InternetAddressList *list, gpointer args, GMimeMessage *messag
/**
* g_mime_message_add_recipient:
- * @message: MIME Message to change
+ * @message: A #GMimeMessage
* @type: A #GMimeRecipientType
* @name: The recipient's name (or %NULL)
* @addr: The recipient's address
*
- * Add a recipient of a chosen type to the MIME Message.
+ * Add a recipient of a chosen type to the MIME message.
+ *
+ * Note: The @name (and @addr) strings should be in UTF-8.
**/
void
g_mime_message_add_recipient (GMimeMessage *message, GMimeRecipientType type, const char *name, const char
*addr)
@@ -1218,13 +1243,13 @@ g_mime_message_add_recipient (GMimeMessage *message, GMimeRecipientType type, co
/**
* g_mime_message_get_recipients:
- * @message: MIME Message
+ * @message: A #GMimeMessage
* @type: A #GMimeRecipientType
*
- * Gets a list of recipients of type @type from @message.
+ * Gets a list of recipients of the specified @type from the @message.
*
- * Returns: (transfer none): a list of recipients of a chosen type
- * from the MIME Message.
+ * Returns: (transfer none): a list of recipients of the specified
+ * @type from the @message.
**/
InternetAddressList *
g_mime_message_get_recipients (GMimeMessage *message, GMimeRecipientType type)
@@ -1238,7 +1263,7 @@ g_mime_message_get_recipients (GMimeMessage *message, GMimeRecipientType type)
/**
* g_mime_message_get_all_recipients:
- * @message: MIME Message
+ * @message: A #GMimeMessage
*
* Gets the complete list of recipients for @message.
*
@@ -1272,10 +1297,12 @@ g_mime_message_get_all_recipients (GMimeMessage *message)
/**
* g_mime_message_set_subject:
- * @message: MIME Message
+ * @message: A #GMimeMessage
* @subject: Subject string
*
- * Set the unencoded UTF-8 Subject field on a MIME Message.
+ * Set the subject of a @message.
+ *
+ * Note: The @subject string should be in UTF-8.
**/
void
g_mime_message_set_subject (GMimeMessage *message, const char *subject)
@@ -1299,11 +1326,13 @@ g_mime_message_set_subject (GMimeMessage *message, const char *subject)
/**
* g_mime_message_get_subject:
- * @message: MIME Message
+ * @message: A #GMimeMessage
*
- * Gets the message's subject.
+ * Gets the subject of the @message.
*
- * Returns: the unencoded UTF-8 Subject field on a MIME Message.
+ * Returns: the subject of the @message in a form suitable for display
+ * or %NULL if no subject is set. If not %NULL, the returned string
+ * will be in UTF-8.
**/
const char *
g_mime_message_get_subject (GMimeMessage *message)
@@ -1316,7 +1345,7 @@ g_mime_message_get_subject (GMimeMessage *message)
/**
* g_mime_message_set_date:
- * @message: MIME Message
+ * @message: A #GMimeMessage
* @date: a date to be used in the Date header
* @tz_offset: timezone offset (in +/- hours)
*
@@ -1343,7 +1372,7 @@ g_mime_message_set_date (GMimeMessage *message, time_t date, int tz_offset)
/**
* g_mime_message_get_date:
- * @message: MIME Message
+ * @message: A #GMimeMessage
* @date: (out): pointer to a date in time_t
* @tz_offset: (out): pointer to timezone offset (in +/- hours)
*
@@ -1366,7 +1395,7 @@ g_mime_message_get_date (GMimeMessage *message, time_t *date, int *tz_offset)
/**
* g_mime_message_get_date_as_string:
- * @message: MIME Message
+ * @message: A #GMimeMessage
*
* Gets the message's sent-date in string format.
*
@@ -1383,7 +1412,7 @@ g_mime_message_get_date_as_string (GMimeMessage *message)
/**
* g_mime_message_set_date_as_string:
- * @message: MIME Message
+ * @message: A #GMimeMessage
* @str: a date string
*
* Sets the sent-date of the message.
@@ -1412,7 +1441,7 @@ g_mime_message_set_date_as_string (GMimeMessage *message, const char *str)
/**
* g_mime_message_set_message_id:
- * @message: MIME Message
+ * @message: A #GMimeMessage
* @message_id: message-id (addr-spec portion)
*
* Set the Message-Id on a message.
@@ -1439,7 +1468,7 @@ g_mime_message_set_message_id (GMimeMessage *message, const char *message_id)
/**
* g_mime_message_get_message_id:
- * @message: MIME Message
+ * @message: A #GMimeMessage
*
* Gets the Message-Id header of @message.
*
@@ -1456,7 +1485,7 @@ g_mime_message_get_message_id (GMimeMessage *message)
/**
* g_mime_message_get_mime_part:
- * @message: MIME Message
+ * @message: A #GMimeMessage
*
* Gets the toplevel MIME part contained within @message.
*
@@ -1476,7 +1505,7 @@ g_mime_message_get_mime_part (GMimeMessage *message)
/**
* g_mime_message_set_mime_part:
- * @message: MIME Message
+ * @message: A #GMimeMessage
* @mime_part: The root-level MIME Part
*
* Set the root-level MIME part of the message.
@@ -1515,7 +1544,7 @@ g_mime_message_set_mime_part (GMimeMessage *message, GMimeObject *mime_part)
/**
* g_mime_message_foreach:
- * @message: a #GMimeMessage
+ * @message: A #GMimeMessage
* @callback: (scope call): function to call on each of the mime parts
* contained by the mime message
* @user_data: user-supplied callback data
@@ -1589,7 +1618,7 @@ multipart_guess_body (GMimeMultipart *multipart)
/**
* g_mime_message_get_body:
- * @message: MIME Message
+ * @message: A #GMimeMessage
*
* Attempts to identify the MIME part containing the body of the
* message.
diff --git a/gmime/gmime-object.c b/gmime/gmime-object.c
index 08e636f..6d326f2 100644
--- a/gmime/gmime-object.c
+++ b/gmime/gmime-object.c
@@ -473,6 +473,9 @@ g_mime_object_get_content_type (GMimeObject *object)
* @value: param value
*
* Sets the content-type param @name to the value @value.
+ *
+ * Note: The @name string should be in US-ASCII while the @value
+ * string should be in UTF-8.
**/
void
g_mime_object_set_content_type_parameter (GMimeObject *object, const char *name, const char *value)
@@ -492,8 +495,9 @@ g_mime_object_set_content_type_parameter (GMimeObject *object, const char *name,
* Gets the value of the content-type param @name set on the MIME part
* @object.
*
- * Returns: the value of the requested content-type param or %NULL on
- * if the param doesn't exist.
+ * Returns: the value of the requested content-type param or %NULL if
+ * the param doesn't exist. If the param is set, the returned string
+ * will be in UTF-8.
**/
const char *
g_mime_object_get_content_type_parameter (GMimeObject *object, const char *name)
@@ -624,49 +628,53 @@ g_mime_object_get_disposition (GMimeObject *object)
/**
* g_mime_object_set_content_disposition_parameter:
* @object: a #GMimeObject
- * @attribute: parameter name
+ * @name: parameter name
* @value: parameter value
*
* Add a content-disposition parameter to the specified mime part.
+ *
+ * Note: The @name string should be in US-ASCII while the @value
+ * string should be in UTF-8.
**/
void
-g_mime_object_set_content_disposition_parameter (GMimeObject *object, const char *attribute, const char
*value)
+g_mime_object_set_content_disposition_parameter (GMimeObject *object, const char *name, const char *value)
{
GMimeContentDisposition *disposition;
g_return_if_fail (GMIME_IS_OBJECT (object));
- g_return_if_fail (attribute != NULL);
+ g_return_if_fail (name != NULL);
if (!object->disposition) {
disposition = g_mime_content_disposition_new ();
_g_mime_object_set_content_disposition (object, disposition);
}
- g_mime_content_disposition_set_parameter (object->disposition, attribute, value);
+ g_mime_content_disposition_set_parameter (object->disposition, name, value);
}
/**
* g_mime_object_get_content_disposition_parameter:
* @object: a #GMimeObject
- * @attribute: parameter name
+ * @name: parameter name
*
* Gets the value of the Content-Disposition parameter specified by
- * @attribute, or %NULL if the parameter does not exist.
+ * @name, or %NULL if the parameter does not exist.
*
- * Returns: the value of a previously defined content-disposition
- * parameter specified by @attribute.
+ * Returns: the value of the requested content-disposition param or
+ * %NULL if the param doesn't exist. If the param is set, the returned
+ * string will be in UTF-8.
**/
const char *
-g_mime_object_get_content_disposition_parameter (GMimeObject *object, const char *attribute)
+g_mime_object_get_content_disposition_parameter (GMimeObject *object, const char *name)
{
g_return_val_if_fail (GMIME_IS_OBJECT (object), NULL);
- g_return_val_if_fail (attribute != NULL, NULL);
+ g_return_val_if_fail (name != NULL, NULL);
if (!object->disposition)
return NULL;
- return g_mime_content_disposition_get_parameter (object->disposition, attribute);
+ return g_mime_content_disposition_get_parameter (object->disposition, name);
}
@@ -777,6 +785,9 @@ object_prepend_header (GMimeObject *object, const char *header, const char *valu
* @value: header value
*
* Prepends a raw, unprocessed header to the MIME object.
+ *
+ * Note: @value should be encoded with a function such as
+ * g_mime_utils_header_encode_text().
**/
void
g_mime_object_prepend_header (GMimeObject *object, const char *header, const char *value)
@@ -803,6 +814,9 @@ object_append_header (GMimeObject *object, const char *header, const char *value
* @value: header value
*
* Appends a raw, unprocessed header to the MIME object.
+ *
+ * Note: @value should be encoded with a function such as
+ * g_mime_utils_header_encode_text().
**/
void
g_mime_object_append_header (GMimeObject *object, const char *header, const char *value)
@@ -830,6 +844,9 @@ object_set_header (GMimeObject *object, const char *header, const char *value)
* @value: header value
*
* Sets an arbitrary raw, unprocessed header on the MIME object.
+ *
+ * Note: @value should be encoded with a function such as
+ * g_mime_utils_header_encode_text().
**/
void
g_mime_object_set_header (GMimeObject *object, const char *header, const char *value)
@@ -858,6 +875,9 @@ object_get_header (GMimeObject *object, const char *header)
*
* Returns: the raw, unprocessed value of the requested header if it
* exists or %NULL otherwise.
+ *
+ * Note: The returned value should be decoded with a function such as
+ * g_mime_utils_header_decode_text() before displaying to the user.
**/
const char *
g_mime_object_get_header (GMimeObject *object, const char *header)
@@ -937,6 +957,8 @@ object_get_headers (GMimeObject *object)
* headers.
*
* Returns: an allocated string containing all of the raw MIME headers.
+ *
+ * Note: The returned string will not be suitable for display.
**/
char *
g_mime_object_get_headers (GMimeObject *object)
diff --git a/gmime/gmime-part.c b/gmime/gmime-part.c
index ee358a2..1c66088 100644
--- a/gmime/gmime-part.c
+++ b/gmime/gmime-part.c
@@ -806,10 +806,12 @@ g_mime_part_get_best_content_encoding (GMimePart *mime_part, GMimeEncodingConstr
/**
* g_mime_part_set_filename:
* @mime_part: a #GMimePart object
- * @filename: the filename of the Mime Part's content
+ * @filename: the file name
*
* Sets the "filename" parameter on the Content-Disposition and also sets the
* "name" parameter on the Content-Type.
+ *
+ * Note: The @filename string should be in UTF-8.
**/
void
g_mime_part_set_filename (GMimePart *mime_part, const char *filename)
@@ -827,12 +829,12 @@ g_mime_part_set_filename (GMimePart *mime_part, const char *filename)
* g_mime_part_get_filename:
* @mime_part: a #GMimePart object
*
- * Gets the filename of the specificed mime part, or %NULL if the mime
- * part does not have the filename or name parameter set.
+ * Gets the filename of the specificed mime part, or %NULL if the
+ * @mime_part does not have the filename or name parameter set.
*
- * Returns: the filename of the specified MIME Part. It first checks to
- * see if the "filename" parameter was set on the Content-Disposition
- * and if not then checks the "name" parameter in the Content-Type.
+ * Returns: the filename of the specified @mime_part or %NULL if
+ * neither of the parameters is set. If a file name is set, the
+ * returned string will be in UTF-8.
**/
const char *
g_mime_part_get_filename (GMimePart *mime_part)
diff --git a/gmime/internet-address.c b/gmime/internet-address.c
index b55e93f..5a80835 100644
--- a/gmime/internet-address.c
+++ b/gmime/internet-address.c
@@ -173,6 +173,8 @@ _internet_address_set_name (InternetAddress *ia, const char *name)
* @name: the display name for the address group or mailbox
*
* Set the display name of the #InternetAddress.
+ *
+ * Note: The @name string should be in UTF-8.
**/
void
internet_address_set_name (InternetAddress *ia, const char *name)
@@ -191,7 +193,9 @@ internet_address_set_name (InternetAddress *ia, const char *name)
*
* Gets the display name of the #InternetAddress.
*
- * Returns: the display name of @ia.
+ * Returns: the name of the mailbox or group in a form suitable for
+ * display if available or %NULL otherwise. If the name is available,
+ * the returned string will be in UTF-8.
**/
const char *
internet_address_get_name (InternetAddress *ia)
@@ -301,10 +305,12 @@ internet_address_mailbox_finalize (GObject *object)
* @name: person's name
* @addr: person's address
*
- * Creates a new #InternetAddress object with name @name and address
+ * Creates a new #InternetAddress object with the specified @name and
* @addr.
*
* Returns: a new #InternetAddressMailbox object.
+ *
+ * Note: The @name string should be in UTF-8.
**/
InternetAddress *
internet_address_mailbox_new (const char *name, const char *addr)
@@ -440,10 +446,12 @@ internet_address_group_finalize (GObject *object)
* internet_address_group_new:
* @name: group name
*
- * Creates a new #InternetAddressGroup object with a display name of
+ * Creates a new #InternetAddressGroup object with the specified
* @name.
*
* Returns: a new #InternetAddressGroup object.
+ *
+ * Note: The @name string should be in UTF-8.
**/
InternetAddress *
internet_address_group_new (const char *name)
@@ -1211,7 +1219,7 @@ internet_address_list_to_string (InternetAddressList *list, gboolean encode)
* @str: string to write to
*
* Writes the rfc2047-encoded rfc822 formatted addresses in @list to
- * @string, folding appropriately.
+ * @str, folding appropriately.
**/
void
internet_address_list_writer (InternetAddressList *list, GString *str)
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
