aboutsummaryrefslogtreecommitdiffstats
path: root/libcontacts.h.0
blob: 67f63f15c98e3e66529da8ff2aa26623498026c1 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
.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)