path: root/contacts.5

.TH CONTACTS 5 LIBCONTACTS
.SH NAME
contacts \- Simple and flexible contact information file format

.SH DESCRIPTION
The directory
.I ~/.config/contacts
is used to store files with contact information, one
person per file, in the format specified by this document.
File names that end with a tilde
.RB ( ~ )
are reserved for temporary storage while saving a file
so that an already existing file (with the same name minus
the tilde) is replaced before the new version is completed,
and also so that other processes do not read incomplete files.
File names that start with a dot
.RB ( . )
are reserved for special purpose entries.
It is recommended that file names do not contain any other
characters than lower case ASCII letters, ASCII digits and
ASCII hyphen
.RB ( - ).
Subdirectories are prohibited.
.PP
The recommended default format for a file name is the
name as the user prefers it to be displayed in the latin
alphabet, in lower case with all non-letters (e.g. hyphens)
removed, and spaces replaced with hyphens.
.PP
The currently defined special puporse entries are:
.TP
.B .me
The user himself.
.TP
.B .nobody
Unused data, such as created groups without any members.
.PP
The files in
.I ~/.config/contacts
are UTF-8 text files, meaning that they must not contain
any NUL bytes and each line is terminated by a <newline>
.RB ( \(aq\en\(aq ).
.PP
Each line in the file is a data entry and should begin
with combination of printable ASCII characters, mostly
upper case letters, called a tag, (non-standard entires
should also begin with
.BR X- ),
followed by either a colon
.RB ( : ),
or a regular blank space (horizontal tab should also be
tolerated) followed by the data for the entry. Some lines
however are only flags and only contain the tag. Lines
using the colon alternative must end with that colon,
and subsequent lines starting a horizontal tab (one or more
regular blank spaces and horizontal tabs should also be
tolerated), until but excluding the subsequent first line
that does not start this way, shall be considered subentries
(this indentation is excluded in the description above, but
is there for subentries, top-level entries are not
indented). There is no prescribed order for entries.
.PP
Standard entires are, unless specified otherwise top-level
entries may be specified multiple times (subentries must
not be specified multiple times):
.TP
.B NAME
The name of the contact as it should be displayed.
May only be specified once.
.TP
.B FNAME
The contact's given name.
May only be specified once.
.TP
.B LNAME
The contact's family name, if any.
May only be specified once.
.TP
.B FLNAME
The full name of the contact. There is no prescribed
format, and there never will be. Application are advised
not to presume any format. May only be specified once.
.TP
.B NICK
The contact's nickname (once upon a time known as surname),
if any. May only be specified once.
.TP
.B PHOTO
Pathname to photo of the contact; should either be an
absolute path or a path 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.
.TP
.B GROUP
Contact group that the contact is a member of.

For the special pseudocontact
.BR .nobody ,
it specified that the group shall exist, even if it may
be empty.
.TP
.B NOTES
Personal note about the contact.
.TP
.B BLOCK:
Contact block information for the contact. Standard
subentries are:
.RS
.TP
.B SRV
The service the block is applied to. Names beginning with a dot
.RB ( . )
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 the
top-level entry
.BR CHAT 's
subentry
.BR SRV .
.RE
.TP
.B EXPLICIT
Flag without data, that specifies that the contact shall
be let known that he is being blocked.
.TP
.B ASK
POSIX time that if passed, the service shall ask the user
if the contact shall be unblocked; must be an unsigned decimal
integer. 0 or unspecified if never.
.TP
.B REMOVE
POSIX time that if passed, the service shall automatically
unblock the contact; must be an unsigned decimal integer.
0 or unspecified if never.
.TP
.B OFF
Flag without data, that specifies that the service shall,
unless it lets the contact know he is being blocked, pretend
that the phone is turned off.
.TP
.B BUSY
Flag without data, that specifies that the service shall,
unless it lets the contact know he is being blocked, pretend
that the user is busy and cannot answer.
.TP
.B IGNORE
Flag without data, that specifies that the service shall,
unless it lets the contact know he is being blocked, just
ignore the call or message.
.PP
The flags
.BR OFF ,
.BR BUSY ,
and
.BR IGNORE
may not be combined. If neither is specified, the service
shall not actually block user, unless
.B EXPLICIT
is specified and the service can honour that flag, but
instead just not call its owner's attention.
.RE
.TP
.B ORG:
Organisation membership for the contact. Standard
subentries are:
.RS
.TP
.B ORG
The name of the organisation the contact is a member of.
.TP
.B TITLE
The contact's title or role within the orginisation.
.RE
.TP
.B EMAIL:
E-mail address for the contact. Standard subentries are:
.RS
.TP
.B CTX
The context in which the e-mail account is used. For example
.B personal
or
.BR work .
.TP
.B ADDR
The e-mail address.
.RE
.TP
.B KEY:
PGP-key for the contact. Standard subentries are:
.RS
.TP
.B CTX
The context in which the PGP-key is used. For example
.B personal
or
.BR work .
.TP
.B ID
The fingerprint if the PGP-key.
.RE
.TP
.B PHONE:
Telephone numbers for the contact. Standard subentries are:
.RS
.TP
.B CTX
The context in which the telephone number is used. For example
.BR home ,
.BR personal ,
or
.BR work .
.TP
.B NUMBER
The telephone number.
.TP
.B MOBILE
Whether the number is to a device that can receive SMS-message,
e.g. a mobile telephone.
.TP
.B FAX
Whether the number is to a facsimile machine (fax).
.PP
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.
.RE
.TP
.B ADDR:
Address (physical location) for the contact. Standard
subentries are:
.RS
.TP
.B CTX
What is the address for. For example,
.B home
may be used if it is the contact's home address,
.B cabin
if its his summer cabin, or
.B work
if its his workplace. If the contact for example has two
workplaces, Alphatech and Betatech,
.B work, alphatech
and
.B work, betatech
would be useful values.
.TP
.B COUNTRY
The country.
.TP
.B C/O
Care of address.
.TP
.B ADDR
Steet address, street number, floor number, appartment number, etc.
.TP
.B CODE
The post code.
.TP
.B CITY
The post town.
.TP
.B COORD
The GPS coordinates in decimal format specified as the
latitude followed by a regular blank space and the longitude.
Unless
.B +
or
.B -
is used,
.BR N ,
.BR S ,
.BR W ,
and
.BR E
suffixes may be used.
.RE
.TP
.B SITE:
Internet sites (e.g. Web sites) that the contact own or
has an account on. Standard subentries are:
.RS
.TP
.B CTX
The context in which the site is used. For example
.B blog
or
.BR software .
.TP
.B ADDR
Address to the site, including protocol. For example
.B https://example.org
or
.BR gopher://example.org .
.RE
.TP
.B CHAT:
The contact's contact information for a services, like
an instant messenging service. Standard subentries are:
.RS
.TP
.B CTX
The context in which the chat account is used. For example
.B personal
or
.BR work .
.TP
.B SRV
The service in which the account exists. For example
.BR matrix .
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
.B ADDR
The account username, telephone number, ID or other address.
.PP
Entries shall be added by the applications that use the
chat services.
.RE
.TP
.B BIRTH:
When the contact celebrates his birthday. The date shall
be specified in the Gregorian calendar. Conversion and or
from other calendar is up to applications. Standard
subentries are:
.RS
.TP
.B YEAR
The year of the birthdate; must be an unsigned decimal
integer. 0 will be treated as unspecified.
.TP
.B MONTH
The month of the birthdate; must be an unsigned decimal
integer. 0 will be treated as unspecified.
.TP
.B DAY
The day of the month of the birthdate; must be an unsigned
decimal integer. 0 will be treated as unspecified.
.TP
.B EARLY
This flag may used (without any data specified) if the
contact's birthday is on February 29. If specified, he
prefers to celebrate his birthday one day early: on
February 29, on common years. Otherwise, he presumable
prefers to celebrate his birthday on the proper date:
on March 1, on common years.
.PP
May only be specified once.
.RE
.TP
.B ICE
Whether the contact shall be listed as an In Case of Emergency
(ICE) contact that can be view without unlocking the phone.
No data may be added to this entry. May only be specified once.
.TP
.B NPERSON
The contact is not a person, it may be for example be a
company or the voice-mail inbox service. No data may be
added to this entry. May only be specified once and cannot
be combined with
.B MALE
or
.BR FEMALE .
.TP
.B MALE
The contact is a male. No data may be added to this entry.
May only be specified once and cannot be combined with
.B NPERSON
or
.BR FEMALE .
.TP
.B FEMALE
The contact is a female. No data may be added to this entry.
May only be specified once and cannot be combined with
.B NPERSON
or
.BR MALE .

.SH SEE ALSO
.BR libcontacts (7),
.BR libcontacts.h (0)