/* See LICENSE file for copyright and license details. */ #ifndef LIBCONTACTS_H #define LIBCONTACTS_H #include #include /** * Gender of contact */ enum libcontacts_gender { LIBCONTACTS_UNSPECIFIED_GENDER, LIBCONTACTS_NOT_A_PERSON, LIBCONTACTS_MALE, LIBCONTACTS_FEMALE }; /** * Block type for contact */ enum libcontacts_block_type { LIBCONTACTS_SILENT, /* The contact is blocked blocked, the phone shall not call its owner's attention */ LIBCONTACTS_BLOCK_OFF, /* The contact is blocked, phone shall appear as turned off */ LIBCONTACTS_BLOCK_BUSY, /* The contact is blocked, phone shall appear as turned busy */ LIBCONTACTS_BLOCK_IGNORE /* The contact is blocked, phone shall appear as on but with no one answering */ }; /** * Block for contact */ struct libcontacts_block { /** * The service the block is applied to, * must be begin with a dot, except if * it is: * - ".call" Telephone calls * - ".sms" SMS, MMS, and similar * - ".global" Block everywhere (least prioritised) */ char *service; int explicit; /* Whether to make an explicit block if possible */ enum libcontacts_block_type shadow_block; /* How block shall appear unless explicit */ time_t soft_unblock; /* When (positive) to ask whether to unblock, 0 if never */ time_t hard_unblock; /* When (positive) to unblock, 0 if never */ char **unrecognised_data; /* Data not recognised by the library */ }; /** * Organisation information for contact */ struct libcontacts_organisation { char *organisation; /* Orginisation the contact belongs to */ char *title; /* The contact's title/role in the orginisation */ char **unrecognised_data; /* Data not recognised by the library */ }; /** * E-mail information for contact */ struct libcontacts_email { char *context; /* Work e-mail (which job?)? Personal e-mail? … */ char *address; /* E-mail address */ char **unrecognised_data; /* Data not recognised by the library */ }; /** * PGP-keys for contact */ struct libcontacts_pgpkey { char *context; /* Work key (which job?)? Personal key? … */ char *id; /* The key's fingerprint */ char **unrecognised_data; /* Data not recognised by the library */ }; /** * Telephone number for contact */ struct libcontacts_number { char *context; /* Work phone (which job?)? Personal phone (mobile?, which home?)? … */ char *number; /* The telephone number */ int is_mobile; /* Is this a mobile phone (does it receive SMS)? */ int is_facsimile; /* Is this facsimile (fax) machine? */ char **unrecognised_data; /* Data not recognised by the library */ }; /** * Address for contact */ struct libcontacts_address { char *context; /* Work address (which job)? Home? Summer cabin? … */ char *country; /* Which country? */ char *care_of; /* Care of address, if any */ char *address; /* Address, all lines in one */ char *postcode; /* Post code */ char *city; /* Which city is the post code tied to? */ int have_coordinates; /* Are `.latitude` and `.longitude` defined? */ double latitude; /* Latitudal GPS coordinate */ double longitude; /* Longitudal GPS coordinate */ char **unrecognised_data; /* Data not recognised by the library */ }; /** * Site (e.g. web and gopher) for contact */ struct libcontacts_site { char *context; /* Work site (which job?)? Personal site (what is it used for?)? … */ char *address; /* Address to the site, including protocol */ char **unrecognised_data; /* Data not recognised by the library */ }; /** * Chat address for contact */ struct libcontacts_chat { char *context; /* Work account (which job?)? Personal account? … */ char *service; /* What service is the account, must not begin with a dot */ char *address; /* What is the name/address/number of the account */ char **unrecognised_data; /* Data not recognised by the library */ }; /** * Birthday of contact */ struct libcontacts_birthday { unsigned int year; /* asis, 0 for unknown */ unsigned char month; /* january = 1, 0 for unknown */ unsigned char day; /* asis, 0 for unknown */ /** * This is applicable only if the birthday * is on a leap day. One non-leap years, a * birthday that occurs on a leap day is * observed the day after the leap day had * it existed; but if this flag is set, the * person observes his birthday the day * before instead. * * (Even if it is not true (as it wasn't in * the past), the leap day is treated as if at * the end of the month, for example a person * born 1970-02-27, would celebrate his birthday * on 1980-02-27, not on 1980-02-28; similarly, * person born 1980-02-27 would celebrate his * birthday on 1989-02-27, not on 1989-02-26.) * * For example, if a person is born 2000-02-29, * his birthday is observed 2011-03-01, but if * this flag is set, he observes it on 2011-02-28 * instead. */ unsigned char before_on_common; char **unrecognised_data; /* Data not recognised by the library */ }; /** * Contact information */ struct libcontacts_contact { /** * The ID of the contact, used to select filename * * Must not begin with a dot, except if it is: * - ".me" The user himself. * - ".nobody" Unused data, such as created groups without any members. * Additionally, it must not end with ~ or contain an /, * and it should be short enough for a filename */ char *id; /** * The name of the contact as it should be displayed */ char *name; /** * The first name of the contact */ char *first_name; /** * The last name(s) of the contact, if any */ char *last_name; /** * The full name of the contact */ char *full_name; /** * Nick name of the contact, if any */ char *nickname; /** * Pathname to photoes of the contact, use * absolute paths or paths relative to the * user's home directory * * Applications may desired which photo to * use based on their size, but put the in * order of preference * * For each telephone number, applications * should only use photos that are shared * exactly between the contacts that share * that telephone number */ char **photos; /** * Groups the contact is a member of */ char **groups; /** * Personal notes about the contact */ char *notes; /** * Block information for contact */ struct libcontacts_block **blocks; /** * Organisation information for contact */ struct libcontacts_organisation **organisations; /** * E-mail information for contact */ struct libcontacts_email **emails; /** * PGP-keys for the contact */ struct libcontacts_pgpkey **pgpkeys; /** * Telephone number for the contact * * Phone number can be shared, in case of an * incoming call where the phone number is * shared, the application shall list contacts * that phone number */ struct libcontacts_number **numbers; /** * Address for the contact */ struct libcontacts_address **addresses; /** * Site (e.g. web and gopher) for the contact */ struct libcontacts_site **sites; /** * Chat address for the contact */ struct libcontacts_chat **chats; /** * Birthday of the contact */ struct libcontacts_birthday *birthday; /** * Whether the contact shall be listed as an ICE * (In Case of Emergency) contact that can be * view without unlocking the phone */ int in_case_of_emergency; /** * The gender of the contact */ enum libcontacts_gender gender; /** * Data not recognised by the library */ char **unrecognised_data; }; void libcontacts_contact_destroy(struct libcontacts_contact *); int libcontacts_list_contacts(char ***, const struct passwd *); int libcontacts_load_contact(const char *, struct libcontacts_contact *, const struct passwd *); /* errno = 0 if malformatted */ int libcontacts_load_contacts(struct libcontacts_contact ***, const struct passwd *); int libcontacts_save_contact(struct libcontacts_contact *, const struct passwd *); char *libcontacts_get_path(const char *, const struct passwd *); int libcontacts_parse_contact(char *, struct libcontacts_contact *); /* does not load .id, not stored in file, but is the filename */ int libcontacts_format_contact(const struct libcontacts_contact *, char **); void libcontacts_block_destroy(struct libcontacts_block *); void libcontacts_organisation_destroy(struct libcontacts_organisation *); void libcontacts_email_destroy(struct libcontacts_email *); void libcontacts_pgpkey_destroy(struct libcontacts_pgpkey *); void libcontacts_number_destroy(struct libcontacts_number *); void libcontacts_address_destroy(struct libcontacts_address *); void libcontacts_site_destroy(struct libcontacts_site *); void libcontacts_chat_destroy(struct libcontacts_chat *); void libcontacts_birthday_destroy(struct libcontacts_birthday *); #endif