SIP Headers

Collaboration diagram for SIP Headers:


Detailed Description

SIP headers and other SIP message elements.


Modules

 SIP Status Codes and Reason Phrases
 The macros and variables for the standard SIP status codes and reason phrases are defined in <sip_status.h>.
 SIP Tags
 SIP headers in tag item lists and tagged argument lists.
 Request Line
 The request line is first line in a SIP request message.
 Status Line
 The status line is first line in a response message.
 Message Payload
 The payload object contains the optional message body.
 Separator Line
 An empty line separates message headers from the message body (payload).
 Unknown Headers
 The unknown headers are handled with sip_unknown_t structure.
 Erroneous Headers
 The erroneous headers are stored in sip_error_t structure.
 Call-ID Header
 The Call-ID header uniquely identifies a particular invitation or all registrations of a particular client.
 CSeq Header
 The CSeq header (command sequence) uniquely identifies transactions within a dialog.
 Contact Header
 The Contact header contain a list of URLs used to redirect future requests.
 Content-Length Header
 The Content-Length header indicates the size of the message-body in decimal number of octets.
 Date Header
 The Date header field reflects the time when the request or response was first sent.
 Expires Header
 The Expires header field gives the date and time after which the message content expires.
 From Header
 The From header indicates the initiator of the request.
 Max-Forwards Header
 The Max-Forwards header is used to limit the number of proxies or gateways that can forward the request.
 Min-Expires Header
 The Min-Expires header is used to limit the number of proxies or gateways that can forward the request.
 Retry-After Header
 The Retry-After response-header field [RFC3261/20.33] can be used to indicate how long the service is expected to be unavailable or when the called party anticipates being available again.
 Route Header
 The Route headers is used to store the route set of a transaction.
 Record-Route Header
 The Record-Route headers are used to establish a route for transactions belonging to a session.
 To Header
 The To header field specifies the "logical" recipient of the request.
 Via Header
 The Via header indicates the path taken by the request so far.
 Request-Disposition Header
 The Request-Disposition header syntax is defined in draft-ietf-sip-callerprefs-08.txt section 10 as follows:.
 Accept-Contact Header
 The Accept-Contact and Reject-Contact syntax is defined in draft-ietf-sip-callerprefs-07.txt section 10 as follows:.
 Reject-Contact Header
 The Reject-Contact header syntax is shown with Accept-Contact Header Accept-Contact header.
 Event Header
 The Event header is used to indicate the which event or class of events the message contains or subscribes.
 Allow-Event Header
 The Allow-Event header is used to indicate which events or classes of events the notifier supports.
 Subscription-State Header
 The Subscription-State header is used to indicate in which state a subscription is.
 Call-Info Header
 The Call-Info header provides additional information about the caller or callee.
 Error-Info Header
 The Error-Info header provides a pointer to additional information about the error status response.
 In-Reply-To Header
 The In-Reply-To request header field enumerates the Call-IDs that this call references or returns.
 Organization Header
 The Organization header field conveys the name of the organization to which the entity issuing the request or response belongs.
 Priority Header
 The Priority request-header field indicates the urgency of the request as perceived by the client.
 Server Header
 The Server response-header field contains information about the software used by the user agent server to handle the request.
 Subject Header
 The Subject header provides a summary or indicates the nature of the request.
 Timestamp Header
 The Timestamp header describes when the client sent the request to the server, and it is used by the client to adjust its retransmission intervals.
 User-Agent Header
 The User-Agent header contains information about the client user agent originating the request.
 SIP-ETag Header
 The SIP-ETag header field identifies the published event state.
 SIP-If-Match Header
 The SIP-If-Match header field identifies the specific entity of event state that the request is refreshing, modifying or removing.
 Allow Header
 The Allow header lists the set of methods supported by the user agent generating the message.
 Proxy-Require Header
 The Proxy-Require header is used to indicate proxy-sensitive features that MUST be supported by the proxy.
 Require Header
 The Require header is used by clients to tell user agent servers about options that the client expects the server to support in order to properly process the request.
 Supported Header
 The Supported header enumerates all the capabilities of the client or server.
 Unsupported Header
 The Unsupported header lists the features not supported by the server.
 Path Header
 The Path header field is a SIP extension header field (RFC 3327) with syntax very similar to the Record-Route header field.
 Service-Route Header
 The "Service-Route" is a SIP extension header field (RFC 3608), which can contain a route vector that will direct requests through a specific sequence of proxies.
 Accept Header
 The Accept request-header field can be used to specify certain media types which are acceptable for the response.
 Accept-Encoding Header
 The Accept-Encoding header is similar to Accept, but restricts the content-codings that are acceptable in the response.
 Accept-Language Header
 The Accept-Language header can be used to allow the client to indicate to the server in which language it would prefer to receive reason phrases, session descriptions or status responses carried as message bodies.
 Content-Disposition Header
 The Content-Disposition header field describes how the message body or, in the case of multipart messages, a message body part is to be interpreted by the UAC or UAS.
 Content-Encoding Header
 The Content-Encoding header indicates what additional content codings have been applied to the entity-body.
 Content-Language Header
 The Content-Language header [H14.12] describes the natural language(s) of the intended audience for the enclosed entity.
 Content-Type Header
 The Content-Type header indicates the media type of the message-body sent to the recipient.
 MIME-Version Header
 MIME-Version header indicates what version of the MIME protocol was used to construct the message.
 Warning Header
 The Warning response-header field is used to carry additional information about the status of a response.
 RAck Header
 The RAck header indicates the sequence number of the provisional response which is being acknowledged.
 RSeq Header
 The RSeq header identifies provisional responses within a transaction.
 Reason Header
 The Reason header is used to indicate why a SIP request was issued or why a provisional response was sent.
 Refer-To Header
 The Refer-To header provides a URI to reference.
 Referred-By Header
 The Referred-By header conveys the identity of the original referrer to the referred-to party.
 Replaces Header
 The Replaces header indicates that a single dialog identified by the header field is to be shut down and logically replaced by the incoming INVITE in which it is contained.
 Authorization Header
 The Authorization header consists of credentials containing the authentication information of the user agent for the realm of the resource being requested.
 Proxy-Authenticate Header
 The Proxy-Authenticate header consists of a challenge that indicates the authentication scheme and parameters applicable to the proxy.
 Proxy-Authorization Header
 The Proxy-Authorization header consists of credentials containing the authentication information of the user agent for the proxy and/or realm of the resource being requested.
 WWW-Authenticate Header
 The WWW-Authenticate header consists of at least one challenge that indicates the authentication scheme(s) and parameters applicable to the Request-URI.
 Authentication-Info Header
 The Authentication-Info header contains either a next-nonce used by next request and/or authentication from server used in mutual authentication.
 Proxy-Authentication-Info Header
 The Proxy-Authentication-Info header contains either a next-nonce used by next request and/or authentication from proxy used in mutual authentication.
 Security-Client Header
 The Security-Client header is defined by RFC 3329, "Security Mechanism Agreement for the Session Initiation Protocol (SIP)".
 Security-Server Header
 The Security-Server header is defined by RFC 3329, "Security Mechanism Agreement for the Session Initiation Protocol (SIP)".
 Security-Verify Header
 The Security-Verify header is defined by RFC 3329, "Security Mechanism Agreement for the Session Initiation Protocol (SIP)".
 Privacy Header
 The Privacy header is used by User-Agent to request privacy services from the network.
 Session-Expires Header
 The Session-Expires header is used to convey the lifetime of the session.
 Min-SE Header
 The Min-SE header is used to indicate the minimum value for the session interval.
#define SIP_X_INIT()
 Initializer for structure sip_X_t.
enum  { sip_X_hash }
sip_X_t * sip_X_init (sip_X_t x[1])
 Initialize a structure sip_X_t.
int sip_is_X (sip_header_t const *header)
 Test if header object is instance of sip_X_t.
sip_X_t * sip_X_dup (su_home_t *home, sip_X_t const *hdr)
 Duplicate (deep copy) sip_X_t.
sip_X_t * sip_X_copy (su_home_t *home, sip_X_t const *hdr)
 Copy a sip_X_t header structure.
sip_X_t * sip_X_make (su_home_t *home, char const *s)
 Make a header structure sip_X_t.
sip_X_t * sip_X_format (su_home_t *home, char const *fmt,...)))
 Make a X from formatting result.
int sip_X_d (su_home_t *home, sip_header_t *h, char *s, int bsiz)
 Decode a header X.
int sip_X_e (char buf[], int bsiz, sip_header_t const *h, int flags)
 Encode a header X.
msg_hclass_t sip_X_class []
 Header class for SIP X.
msg_parse_f sip_X_d
 Parse a X.
msg_print_f sip_X_e
 Print a X.

SIP Header Structure Conventions

For each SIP header recognized by the SIP module, there is a header structure containing the parsed value.

The header structure name is generated from the header name by lowercasing the name, replacing the non-alphanumeric characters (usually just minus "-") with underscore "_" characters, and then adding prefix sip_ and suffix _t. For instance, the contents of header "MIME-Version" is stored in a structure called sip_mime_version_t.

All header structures contain the common part, a sip_common_t structure (X_common[]), a link to the next header in list (X_next), and a various fields describing the header value (in this case, X_value).

 typedef struct sip_X_s
 {
  sip_common_t    X_common[1];
  sip_X_t        *X_next;
  unsigned long   X_value; 
 } sip_X_t;

The X_common is a structure sip_common_t (aka msg_common_t), which is common to each fragment and can be considered as a base class for all headers. The structure sip_common_t contains the pointers for dual-linked fragment chain (h_succ, h_prev), a pointer to header class (h_class), a pointer to the text encoding of header contents (h_data) and the length of the encoding (h_len). (X_common is an array of size 1, as it makes it easy to cast a header pointer to a pointer to sip_common_t.)

The X_next is a pointer to another header (usually a pointer to structure of same type). If there are multiple headers with same name, like the two "Via" headers in the example above, the X_next is used to link the second header to the first. The fragment chain cannot be used for this purpose as the headers with same name are not necessarily adjacent.


Define Documentation

 
#define SIP_X_INIT (  ) 

Initializer for structure sip_X_t.

A static sip_X_t structure must be initialized with the SIP_X_INIT() macro. For instance,

  sip_X_t sip_X = SIP_X_INIT;


Enumeration Type Documentation

anonymous enum

Enumerator:
sip_X_hash  Hash of X.


Function Documentation

int sip_is_X ( sip_header_t const *  header  )  [inline]

Test if header object is instance of sip_X_t.

The function sip_is_X() returns true (nonzero) if the header class is an instance of X object and false (zero) otherwise.

Parameters:
header pointer to the header structure to be tested
Returns:
The function sip_is_X() returns true (nonzero) if the header object is an instance of header X and false (zero) otherwise.

sip_X_t* sip_X_copy ( su_home_t home,
sip_X_t const *  hdr 
)

Copy a sip_X_t header structure.

The function sip_X_copy() copies a header structure hdr. If the header structure hdr contains a reference (hdr->h_next) to a list of headers, all the headers in that list are copied, too. The function uses given memory home to allocate all the memory areas used to copy the header structure hdr.

Parameters:
home memory home used to allocate new structure
hdr pointer to the header structure to be duplicated
When copying, only the header structure and parameter lists attached to it are duplicated. The new header structure retains all the references to the strings within the old header, including the encoding of the old header, if present.

Example
   X = sip_X_copy(home, sip->sip_X);
Returns:
The function sip_X_copy() returns a pointer to newly copied header structure, or NULL upon an error.

int sip_X_d ( su_home_t home,
sip_header_t *  h,
char *  s,
int  bsiz 
)

Decode a header X.

The function sip_X_d() decodes value of the header X in the preallocated header structure h. The string s to be decoded should not contain the header name or colon. The decoding function also expects that the leading and trailing whitespace has been removed from the string s.

Parameters:
home memory home used to allocate new header structure.
h sip_X_t header structure
s string to be decoded
bsiz length of string s
Returns:
The function sip_X_d() returns non-negative value when successful, or -1 upon an error.

sip_X_t* sip_X_dup ( su_home_t home,
sip_X_t const *  hdr 
)

Duplicate (deep copy) sip_X_t.

The function sip_X_dup() duplicates a header structure hdr. If the header structure hdr contains a reference (hdr->x_next) to a list of headers, all the headers in the list are duplicated, too.

Parameters:
home memory home used to allocate new structure
hdr header structure to be duplicated
When duplicating, all parameter lists and non-constant strings attached to the header are copied, too. The function uses given memory home to allocate all the memory areas used to copy the header.

Example
   X = sip_X_dup(home, sip->sip_X);
Returns:
The function sip_X_dup() returns a pointer to the newly duplicated sip_X_t header structure, or NULL upon an error.

int sip_X_e ( char  buf[],
int  bsiz,
sip_header_t const *  h,
int  flags 
)

Encode a header X.

The function sip_X_e() encodes a header structure h to the given buffer buf. Even if the given buffer buf is NULL or its size bufsiz is too small to fit the encoding result, the function returns the number of characters required for the encoding.

Parameters:
buf buffer to store the encoding result
bsiz size of the encoding buffer
h header to be encoded.
flags flags controlling the encoding
Note:
The encoding buffer size must be bigger than, not equal to, the actual encoding result.
Returns:
The function sip_X_e() returns the number of characters required for the encoding.

sip_X_t * sip_X_format ( su_home_t home,
char const *  fmt,
  ... 
) [inline]

Make a X from formatting result.

The function sip_X_format() makes a new X object using formatting result as its value. The function first prints the arguments according to the format fmt specified. Then it allocates a new header structure, and uses the formatting result as the header value.

Parameters:
home memory home used to allocate new header structure.
fmt string used as a printf()-style format
... argument list for format
Note:
This function is usually implemented as a macro calling msg_header_format().
Returns:
The function sip_X_format() returns a pointer to newly makes header structure, or NULL upon an error.

sip_X_t* sip_X_init ( sip_X_t  x[1]  )  [inline]

Initialize a structure sip_X_t.

An sip_X_t structure can be initialized with the sip_X_init() function/macro. For instance,

  sip_X_t sip_X;
 
  sip_X_init(&sip_X);

sip_X_t* sip_X_make ( su_home_t home,
char const *  s 
) [inline]

Make a header structure sip_X_t.

The function sip_X_make() makes a new sip_X_t header structure. It allocates a new header structure, and decodes the string s as the value of the structure.

Parameters:
home memory home used to allocate new header structure.
s string to be decoded as value of the new header structure
Note:
This function is usually implemented as a macro calling sip_header_make().
Returns:
The function sip_X_make() returns a pointer to newly maked sip_X_t header structure, or NULL upon an error.


Variable Documentation

msg_hclass_t sip_X_class[]

Header class for SIP X.

The header class sip_X_class defines how a SIP X is parsed and printed. It also contains methods used by SIP parser and other functions to manipulate the sip_X_t header structure.


Sofia-SIP 1.12.1 - Copyright (C) 2006 Nokia Corporation. All rights reserved. Licensed under the terms of the GNU Lesser General Public License.