MIMEDirVCard

Name

MIMEDirVCard -- 

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;

GList*      mimedir_vcard_read_list         (const gchar *filename,
                                             GError **error);
GList*      mimedir_vcard_read_list_from_channel
                                            (GIOChannel *channel,
                                             GError **error);
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_channel
                                            (GIOChannel *channel,
                                             GError **error);
gboolean    mimedir_vcard_read_from_channel (MIMEDirVCard *vcard,
                                             GIOChannel *channel,
                                             GError **error);
gboolean    mimedir_vcard_write_to_channel  (MIMEDirVCard *vcard,
                                             GIOChannel *channel,
                                             GError **error);
gchar*      mimedir_vcard_write_to_buffer   (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_UNKNOWNunknown/unsupported key type
MIMEDIR_VCARD_KEY_X509X.509 key
MIMEDIR_VCARD_KEY_PGPPGP/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_read_list ()

GList*      mimedir_vcard_read_list         (const gchar *filename,
                                             GError **error);

Reads a list of vCards from the supplied file and returns it. error will be set if an error occurs. You should free the returned list with mimedir_vcard_free_list().

filename : file to read
error : error storage location or NULL
Returns : list of read vCards


mimedir_vcard_read_list_from_channel ()

GList*      mimedir_vcard_read_list_from_channel
                                            (GIOChannel *channel,
                                             GError **error);

Reads a list of vCards from the supplied I/O channel and returns it. error will be set if an error occurs. You should free the returned list with mimedir_vcard_free_list().

channel : I/O channel to read from
error : error storage location or NULL
Returns : list of read vCards


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_channel ()

MIMEDirVCard* mimedir_vcard_new_from_channel
                                            (GIOChannel *channel,
                                             GError **error);

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

channel : I/O channel to read from
error : error storage location or NULL
Returns : the new vCard object or NULL


mimedir_vcard_read_from_channel ()

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

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

vcard : a vCard
channel : I/O channel to read from
error : error storage location or NULL
Returns : success indicator


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_buffer ()

gchar*      mimedir_vcard_write_to_buffer   (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_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