GDataContactsGroup: GData Reference Manual

## GDataContactsGroup GDataContactsGroup — GData Contacts group object |

## Stability Level

Stable, unless otherwise indicated

## Functions

GDataContactsGroup * | gdata_contacts_group_new ()
gint64 | gdata_contacts_group_get_edited ()
gboolean | gdata_contacts_group_is_deleted ()
const gchar * | gdata_contacts_group_get_system_group_id ()
const gchar * | gdata_contacts_group_get_extended_property ()
GHashTable * | gdata_contacts_group_get_extended_properties ()
gboolean | gdata_contacts_group_set_extended_property ()

## Properties

gboolean | deleted | Read
gint64 | edited | Read
char * | system-group-id | Read

## Types and Values

#define | GDATA_CONTACTS_GROUP_CONTACTS
#define | GDATA_CONTACTS_GROUP_FRIENDS
#define | GDATA_CONTACTS_GROUP_FAMILY
#define | GDATA_CONTACTS_GROUP_COWORKERS
| GDataContactsGroup
| GDataContactsGroupClass

## Object Hierarchy

        GObject
        ╰── GDataParsable
            ╰── GDataEntry
                ╰── GDataContactsGroup

## Includes

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

## 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 25. 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);

## Functions

### gdata_contacts_group_new ()

    GDataContactsGroup *
    gdata_contacts_group_new (const gchar *id);

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

#### Parameters

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.

#### Parameters

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”).

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

## Types and Values

### 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

## Property Details

### The `“deleted”` property

      “deleted”                  gboolean

Whether the entry has been deleted.

Owner: GDataContactsGroup

Flags: Read

Default value: FALSE

Since: 0.7.0

### The `“edited”` property

      “edited”                   gint64

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.

Owner: GDataContactsGroup

Flags: Read

Allowed values: >= -1

Default value: -1

Since: 0.7.0

### The `“system-group-id”` property

      “system-group-id”          char *

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.

Owner: GDataContactsGroup

Flags: Read

Default value: NULL

Since: 0.7.0