$Revision$
$Date$

# Contact Header Field Parser

The parser is located under `parser/contact` 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.

Main function is `parse_contact` in file `parse_contact.c`. The function accepts one parameter which is structure hdr_field 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.

The function creates and initializes an instance of contact_body structure. Then function `contact_parser` will be called. If everything went OK, pointer to the newly created structure will be stored in parsed field of the hdr_field structure representing the parsed header field.

Function `contact_parser` will then check if the contact is star, if not it will call `parse_contacts` function that will parse all contacts of the header field.

Function `parse_contacts` can be found in file `contact.c`. It extracts URI and parses all contact parameters.

The Contact parameter parser can be found in file `cparam.c`.

The following structures will be created during parsing:

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) !

    typedef struct contact_body {
        unsigned char star;    /* Star contact */
        contact_t* contacts;   /* List of contacts */
    } contact_body_t;

This is the main structure. Pointer to instance of this structure will be stored in parsed field of structure representing the header field to be parsed. The structure contains two field:

- star field - This field will contain 1 if the Contact was star (see RFC3261 for more details).

- contacts field - This field contains pointer to linked list of all contacts found in the Contact header field.

    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;

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:

- uri - This field contains pointer to begin of URI and its length.

- q - This is a hook to structure representing q parameter. If there is no such parameter, the hook contains 0.

- expires - This is a hook to structure representing expires parameter. If there is no such parameter, the hook contains 0.

- method - This is a hook to structure representing method parameter. If there is no such parameter, the hook contains 0.

- params - Linked list of all parameters.

- next - Pointer to the next contact that was in the same header field.

    typedef enum cptype {
        CP_OTHER = 0,  /* Unknown parameter */
        CP_Q,          /* Q parameter */
        CP_EXPIRES,    /* Expires parameter */
        CP_METHOD      /* Method parameter */
    } cptype_t;

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.

    /*
     * 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;

This structure represents a contact parameter. Field description follows:

- type - Type of the parameter, see cptype enum for more details.

- name - Name of the parameter (i.e. the part before "=").

- body - Body of the parameter (i.e. the part after "=").

- next - Next parameter in the linked list.