GDataContactsGroup

## GDataContactsGroup GDataContactsGroup — GData Contacts group object |

## Stability Level

Unstable, unless otherwise indicated

## Synopsis

    #include <gdata/services/contacts/gdata-contacts-group.h>

    #define             GDATA_CONTACTS_GROUP_CONTACTS
    #define             GDATA_CONTACTS_GROUP_FRIENDS
    #define             GDATA_CONTACTS_GROUP_FAMILY
    #define             GDATA_CONTACTS_GROUP_COWORKERS
                        GDataContactsGroup;
                        GDataContactsGroupClass;
    GDataContactsGroup * gdata_contacts_group_new           (const gchar *id);
    gint64              gdata_contacts_group_get_edited     (GDataContactsGroup *self);
    gboolean            gdata_contacts_group_is_deleted     (GDataContactsGroup *self);
    const gchar *       gdata_contacts_group_get_system_group_id
                                                            (GDataContactsGroup *self);
    const gchar *       gdata_contacts_group_get_extended_property
                                                            (GDataContactsGroup *self,
                                                             const gchar *name);
    GHashTable *        gdata_contacts_group_get_extended_properties
                                                            (GDataContactsGroup *self);
    gboolean            gdata_contacts_group_set_extended_property
                                                            (GDataContactsGroup *self,
                                                             const gchar *name,
                                                             const gchar *value);

## Object Hierarchy

      GObject
       +----GDataParsable
             +----GDataEntry
                   +----GDataContactsGroup

## Properties

      "deleted"                  gboolean              : Read
      "edited"                   gint64                : Read
      "system-group-id"          gchar*                : Read

## Description

GDataContactsGroup is a subclass of GDataEntry to represent a group from a Google address book.

For more details of Google Contacts' GData API, see the online documentation.

The user-set name of the group is stored in the "title" property, retrievable using `gdata_entry_get_title()`. Note that for system groups (see "system-group-id"), this group name is provided by Google, and is not localised. Clients should provide their own localised group names for the system groups.

In addition to all the standard properties available for a group, GDataContactsGroup supports an additional kind of property: extended properties. Extended properties, set with `gdata_contacts_group_set_extended_property()` and retrieved with `gdata_contacts_group_get_extended_property()`, are provided as a method of storing client-specific data which shouldn't be seen or be editable by the user, such as IDs and cache times.

Example 26. Adding a New Group

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    GDataContactsService *service;
    GDataContactsGroup *group, *updated_group;
    GDataContactsContact *contact, *updated_contact;
    GError *error = NULL;

    /* Create a service and return a contact to add to the new group. */
    service = create_contacts_service ();
    contact = query_user_for_contact (service);

    /* Create the new group */
    group = gdata_contacts_group_new (NULL);
    gdata_entry_set_title (GDATA_ENTRY (group), "Group Name");

    /* Insert the group on the server */
    updated_group = gdata_contacts_service_insert_group (service, group, NULL, &error);

    g_object_unref (group);

    if (error != NULL) {
        g_error ("Error adding a group: %s", error->message);
        g_error_free (error);
        g_object_unref (contact);
        g_object_unref (service);
        return;
    }

    /* Add the contact to the new group. */
    gdata_contacts_contact_add_group (contact, gdata_entry_get_id (GDATA_ENTRY (updated_group)));

    g_object_unref (updated_group);

    /* Update the contact on the server */
    updated_contact = GDATA_CONTACTS_CONTACT (gdata_service_update_entry (GDATA_SERVICE (service), GDATA_ENTRY (contact), NULL, &error));

    g_object_unref (contact);
    g_object_unref (service);

    if (error != NULL) {
        g_error ("Error updating contact: %s", error->message);
        g_error_free (error);
        return;
    }

    /* Do something with the updated contact, such as update them in the UI, or store their ID for future use. */

    g_object_unref (updated_contact);

## Details

### GDATA_CONTACTS_GROUP_CONTACTS

    #define GDATA_CONTACTS_GROUP_CONTACTS "Contacts"

The system group ID for the "My Contacts" system group.

Since 0.7.0

### GDATA_CONTACTS_GROUP_FRIENDS

    #define GDATA_CONTACTS_GROUP_FRIENDS "Friends"

The system group ID for the "Friends" system group.

Since 0.7.0

### GDATA_CONTACTS_GROUP_FAMILY

    #define GDATA_CONTACTS_GROUP_FAMILY "Family"

The system group ID for the "Family" system group.

Since 0.7.0

### GDATA_CONTACTS_GROUP_COWORKERS

    #define GDATA_CONTACTS_GROUP_COWORKERS "Coworkers"

The system group ID for the "Coworkers" system group.

Since 0.7.0

### GDataContactsGroup

    typedef struct _GDataContactsGroup GDataContactsGroup;

All the fields in the GDataContactsGroup structure are private and should never be accessed directly.

Since 0.7.0

### GDataContactsGroupClass

    typedef struct {
    } GDataContactsGroupClass;

All the fields in the GDataContactsGroupClass structure are private and should never be accessed directly.

Since 0.7.0

### gdata_contacts_group_new ()

    GDataContactsGroup * gdata_contacts_group_new           (const gchar *id);

Creates a new GDataContactsGroup with the given ID and default properties.

`id` : | the group's ID, or `NULL`. [allow-none]
Returns : | a new GDataContactsGroup; unref with `g_object_unref()`

Since 0.7.0

### gdata_contacts_group_get_edited ()

    gint64              gdata_contacts_group_get_edited     (GDataContactsGroup *self);

Gets the "edited" property. If the property is unset, `-1` will be returned.

`self` : | a GDataContactsGroup
Returns : | the UNIX timestamp for the time the file was last edited, or `-1`

Since 0.7.0

### gdata_contacts_group_is_deleted ()

    gboolean            gdata_contacts_group_is_deleted     (GDataContactsGroup *self);

Returns whether the group has recently been deleted. This will always return `FALSE` unless "show-deleted" has been set to `TRUE` for the query which returned the group; then this function will return `TRUE` only if the group has been deleted.

If a group has been deleted, no other information is available about it. This is designed to allow groups to be deleted from local address books using incremental updates from the server (e.g. with "updated-min" and "show-deleted").

`self` : | a GDataContactsGroup
Returns : | `TRUE` if the group has been deleted, `FALSE` otherwise

Since 0.7.0

### gdata_contacts_group_get_system_group_id ()

    const gchar *       gdata_contacts_group_get_system_group_id
                                                            (GDataContactsGroup *self);

Gets the "system-group-id" property. If the group is not a system group, `NULL` will be returned.

`self` : | a GDataContactsGroup
Returns : | the group's system group ID, or `NULL`

Since 0.7.0

### gdata_contacts_group_get_extended_property ()

    const gchar *       gdata_contacts_group_get_extended_property
                                                            (GDataContactsGroup *self,
                                                             const gchar *name);

Gets the value of an extended property of the group. Each group can have up to 10 client-set extended properties to store data of the client's choosing.

`self` : | a GDataContactsGroup
`name` : | the property name; an arbitrary, unique string
Returns : | the property's value, or `NULL`

Since 0.7.0

### gdata_contacts_group_get_extended_properties ()

    GHashTable *        gdata_contacts_group_get_extended_properties
                                                            (GDataContactsGroup *self);

Gets the full list of extended properties of the group; a hash table mapping property name to value.

`self` : | a GDataContactsGroup
Returns : | a GHashTable of extended properties. [transfer none]

Since 0.7.0

### gdata_contacts_group_set_extended_property ()

    gboolean            gdata_contacts_group_set_extended_property
                                                            (GDataContactsGroup *self,
                                                             const gchar *name,
                                                             const gchar *value);

Sets the value of a group's extended property. Extended property names are unique (but of the client's choosing), and reusing the same property name will result in the old value of that property being overwritten.

To unset a property, set `value` to `NULL` or an empty string.

A group may have up to 10 extended properties, and each should be reasonably small (i.e. not a photo or ringtone). For more information, see the online documentation. `FALSE` will be returned if you attempt to add more than 10 extended properties.

`self` : | a GDataContactsGroup
`name` : | the property name; an arbitrary, unique string
`value` : | the property value, or `NULL`. [allow-none]
Returns : | `TRUE` if the property was updated or deleted successfully, `FALSE` otherwise

Since 0.7.0

## Property Details

### The `"deleted"` property

      "deleted"                  gboolean              : Read

Whether the entry has been deleted.

Default value: FALSE

Since 0.7.0

### The `"edited"` property

      "edited"                   gint64                : Read

The last time the group was edited. If the group has not been edited yet, the content indicates the time it was created.

For more information, see the Atom Publishing Protocol specification.

Allowed values: >= -1

Default value: -1

Since 0.7.0

### The `"system-group-id"` property

      "system-group-id"          gchar*                : Read

The system group ID for this group, if it's a system group. If the group is not a system group, this is `NULL`. Otherwise, it is one of the four system group IDs: `GDATA_CONTACTS_GROUP_CONTACTS`, `GDATA_CONTACTS_GROUP_FRIENDS`, `GDATA_CONTACTS_GROUP_FAMILY` and `GDATA_CONTACTS_GROUP_COWORKERS`.

If this is non-`NULL`, the group name stored in "title" will not be localised, so clients should provide localised group names of their own for each of the system groups. Whether a group is a system group should be detected solely on the basis of the value of this property, not by comparing the group name ("title") or entry ID ("id"). The entry ID is not the same as the system group ID.

Default value: NULL

Since 0.7.0