serdev.sgml

SIP Express Router, Linux下的SIP代理服务器,小巧实用,开发测试VoIP设备和应用的必备.

		    Because we store string lengths, there is no need to zero terminate them. Some strings in the
		    server are still zero terminated, some are not. Be careful when using functions like 
		    <function moreinfo="none">snprintf</function> that rely on the ending zero. You can print 
		    variable of type <type>str</type> this way:
		    <programlisting format="linespecific">printf("%.*s", mystring->len, mystring->s);</programlisting>
		    That ensures that the string will be printed correctly even if there is no zero character at
		    the end.
		</para>
	    </warning>
	</section> <!-- str -->
	
	<section id="hdr-field">
	    <title>Structure <structname>hdr_field</structname></title>
	    <para>
		The structure represents a header field of a <acronym>SIP</acronym> message. A header field
		consist of <emphasis>name</emphasis> and <emphasis>body</emphasis> separated by a double colon.
		For example: <quote>Server: SIP Express Router\r\n</quote> is one header field. <quote>Server</quote> 
		is header field name and <quote>SIP Express Router\r\n</quote> is header field body.
	    </para>
	    <para>
		The structure is defined in file <filename moreinfo="none">hf.h</filename> under
		<filename moreinfo="none">parser</filename> subdirectory.
	    </para>
	    <para>
		<emphasis>Structure Declaration</emphasis>
	    </para>
	    <programlisting format="linespecific">
struct hdr_field {   
    int type;                /* Header field type */
    str name;                /* Header field name */
    str body;                /* Header field body */
    void* parsed;            /* Parsed data structures */
    struct hdr_field* next;  /* Next header field in the list */
};
</programlisting>
	    <para>
		<emphasis>Field Description:</emphasis>
	    </para>
	    <itemizedlist>
		<listitem>
		    <para>
			<structfield>type</structfield> - Type of the header field, the following header field
			types are defined (and recognized by the parser): 
		    </para>
		    <para>
			HDR_VIA1, HDR_VIA2, HDR_TO, HDR_FROM, HDR_CSEQ, HDR_CALLID, HDR_CONTACT, HDR_MAXFORWARDS, 
			HDR_ROUTE, HDR_RECORDROUTE, HDR_CONTENTTYPE, HDR_CONTENTLENGTH, HDR_AUTHORIZATION, 
			HDR_EXPIRES, HDR_PROXYAUTH, HDR_WWWAUTH, HDR_SUPPORTED, HDR_REQUIRE, HDR_PROXYREQUIRE, 
			HDR_UNSUPPORTED, HDR_ALLOW, HDR_EVENT, HDR_OTHER.
		    </para>
		    <para>
			Their meaning is self explanatory. HDR_OTHER marks header field not recognized by the parser.
		    </para>
		</listitem>
		<listitem>
		    <para>
			<structfield>name</structfield> - Name of the header field (the part before colon)
		    </para>
		</listitem>
		<listitem>
		    <para>
			<structfield>body</structfield> - body of the header field (the part after colon)
		    </para>
		</listitem>
		<listitem>
		    <para>
			<structfield>parsed</structfield> - Each header field body can be further parsed. The field
			contains pointer to parsed structure if the header field was parsed already. The pointer is
			of type <type>void*</type> because it can point to different types of structure depending on 
			the header field type.
		    </para>
		</listitem>
		<listitem>
		    <para>
			<structfield>next</structfield> - Pointer to the next header field in linked list.
		    </para>
		</listitem>
	    </itemizedlist>
	</section> <!-- hdr-field -->

	<section id="sip-uri"> 
	    <title>Structure <structname>sip_uri</structname></title>
	    <para>This structure represents parsed <acronym>SIP</acronym> <acronym>URI</acronym>.</para>
	    <programlisting format="linespecific">
struct sip_uri {
    str user;     /* Username */
    str passwd;   /* Password */
    str host;     /* Host name */
    str port;     /* Port number */
    str params;   /* Parameters */
    str headers;  
};
</programlisting>
	    <para><emphasis>Field Description:</emphasis></para>
	    <itemizedlist>
		<listitem>
		    <para>
			<structfield>user</structfield> - Username if found in the <acronym>URI</acronym>.
		    </para>
		</listitem>
		<listitem>
		    <para>
			<structfield>passwd</structfield> - Password if found in the <acronym>URI</acronym>.
		    </para>
		</listitem>
		<listitem>
		    <para>
			<structfield>host</structfield> - Hostname of the <acronym>URI</acronym>.
		    </para>
		</listitem>
		<listitem>
		    <para>
			<structfield>params</structfield> - Parameters of the <acronym>URI</acronym> if any.
		    </para>
		</listitem>
		<listitem>
		    <para>
			<structfield>headers</structfield> - See the <acronym>SIP</acronym> <acronym>RFC</acronym>.
		    </para>
		</listitem>
	    </itemizedlist>
	</section> <!-- sip-uri -->
	
	<section id="via-body">
	    <title>Structure <structname>via_body</structname></title>
	    <para>
		The structure represents parsed Via header field. See file <filename moreinfo="none">parse_via.h</filename>
		under <filename moreinfo="none">parser</filename> subdirectory for more details.
	    </para>
	    <programlisting format="linespecific">
struct via_body { 
    int error;
    str hdr;                      /* Contains "Via" or "v" */
    str name;
    str version;   
    str transport;
    str host;
    int port;
    str port_str;
    str params;
    str comment;
    int bsize;                    /* body size, not including hdr */
    struct via_param* param_lst;  /* list of parameters*/
    struct via_param* last_param; /*last via parameter, internal use*/

    /* shortcuts to "important" params*/
    struct via_param* branch;
    struct via_param* received;

    struct via_body* next;        /* pointer to next via body string if
    compact via or null */
};
</programlisting>
	    <para><emphasis>Field Description:</emphasis></para>
	    <itemizedlist>
		<listitem>
		    <para>
			<structfield>error</structfield> - The field contains error code when the parser was unable
			to parse the header field.
		    </para>
		</listitem>
		<listitem>
		    <para>
			<structfield>hdr</structfield>- Header field name, it can be <quote>Via</quote> or <quote>v</quote>
			in this case.
		    </para>
		</listitem>
		<listitem>
		    <para>
			<structfield>name</structfield> - Protocol name (<quote>SIP</quote> in this case).
		    </para>
		</listitem>
		<listitem>
		    <para>
			<structfield>version</structfield> - Protocol version (for example <quote>2.0</quote>).
		    </para>
		</listitem>
		<listitem>
		    <para>
			<structfield>transport</structfield> - Transport protocol name (<quote>TCP</quote>, <quote>UDP</quote>
			and so on).
		    </para>
		</listitem>
		<listitem>
		    <para>
			<structfield>host</structfield> - Hostname or IP address contained in the Via header field.
		    </para>
		</listitem>
		<listitem>
		    <para>
			<structfield>port</structfield> - Port number as integer.
		    </para>
		</listitem>
		<listitem>
		    <para>
			<structfield>port_str</structfield> - Port number as string.
		    </para>
		</listitem>
		<listitem>
		    <para>
			<structfield>params</structfield> - Unparsed parameters (as one string containing all the parameters).
		    </para>
		</listitem>
		<listitem>
		    <para>
			<structfield>comment</structfield> - Comment.
		    </para>
		</listitem>
		<listitem>
		    <para>
			<structfield>bsize</structfield> - Size of the body (not including hdr).
		    </para>
		</listitem>
		<listitem>
		    <para>
			<structfield>param_lst</structfield> - Linked list of all parameters.
		    </para>
		</listitem>
		<listitem>
		    <para>
			<structfield>last_param</structfield> - Last parameter in the list.
		    </para>
		</listitem>
		<listitem>
		    <para>
			<structfield>branch</structfield> - Branch parameter.
		    </para>
		</listitem>
		<listitem>
		    <para>
			<structfield>received</structfield> - Received parameter.
		    </para>
		</listitem>
		<listitem>
		    <para>
			<structfield>next</structfield> - If the Via is in compact form (more Vias in the same header
			field), this field contains pointer to the next Via.
		    </para>
		</listitem>
	    </itemizedlist>
	</section> <!-- via-body -->

	<section id="ip-addr">
	    <title>Structure <structname>ip_addr</structname></title>
	    <para>
		The structure represents <acronym>IPv4</acronym> or <acronym>IPv6</acronym> address. It is defined in 
		<filename moreinfo="none">ip_addr.h</filename>.
	    </para>
	    <programlisting format="linespecific">
struct ip_addr{
    unsigned int af;     /* address family: AF_INET6 or AF_INET */
    unsigned int len;    /* address len, 16 or 4 */
		
    /* 64 bits aligned address */
    union {
        unsigned int   addr32[4];
        unsigned short addr16[8];
        unsigned char  addr[16];
    }u;
};
</programlisting>
	</section> <!-- ip-addr -->

	<section id="lump">
	    <title>Structure <structname>lump</structname></title>
	    <para>
		The structure describes modifications that should be made to the message before
		the message will be sent. 
	    </para>
	    <para>
		The structure will be described in more detail later in chapter 
		SIP Message Modifications.
	    </para>
	</section> <!-- lump -->
	
	<section id="lump-rpl">
	    <title>Structure <structname>lump_rpl</structname></title>
	    <para>
		The structure represents text that should be added to reply. List of such data is
		kept in the request and processed when the request is being turned into reply. 
	    </para>
	    <para>
		The structure will be described in more detail later in chapter
		SIP Message Modifications.
	    </para>
	</section> <!-- lump-rpl -->

	<section id="msg-start">
	    <title>Structure <structname>msg_start</structname></title>
	    <para>
		The structure represents the first line of a <acronym>SIP</acronym> request or response. 
	    </para>
	    <para>
		The structure is defined in file <filename moreinfo="none">parse_fline.h</filename> under 
		<filename moreinfo="none">parser</filename> subdirectory.
	    </para>

	    <para>
		<emphasis>Structure Declaration</emphasis>
	    </para>
	    <programlisting format="linespecific">
struct msg_start {
    int type;                        /* Type of the Message - Request/Response */
    union {
        struct {
            str method;              /* Method string */
            str uri;                 /* Request URI */
            str version;             /* SIP version */
            int method_value;        /* Parsed method */
        } request;
	struct {
            str version;             /* SIP version */
            str status;              /* Reply status */
            str reason;              /* Reply reason phrase */
            unsigned int statuscode; /* Status code */
        } reply;
    }u;
};
</programlisting>
	    
	    <para>
		<emphasis>Description of Request Related Fields:</emphasis>
	    </para>

	    <itemizedlist>
		<listitem>
		    <para>
			<structfield>type</structfield> - Type of the message - REQUEST or RESPONSE.
		    </para>
		</listitem>
		<listitem>
		    <para>
			<structfield>method</structfield> - Name of method (same as in the message).
		    </para>
		</listitem>