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
|
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<section id="contact_parser" xmlns:xi="http://www.w3.org/2001/XInclude">
<sectioninfo>
<revhistory>
<revision>
<revnumber>$Revision$</revnumber>
<date>$Date$</date>
</revision>
</revhistory>
</sectioninfo>
<title>Contact Header Field Parser</title>
<para>
The parser is located under <filename>parser/contact</filename>
subdirectory. The parser is not called automatically when the main
parser finds a Contact header field. It is your responsibility to call
the parser if you want a Contact header field body to be parsed.
</para>
<para>
Main function is <function>parse_contact</function> in file
<filename>parse_contact.c</filename>. The function accepts one
parameter which is structure <structname>hdr_field</structname>
representing the header field to be parsed. A single Contact header
field may contain multiple contacts, the parser will parse all of them
and will create linked list of all such contacts.
</para>
<para>
The function creates and initializes an instance of
<structname>contact_body</structname> structure. Then function
<function>contact_parser</function> will be called. If everything went
OK, pointer to the newly created structure will be stored in
<structfield>parsed</structfield> field of the
<structname>hdr_field</structname> structure representing the parsed
header field.
</para>
<para>
Function <function>contact_parser</function> will then check if the
contact is star, if not it will call
<function>parse_contacts</function> function that will parse all
contacts of the header field.
</para>
<para>
Function <function>parse_contacts</function> can be found in file
<filename>contact.c</filename>. It extracts <acronym>URI</acronym> and
parses all contact parameters.
</para>
<para>
The Contact parameter parser can be found in file
<filename>cparam.c</filename>.
</para>
<para>
The following structures will be created during parsing:
</para>
<note>
<para>
Mind that none of string in the following structures is zero
terminated ! Be very careful when processing the strings with
functions that require zero termination (printf for example) !
</para>
</note>
<programlisting>
typedef struct contact_body {
unsigned char star; /* Star contact */
contact_t* contacts; /* List of contacts */
} contact_body_t;
</programlisting>
<para>
This is the main structure. Pointer to instance of this structure will be stored in
<structfield>parsed</structfield> field of structure representing the header field to be parsed.
The structure contains two field:
<itemizedlist>
<listitem>
<para>
<structfield>star</structfield> field - This field will
contain 1 if the Contact was star (see
<acronym>RFC3261</acronym> for more details).
</para>
</listitem>
<listitem>
<para>
<structfield>contacts</structfield> field - This field
contains pointer to linked list of all contacts found in
the Contact header field.
</para>
</listitem>
</itemizedlist>
</para>
<programlisting>
typedef struct contact {
str uri; /* contact uri */
cparam_t* q; /* q parameter hook */
cparam_t* expires; /* expires parameter hook */
cparam_t* method; /* method parameter hook */
cparam_t* params; /* List of all parameters */
struct contact* next; /* Next contact in the list */
} contact_t;
</programlisting>
<para>
This structure represents one Contact (Mind that there might be several
contacts in one Contact header field delimited by a comma). Its fields
have the following meaning:
<itemizedlist>
<listitem>
<para>
<structfield>uri</structfield> - This field contains
pointer to begin of <acronym>URI</acronym> and its length.
</para>
</listitem>
<listitem>
<para>
<structfield>q</structfield> - This is a hook to structure representing q parameter.
If there is no such parameter, the hook contains 0.
</para>
</listitem>
<listitem>
<para>
<structfield>expires</structfield> - This is a hook to
structure representing expires parameter. If there is no
such parameter, the hook contains 0.
</para>
</listitem>
<listitem>
<para>
<structfield>method</structfield> - This is a hook to
structure representing method parameter. If there is no
such parameter, the hook contains 0.
</para>
</listitem>
<listitem>
<para>
<structfield>params</structfield> - Linked list of all
parameters.
</para>
</listitem>
<listitem>
<para>
<structfield>next</structfield> - Pointer to the next
contact that was in the same header field.
</para>
</listitem>
</itemizedlist>
</para>
<programlisting>
typedef enum cptype {
CP_OTHER = 0, /* Unknown parameter */
CP_Q, /* Q parameter */
CP_EXPIRES, /* Expires parameter */
CP_METHOD /* Method parameter */
} cptype_t;
</programlisting>
<para>
This is an enum of recognized types of contact parameters. Q parameter
will have type set to CP_Q, Expires parameter will have type set to
CP_EXPIRES and Method parameter will have type set to CP_METHOD. All
other parameters will have type set to CP_OTHER.
</para>
<programlisting>
/*
* Structure representing a contact
*/
typedef struct cparam {
cptype_t type; /* Type of the parameter */
str name; /* Parameter name */
str body; /* Parameter body */
struct cparam* next; /* Next parameter in the list */
} cparam_t;
</programlisting>
<para>
This structure represents a contact parameter. Field description
follows:
<itemizedlist>
<listitem>
<para>
<structfield>type</structfield> - Type of the parameter,
see <structname>cptype</structname> enum for more details.
</para>
</listitem>
<listitem>
<para>
<structfield>name</structfield> - Name of the parameter
(i.e. the part before "=").
</para>
</listitem>
<listitem>
<para>
<structfield>body</structfield> - Body of the parameter
(i.e. the part after "=").
</para>
</listitem>
<listitem>
<para>
<structfield>next</structfield> - Next parameter in the linked list.
</para>
</listitem>
</itemizedlist>
</para>
</section>
|
