diff options
Diffstat (limited to '')
| -rw-r--r-- | libcontacts.h | 152 | ||||
| -rw-r--r-- | libcontacts.h.0 | 530 |
2 files changed, 606 insertions, 76 deletions
diff --git a/libcontacts.h b/libcontacts.h index 6ce77d2..f0aa70b 100644 --- a/libcontacts.h +++ b/libcontacts.h @@ -7,6 +7,16 @@ /** + * Block type for contact + */ +enum libcontacts_block_type { + LIBCONTACTS_SILENT, /* The phone shall not call its owner's attention */ + LIBCONTACTS_BLOCK_OFF, /* The phone shall appear as turned off */ + LIBCONTACTS_BLOCK_BUSY, /* The phone shall appear as busy */ + LIBCONTACTS_BLOCK_IGNORE /* The phone shall appear as on but with no one answering */ +}; + +/** * Gender of contact */ enum libcontacts_gender { @@ -17,13 +27,54 @@ enum libcontacts_gender { }; /** - * Block type for contact + * Address 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 */ +struct libcontacts_address { + char *context; /* Work address (which job)? Home? Summer cabin? … */ + 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? */ + char *country; /* Which country? */ + int have_coordinates; /* Are `.latitude` and `.longitude` defined? */ + double latitude; /* Latitudinal GPS coordinate */ + double longitude; /* Longitudinal GPS coordinate */ + 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 */ }; /** @@ -47,11 +98,12 @@ struct libcontacts_block { }; /** - * Organisation information for contact + * Chat address for contact */ -struct libcontacts_organisation { - char *organisation; /* Orginisation the contact belongs to */ - char *title; /* The contact's title/role in the orginisation */ +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 */ }; @@ -65,15 +117,6 @@ struct libcontacts_email { }; /** - * 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 { @@ -85,72 +128,29 @@ struct libcontacts_number { }; /** - * Address for contact - */ -struct libcontacts_address { - char *context; /* Work address (which job)? Home? Summer cabin? … */ - 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? */ - char *country; /* Which country? */ - 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 + * Organisation information 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 */ +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 */ }; /** - * Chat address for contact + * PGP-keys 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 */ +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 */ }; /** - * Birthday of contact + * Site (e.g. web and gopher) for 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; - +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 */ }; @@ -196,11 +196,11 @@ struct libcontacts_contact { char *nickname; /** - * Pathname to photoes of the contact, use + * Pathnames to photos of the contact, use * absolute paths or paths relative to the * user's home directory * - * Applications may desired which photo to + * Applications may decide which photo to * use based on their size, but put the in * order of preference * diff --git a/libcontacts.h.0 b/libcontacts.h.0 new file mode 100644 index 0000000..4745c9c --- /dev/null +++ b/libcontacts.h.0 @@ -0,0 +1,530 @@ +.TH LIBCONTACTS.H 0 LIBCONTACTS +.SH NAME +libcontacts.h \- Simple, flexible contact list library header + +.SH SYNOPSIS +#include <libcontacts.h> + +.SH DESCRIPTION +The +.B <libcontacts.h> +header defines +.B struct libcontacts_contact +with the following fields: +.RS +.TP +.BI "char *" id +The ID of the contact, used to select filename. +This must not begin with a dot +.RB ( . ), +(unless it is reserved) end with a tilde +.RB ( ~ ), +or contain a slash +.RB ( / ), +and it is recommended that it only contains +lower case ASCII letters, ASCII digits, and ASCII hyphen +.RB ( - ). +Reserved values are: +.RS +.TP +.B .me +The user himself. +.TP +.B .nobody +Unused data, such as created groups without any members. +.RE +.TP +.BI "char *" name +The name of the contact as it should be displayed. +.TP +.BI "char *" first_name +The contact's given name (even if it is pronounced +after the family name). +.TP +.BI "char *" last_name +The contact's family name (even if it is pronounced +after the given name), if any. +.TP +.BI "char *" full_name +The full name of the contact. There is no prescribed +format, and there never will be. Application are +advised not to presume any format. +.TP +.BI "char *" nickname. +The contact's nickname (once upon a time known as +surname), if any. +.TP +.BI "char **" photos. +Pathnames to photos of the contact. They are either +absolute paths or relative to the user's home directory. + +Applications may decide which photo to use based on +their size, but user shall put the order of preference. + +For each telephone number, applications should only use +photos that are shared exactly between the contacts that +share that telephone number. + +This list is +.IR NULL -terminated. +.TP +.BI "char **" groups +List of groups the contact is a member of. For the +special pseudocontact +.BR .nobody , +this list only contains groups that should be exist, +but the contact should not be a member of them, allowing +the existance of empty groups. This list is +.IR NULL -terminated. +.TP +.BI "char *" notes +Multiline entry for personal notes about the contact. +.TP +.BI "struct libcontacts_block **" blocks +List of contact block information for the contact. +This list is +.IR NULL -terminated. +.TP +.BI "struct libcontacts_organisation **" organisations +List of organisation memberships for the contact. +This list is +.IR NULL -terminated. +.TP +.BI "struct libcontacts_email **" emails +List of e-mail addresses for the contact. +This list is +.IR NULL -terminated. +.TP +.BI "struct libcontacts_pgpkey **" pgpkeys +List of PGP-keys for the contact. +This list is +.IR NULL -terminated. +.TP +.BI "struct libcontacts_number **" numbers +List of telephone numbers for the contact. +This list is +.IR NULL -terminated. + +Telephone numbers can be shared, in case of an incoming call +where the phone number is shared, the application shall list +contacts that telephone number. +.TP +.BI "struct libcontacts_address **" addresses +Address (physical location) information for the contact. +This list is +.IR NULL -terminated. +.TP +.BI "struct libcontacts_site **" sites +Internet sites (e.g. Web sites) that the contact own or +has an account on. This list is +.IR NULL -terminated. +.TP +.BI "struct libcontacts_chat **" chats +The contact's contact information for different services, +like instant messengers. Entries shall be added by the +applications that use the chat services. This list is +.IR NULL -terminated. +.TP +.BI "struct libcontacts_birthday *" birthday +When the contact celebrates his birthday. +.TP +.BI "int " in_case_of_emergency +Whether the contact shall be listed as an +In Case of Emergency (ICE) contact that can be +view without unlocking the phone. +.TP +.BI "enum libcontacts_gender " gender +The gender of the contact. This lets applications select +a default profile picture for the contact. +.TP +.BI "char **" unrecognised_data +List of entries, for the contact, that was not recognised by +.BR libcontacts . +This list is +.IR NULL -terminated. +.RE +.PP +The +.B <libcontacts.h> +header defines +.B struct libcontacts_address +with the following fields: +.RS +.TP +.BI "char *" context +What is the address for. For example, +.B \(dqhome\(dq +may be used if it is the contact's home address, +.B \(dqcabin\(dq +if its his summer cabin, or +.B \(dqwork\(dq +if its his workplace. If the contact for example +has to workplaces, Alphatech and Betatech, +.B \(dqwork, alphatech\(dq +and +.B \(dqwork, betatech\(dq +would be useful values. +.TP +.BI "char *" care_of +Care of address. +.TP +.BI "char *" address +Steet address, street number, floor number, appartment number, etc., +all in one line. +.TP +.BI "char *" postcode +The post code. +.TP +.BI "char *" city +The post town. +.TP +.BI "char *" country +The country. +.TP +.BI "int " have_coordinates +Non-zero if +.I latitude +and +.I longitude +are defined. +.TP +.BI "double " latitude +Latitudinal GPS coordinate. +.TP +.BI "double " latitude +Longitudinal GPS coordinate. +.TP +.BI "char **" unrecognised_data +List of entries, for the address, that was not recognised by +.BR libcontacts . +.RE +.PP +The +.B <libcontacts.h> +header defines +.B struct libcontacts_birthday +with the following fields: +.RS +.TP +.BI "unsigned int " year +The year, the contact was born, 0 if unknown. +.TP +.BI "unsigned int " month +The month, the contact was born, 0 if unknown. +.TP +.BI "unsigned int " day +The day of the month, the contact was born, 0 if unknown. +.TP +.BI "int " before_on_common +This field is applicable only if the contact's birthday is +on February 29. If non-zero, he prefers to celebrate his +birthday one day early: on February 29, on common years. +If zero, he prefers to celebrate his birthday on the proper +date: on March 1, on common years. +.TP +.BI "char **" unrecognised_data +List of entries, for the birthday, that was not recognised by +.BR libcontacts . +.RE +.PP +The +.B <libcontacts.h> +header defines +.B struct libcontacts_block +with the following fields: +.RS +.TP +.BI "char *" service +The service the block is applied to. Names beginning with a +dot are reserved, currently defined special service names are: +.RS +.TP +.B .call +Telephone calls. +.TP +.B .sms +SMS, MMS, and similar. +.TP +.B .global +The block allows everywhere. When checking if a contact +is blocked, this entry is least prioritised, meaning that +if a block entry that is specific the service that makes +checks exists, that entry is used, otherwise this entry +is used. +.PP +Other values are defines by the services that use them, +and should, if appropriate, be the package name of the +application's reference implementation. In some situation, +the protocol may be standardised, in which case the name +of the protocol should be used. These values +shall be identical to those used in +.BR "struct libcontacts_chat" . +.RE +.TP +.BI "int " explicit +Whether the contact shall be let known that he is being +blocked. +.TP +.BI "enum libcontacts_block_type " shadow_block +How the service shall behave if it does not let the contact +know he is being blocked. +.TP +.BI "time_t " soft_unblock +POSIX time that if passed, the service shall ask the user +if the contact shall be unblocked. 0 if never. +.TP +.BI "time_t " hard_unblock +POSIX time that if passed, the service shall automatically +unblock the contact. 0 if never. +.TP +.BI "char **" unrecognised_data +List of entries, for the block entry, that was not recognised by +.BR libcontacts . +.RE +.PP +The +.B <libcontacts.h> +header defines +.B struct libcontacts_chat +with the following fields: +.RS +.TP +.BI "char *" context +The context in which the chat account is used. For example +.B \(dqpersonal\(dq +or +.BR \(dqwork\(dq . +.TP +.BI "char *" service +The service in which the account exists. For example +.BR \(dqmatrix\(dq . +Values are defines by the services that use them, +and should, if appropriate, be the package name of the +application's reference implementation. In some situation, +the protocol may be standardised, in which case the name +of the protocol should be used. +.TP +.BI "char *" address +The account username, telephone number, ID or other address. +.TP +.BI "char **" unrecognised_data +List of entries, for the chat account, that was not recognised by +.BR libcontacts . +.RE +.PP +The +.B <libcontacts.h> +header defines +.B struct libcontacts_email +with the following fields: +.RS +.TP +.BI "char *" context +The context in which the e-mail account is used. For example +.B \(dqpersonal\(dq +or +.BR \(dqwork\(dq . +.TP +.BI "char *" address +The e-mail address. +.TP +.BI "char **" unrecognised_data +List of entries, for the e-mail account, that was not recognised by +.BR libcontacts . +.RE +.PP +The +.B <libcontacts.h> +header defines +.B struct libcontacts_number +with the following fields: +.RS +.TP +.BI "char *" context +The context in which the telephone number is used. For example +.BR \(dqhome\(dq , +.BR \(dqpersonal\(dq , +or +.BR \(dqwork\(dq . +.TP +.BI "char *" number +The telephone number. +.TP +.BI "int " is_mobile +Whether the number is to a device that can receive SMS-message, e.g. a mobile telephone. +.TP +.BI "int " is_facsimile +Whether the number is to a facsimile machine (fax). +.TP +.BI "char **" unrecognised_data +List of entries, for the telephone number, that was not recognised by +.BR libcontacts . +.RE +.PP +The +.B <libcontacts.h> +header defines +.B struct libcontacts_organisation +with the following fields: +.RS +.TP +.BI "char *" organisation +The name of the organisation the contact is a member of. +.TP +.BI "char *" title +The contact's title or role within the orginisation. +.TP +.BI "char **" unrecognised_data +List of entries, for the organisation membership, that was not recognised by +.BR libcontacts . +.RE +.PP +The +.B <libcontacts.h> +header defines +.B struct libcontacts_pgpkey +with the following fields: +.RS +.TP +.BI "char *" context +The context in which the PGP-key is used. For example +.B \(dqpersonal\(dq +or +.BR \(dqwork\(dq . +.TP +.BI "char *" id +The fingerprint if the PGP-key. +.TP +.BI "char **" unrecognised_data +List of entries, for the PGP-key, that was not recognised by +.BR libcontacts . +.RE +.PP +The +.B <libcontacts.h> +header defines +.B struct libcontacts_site +with the following fields: +.RS +.TP +.BI "char *" context +The context in which the site is used. For example +.B \(dqblog\(dq +or +.BR \(dqsoftware\(dq . +.TP +.BI "char *" address +Address to the site, including protocol. For example +.B https://example.org +or +.BR gopher://example.org . +.TP +.BI "char **" unrecognised_data +List of entries, for the site, that was not recognised by +.BR libcontacts . +.RE +.PP +The +.B <libcontacts.h> +header defines +.B enum libcontacts_block_type +with the following values: +.RS +.TP +.B LIBCONTACTS_SILENT +The phone shall not call its owner's attention. +.TP +.B LIBCONTACTS_BLOCK_OFF +The phone shall appear to the caller as as turned off. +.TP +.B LIBCONTACTS_BLOCK_BUSY +The phone shall appear to the caller as as busy. +.TP +.B LIBCONTACTS_BLOCK_IGNORE +The phone shall appear to the caller as turned on +but with no one answering. +.RE +.PP +The +.B <libcontacts.h> +header defines +.B enum libcontacts_gender +with the following values: +.RS +.TP +.B LIBCONTACTS_UNSPECIFIED_GENDER +No gender has been specified for the contact. +.TP +.B LIBCONTACTS_NOT_A_PERSON +The contact is not to a person. It may be to a company or service. +.TP +.B LIBCONTACTS_MALE +The contact is a male. +.TP +.B LIBCONTACTS_FEMALE +The contact is a female. +.RE +.PP +The +.B <libcontacts.h> +header defines the following functions: +.RS +.TP +.BR libcontacts_list_contacts (3) +Get a list of all contacts. +.TP +.BR libcontacts_load_contact (3) +Load a contact. +.TP +.BR libcontacts_load_contacts (3) +Load all contacts. +.TP +.BR libcontacts_save_contact (3) +Save a contact. +.TP +.BR libcontacts_contact_destroy (3) +Deallocate memory for a contact entry. +.TP +.BR libcontacts_address_destroy (3) +Deallocate memory for a contact address entry. +.TP +.BR libcontacts_birthday_destroy (3) +Deallocate memory for a contact birthday entry. +.TP +.BR libcontacts_block_destroy (3) +Deallocate memory for a contact block entry. +.TP +.BR libcontacts_chat_destroy (3) +Deallocate memory for a contact chat service address entry. +.TP +.BR libcontacts_email_destroy (3) +Deallocate memory for a contact e-mail address entry. +.TP +.BR libcontacts_number_destroy (3) +Deallocate memory for a contact telephone number entry. +.TP +.BR libcontacts_organisation_destroy (3) +Deallocate memory for a contact organisation membership entry. +.TP +.BR libcontacts_pgp_destroy (3) +Deallocate memory for a contact PGP-key fingerprint entry. +.TP +.BR libcontacts_site_destroy (3) +Deallocate memory for a contact Internet site entry. +.TP +.BR libcontacts_get_path (3) +Get the file information for a contact is or would be stored in. +.TP +.BR libcontacts_parse_contact (3) +Parse a contact file. +.TP +.BR libcontacts_format_contact (3) +Construct a contact file. +.TP +.BR libcontacts_same_number (3) +Compare two telephone numbers for equality. +.RE + +.SH SEE ALSO +.BR libcontacts (7), +.BR contacts (5) |