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,
                                                         gboolean read_only);
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;
	gboolean read_only;
} 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, embedded 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

gboolean read_only;

TRUE if the feed is read-only, FALSE otherwise

gdata_gd_feed_link_new ()

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

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

Currently, embedded 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

read_only :

TRUE if the feed is read-only, FALSE otherwise

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