# 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

                        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.

### MIMEDirVCard

    typedef struct {
    	GObject parent;

    	MIMEDirVCardPriv *priv;
    } MIMEDirVCard;

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