MIMEDirVCard

Name

MIMEDirVCard -- vCard business card object

Synopsis

#include <mimedir/mimedir-vcard.h>

enum                MIMEDirVCardKeyType;

#define             MIMEDIR_VCARD_TIMEZONE_MAX
#define             MIMEDIR_VCARD_TIMEZONE_MIN
#define             MIMEDIR_VCARD_LATITUDE_MAX
#define             MIMEDIR_VCARD_LATITUDE_MIN
#define             MIMEDIR_VCARD_LONGITUDE_MAX
#define             MIMEDIR_VCARD_LONGITUDE_MIN

struct              MIMEDirVCard;

void                mimedir_vcard_free_list             (GList *list);
gboolean            mimedir_vcard_write_list            (const gchar *filename,
                                                         GList *list,
                                                         GError **error);
gboolean            mimedir_vcard_write_list_to_channel (GIOChannel *channel,
                                                         GList *list,
                                                         GError **error);

MIMEDirVCard *      mimedir_vcard_new                   (void);
MIMEDirVCard *      mimedir_vcard_new_from_profile      (MIMEDirProfile *profile,
                                                         GError **error);
gboolean            mimedir_vcard_read_from_profile     (MIMEDirVCard *vcard,
                                                         MIMEDirProfile *profile,
                                                         GError **error);
MIMEDirProfile *    mimedir_vcard_write_to_profile      (MIMEDirVCard *vcard);
gboolean            mimedir_vcard_write_to_channel      (MIMEDirVCard *vcard,
                                                         GIOChannel *channel,
                                                         GError **error);
gchar *             mimedir_vcard_write_to_string       (MIMEDirVCard *vcard);
void                mimedir_vcard_set_birthday          (MIMEDirVCard *vcard,
                                                         MIMEDirDateTime *birthday);
MIMEDirDateTime *   mimedir_vcard_get_birthday          (MIMEDirVCard *vcard);
void                mimedir_vcard_set_timezone          (MIMEDirVCard *vcard,
                                                         gint timezone);
gboolean            mimedir_vcard_get_timezone          (MIMEDirVCard *vcard,
                                                         gint *timezone);
void                mimedir_vcard_clear_timezone        (MIMEDirVCard *vcard);
void                mimedir_vcard_set_geo_position      (MIMEDirVCard *vcard,
                                                         gdouble latitude,
                                                         gdouble longitude);
gboolean            mimedir_vcard_get_geo_position      (MIMEDirVCard *vcard,
                                                         gdouble *latitude,
                                                         gdouble *longitude);
void                mimedir_vcard_clear_geo_position    (MIMEDirVCard *vcard);
void                mimedir_vcard_append_address        (MIMEDirVCard *vcard,
                                                         MIMEDirVCardAddress *address);
void                mimedir_vcard_remove_address        (MIMEDirVCard *vcard,
                                                         MIMEDirVCardAddress *address);
void                mimedir_vcard_append_email          (MIMEDirVCard *vcard,
                                                         MIMEDirVCardEMail *email);
void                mimedir_vcard_remove_email          (MIMEDirVCard *vcard,
                                                         MIMEDirVCardEMail *email);
void                mimedir_vcard_append_phone          (MIMEDirVCard *vcard,
                                                         MIMEDirVCardPhone *phone);
void                mimedir_vcard_remove_phone          (MIMEDirVCard *vcard,
                                                         MIMEDirVCardPhone *phone);
MIMEDirVCardAddress * mimedir_vcard_get_preferred_address
                                                        (MIMEDirVCard *vcard);
MIMEDirVCardEMail * mimedir_vcard_get_preferred_email   (MIMEDirVCard *vcard);
MIMEDirVCardPhone * mimedir_vcard_get_preferred_phone   (MIMEDirVCard *vcard);
gchar *             mimedir_vcard_get_as_string         (MIMEDirVCard *vcard);

Description

Details

enum MIMEDirVCardKeyType

typedef enum {
	MIMEDIR_VCARD_KEY_UNKNOWN, /* Key type is not known */
	MIMEDIR_VCARD_KEY_X509,		/* Key is a X.509 key */
	MIMEDIR_VCARD_KEY_PGP		/* Key is a PGP/GnuPG key */
} MIMEDirVCardKeyType;

The type of a public key that is associated with the vCard.

MIMEDIR_VCARD_KEY_UNKNOWN

unknown/unsupported key type

MIMEDIR_VCARD_KEY_X509

X.509 key

MIMEDIR_VCARD_KEY_PGP

PGP/GnuPG key


MIMEDIR_VCARD_TIMEZONE_MAX

#define MIMEDIR_VCARD_TIMEZONE_MAX (+23 * 60 + 59)

Maximum valid value for the timezone parameter.


MIMEDIR_VCARD_TIMEZONE_MIN

#define MIMEDIR_VCARD_TIMEZONE_MIN (-23 * 60 + 59)

Minimum valid value for the timezone parameter.


MIMEDIR_VCARD_LATITUDE_MAX

#define MIMEDIR_VCARD_LATITUDE_MAX (+90.0)

Maximum valid value for the latitude parameter.


MIMEDIR_VCARD_LATITUDE_MIN

#define MIMEDIR_VCARD_LATITUDE_MIN (-90.0)

Minimum valid value for the latitude parameter.


MIMEDIR_VCARD_LONGITUDE_MAX

#define MIMEDIR_VCARD_LONGITUDE_MAX (+180.0)

Maximum valid value for the longitude parameter.


MIMEDIR_VCARD_LONGITUDE_MIN

#define MIMEDIR_VCARD_LONGITUDE_MIN (-180.0)

Minimum valid value for the longitude parameter.


struct MIMEDirVCard

struct MIMEDirVCard {
	GObject parent;

	MIMEDirVCardPriv *priv;
};

The MIMEDirVCard struct contains private data only, and should be accessed using the functions below.


mimedir_vcard_free_list ()

void                mimedir_vcard_free_list             (GList *list);

Frees a list of vCards as returned by mimedir_vcard_read_list_from_file() or mimedir_vcard_read_list_from_channel().

list :

list of vCards


mimedir_vcard_write_list ()

gboolean            mimedir_vcard_write_list            (const gchar *filename,
                                                         GList *list,
                                                         GError **error);

Saves a list of vCard to a file.

filename :

file to save to

list :

list of vCard objects

error :

error storage location or NULL

Returns :

success indicator


mimedir_vcard_write_list_to_channel ()

gboolean            mimedir_vcard_write_list_to_channel (GIOChannel *channel,
                                                         GList *list,
                                                         GError **error);

Saves a list of vCard to an I/O channel.

channel :

I/O channel to save to

list :

list of vCard objects

error :

error storage location or NULL

Returns :

success indicator


mimedir_vcard_new ()

MIMEDirVCard *      mimedir_vcard_new                   (void);

Creates a new (empty) vCard object.

Returns :

a new vCard object


mimedir_vcard_new_from_profile ()

MIMEDirVCard *      mimedir_vcard_new_from_profile      (MIMEDirProfile *profile,
                                                         GError **error);

Create a new vCard object and fills it with data retrieved from the supplied profile object. If an error occurs during the read, error will be set and NULL will be returned.

profile :

a profile object

error :

error storage location or NULL

Returns :

the new vCard object or NULL


mimedir_vcard_read_from_profile ()

gboolean            mimedir_vcard_read_from_profile     (MIMEDirVCard *vcard,
                                                         MIMEDirProfile *profile,
                                                         GError **error);

Clears the supplied vCard object and re-initializes it with data read from the supplied profile. If an error occurs during the read, error will be set and FALSE will be returned. Otherwise, TRUE is returned.

vcard :

a vCard

profile :

a profile object

error :

error storage location or NULL

Returns :

success indicator


mimedir_vcard_write_to_profile ()

MIMEDirProfile *    mimedir_vcard_write_to_profile      (MIMEDirVCard *vcard);

Saves the vCard object to a newly allocated profile object.

vcard :

a vCard

Returns :

a new profile


mimedir_vcard_write_to_channel ()

gboolean            mimedir_vcard_write_to_channel      (MIMEDirVCard *vcard,
                                                         GIOChannel *channel,
                                                         GError **error);

Saves the vCard object to the supplied I/O channel. If an error occurs during the write, error will be set and FALSE will be returned. Otherwise, TRUE is returned.

vcard :

a vCard

channel :

I/O channel to save to

error :

error storage location or NULL

Returns :

success indicator


mimedir_vcard_write_to_string ()

gchar *             mimedir_vcard_write_to_string       (MIMEDirVCard *vcard);

Saves the vCard object to a newly allocated memory buffer. You should free the returned buffer with g_free().

vcard :

a vCard

Returns :

a newly allocated memory buffer


mimedir_vcard_set_birthday ()

void                mimedir_vcard_set_birthday          (MIMEDirVCard *vcard,
                                                         MIMEDirDateTime *birthday);

Set's the person's birthday. Setting the birthday to NULL unsets it.

vcard :

a vCard

birthday :

a MIMEDirDateTime object or NULL


mimedir_vcard_get_birthday ()

MIMEDirDateTime *   mimedir_vcard_get_birthday          (MIMEDirVCard *vcard);

Get's the person's birthday. The return value is not ref'fed.

vcard :

a vCard

Returns :

a MIMEDirDateTime object or NULL if the birthday is undefined


mimedir_vcard_set_timezone ()

void                mimedir_vcard_set_timezone          (MIMEDirVCard *vcard,
                                                         gint timezone);

Sets the time zone to timezone.

vcard :

a vCard

timezone :

time zone in minutes from UTC


mimedir_vcard_get_timezone ()

gboolean            mimedir_vcard_get_timezone          (MIMEDirVCard *vcard,
                                                         gint *timezone);

If the object's time zone is cleared, FALSE is returned and timezone is left unchanged. Otherwise TRUE is returned and timezone is set to the vCard's time zone.

vcard :

a vCard

timezone :

pointer to the timezone storage location or NULL

Returns :

TRUE if the object has a valid time zone, FALSE otherwise


mimedir_vcard_clear_timezone ()

void                mimedir_vcard_clear_timezone        (MIMEDirVCard *vcard);

Clears the card's time zone information.

vcard :

a vCard


mimedir_vcard_set_geo_position ()

void                mimedir_vcard_set_geo_position      (MIMEDirVCard *vcard,
                                                         gdouble latitude,
                                                         gdouble longitude);

Sets the vCard's geographical position to latitude and longitude.

vcard :

a vCard

latitude :

new latitude

longitude :

new longitude


mimedir_vcard_get_geo_position ()

gboolean            mimedir_vcard_get_geo_position      (MIMEDirVCard *vcard,
                                                         gdouble *latitude,
                                                         gdouble *longitude);

If the object's geographical position is cleared, FALSE is returned and latitude and longitude are left unchanged. Otherwise TRUE is returned and latitude and longitude are set to the vCard's geographical position.

vcard :

a vCard

latitude :

pointer to the latitude storage location or NULL

longitude :

pointer to the longitude storage location or NULL

Returns :

TRUE if the object has a valid geographical position, FALSE otherwise


mimedir_vcard_clear_geo_position ()

void                mimedir_vcard_clear_geo_position    (MIMEDirVCard *vcard);

Clears the vCard's geographical position.

vcard :

a vCard


mimedir_vcard_append_address ()

void                mimedir_vcard_append_address        (MIMEDirVCard *vcard,
                                                         MIMEDirVCardAddress *address);

Appends the supplied address object to the vCard.

vcard :

a vCard

address :

a vCard address


mimedir_vcard_remove_address ()

void                mimedir_vcard_remove_address        (MIMEDirVCard *vcard,
                                                         MIMEDirVCardAddress *address);

Removes the supplied address to the vCard.

vcard :

a vCard

address :

a vCard address


mimedir_vcard_append_email ()

void                mimedir_vcard_append_email          (MIMEDirVCard *vcard,
                                                         MIMEDirVCardEMail *email);

Appends the supplied e-mail address to the vCard.

vcard :

a vCard

email :

a vCard e-mail


mimedir_vcard_remove_email ()

void                mimedir_vcard_remove_email          (MIMEDirVCard *vcard,
                                                         MIMEDirVCardEMail *email);

Removes the supplied e-mail address from the vCard.

vcard :

a vCard

email :

a vCard e-mail


mimedir_vcard_append_phone ()

void                mimedir_vcard_append_phone          (MIMEDirVCard *vcard,
                                                         MIMEDirVCardPhone *phone);

Appends the supplied telephone number to the vCard.

vcard :

a vCard

phone :

a vCard phone


mimedir_vcard_remove_phone ()

void                mimedir_vcard_remove_phone          (MIMEDirVCard *vcard,
                                                         MIMEDirVCardPhone *phone);

Removes the supplied telephone number from the vCard.

vcard :

a vCard

phone :

a vCard phone


mimedir_vcard_get_preferred_address ()

MIMEDirVCardAddress * mimedir_vcard_get_preferred_address
                                                        (MIMEDirVCard *vcard);

Returns the preferred address of the supplied vCard object. If no address has the preferred flag set, the first address of the address list is returned. If the address list is empty, NULL is returned.

vcard :

a vCard

Returns :

an address object or NULL


mimedir_vcard_get_preferred_email ()

MIMEDirVCardEMail * mimedir_vcard_get_preferred_email   (MIMEDirVCard *vcard);

Returns the preferred email address of the supplied vCard object. If no email address has the preferred flag set, the first email address of the email address list is returned. If the email address list is empty, NULL is returned.

vcard :

a vCard

Returns :

an email address object or NULL


mimedir_vcard_get_preferred_phone ()

MIMEDirVCardPhone * mimedir_vcard_get_preferred_phone   (MIMEDirVCard *vcard);

Returns the preferred phone number of the supplied vCard object. If no phone number has the preferred flag set, the first phone number of the phone number list is returned. If the phone number list is empty, NULL is returned.

vcard :

a vCard

Returns :

a phone number object or NULL


mimedir_vcard_get_as_string ()

gchar *             mimedir_vcard_get_as_string         (MIMEDirVCard *vcard);

Returns the contents of the vCard object as a multi-line human-readable string. It is not guaranteed that this string is of a particular format or contains all information from the vCard object. Nevertheless, it will contain all vital information. You should free the returned string with g_free().

vcard :

a vCard

Returns :

a multi-line string