path: root/libcontacts.h.0

.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 contact 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 two 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 " longitude
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 applies 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 defined 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. This
means that the contact should not actually be blocked.
.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)