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
|
<?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 "../../../docbook/entities.xml">
%docentities;
]>
<!-- Module Developer's Guide -->
<chapter>
<title>&develguide;</title>
<para>
The module exports a number of functions that allow selecting
and retrieving an element from an xcap server and also registering
a callback to be called when the management command refreshXcapDoc is received
and the document in question is retrieved.
</para>
<section>
<title>
<function moreinfo="none">bind_xcap_api(xcap_api_t* api)</function>
</title>
<para>
This function allows binding the needed functions.
</para>
<example>
<title><function>xcap_api</function> structure</title>
<programlisting format="linespecific">
...
typedef struct xcap_api {
/* xcap node selection and retrieving functions*/
xcap_get_elem_t get_elem;
xcap_nodeSel_init_t int_node_sel;
xcap_nodeSel_add_step_t add_step;
xcap_nodeSel_add_terminal_t add_terminal;
xcap_nodeSel_free_t free_node_sel;
xcapGetNewDoc_t getNewDoc; /* an initial request for the module
fo fetch this document that does not exist in xcap db table
and handle its update*/
/* function to register a callback to document changes*/
register_xcapcb_t register_xcb;
}xcap_api_t;
...
</programlisting>
</example>
</section>
<section>
<title>
<function moreinfo="none">get_elem</function>
</title>
<para>
Field type:
<programlisting format="linespecific">
...
typedef char* (*xcap_get_elem_t)(char* xcap_root,
xcap_doc_sel_t* doc_sel, xcap_node_sel_t* node_sel);
...
</programlisting>
</para>
<para>
This function sends a HTTP request and gets the specified information
from the xcap server.
</para>
<para>
The parameters signification:
</para>
<itemizedlist>
<listitem>
<para>
<emphasis>xcap_root</emphasis>-
the XCAP server address;
</para>
</listitem>
<listitem>
<para>
<emphasis>doc_sel</emphasis>-
structure with document selection info;
</para>
<programlisting format="linespecific">
Parameter type:
...
typedef struct xcap_doc_sel
{
str auid; /* application defined Unique ID*/
int type; /* the type of the path segment
after the AUID which must either
be GLOBAL_TYPE (for "global") or
USERS_TYPE (for "users") */
str xid; /* the XCAP User Identifier
if type is USERS_TYPE */
str filename;
}xcap_doc_sel_t;
...
</programlisting>
</listitem>
<listitem>
<para>
<emphasis>node_sel</emphasis>-
structure with node selection info;
</para>
<programlisting format="linespecific">
Parameter type:
...
typedef struct xcap_node_sel
{
step_t* steps;
step_t* last_step;
int size;
ns_list_t* ns_list;
ns_list_t* last_ns;
int ns_no;
}xcap_node_sel_t;
typedef struct step
{
str val;
struct step* next;
}step_t;
typedef struct ns_list
{
int name;
str value;
struct ns_list* next;
}ns_list_t;
...
</programlisting>
<para>
The node selector is represented like a list of steps that will
be represented in the path string separated by '/' signs.
The namespaces for the nodes are stored also in a list, as an
association of name and value, where the value is to be included
in the respective string val field of the step.
</para>
<para>
To construct the node structure the following functions in the xcap_api
structure should be used: 'int_node_sel', 'add_step' and if needed,
'add_terminal'.
</para>
<para>
If the intention is to retrieve the whole document this argument must
be NULL.
</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>
<function moreinfo="none">register_xcb</function>
</title>
<para>
Field type:
<programlisting format="linespecific">
...
typedef int (*register_xcapcb_t)(int types, xcap_cb f);
...
</programlisting>
</para>
<para>
- 'types' parameter can have a combined value of PRES_RULES, RESOURCE_LIST,
RLS_SERVICES and PIDF_MANIPULATION.
</para>
<para>
-the callback function has type :
<programlisting format="linespecific">
...
typedef int (xcap_cb)(int doc_type, str xid, char* doc);
...
</programlisting>
</para>
</section>
</chapter>
|
