GDataContactsContact

## GDataContactsContact GDataContactsContact — GData Contacts contact object |

## Stability Level

Unstable, unless otherwise indicated

## Synopsis

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

                        GDataContactsContact;
                        GDataContactsContactClass;
    GDataContactsContact * gdata_contacts_contact_new       (const gchar *id);
    GDataGDName *       gdata_contacts_contact_get_name     (GDataContactsContact *self);
    void                gdata_contacts_contact_set_name     (GDataContactsContact *self,
                                                             GDataGDName *name);
    GList *             gdata_contacts_contact_get_email_addresses
                                                            (GDataContactsContact *self);
    GDataGDEmailAddress * gdata_contacts_contact_get_primary_email_address
                                                            (GDataContactsContact *self);
    void                gdata_contacts_contact_add_email_address
                                                            (GDataContactsContact *self,
                                                             GDataGDEmailAddress *email_address);
    void                gdata_contacts_contact_remove_all_email_addresses
                                                            (GDataContactsContact *self);
    GList *             gdata_contacts_contact_get_im_addresses
                                                            (GDataContactsContact *self);
    GDataGDIMAddress *  gdata_contacts_contact_get_primary_im_address
                                                            (GDataContactsContact *self);
    void                gdata_contacts_contact_add_im_address
                                                            (GDataContactsContact *self,
                                                             GDataGDIMAddress *im_address);
    void                gdata_contacts_contact_remove_all_im_addresses
                                                            (GDataContactsContact *self);
    GList *             gdata_contacts_contact_get_postal_addresses
                                                            (GDataContactsContact *self);
    GDataGDPostalAddress * gdata_contacts_contact_get_primary_postal_address
                                                            (GDataContactsContact *self);
    void                gdata_contacts_contact_add_postal_address
                                                            (GDataContactsContact *self,
                                                             GDataGDPostalAddress *postal_address);
    void                gdata_contacts_contact_remove_all_postal_addresses
                                                            (GDataContactsContact *self);
    GList *             gdata_contacts_contact_get_phone_numbers
                                                            (GDataContactsContact *self);
    GDataGDPhoneNumber * gdata_contacts_contact_get_primary_phone_number
                                                            (GDataContactsContact *self);
    void                gdata_contacts_contact_add_phone_number
                                                            (GDataContactsContact *self,
                                                             GDataGDPhoneNumber *phone_number);
    void                gdata_contacts_contact_remove_all_phone_numbers
                                                            (GDataContactsContact *self);
    GList *             gdata_contacts_contact_get_organizations
                                                            (GDataContactsContact *self);
    GDataGDOrganization * gdata_contacts_contact_get_primary_organization
                                                            (GDataContactsContact *self);
    void                gdata_contacts_contact_add_organization
                                                            (GDataContactsContact *self,
                                                             GDataGDOrganization *organization);
    void                gdata_contacts_contact_remove_all_organizations
                                                            (GDataContactsContact *self);
    GList *             gdata_contacts_contact_get_groups   (GDataContactsContact *self);
    void                gdata_contacts_contact_add_group    (GDataContactsContact *self,
                                                             const gchar *href);
    void                gdata_contacts_contact_remove_group (GDataContactsContact *self,
                                                             const gchar *href);
    gboolean            gdata_contacts_contact_is_group_deleted
                                                            (GDataContactsContact *self,
                                                             const gchar *href);
    const gchar *       gdata_contacts_contact_get_extended_property
                                                            (GDataContactsContact *self,
                                                             const gchar *name);
    GHashTable *        gdata_contacts_contact_get_extended_properties
                                                            (GDataContactsContact *self);
    gboolean            gdata_contacts_contact_set_extended_property
                                                            (GDataContactsContact *self,
                                                             const gchar *name,
                                                             const gchar *value);
    void                gdata_contacts_contact_get_edited   (GDataContactsContact *self,
                                                             GTimeVal *edited);
    gboolean            gdata_contacts_contact_is_deleted   (GDataContactsContact *self);
    gboolean            gdata_contacts_contact_has_photo    (GDataContactsContact *self);
    gchar *             gdata_contacts_contact_get_photo    (GDataContactsContact *self,
                                                             GDataContactsService *service,
                                                             gsize *length,
                                                             gchar **content_type,
                                                             GCancellable *cancellable,
                                                             GError **error);
    gboolean            gdata_contacts_contact_set_photo    (GDataContactsContact *self,
                                                             GDataService *service,
                                                             const gchar *data,
                                                             gsize length,
                                                             GCancellable *cancellable,
                                                             GError **error);

## Object Hierarchy

      GObject
       +----GDataParsable
             +----GDataEntry
                   +----GDataContactsContact

## Properties

      "deleted"                  gboolean              : Read
      "edited"                   GDataTimeVal*         : Read
      "has-photo"                gboolean              : Read
      "name"                     GDataGDName*          : Read / Write

## Description

GDataContactsContact is a subclass of GDataEntry to represent a contact from a Google address book.

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

## Details

### GDataContactsContact

    typedef struct _GDataContactsContact GDataContactsContact;

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

Since 0.2.0

### GDataContactsContactClass

    typedef struct {
    } GDataContactsContactClass;

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

Since 0.2.0

### gdata_contacts_contact_new ()

    GDataContactsContact * gdata_contacts_contact_new       (const gchar *id);

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

`id` : | the contact's ID, or `NULL`
Returns : | a new GDataContactsContact; unref with `g_object_unref()`

Since 0.2.0

### gdata_contacts_contact_get_name ()

    GDataGDName *       gdata_contacts_contact_get_name     (GDataContactsContact *self);

Gets the "name" property.

`self` : | a GDataContactsContact
Returns : | the contact's name, or `NULL`. [transfer none]

Since 0.5.0

### gdata_contacts_contact_set_name ()

    void                gdata_contacts_contact_set_name     (GDataContactsContact *self,
                                                             GDataGDName *name);

Sets the "name" property to `name`, and increments its reference count.

`name` must not be `NULL`, though all its properties may be `NULL`.

`self` : | a GDataContactsContact
`name` : | the new GDataGDName

Since 0.6.3

### gdata_contacts_contact_get_email_addresses ()

    GList *             gdata_contacts_contact_get_email_addresses
                                                            (GDataContactsContact *self);

Gets a list of the e-mail addresses owned by the contact.

`self` : | a GDataContactsContact
Returns : | a GList of GDataGDEmailAddresses, or `NULL`. [element-type GData.GDEmailAddress][transfer none]

Since 0.2.0

### gdata_contacts_contact_get_primary_email_address ()

    GDataGDEmailAddress * gdata_contacts_contact_get_primary_email_address
                                                            (GDataContactsContact *self);

Gets the contact's primary e-mail address, if one exists.

`self` : | a GDataContactsContact
Returns : | a GDataGDEmailAddress, or `NULL`. [transfer none]

Since 0.2.0

### gdata_contacts_contact_add_email_address ()

    void                gdata_contacts_contact_add_email_address
                                                            (GDataContactsContact *self,
                                                             GDataGDEmailAddress *email_address);

Adds an e-mail address to the contact's list of e-mail addresses and increments its reference count.

Note that only one e-mail address per contact may be marked as "primary". Insertion and update operations (with `gdata_contacts_service_insert_contact()`) will return an error if more than one e-mail address is marked as primary.

Duplicate e-mail addresses will not be added to the list.

`self` : | a GDataContactsContact
`email_address` : | a GDataGDEmailAddress to add

Since 0.2.0

### gdata_contacts_contact_remove_all_email_addresses ()

    void                gdata_contacts_contact_remove_all_email_addresses
                                                            (GDataContactsContact *self);

Removes all e-mail addresses from the contact.

`self` : | a GDataContactsContact

Since 0.4.0

### gdata_contacts_contact_get_im_addresses ()

    GList *             gdata_contacts_contact_get_im_addresses
                                                            (GDataContactsContact *self);

Gets a list of the IM addresses owned by the contact.

`self` : | a GDataContactsContact
Returns : | a GList of GDataGDIMAddresses, or `NULL`. [element-type GData.GDIMAddress][transfer none]

Since 0.2.0

### gdata_contacts_contact_get_primary_im_address ()

    GDataGDIMAddress *  gdata_contacts_contact_get_primary_im_address
                                                            (GDataContactsContact *self);

Gets the contact's primary IM address, if one exists.

`self` : | a GDataContactsContact
Returns : | a GDataGDIMAddress, or `NULL`. [transfer none]

Since 0.2.0

### gdata_contacts_contact_add_im_address ()

    void                gdata_contacts_contact_add_im_address
                                                            (GDataContactsContact *self,
                                                             GDataGDIMAddress *im_address);

Adds an IM (instant messaging) address to the contact's list of IM addresses and increments its reference count.

Note that only one IM address per contact may be marked as "primary". Insertion and update operations (with `gdata_contacts_service_insert_contact()`) will return an error if more than one IM address is marked as primary.

Duplicate IM addresses will not be added to the list.

`self` : | a GDataContactsContact
`im_address` : | a GDataGDIMAddress to add

Since 0.2.0

### gdata_contacts_contact_remove_all_im_addresses ()

    void                gdata_contacts_contact_remove_all_im_addresses
                                                            (GDataContactsContact *self);

Removes all IM addresses from the contact.

`self` : | a GDataContactsContact

Since 0.4.0

### gdata_contacts_contact_get_postal_addresses ()

    GList *             gdata_contacts_contact_get_postal_addresses
                                                            (GDataContactsContact *self);

Gets a list of the postal addresses owned by the contact.

`self` : | a GDataContactsContact
Returns : | a GList of GDataGDPostalAddresses, or `NULL`. [element-type GData.GDPostalAddress][transfer none]

Since 0.2.0

### gdata_contacts_contact_get_primary_postal_address ()

    GDataGDPostalAddress * gdata_contacts_contact_get_primary_postal_address
                                                            (GDataContactsContact *self);

Gets the contact's primary postal address, if one exists.

`self` : | a GDataContactsContact
Returns : | a GDataGDPostalAddress, or `NULL`. [transfer none]

Since 0.2.0

### gdata_contacts_contact_add_postal_address ()

    void                gdata_contacts_contact_add_postal_address
                                                            (GDataContactsContact *self,
                                                             GDataGDPostalAddress *postal_address);

Adds a postal address to the contact's list of postal addresses and increments its reference count.

Note that only one postal address per contact may be marked as "primary". Insertion and update operations (with `gdata_contacts_service_insert_contact()`) will return an error if more than one postal address is marked as primary.

Duplicate postal addresses will not be added to the list.

`self` : | a GDataContactsContact
`postal_address` : | a GDataGDPostalAddress to add

Since 0.2.0

### gdata_contacts_contact_remove_all_postal_addresses ()

    void                gdata_contacts_contact_remove_all_postal_addresses
                                                            (GDataContactsContact *self);

Removes all postal addresses from the contact.

`self` : | a GDataContactsContact

Since 0.4.0

### gdata_contacts_contact_get_phone_numbers ()

    GList *             gdata_contacts_contact_get_phone_numbers
                                                            (GDataContactsContact *self);

Gets a list of the phone numbers owned by the contact.

`self` : | a GDataContactsContact
Returns : | a GList of GDataGDPhoneNumbers, or `NULL`. [element-type GData.GDPhoneNumber][transfer none]

Since 0.2.0

### gdata_contacts_contact_get_primary_phone_number ()

    GDataGDPhoneNumber * gdata_contacts_contact_get_primary_phone_number
                                                            (GDataContactsContact *self);

Gets the contact's primary phone number, if one exists.

`self` : | a GDataContactsContact
Returns : | a GDataGDPhoneNumber, or `NULL`. [transfer none]

Since 0.2.0

### gdata_contacts_contact_add_phone_number ()

    void                gdata_contacts_contact_add_phone_number
                                                            (GDataContactsContact *self,
                                                             GDataGDPhoneNumber *phone_number);

Adds a phone number to the contact's list of phone numbers and increments its reference count

Note that only one phone number per contact may be marked as "primary". Insertion and update operations (with `gdata_contacts_service_insert_contact()`) will return an error if more than one phone number is marked as primary.

Duplicate phone numbers will not be added to the list.

`self` : | a GDataContactsContact
`phone_number` : | a GDataGDPhoneNumber to add

Since 0.2.0

### gdata_contacts_contact_remove_all_phone_numbers ()

    void                gdata_contacts_contact_remove_all_phone_numbers
                                                            (GDataContactsContact *self);

Removes all phone numbers from the contact.

`self` : | a GDataContactsContact

Since 0.4.0

### gdata_contacts_contact_get_organizations ()

    GList *             gdata_contacts_contact_get_organizations
                                                            (GDataContactsContact *self);

Gets a list of the organizations to which the contact belongs.

`self` : | a GDataContactsContact
Returns : | a GList of GDataGDOrganizations, or `NULL`. [element-type GData.GDOrganization][transfer none]

Since 0.2.0

### gdata_contacts_contact_get_primary_organization ()

    GDataGDOrganization * gdata_contacts_contact_get_primary_organization
                                                            (GDataContactsContact *self);

Gets the contact's primary organization, if one exists.

`self` : | a GDataContactsContact
Returns : | a GDataGDOrganization, or `NULL`. [transfer none]

Since 0.2.0

### gdata_contacts_contact_add_organization ()

    void                gdata_contacts_contact_add_organization
                                                            (GDataContactsContact *self,
                                                             GDataGDOrganization *organization);

Adds an organization to the contact's list of organizations (e.g. employers) and increments its reference count.

Note that only one organization per contact may be marked as "primary". Insertion and update operations (with `gdata_contacts_service_insert_contact()`) will return an error if more than one organization is marked as primary.

Duplicate organizations will not be added to the list.

`self` : | a GDataContactsContact
`organization` : | a GDataGDOrganization to add

Since 0.2.0

### gdata_contacts_contact_remove_all_organizations ()

    void                gdata_contacts_contact_remove_all_organizations
                                                            (GDataContactsContact *self);

Removes all organizations from the contact.

`self` : | a GDataContactsContact

Since 0.4.0

### gdata_contacts_contact_get_groups ()

    GList *             gdata_contacts_contact_get_groups   (GDataContactsContact *self);

Gets a list of the groups to which the contact belongs.

`self` : | a GDataContactsContact
Returns : | a GList of constant group ID URIs, or `NULL`; free with `g_list_free()`. [element-type utf8][transfer container]

Since 0.2.0

### gdata_contacts_contact_add_group ()

    void                gdata_contacts_contact_add_group    (GDataContactsContact *self,
                                                             const gchar *href);

Adds the contact to the given group. `href` should be a URI.

`self` : | a GDataContactsContact
`href` : | the group's ID URI

Since 0.2.0

### gdata_contacts_contact_remove_group ()

    void                gdata_contacts_contact_remove_group (GDataContactsContact *self,
                                                             const gchar *href);

Removes the contact from the given group. `href` should be a URI.

`self` : | a GDataContactsContact
`href` : | the group's ID URI

Since 0.2.0

### gdata_contacts_contact_is_group_deleted ()

    gboolean            gdata_contacts_contact_is_group_deleted
                                                            (GDataContactsContact *self,
                                                             const gchar *href);

Returns whether the contact has recently been removed from the given group. This will always return `FALSE` unless "show-deleted" has been set to `TRUE` for the query which returned the contact.

`self` : | a GDataContactsContact
`href` : | the group's ID URI
Returns : | `TRUE` if the contact has recently been removed from the group, `FALSE` otherwise

Since 0.2.0

### gdata_contacts_contact_get_extended_property ()

    const gchar *       gdata_contacts_contact_get_extended_property
                                                            (GDataContactsContact *self,
                                                             const gchar *name);

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

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

Since 0.2.0

### gdata_contacts_contact_get_extended_properties ()

    GHashTable *        gdata_contacts_contact_get_extended_properties
                                                            (GDataContactsContact *self);

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

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

Since 0.4.0

### gdata_contacts_contact_set_extended_property ()

    gboolean            gdata_contacts_contact_set_extended_property
                                                            (GDataContactsContact *self,
                                                             const gchar *name,
                                                             const gchar *value);

Sets the value of a contact'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`.

A contact 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 GDataContactsContact
`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.2.0

### gdata_contacts_contact_get_edited ()

    void                gdata_contacts_contact_get_edited   (GDataContactsContact *self,
                                                             GTimeVal *edited);

Gets the "edited" property and puts it in `edited`. If the property is unset, both fields in the GTimeVal will be set to `0`.

`self` : | a GDataContactsContact
`edited` : | a GTimeVal. [out caller-allocates]

Since 0.2.0

### gdata_contacts_contact_is_deleted ()

    gboolean            gdata_contacts_contact_is_deleted   (GDataContactsContact *self);

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

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

`self` : | a GDataContactsContact
Returns : | `TRUE` if the contact has been deleted, `FALSE` otherwise

Since 0.2.0

### gdata_contacts_contact_has_photo ()

    gboolean            gdata_contacts_contact_has_photo    (GDataContactsContact *self);

Returns whether the contact has a photo attached to their contact entry. If the contact does have a photo, it can be returned using `gdata_contacts_contact_get_photo()`.

`self` : | a GDataContactsContact
Returns : | `TRUE` if the contact has a photo, `FALSE` otherwise

Since 0.4.0

### gdata_contacts_contact_get_photo ()

    gchar *             gdata_contacts_contact_get_photo    (GDataContactsContact *self,
                                                             GDataContactsService *service,
                                                             gsize *length,
                                                             gchar **content_type,
                                                             GCancellable *cancellable,
                                                             GError **error);

Downloads and returns the contact's photo, if they have one. If the contact doesn't have a photo (i.e. `gdata_contacts_contact_has_photo()` returns `FALSE`), `NULL` is returned, but no error is set in `error`.

If `cancellable` is not `NULL`, then the operation can be cancelled by triggering the `cancellable` object from another thread. If the operation was cancelled, the error `G_IO_ERROR_CANCELLED` will be returned.

If there is an error getting the photo, a `GDATA_SERVICE_ERROR_PROTOCOL_ERROR` error will be returned.

`self` : | a GDataContactsContact
`service` : | a GDataContactsService
`length` : | return location for the image length, in bytes. [out caller-allocates]
`content_type` : | return location for the image's content type, or `NULL`; free with `g_free()`. [out callee-allocates][transfer full][allow-none]
`cancellable` : | optional GCancellable object, or `NULL`
`error` : | a GError, or `NULL`
Returns : | the image data, or `NULL`; free with `g_free()`

Since 0.4.0

### gdata_contacts_contact_set_photo ()

    gboolean            gdata_contacts_contact_set_photo    (GDataContactsContact *self,
                                                             GDataService *service,
                                                             const gchar *data,
                                                             gsize length,
                                                             GCancellable *cancellable,
                                                             GError **error);

Sets the contact's photo to `data` or, if `data` is `NULL`, deletes the contact's photo.

If `cancellable` is not `NULL`, then the operation can be cancelled by triggering the `cancellable` object from another thread. If the operation was cancelled, the error `G_IO_ERROR_CANCELLED` will be returned.

If there is an error setting the photo, a `GDATA_SERVICE_ERROR_PROTOCOL_ERROR` error will be returned.

`self` : | a GDataContactsContact
`service` : | a GDataService
`data` : | the image data, or `NULL`. [allow-none]
`length` : | the image length, in bytes, or `0`
`cancellable` : | optional GCancellable object, or `NULL`
`error` : | a GError, or `NULL`
Returns : | `TRUE` on success, `FALSE` otherwise

Since 0.4.0

## Property Details

### The `"deleted"` property

      "deleted"                  gboolean              : Read

Whether the entry has been deleted.

Default value: FALSE

Since 0.2.0

### The `"edited"` property

      "edited"                   GDataTimeVal*         : Read

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

For more information, see the Atom Publishing Protocol specification.

Since 0.2.0

### The `"has-photo"` property

      "has-photo"                gboolean              : Read

Whether the contact has a photo.

Default value: FALSE

Since 0.4.0

### The `"name"` property

      "name"                     GDataGDName*          : Read / Write

The contact's name in a structured representation.

Since 0.5.0