GData API

GData API — GData namespace API

Stability Level

Unstable, unless otherwise indicated

Synopsis


#include <gdata/gdata-gdata.h>

                    GDataGDEmailAddress;
GDataGDEmailAddress * gdata_gd_email_address_new        (const gchar *address,
                                                         const gchar *rel,
                                                         const gchar *label,
                                                         gboolean primary);
void                gdata_gd_email_address_free         (GDataGDEmailAddress *self);
                    GDataGDFeedLink;
GDataGDFeedLink *   gdata_gd_feed_link_new              (const gchar *href,
                                                         const gchar *rel,
                                                         guint count_hint);
void                gdata_gd_feed_link_free             (GDataGDFeedLink *self);
                    GDataGDIMAddress;
GDataGDIMAddress *  gdata_gd_im_address_new             (const gchar *address,
                                                         const gchar *protocol,
                                                         const gchar *rel,
                                                         const gchar *label,
                                                         gboolean primary);
void                gdata_gd_im_address_free            (GDataGDIMAddress *self);
                    GDataGDOrganization;
GDataGDOrganization * gdata_gd_organization_new         (const gchar *name,
                                                         const gchar *title,
                                                         const gchar *rel,
                                                         const gchar *label,
                                                         gboolean primary);
void                gdata_gd_organization_free          (GDataGDOrganization *self);
                    GDataGDPhoneNumber;
GDataGDPhoneNumber * gdata_gd_phone_number_new          (const gchar *number,
                                                         const gchar *rel,
                                                         const gchar *label,
                                                         const gchar *uri,
                                                         gboolean primary);
void                gdata_gd_phone_number_free          (GDataGDPhoneNumber *self);
                    GDataGDPostalAddress;
GDataGDPostalAddress * gdata_gd_postal_address_new      (const gchar *address,
                                                         const gchar *rel,
                                                         const gchar *label,
                                                         gboolean primary);
void                gdata_gd_postal_address_free        (GDataGDPostalAddress *self);
                    GDataGDRating;
GDataGDRating *     gdata_gd_rating_new                 (guint min,
                                                         guint max,
                                                         guint num_raters,
                                                         gdouble average);
void                gdata_gd_rating_free                (GDataGDRating *self);
                    GDataGDWhen;
GDataGDWhen *       gdata_gd_when_new                   (GTimeVal *start_time,
                                                         GTimeVal *end_time,
                                                         gboolean is_date,
                                                         const gchar *value_string,
                                                         GList *reminders);
void                gdata_gd_when_free                  (GDataGDWhen *self);
                    GDataGDReminder;
GDataGDReminder *   gdata_gd_reminder_new               (const gchar *method,
                                                         GTimeVal *absolute_time,
                                                         gint days,
                                                         gint hours,
                                                         gint minutes);
void                gdata_gd_reminder_free              (GDataGDReminder *self);
                    GDataGDWhere;
GDataGDWhere *      gdata_gd_where_new                  (const gchar *rel,
                                                         const gchar *value_string,
                                                         const gchar *label);
void                gdata_gd_where_free                 (GDataGDWhere *self);
                    GDataGDWho;
GDataGDWho *        gdata_gd_who_new                    (const gchar *rel,
                                                         const gchar *value_string,
                                                         const gchar *email);
void                gdata_gd_who_free                   (GDataGDWho *self);

Description

The structures here represent several core GData-specific elements used by various different GData-based services, from the "gdata" namespace.

For more information on the common GData elements, see the GData specification.

Details

GDataGDEmailAddress

typedef struct {
	gchar *address;
	gchar *rel;
	gchar *label;
	gboolean primary;
} GDataGDEmailAddress;

A structure fully representing a GData "email" element. The address field is required, but the others are optional.

See the GData specification for more information.

gchar *address;

the e-mail address

gchar *rel;

the relationship between the e-mail address and its owner, or NULL

gchar *label;

a human-readable label for the e-mail address, or NULL

gboolean primary;

TRUE if this e-mail address is its owner's primary address, FALSE otherwise

gdata_gd_email_address_new ()

GDataGDEmailAddress * gdata_gd_email_address_new        (const gchar *address,
                                                         const gchar *rel,
                                                         const gchar *label,
                                                         gboolean primary);

Creates a new GDataGDEmailAddress. More information is available in the GData specification.

address :

the e-mail address

rel :

the relationship between the e-mail address and its owner, or NULL

label :

a human-readable label for the e-mail address, or NULL

primary :

TRUE if this e-mail address is its owner's primary address, FALSE otherwise

Returns :

a new GDataGDEmailAddress, or NULL; free with gdata_gd_email_address_free()

Since 0.2.0


gdata_gd_email_address_free ()

void                gdata_gd_email_address_free         (GDataGDEmailAddress *self);

Frees a GDataGDEmailAddress.

Since 0.2.0


GDataGDFeedLink

typedef struct {
	gchar *rel;
	gchar *href;
	guint count_hint;
	/* TODO: support readOnly and feed */
} GDataGDFeedLink;

A structure fully representing a GData "rating" element. The href field is required, but the others are optional.

See the GData specification for more information.

Currently, readOnly and feed functionality is not implemented in GDataGDFeedLink.

gchar *rel;

the relationship between the related feed and the current item, or NULL

gchar *href;

the URI of the related feed

guint count_hint;

a hint about the number of items in the related feed

gdata_gd_feed_link_new ()

GDataGDFeedLink *   gdata_gd_feed_link_new              (const gchar *href,
                                                         const gchar *rel,
                                                         guint count_hint);

Creates a new GDataGDFeedLink. More information is available in the GData specification.

Currently, readOnly and feed functionality is not implemented in GDataGDFeedLink.

href :

the URI of the related feed

rel :

the relationship between the related feed and the current item, or NULL

count_hint :

a hint about the number of items in the related feed

Returns :

a new GDataGDFeedLink, or NULL; free with gdata_gd_feed_link_free()

gdata_gd_feed_link_free ()

void                gdata_gd_feed_link_free             (GDataGDFeedLink *self);

Frees a GDataGDFeedLink.

self :

a GDataGDFeedLink

GDataGDIMAddress

typedef struct {
	gchar *address;
	gchar *protocol;
	gchar *rel;
	gchar *label;
	gboolean primary;
} GDataGDIMAddress;

A structure fully representing a GData "im" element. The address field is required, but the others are optional.

See the GData specification for more information.

gchar *address;

the IM address

gchar *protocol;

a URI identifying the IM protocol, or NULL

gchar *rel;

the relationship between the IM address and its owner, or NULL

gchar *label;

a human-readable label for the IM address, or NULL

gboolean primary;

TRUE if this IM address is its owner's primary address, FALSE otherwise

gdata_gd_im_address_new ()

GDataGDIMAddress *  gdata_gd_im_address_new             (const gchar *address,
                                                         const gchar *protocol,
                                                         const gchar *rel,
                                                         const gchar *label,
                                                         gboolean primary);

Creates a new GDataGDIMAddress. More information is available in the GData specification.

address :

the IM address

protocol :

a URI identifying the IM protocol, or NULL

rel :

the relationship between the IM address and its owner, or NULL

label :

a human-readable label for the IM address, or NULL

primary :

TRUE if this IM address is its owner's primary address, FALSE otherwise

Returns :

a new GDataGDIMAddress, or NULL; free with gdata_gd_im_address_free()

Since 0.2.0


gdata_gd_im_address_free ()

void                gdata_gd_im_address_free            (GDataGDIMAddress *self);

Frees a GDataGDIMAddress.

self :

a GDataGDIMAddress

Since 0.2.0


GDataGDOrganization

typedef struct {
	gchar *name;
	gchar *title;
	gchar *rel;
	gchar *label;
	gboolean primary;
} GDataGDOrganization;

A structure fully representing a GData "organization" element. All fields are optional.

See the GData specification for more information.

gchar *name;

the name of the organization, or NULL

gchar *title;

the owner's title within the organization, or NULL

gchar *rel;

the relationship between the organization and its owner, or NULL

gchar *label;

a human-readable label for the organization, or NULL

gboolean primary;

TRUE if this organization is its owner's primary organization, FALSE otherwise

gdata_gd_organization_new ()

GDataGDOrganization * gdata_gd_organization_new         (const gchar *name,
                                                         const gchar *title,
                                                         const gchar *rel,
                                                         const gchar *label,
                                                         gboolean primary);

Creates a new GDataGDOrganization. More information is available in the GData specification.

name :

the name of the organization, or NULL

title :

the owner's title within the organization, or NULL

rel :

the relationship between the organization and its owner, or NULL

label :

a human-readable label for the organization, or NULL

primary :

TRUE if this organization is its owner's primary organization, FALSE otherwise

Returns :

a new GDataGDOrganization, or NULL; free with gdata_gd_organization_free()

Since 0.2.0


gdata_gd_organization_free ()

void                gdata_gd_organization_free          (GDataGDOrganization *self);

Frees a GDataGDOrganization.

Since 0.2.0


GDataGDPhoneNumber

typedef struct {
	gchar *number;
	gchar *rel;
	gchar *label;
	gchar *uri;
	gboolean primary;
} GDataGDPhoneNumber;

A structure fully representing a GData "phoneNumber" element. The number field is required, but the others are optional.

See the GData specification for more information.

gchar *number;

the phone number, in human-readable format

gchar *rel;

the relationship between the phone number and its owner, or NULL

gchar *label;

a human-readable label for the phone number, or NULL

gchar *uri;

a "tel URI" to represent the number formally (see RFC 3966), or NULL

gboolean primary;

TRUE if this phone number is its owner's primary number, FALSE otherwise

gdata_gd_phone_number_new ()

GDataGDPhoneNumber * gdata_gd_phone_number_new          (const gchar *number,
                                                         const gchar *rel,
                                                         const gchar *label,
                                                         const gchar *uri,
                                                         gboolean primary);

Creates a new GDataGDPhoneNumber. More information is available in the GData specification.

number :

the phone number, in human-readable format

rel :

the relationship between the phone number and its owner, or NULL

label :

a human-readable label for the phone number, or NULL

uri :

a "tel URI" to represent the number formally (see RFC 3966), or NULL

primary :

TRUE if this phone number is its owner's primary number, FALSE otherwise

Returns :

a new GDataGDPhoneNumber, or NULL; free with gdata_gd_phone_number_free()

Since 0.2.0


gdata_gd_phone_number_free ()

void                gdata_gd_phone_number_free          (GDataGDPhoneNumber *self);

Frees a GDataGDPhoneNumber.

self :

a GDataGDPhoneNumber

Since 0.2.0


GDataGDPostalAddress

typedef struct {
	gchar *address;
	gchar *rel;
	gchar *label;
	gboolean primary;
} GDataGDPostalAddress;

A structure fully representing a GData "postalAddress" element. The address field is required, but the others are optional.

See the GData specification for more information.

gchar *address;

the postal address, in human-readable format (new lines are significant)

gchar *rel;

the relationship between the address and its owner, or NULL

gchar *label;

a human-readable label for the address, or NULL

gboolean primary;

TRUE if this phone number is its owner's primary number, FALSE otherwise

gdata_gd_postal_address_new ()

GDataGDPostalAddress * gdata_gd_postal_address_new      (const gchar *address,
                                                         const gchar *rel,
                                                         const gchar *label,
                                                         gboolean primary);

Creates a new GDataGDPostalAddress. More information is available in the GData specification.

address :

the postal address, in human-readable format (new lines are significant)

rel :

the relationship between the address and its owner, or NULL

label :

a human-readable label for the address, or NULL

primary :

TRUE if this phone number is its owner's primary number, FALSE otherwise

Returns :

a new GDataGDPostalAddress, or NULL; free with gdata_gd_postal_address_free()

Since 0.2.0


gdata_gd_postal_address_free ()

void                gdata_gd_postal_address_free        (GDataGDPostalAddress *self);

Frees a GDataGDPostalAddress.

Since 0.2.0


GDataGDRating

typedef struct {
	guint min;
	guint max;
	guint num_raters;
	gdouble average;
} GDataGDRating;

A structure fully representing a GData "rating" element. All fields are required.

See the GData specification for more information.

Currently, rel and value functionality is not implemented in GDataGDRating.

guint min;

the minimum rating which can be chosen (typically 1)

guint max;

the maximum rating which can be chosen (typically 5)

guint num_raters;

the number of people who have rated the item

gdouble average;

the average rating for the item

gdata_gd_rating_new ()

GDataGDRating *     gdata_gd_rating_new                 (guint min,
                                                         guint max,
                                                         guint num_raters,
                                                         gdouble average);

Creates a new GDataGDRating. More information is available in the GData specification.

Currently, rel and value functionality is not implemented in GDataGDRating.

min :

the minimum rating which can be chosen (typically 1)

max :

the maximum rating which can be chosen (typically 5)

num_raters :

the number of people who have rated the item

average :

the average rating for the item

Returns :

a new GDataGDRating; free with gdata_gd_rating_free()

gdata_gd_rating_free ()

void                gdata_gd_rating_free                (GDataGDRating *self);

Frees a GDataGDRating.

self :

a GDataGDRating

GDataGDWhen

typedef struct {
	GTimeVal start_time;
	GTimeVal end_time;
	gboolean is_date;
	gchar *value_string;
	GList *reminders;
} GDataGDWhen;

A structure fully representing a GData "when" element. The start_time field is required, but the others are optional.

If end_time is empty (all fields are zero), the structure is considered to represent: an instance in time if start_time is a time (if is_date is FALSE), or an entire day if start_time is a date (if is_date is TRUE).

See the GData specification for more information.

GTimeVal start_time;

when the event starts or (for zero-duration events) when it occurs

GTimeVal end_time;

when the event ends

gboolean is_date;

TRUE if start_time and end_time specify dates rather than times, FALSE otherwise

gchar *value_string;

a string to represent the time period, or NULL

GList *reminders;

a GList of GDataGDReminders for the time period, or NULL

gdata_gd_when_new ()

GDataGDWhen *       gdata_gd_when_new                   (GTimeVal *start_time,
                                                         GTimeVal *end_time,
                                                         gboolean is_date,
                                                         const gchar *value_string,
                                                         GList *reminders);

Creates a new GDataGDWhen. More information is available in the GData specification.

This function takes ownership of reminders, so the list (or its entries) must not be freed by the caller after a call to gdata_gd_when_new has finished.

start_time :

when the event starts or (for zero-duration events) when it occurs

end_time :

when the event ends, or NULL

is_date :

TRUE if start_time and end_time specify dates rather than times, FALSE otherwise

value_string :

a string to represent the time period, or NULL

reminders :

a GList of GDataGDReminders for the time period, or NULL

Returns :

a new GDataGDWhen, or NULL; free with gdata_gd_when_free()

Since 0.2.0


gdata_gd_when_free ()

void                gdata_gd_when_free                  (GDataGDWhen *self);

Frees a GDataGDWhen.

self :

a GDataGDWhen

Since 0.2.0


GDataGDReminder

typedef struct {
	gchar *method;
	GTimeVal absolute_time;
	gint days;
	gint hours;
	gint minutes;
} GDataGDReminder;

A structure fully representing a GData "reminder" element. All fields are optional. The days, hours and minutes fields are mutually exclusive with each other, and all mutually exclusive with absolute_time.

See the GData specification for more information.

gchar *method;

the notification method the reminder should use, or NULL

GTimeVal absolute_time;

the absolute time for the reminder, or NULL

gint days;

number of days before the event's start time for the reminder, or -1

gint hours;

number of hours before the event's start time for the reminder, or -1

gint minutes;

number of minutes before the event's start time for the reminder, or -1

gdata_gd_reminder_new ()

GDataGDReminder *   gdata_gd_reminder_new               (const gchar *method,
                                                         GTimeVal *absolute_time,
                                                         gint days,
                                                         gint hours,
                                                         gint minutes);

Creates a new GDataGDReminder. More information is available in the GData specification.

method :

the notification method the reminder should use, or NULL

absolute_time :

the absolute time for the reminder, or NULL

days :

number of days before the event's start time for the reminder, or -1

hours :

number of hours before the event's start time for the reminder, or -1

minutes :

number of minutes before the event's start time for the reminder, or -1

Returns :

a new GDataGDReminder, or NULL; free with gdata_gd_reminder_free()

Since 0.2.0


gdata_gd_reminder_free ()

void                gdata_gd_reminder_free              (GDataGDReminder *self);

Frees a GDataGDReminder.

self :

a GDataGDReminder

Since 0.2.0


GDataGDWhere

typedef struct {
	gchar *rel;
	gchar *value_string;
	gchar *label;
	/* TODO: deal with the entryLink */
} GDataGDWhere;

A structure fully representing a GData "where" element. All fields are optional.

See the GData specification for more information.

Currently, entryLink functionality is not implemented in GDataGDWhere.

gchar *rel;

the relationship between the item and this place, or NULL

gchar *value_string;

a string to represent the place, or NULL

gchar *label;

a human-readable label for the place, or NULL

gdata_gd_where_new ()

GDataGDWhere *      gdata_gd_where_new                  (const gchar *rel,
                                                         const gchar *value_string,
                                                         const gchar *label);

Creates a new GDataGDWhere. More information is available in the GData specification.

Currently, entryLink functionality is not implemented in GDataGDWhere.

rel :

the relationship between the item and this place, or NULL

value_string :

a string to represent the place, or NULL

label :

a human-readable label for the place, or NULL

Returns :

a new GDataGDWhere; free with gdata_gd_where_free()

gdata_gd_where_free ()

void                gdata_gd_where_free                 (GDataGDWhere *self);

Frees a GDataGDWhere.

self :

a GDataGDWhere

GDataGDWho

typedef struct {
	gchar *rel;
	gchar *value_string;
	gchar *email;
	/* TODO: deal with the attendeeType, attendeeStatus and entryLink */
} GDataGDWho;

A structure fully representing a GData "who" element. All fields are optional.

See the GData specification for more information.

Currently, entryLink functionality is not implemented in GDataGDWho.

gchar *rel;

the relationship between the item and this person, or NULL

gchar *value_string;

a string to represent the person, or NULL

gchar *email;

the person's e-mail address, or NULL

gdata_gd_who_new ()

GDataGDWho *        gdata_gd_who_new                    (const gchar *rel,
                                                         const gchar *value_string,
                                                         const gchar *email);

Creates a new GDataGDWho. More information is available in the GData specification.

Currently, entryLink functionality is not implemented in GDataGDWho.

rel :

the relationship between the item and this person, or NULL

value_string :

a string to represent the person, or NULL

email :

the person's e-mail address, or NULL

Returns :

a new GDataGDWho; free with gdata_gd_who_free()

gdata_gd_who_free ()

void                gdata_gd_who_free                   (GDataGDWho *self);

Frees a GDataGDWho.

self :

a GDataGDWho