diff options
Diffstat (limited to 'camel/camel-recipient.c')
| -rw-r--r-- | camel/camel-recipient.c | 93 |
1 files changed, 83 insertions, 10 deletions
diff --git a/camel/camel-recipient.c b/camel/camel-recipient.c index 436af5058b..f1b18bea24 100644 --- a/camel/camel-recipient.c +++ b/camel/camel-recipient.c @@ -27,6 +27,17 @@ #include "camel-recipient.h" +/** + * camel_recipient_table_new: Create a new recipient table object + * + * + * creates a new recipient table object. A recipient table + * objects merely associates a recipient list (GList) to + * recipient types (as for example "To", "Cc" for mime + * maile messages + * + * Return value: the newly created recipient table object + **/ CamelRecipientTable * camel_recipient_table_new () { @@ -39,6 +50,12 @@ camel_recipient_table_new () } +/** + * camel_recipient_table_ref: add a reference to a recipient table object + * @recipient_table: the recipient table object + * + * Add a reference to a recipient table object. + **/ void camel_recipient_table_ref (CamelRecipientTable *recipient_table) { @@ -63,6 +80,13 @@ _free_recipient_list (gpointer key, gpointer value, gpointer user_data) } +/** + * camel_recipient_table_free: Free a recipient table object + * @recipient_table: the recipient table object to free + * + * Free a recipient table object. All recipients and recipient + * are freed. + **/ void camel_recipient_table_free (CamelRecipientTable *recipient_table) { @@ -76,6 +100,15 @@ camel_recipient_table_free (CamelRecipientTable *recipient_table) +/** + * camel_recipient_table_unref: Removes a reference to a recipient table object + * @recipient_table: the recipient table object + * + * Removes a reference to the reference count of a recipient + * table object. If the reference count falls to zero, the + * recipient table object is freed. + * + **/ void camel_recipient_table_unref (CamelRecipientTable *recipient_table) { @@ -89,13 +122,18 @@ camel_recipient_table_unref (CamelRecipientTable *recipient_table) + /** - * camel_recipient_table_add: - * @recipient_table: - * @recipient_type: - * @recipient: - * + * camel_recipient_table_add: Add a recipient to a recipient table object. + * @recipient_table: The recipient table object + * @recipient_type: Recipient type string + * @recipient: The recipient to add * + * Add a recipient to a recipient table object. + * The recipient is appended to the list of recipients + * of type @recipient_type. @recipient and @recipient_type + * are duplicated if necessary and freed when + * camel_recipient_table_free is called. **/ void camel_recipient_table_add (CamelRecipientTable *recipient_table, @@ -122,12 +160,15 @@ camel_recipient_table_add (CamelRecipientTable *recipient_table, /** - * camel_recipient_table_add_list: - * @recipient_table: - * @recipient_type: - * @recipient_list: + * camel_recipient_table_add_list: Add a full list of recipients to a recipient table. + * @recipient_table: The recipient table object + * @recipient_type: Recipient type string. + * @recipient_list: Recipient list to add. * - * be careful, that the list is used as is, and its element + * Add a full list of recipients to a recipient table. + * The new recipients are appended at the end of the + * existing recipient list corresponding to @recipient_type. + * Be careful, the list is used as is, and its element * will be freed by camel_recipient_table_unref **/ void @@ -151,6 +192,17 @@ camel_recipient_table_add_list (CamelRecipientTable *recipient_table, +/** + * camel_recipient_table_remove: Remove a recipient from a recipient table. + * @recipient_table: The recipient table object + * @recipient_type: Recipient type string. + * @recipient: Recipient to remove from the table + * + * Remove a recipient from a recipient table. The recipient is + * only removed from the recipient list corresponding to + * @recipient_type. The removed recipient is freed. + * + **/ void camel_recipient_table_remove (CamelRecipientTable *recipient_table, const gchar *recipient_type, @@ -186,6 +238,19 @@ camel_recipient_table_remove (CamelRecipientTable *recipient_table, +/** + * camel_recipient_table_get: Get the recipients corresponding to a recipient type. + * @recipient_table: The recipient table object + * @recipient_type: Recipient type string. + * + * Return the list of recipients corresponding to + * @recipient_type. The returned list is not a copy + * of the internal list used by the recipient table object + * but the list itself. It thus must not be freed. + * The recipients it contains can be modified. + * + * Return value: The list of recipients. + **/ const GList * camel_recipient_table_get (CamelRecipientTable *recipient_table, const gchar *recipient_type) @@ -196,6 +261,14 @@ camel_recipient_table_get (CamelRecipientTable *recipient_table, +/** + * camel_recipient_foreach_recipient_type: Runs a function over over all recipients type lists. + * @recipient_table: The recipient table object. + * @func: The function to run. + * @user_data: User data to pass to the function. + * + * Runs a function over over all recipients type lists. + **/ void camel_recipient_foreach_recipient_type (CamelRecipientTable *recipient_table, CRLFunc func, |