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
gchar *	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 26. Adding a New Group

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

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.

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.

Flags: Read

Allowed values: >= -1

Default value: -1

Since: 0.7.0

The `“system-group-id”` property

  “system-group-id”          gchar *

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.

Flags: Read

Default value: NULL

Since: 0.7.0

GDataContactsGroup

Stability Level

Functions

Properties

Types and Values

Object Hierarchy

Includes

Description

Functions

gdata_contacts_group_new ()

Parameters

Returns

gdata_contacts_group_get_edited ()

Parameters

Returns

gdata_contacts_group_is_deleted ()

Parameters

Returns

gdata_contacts_group_get_system_group_id ()

Parameters

Returns

gdata_contacts_group_get_extended_property ()

Parameters

Returns

gdata_contacts_group_get_extended_properties ()

Parameters

Returns

gdata_contacts_group_set_extended_property ()

Parameters

Returns

Types and Values

GDATA_CONTACTS_GROUP_CONTACTS

GDATA_CONTACTS_GROUP_FRIENDS

GDATA_CONTACTS_GROUP_FAMILY

GDATA_CONTACTS_GROUP_COWORKERS

GDataContactsGroup

GDataContactsGroupClass

Property Details

The “deleted” property

The “edited” property

The “system-group-id” property

The `“deleted”` property

The `“edited”` property

The `“system-group-id”` property