mirror of https://github.com/sipwise/kamailio.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
205 lines
6.5 KiB
205 lines
6.5 KiB
<?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>
|