SIP parser library prototypes. More...

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

Include dependency graph for sip_header.h:

Go to the source code of this file.

Defines
#define	SIP_HEADER_H
	Defined when <sofia-sip/sip_header.h> has been included.
#define	sip_is_sip(sip)
	Check that sip_t is a SIP header structure (not MIME or HTTP).
#define	SIP_HDR_INIT(name)
	Initializer for a SIP header structure.
#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.
#define	SIP_IS_ALLOWED(allow, method)
	Check if the well-known method is listed in Allow header.
Enumerations
enum	sip_bad_mask { sip_mask_request, sip_mask_response, sip_mask_ua, sip_mask_proxy, sip_mask_registrar, sip_mask_100rel, sip_mask_events, sip_mask_timer, sip_mask_privacy, sip_mask_pref, sip_mask_publish }
	Bitmasks for header classifications. More...
Functions
msg_mclass_t const *	sip_default_mclass (void)
	Return a built-in SIP parser object.
int	sip_update_default_mclass (msg_mclass_t const *mclass)
	Update the default SIP parser.
msg_mclass_t *	sip_extend_mclass (msg_mclass_t *input)
	Extend SIP parser class with extension headers.
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_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.
int	sip_complete_message (msg_t *msg)
	Complete SIP message.
sip_header_t *	sip_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_t *	sip_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_t *	sip_status_create (su_home_t home, unsigned status, char const phrase, char const *version)
	Create a status line object.
sip_call_id_t *	sip_call_id_create (su_home_t home, char const domain)
	Create a Call-ID header object.
sip_cseq_t *	sip_cseq_create (su_home_t , uint32_t seq, unsigned method, char const name)
	Create a CSeq header object.
sip_contact_t *	sip_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_t *	sip_content_length_create (su_home_t *, uint32_t n)
	Create a Content-Length header object.
sip_date_t *	sip_date_create (su_home_t *, sip_time_t t)
	Create an Date header object.
sip_expires_t *	sip_expires_create (su_home_t *, sip_time_t delta)
	Create an Expires header object.
sip_route_t *	sip_route_create (su_home_t home, url_t const url, url_t const *maddr)
	Create a Route header object.
sip_record_route_t *	sip_record_route_create (su_home_t , url_t const rq_url, url_t const *m_url)
	Create a Record-Route header object.
sip_from_t *	sip_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_t *	sip_to_create (su_home_t , url_string_t const url)
	Create a To header object.
sip_via_t *	sip_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_t *	sip_payload_create (su_home_t , void const data, isize_t len)
	Create a SIP payload structure.
sip_separator_t *	sip_separator_create (su_home_t *home)
	Create a SIP separator line structure.
sip_unsupported_t *	sip_has_unsupported (su_home_t , sip_supported_t const support, sip_require_t const *require)
	Check that a required feature is supported.
sip_unsupported_t *	sip_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 not supported.
sip_unsupported_t *	sip_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)
	Check if required features are not 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.
int	sip_is_allowed (sip_allow_t const allow, sip_method_t method, char const name)
	Return true if the method is listed in Allow header.
issize_t	sip_header_e (char[], isize_t, sip_header_t const *, int)
	Encode a SIP header field (name: contents CRLF).
sip_header_t *	sip_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_t *	sip_header_dup (su_home_t , sip_header_t const )
	Duplicate (deep copy) a SIP header or whole list.
sip_header_t *	sip_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.

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

Define Documentation

#define SIP_HEADER_H

Defined when <sofia-sip/sip_header.h> has been included.

#define SIP_IS_ALLOWED	(	allow,
		method
	)

Check if the well-known method is listed in Allow header.

Since:: New in 1.12.6.

Enumeration Type Documentation

enum sip_bad_mask

Bitmasks for header classifications.

If parsing of a particular header fails, the error bits in msg_t are updated. The error bits can be obtained via msg_extract_errors() after parsing. The header-specific bits are stored along with the header class in the msg_href_t structure, found in the parser tables of the msg_mclass_t object.

See also:: NTATAG_BAD_REQ_MASK(), NTATAG_BAD_RESP_MASK(), msg_mclass_t, struct msg_mclass_s, msg_mclass_clone(), msg_mclass_insert_with_mask(), msg_href_t, struct msg_href_s, msg_mclass_insert().

Enumerator:

sip_mask_request	Bit marking essential headers in a request message. Request Line "request line"", @ref sip_from "From", @ref sip_to "To", @ref sip_cseq "CSeq", @ref sip_call_id "Call-ID", @ref sip_content_length "Content-Length", @ref sip_via "Via"
sip_mask_response	Bit marking essential headers in a response message. Status Line "status line"", @ref sip_from "From", @ref sip_to "To", @ref sip_cseq "CSeq", @ref sip_call_id "Call-ID", @ref sip_content_length "Content-Length", @ref sip_via "Via"
sip_mask_ua	Bit marking essential headers for User-Agent. Content-Type, Content-Disposition, Content-Encoding, Supported, Contact, Require, and Record-Route.
sip_mask_proxy	Bit marking essential headers for proxy server. Route, Max-Forwards, Proxy-Require, Proxy-Authorization, Supported, Contact, and Record-Route.
sip_mask_registrar	Bit marking essential headers for registrar server. Min-Expires, Authorization, Path, Supported, Contact, Require, and Expires.
sip_mask_100rel	Bit marking essential headers for 100rel extension. RAck and RSeq. See also: RFC 3262.
sip_mask_events	Bit marking essential headers for SIP events. Event, Expires, and Subscription-State. See also: RFC 3265.
sip_mask_timer	Bit marking essential headers for session timer extension. Session-Expires, and Min-SE. RFC 4028
sip_mask_privacy	Bit marking essential headers for privacy extension. Privacy. See also: RFC 3323
sip_mask_pref	Bit marking essential headers for caller preference extension. Request-Disposition, Accept-Contact, and Reject-Contact. See also: RFC 3841.
sip_mask_publish	Bit marking essential headers for PUBLISH servers and clients. SIP-ETag, and SIP-If-Match. See also: RFC 3903.

Function Documentation

int sip_add_dup	(	msg_t *	msg,
		sip_t *	sip,
		sip_header_t const *	o
	)

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_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.

int sip_add_tagis	(	msg_t *	msg,
		sip_t *	sip,
		tagi_t const **	inout_list
	)

Add duplicates of headers from taglist 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_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

msg_mclass_t const* sip_default_mclass ( void )

Return a built-in SIP parser object.

issize_t sip_e	(	sip_t const *	sip,
		int	flags,
		char	b[],
		isize_t	size
	)

Encode a SIP message.

msg_mclass_t* sip_extend_mclass ( msg_mclass_t * input )

Extend SIP parser class with extension headers.

Extend given SIP parser class with extension headers. If the given parser (message class) is the default one or NULL, make a clone of default parser before extending it.

Parameters:

input

pointer to a SIP message class (may be NULL)

Returns:: Pointer to extended mclass, or NULL upon an error.

See also:: Alert-Info, Reply-To, Remote-Party-Id, P-Asserted-Identity, P-Preferred-Identity, Suppress-Body-If-Match, Suppress-Notify-If-Match

Since:: New in 1.12.7.

int sip_has_feature	(	msg_list_t const *	supported,
		char const *	feature
	)

Check that a feature is in the list.

int sip_has_supported	(	sip_supported_t const *	supported,
		char const *	feature
	)

Check that a feature is supported.

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

Check if required features are not 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

char* sip_header_as_string	(	su_home_t *	home,
		sip_header_t const *	h
	)

Convert the header h to a string allocated from home.

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.

issize_t sip_header_field_e	(	char	[],
		isize_t	,
		sip_header_t const *	,
		int
	)

Encode contents of a SIP header field.

sip_header_t* sip_header_format	(	su_home_t *	home,
		msg_hclass_t *	hc,
		char const *	fmt,
			...
	)

Make a SIP header with formatting provided.

isize_t sip_header_size ( sip_header_t const * h )

Calculate the size of a SIP header and associated memory areas.

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

int sip_is_allowed	(	sip_allow_t const *	allow,
		sip_method_t	method,
		char const *	name
	)

Return true if the method is listed in Allow header.

int sip_is_header ( sip_header_t const * header )

Test if header is a pointer to a SIP header object.

char const* sip_method_name	(	sip_method_t	method,
		char const *	name
	)

Return string corresponding to the method.

int sip_serialize	(	msg_t *	msg,
		sip_t *	sip
	)

Serialize headers into the fragment chain.

int sip_update_default_mclass ( msg_mclass_t const * mclass )

Update the default SIP parser.

Use the extended SIP parser as default one.

If the applications want to use headers added after 1.12.5, they should call this function before doing any other initialization, e.g.,

   su_init();
   if (sip_update_default_mclass(sip_extend_mclass(NULL)) < 0) {
     su_deinit();
     exit(2);
   }

The default parser is not extended because it may break the old applications looking for extension headers from sip_unknown list.

Return values:

	0	when successful
	-1	upon an error

See also:: sip_extend_mclass()

Since:: New in 1.12.7.

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.

char const* sip_via_transport ( sip_via_t const * v ) [inline]

Get transport protocol name.

Variable Documentation

char const* const sip_method_names[]

Well-known SIP method names.

char const sip_version_2_0[]

SIP version 2.0.

sofia-sip/sip_header.h File Reference

Defines

Enumerations

Functions

Variables

Detailed Description

Define Documentation

Enumeration Type Documentation

Function Documentation

Variable Documentation