-
Notifications
You must be signed in to change notification settings - Fork 909
/
usrloc_devel.xml
478 lines (455 loc) · 12.5 KB
/
usrloc_devel.xml
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
<?xml version="1.0" encoding='ISO-8859-1'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
<!-- Include general documentation entities -->
<!ENTITY % docentities SYSTEM "../../../../doc/docbook/entities.xml">
%docentities;
]>
<!-- Module Developer's Guide -->
<chapter>
<title>&develguide;</title>
<section>
<title>Available Functions</title>
<section>
<title>
<function moreinfo="none">ul_register_domain(name)</function>
</title>
<para>
The function registers a new domain. Domain is just another name for
table used in registrar. The function is called from fixups in
registrar. It gets name of the domain as a parameter and returns
pointer to a new domain structure. The fixup than 'fixes' the
parameter in registrar so that it will pass the pointer instead of the
name every time save() or lookup() is called. Some usrloc functions
get the pointer as parameter when called. For more details see
implementation of save function in registrar.
</para>
<para>Meaning of the parameters is as follows:</para>
<itemizedlist>
<listitem>
<para><emphasis>const char* name</emphasis> - Name of the domain
(also called table) to be registered.
</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>
<function moreinfo="none">ul_insert_urecord(domain, aor, rec)</function>
</title>
<para>
The function creates a new record structure and inserts it in the
specified domain. The record is structure that contains all the
contacts for belonging to the specified username.
</para>
<para>Meaning of the parameters is as follows:</para>
<itemizedlist>
<listitem>
<para><emphasis>udomain_t* domain</emphasis> - Pointer to domain
returned by ul_register_udomain.
</para>
</listitem>
</itemizedlist>
<itemizedlist>
<listitem>
<para><emphasis>str* aor</emphasis> - Address of Record (aka
username) of the new record (at this time the record will
contain no contacts yet).
</para>
</listitem>
</itemizedlist>
<itemizedlist>
<listitem>
<para><emphasis>urecord_t** rec</emphasis> - The newly created
record structure.
</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>
<function moreinfo="none">ul_delete_urecord(domain, aor)</function>
</title>
<para>
The function deletes all the contacts bound with the given Address
Of Record.
</para>
<para>Meaning of the parameters is as follows:</para>
<itemizedlist>
<listitem>
<para><emphasis>udomain_t* domain</emphasis> - Pointer to domain
returned by ul_register_udomain.
</para>
</listitem>
</itemizedlist>
<itemizedlist>
<listitem>
<para><emphasis>str* aor</emphasis> - Address of record (aka
username) of the record, that should be deleted.
</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>
<function moreinfo="none">ul_delete_urecord_by_ruid(domain, ruid)</function>
</title>
<para>
The function deletes from given domain a contact with
given ruid.
</para>
<para>Meaning of the parameters is as follows:</para>
<itemizedlist>
<listitem>
<para><emphasis>udomain_t* domain</emphasis> - Pointer
to domain returned by ul_register_udomain.
</para>
</listitem>
</itemizedlist>
<itemizedlist>
<listitem>
<para><emphasis>str* ruid</emphasis> - ruid of contact
that should be deleted.
</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>
<function moreinfo="none">ul_get_urecord(domain, aor)</function>
</title>
<para>
The function returns pointer to record with given Address of Record.
</para>
<para>Meaning of the parameters is as follows:</para>
<itemizedlist>
<listitem>
<para><emphasis>udomain_t* domain</emphasis> - Pointer to domain
returned by ul_register_udomain.
</para>
</listitem>
</itemizedlist>
<itemizedlist>
<listitem>
<para><emphasis>str* aor</emphasis> - Address of Record of request
record.
</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>
<function moreinfo="none">ul_lock_udomain(domain)</function>
</title>
<para>
The function lock the specified domain, it means, that no other
processes will be able to access during the time. This prevents race
conditions. Scope of the lock is the specified domain, that means,
that multiple domain can be accessed simultaneously, they don't block
each other.
</para>
<para>Meaning of the parameters is as follows:</para>
<itemizedlist>
<listitem>
<para><emphasis>udomain_t* domain</emphasis> - Domain to be locked.
</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>
<function moreinfo="none">ul_unlock_udomain(domain)</function>
</title>
<para>
Unlock the specified domain previously locked by ul_lock_udomain.
</para>
<para>Meaning of the parameters is as follows:</para>
<itemizedlist>
<listitem>
<para><emphasis>udomain_t* domain</emphasis> - Domain to be
unlocked.
</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>
<function moreinfo="none">ul_release_urecord(record)</function>
</title>
<para>
Do some sanity checks - if all contacts have been removed, delete
the entire record structure.
</para>
<para>Meaning of the parameters is as follows:</para>
<itemizedlist>
<listitem>
<para><emphasis>urecord_t* record</emphasis> - Record to be
released.
</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>
<function moreinfo="none">ul_insert_ucontact(record, contact,
expires, q, callid, cseq, flags, cont, ua, sock)</function>
</title>
<para>
The function inserts a new contact in the given record with
specified parameters.
</para>
<para>Meaning of the parameters is as follows:</para>
<itemizedlist>
<listitem>
<para><emphasis>urecord_t* record</emphasis> - Record in which
the contact should be inserted.
</para>
</listitem>
<listitem>
<para><emphasis>str* contact</emphasis> - Contact &uri;.
</para>
</listitem>
<listitem>
<para><emphasis>time_t expires</emphasis> - Expires of the
contact in absolute value.
</para>
</listitem>
<listitem>
<para><emphasis>float q</emphasis> - q value of the contact.
</para>
</listitem>
<listitem>
<para><emphasis>str* callid</emphasis> - Call-ID of the REGISTER
message that contained the contact.
</para>
</listitem>
<listitem>
<para><emphasis>int cseq</emphasis> - CSeq of the REGISTER
message that contained the contact.
</para>
</listitem>
<listitem>
<para><emphasis>unsigned int flags</emphasis> - Flags to be set.
</para>
</listitem>
<listitem>
<para><emphasis>ucontact_t* cont</emphasis> - Pointer to newly
created structure.
</para>
</listitem>
<listitem>
<para><emphasis>str* ua</emphasis> - User-Agent of the REGISTER
message that contained the contact.
</para>
</listitem>
<listitem>
<para><emphasis>struct socket_info *sock</emphasis> - socket on
which the REGISTER message was received on.
</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>
<function moreinfo="none">ul_delete_ucontact
(record, contact)</function>
</title>
<para>
The function deletes given contact from record.
</para>
<para>Meaning of the parameters is as follows:</para>
<itemizedlist>
<listitem>
<para><emphasis>urecord_t* record</emphasis> - Record from which
the contact should be removed.
</para>
</listitem>
</itemizedlist>
<itemizedlist>
<listitem>
<para><emphasis>ucontact_t* contact</emphasis> - Contact to be
deleted.
</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>
<function moreinfo="none">ul_get_ucontact(record, contact)</function>
</title>
<para>
The function tries to find contact with given Contact &uri; and
returns pointer to structure representing the contact.
</para>
<para>Meaning of the parameters is as follows:</para>
<itemizedlist>
<listitem>
<para><emphasis>urecord_t* record</emphasis> - Record to be
searched for the contact.
</para>
</listitem>
</itemizedlist>
<itemizedlist>
<listitem>
<para><emphasis>str_t* contact</emphasis> - &uri; of the request
contact.
</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>
<function moreinfo="none">ul_get_all_ucontacts
(buf, len, flags)</function>
</title>
<para>
The function retrieves all contacts of all registered users and
returns them in the caller-supplied buffer. If the buffer is too small,
the function returns positive value indicating how much additional
space would be necessary to accommodate all of them. Please note
that the positive return value should be used only as a
<quote>hint</quote>, as there is no guarantee that during the time
between two subsequent calls number of registered contacts will
remain the same.
</para>
<para>
If flag parameter is set to non-zero value then only contacts that
have the specified flags set will be returned. It is, for example,
possible to list only contacts that are behind NAT.
</para>
<para>Meaning of the parameters is as follows:</para>
<itemizedlist>
<listitem>
<para><emphasis>void* buf</emphasis> - Buffer for returning
contacts.
</para>
</listitem>
</itemizedlist>
<itemizedlist>
<listitem>
<para><emphasis>int len</emphasis> - Length of the buffer.
</para>
</listitem>
</itemizedlist>
<itemizedlist>
<listitem>
<para><emphasis>unsigned int flags</emphasis> - Flags that must
be set.
</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>
<function moreinfo="none">ul_update_ucontact(contact, expires, q,
callid, cseq, set, res, ua, sock)</function>
</title>
<para>
The function updates contact with new values.
</para>
<para>Meaning of the parameters is as follows:</para>
<itemizedlist>
<listitem>
<para><emphasis>ucontact_t* contact</emphasis> - Contact &uri;.
</para>
</listitem>
<listitem>
<para><emphasis>time_t expires</emphasis> - Expires of the
contact in absolute value.
</para>
</listitem>
<listitem>
<para><emphasis>float q</emphasis> - q value of the contact.
</para>
</listitem>
<listitem>
<para><emphasis>str* callid</emphasis> - Call-ID of the REGISTER
message that contained the contact.
</para>
</listitem>
<listitem>
<para><emphasis>int cseq</emphasis> - CSeq of the REGISTER message
that contained the contact.
</para>
</listitem>
<listitem>
<para>
<emphasis>unsigned int set</emphasis> - OR value of flags to
be set.
</para>
</listitem>
<listitem>
<para>
<emphasis>unsigned int res</emphasis> - OR value of flags to be
reset.
</para>
</listitem>
<listitem>
<para><emphasis>str* ua</emphasis> - User-Agent of the REGISTER
message that contained the contact.
</para>
</listitem>
<listitem>
<para><emphasis>struct socket_info *sock</emphasis> - socket on
which the REGISTER message was received on.
</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>
<function moreinfo="none">ul_bind_ursloc(api)
</function>
</title>
<para>
The function imports all functions that are exported by the
USRLOC module. Overs for other modules which want to user the
internal USRLOC API an easy way to load and access the functions.
</para>
<para>Meaning of the parameters is as follows:</para>
<itemizedlist>
<listitem>
<para><emphasis>usrloc_api_t* api</emphasis> - USRLOC API
</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>
<function moreinfo="none">ul_register_ulcb(type, callback, param)
</function>
</title>
<para>
The function register with USRLOC a callback function to be called
when some event occures inside USRLOC.
</para>
<para>Meaning of the parameters is as follows:</para>
<itemizedlist>
<listitem>
<para><emphasis>int types</emphasis> - type of event for which
the callback should be called (see usrloc/ul_callback.h).
</para>
</listitem>
<listitem>
<para><emphasis>ul_cb f</emphasis> - callback function; see
usrloc/ul_callback.h for prototype.
</para>
</listitem>
<listitem>
<para><emphasis>void *param</emphasis> - some parameter to be
passed to the callback each time when it is called.
</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>
<function moreinfo="none">ul_get_num_users()
</function>
</title>
<para>
The function loops through all domains summing up the number of users.
</para>
</section>
</section>
</chapter>