sofia-sip/sip_header.h File Reference


Detailed Description

SIP parser library prototypes.

Author:
Pekka Pessi <Pekka.Pessi@nokia-email.address.hidden>.
Date:
Created: Tue Jun 13 02:58:26 2000 ppessi

#include <sofia-sip/su_alloc.h>
#include <sofia-sip/su_tag.h>
#include <sofia-sip/sip.h>
#include <sofia-sip/msg_header.h>
#include <string.h>
#include <sofia-sip/sip_protos.h>

Include dependency graph for sip_header.h:

Go to the source code of this file.

Defines

#define sip_is_sip(sip)
 Check that sip_t is a SIP structure (not RTSP or HTTP).
#define SIP_HDR_INIT(name)
 Initializer for a SIP header object.
#define SIP_HEADER_INIT(h, sip_class, size)
 Initialize a SIP header structure.
#define sip_fragment_clear(a)
 Clear encoded data.
#define SIP_PORT(s)
 Get SIP service name.
#define SIPS_PORT(s)
 Get SIPS service name.
#define SIP_PAYLOAD_INIT2(data, length)
 Initialize a SIP payload structure with pointer to data and its length.

Functions

msg_mclass_tsip_default_mclass (void)
 Return built-in SIP parser object.
int sip_serialize (msg_t *msg, sip_t *sip)
 Serialize headers into the fragment chain.
issize_t sip_e (sip_t const *sip, int flags, char b[], isize_t size)
 Encode a SIP message.
int sip_is_header (sip_header_t const *header)
 Test if header is a pointer to a SIP header object.
char * sip_header_as_string (su_home_t *home, sip_header_t const *h)
 Convert the header h to a string allocated from home.
int sip_add_dup (msg_t *, sip_t *, sip_header_t const *)
 Add a duplicate of header object to a SIP message.
int sip_add_dup_as (msg_t *msg, sip_t *sip, msg_hclass_t *hc, sip_header_t const *o)
 Add a duplicate of header object to the SIP message.
int sip_add_headers (msg_t *msg, sip_t *sip, void const *extra, va_list headers)
 Add duplicates of headers to the SIP message.
int sip_add_tl (msg_t *msg, sip_t *sip, tag_type_t tag, tag_value_t value,...)
 Add duplicates of headers from taglist to the SIP message.
int sip_add_tagis (msg_t *, sip_t *, tagi_t const **inout_list)
 Add duplicates of headers from taglist to the SIP message.
int sip_add_make (msg_t *, sip_t *, msg_hclass_t *hc, char const *s)
 Parse a string as a header and add it to the SIP message.
char * sip_headers_as_url_query (su_home_t *home, tag_type_t tag, tag_value_t value,...)
 Convert headers from taglist as URL query.
tagi_tsip_url_query_as_taglist (su_home_t *home, char const *query, msg_mclass_t const *parser)
 Convert URL query to a tag list.
int sip_complete_message (msg_t *msg)
 Complete SIP message.
sip_header_tsip_header_format (su_home_t *home, msg_hclass_t *hc, char const *fmt,...)))
 Make a SIP header with formatting provided.
sip_time_t sip_now (void)
 Return current time.
char const * sip_method_name (sip_method_t method, char const *name)
 Return string corresponding to the method.
sip_method_t sip_method_code (char const *name)
 Return code corresponding to the method code.
sip_request_tsip_request_create (su_home_t *home, sip_method_t method, const char *name, url_string_t const *url, char const *version)
 Create a request line object.
sip_status_tsip_status_create (su_home_t *home, unsigned status, char const *phrase, char const *version)
 Create a status line object.
sip_call_id_tsip_call_id_create (su_home_t *home, char const *domain)
 Create a Call-ID header object.
sip_cseq_tsip_cseq_create (su_home_t *, uint32_t seq, unsigned method, char const *name)
 Create a CSeq header object.
sip_contact_tsip_contact_create (su_home_t *, url_string_t const *url, char const *param,...)
 Create a Contact header object.
sip_time_t sip_contact_expires (sip_contact_t const *m, sip_expires_t const *ex, sip_date_t const *date, sip_time_t def, sip_time_t now)
 Calculate expiration time of a Contact header.
sip_content_length_tsip_content_length_create (su_home_t *, uint32_t n)
 Create a Content-Length header object.
sip_date_tsip_date_create (su_home_t *, sip_time_t t)
 Create an Date header object.
sip_expires_tsip_expires_create (su_home_t *, sip_time_t delta)
 Create an Expires header object.
sip_route_tsip_route_create (su_home_t *home, url_t const *url, url_t const *maddr)
 Create a Route header object.
sip_record_route_tsip_record_route_create (su_home_t *, url_t const *rq_url, url_t const *m_url)
 Create a Record-Route header object.
sip_from_tsip_from_create (su_home_t *, url_string_t const *url)
 Create a From header object.
int sip_from_tag (su_home_t *, sip_from_t *from, char const *tag)
 Add a tag to a From header.
sip_to_tsip_to_create (su_home_t *, url_string_t const *url)
 Create a To header object.
sip_via_tsip_via_create (su_home_t *h, char const *host, char const *port, char const *transport,...)
 Create a Via object.
char const * sip_via_transport (sip_via_t const *v)
 Get transport protocol name.
char const * sip_via_port (sip_via_t const *v, int *using_rport)
 Get port number corresponding to a Via line.
sip_payload_tsip_payload_create (su_home_t *, void const *data, isize_t len)
 Create a SIP payload structure.
sip_separator_tsip_separator_create (su_home_t *home)
 Create a SIP separator line structure.
sip_unsupported_tsip_has_unsupported (su_home_t *, sip_supported_t const *support, sip_require_t const *require)
 Check that a required feature is supported.
sip_unsupported_tsip_has_unsupported2 (su_home_t *, sip_supported_t const *support, sip_require_t const *by_require, sip_require_t const *require)
 Check if required feature is supported.
sip_unsupported_tsip_has_unsupported_any (su_home_t *, sip_supported_t const *support, sip_require_t const *by_require, sip_proxy_require_t const *by_proxy_require, sip_require_t const *require, sip_require_t const *require2, sip_require_t const *require3)
 Ensure that required features are supported.
int sip_has_supported (sip_supported_t const *support, char const *feature)
 Check that a feature is supported.
int sip_has_feature (msg_list_t const *supported, char const *feature)
 Check that a feature is in the list.
issize_t sip_header_e (char[], isize_t, sip_header_t const *, int)
 Encode a SIP header field (name: contents CRLF).
sip_header_tsip_header_d (su_home_t *, msg_t const *, char const *)
 Decode a SIP header string (name: contents CRLF?).
issize_t sip_header_field_e (char[], isize_t, sip_header_t const *, int)
 Encode contents of a SIP header field.
issize_t sip_header_field_d (su_home_t *, sip_header_t *, char *, isize_t)
 Decode the string containing header field.
isize_t sip_header_size (sip_header_t const *h)
 Calculate the size of a SIP header and associated memory areas.
sip_header_tsip_header_dup (su_home_t *, sip_header_t const *)
 Duplicate (deep copy) a SIP header or whole list.
sip_header_tsip_header_copy (su_home_t *, sip_header_t const *o)
 Copy a SIP header or whole list.
int sip_allow_events_add (su_home_t *, sip_allow_events_t *ae, char const *e)
 Add an event to Allow-Events header.
int sip_contact_add_param (su_home_t *, sip_contact_t *, char const *param)
 Add a parameter to a Contact header object.
int sip_to_add_param (su_home_t *, sip_to_t *, char const *)
 Add a parameter to a sip_to_t object.
int sip_from_add_param (su_home_t *, sip_from_t *, char const *)
 Add a parameter to an sip_from_t object.
int sip_via_add_param (su_home_t *, sip_via_t *, char const *)
 Add a parameter to a Via header object.

Variables

char const sip_version_2_0 []
 SIP version 2.0.
char const sip_parser_version []
 SIP parser version.
char const *const sip_method_names []
 Well-known SIP method names.


Function Documentation

int sip_allow_events_add ( su_home_t *  home,
sip_allow_events_t ae,
char const *  event 
)

Add an event to Allow-Events header.

Note:
This function does duplicate event.
Deprecated:
Use msg_header_replace_item() directly.

int sip_complete_message ( msg_t msg  ) 

Complete SIP message.

Add sip_content_length and sip_separator if they are missing. The test that all necessary message components ( From, To, CSeq, Call-ID, Content-Length and message separator are present.

Return values:
0 when successful
-1 upon an error: headers are missing and they could not be added

sip_unsupported_t* sip_has_unsupported ( su_home_t *  home,
sip_supported_t const *  support,
sip_require_t const *  require 
)

Check that a required feature is supported.

Return values:
NULL if all the required features are supported
pointer to a Unsupported header or SIP_NONE if home is NULL

sip_unsupported_t* sip_has_unsupported2 ( su_home_t *  home,
sip_supported_t const *  support,
sip_require_t const *  support_by_require,
sip_require_t const *  require 
)

Check if required feature is supported.

Return values:
NULL if all the required features are supported
pointer to a Unsupported header or SIP_NONE if home is NULL

sip_unsupported_t* sip_has_unsupported_any ( su_home_t *  home,
sip_supported_t const *  supported,
sip_require_t const *  by_require,
sip_proxy_require_t const *  by_proxy_require,
sip_require_t const *  require,
sip_require_t const *  require2,
sip_require_t const *  require3 
)

Ensure that required features are supported.

The supported features can be listed in Supported, Require or Proxy-Require headers (in supported, by_require, or by_proxy_require parameters, respectively)

Parameters:
home (optional) home pointer for allocating Unsupported header
supported Supported features (may be NULL) [IN]
by_require supported features listed by Require (may be NULL) [IN]
by_proxy_require supported features listed by Proxy-Require (may be NULL) [IN]
require list of required features (may be NULL) [IN]
require2 2nd list of required features (may be NULL) [IN]
require3 3rd list of required features (may be NULL) [IN]
Return values:
NULL if all the required features are supported
pointer to a Unsupported header or SIP_NONE if home is NULL

sip_header_t* sip_header_copy ( su_home_t *  home,
sip_header_t const *  h 
)

Copy a SIP header or whole list.

Deprecated:
Use msg_header_copy() instead.

sip_header_t* sip_header_d ( su_home_t *  home,
msg_t const *  msg,
char const *  b 
)

Decode a SIP header string (name: contents CRLF?).

Deprecated:
Use msg_header_d() instead.

sip_header_t* sip_header_dup ( su_home_t *  home,
sip_header_t const *  h 
)

Duplicate (deep copy) a SIP header or whole list.

Deprecated:
Use msg_header_dup() instead.

issize_t sip_header_e ( char  b[],
isize_t  bsiz,
sip_header_t const *  h,
int  flags 
)

Encode a SIP header field (name: contents CRLF).

Deprecated:
Use msg_header_e() instead.

issize_t sip_header_field_d ( su_home_t *  home,
sip_header_t h,
char *  s,
isize_t  slen 
)

Decode the string containing header field.

The header object is initialized with the contents of the string. The string is modified when parsing. The home is used to allocate extra memory required when parsing, e.g., for parameter list or when there string contains multiple header fields.

Deprecated:
Use msg_header_make() or header-specific make functions, e.g., sip_via_make().
Return values:
0 when successful
-1 upon an error.

char* sip_headers_as_url_query ( su_home_t *  home,
tag_type_t  tag,
tag_value_t  value,
  ... 
)

Convert headers from taglist as URL query.

The SIP URI can contain a query part separated with the "?", which specifies SIP headers that are included in the request constructed from the URI. For example, using URI

 <sip:example.com?subject=test>
 would include @Subject header with value "test" in the request.

 @param home memory home used to allocate query string (if NULL, use malloc)
 @param tag, value, ... list of tagged arguments

 @bug This function returns NULL if SIPTAG_REQUEST(), SIPTAG_STATUS(),
 SIPTAG_HEADER(), SIPTAG_UNKNOWN(), SIPTAG_ERROR(), SIPTAG_SEPARATOR(), or
 any corresponding string tag is included in the tag list. It ignores
 SIPTAG_SIP().

 @par Example
 @code
 url->url_headers = 
   sip_headers_as_url_query(home, SIPTAG_REPLACES(replaces), TAG_END());

Since:
New in 1.12.4.
See also:
url_query_as_header_string(), sip_url_query_as_taglist(), nta_msg_request_complete(), RFC 3261 section 19.1.1 "Headers", url_t, url_s::url_headers

tagi_t* sip_url_query_as_taglist ( su_home_t *  home,
char const *  query,
msg_mclass_t const *  parser 
)

Convert URL query to a tag list.

SIP headers encoded as URL query is parsed returned as a tag list. Unknown headers are encoded as SIPTAG_HEADER_STR().

Parameters:
home memory home used to alloate string (if NULL, malloc() it)
query query part from SIP URL
parser optional SIP parser used
See also:
sip_add_tl(), sip_add_tagis(), SIPTAG_HEADER_STR(), sip_headers_as_url_query(), url_query_as_header_string(), RFC 3261 section 19.1.1 "Headers", url_t, url_s::url_headers
Since:
New in 1.12.4.
Bug:
Extension headers are ignored. The parser parameter is not used at the moment.


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