Loading...
Searching...
No Matches
sip_header.h File Reference

SIP parser library prototypes. More...

`#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.

## Macros

#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.nosp@m..Pes.nosp@m.si@no.nosp@m.kia..nosp@m.com.

Date
  Created: Tue Jun 13 02:58:26 2000 ppessi

## Macro Definition Documentation

## SIP_IS_ALLOWED

#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

## sip_bad_mask

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. Sip_request "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. Sip_status "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

## sip_add_tl()

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.

Add duplicates of headers from taglist to the SIP message.

## sip_allow_events_add()

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

Add an event to Allow-Events header.

Add an event to Allow-Events header.

Note
  This function does duplicate `event`.

Deprecated
  Use msg_header_replace_item() directly.

## sip_complete_message()

int sip_complete_message | ( | msg_t * | msg | ) |

Complete SIP message.

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_extend_mclass()

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.

## sip_has_unsupported()

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.

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_has_unsupported2()

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_has_unsupported_any()

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

## sip_header_copy()

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

Copy a SIP header or whole list.

Copy a SIP header or whole list.

Deprecated
  Use msg_header_copy() instead.

## sip_header_d()

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?).

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

Deprecated
  Use msg_header_d() instead.

## sip_header_dup()

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

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

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

Deprecated
  Use msg_header_dup() instead.

## sip_header_e()

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

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

Deprecated
  Use msg_header_e() instead.

## sip_header_field_d()

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.

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.

## sip_header_size()

isize_t sip_header_size | ( | sip_header_t const * | h | ) |

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

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

## sip_headers_as_url_query()

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.

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());
SIPTAG_ERROR
#define SIPTAG_ERROR(x)
Tag list item for pointer to a erroneous headers structure sip_error_t.
Definition sip_tag.h:4951
SIPTAG_REPLACES
#define SIPTAG_REPLACES(x)
Tag list item for pointer to a Replaces header structure sip_replaces_t.
Definition sip_tag.h:3621
SIPTAG_REQUEST
#define SIPTAG_REQUEST(x)
Tag list item for pointer to a request line structure sip_request_t.
Definition sip_tag.h:191
SIPTAG_SEPARATOR
#define SIPTAG_SEPARATOR(x)
Tag list item for pointer to a separator line between headers and body structure sip_separator_t.
Definition sip_tag.h:5021
SIPTAG_STATUS
#define SIPTAG_STATUS(x)
Tag list item for pointer to a status line structure sip_status_t.
Definition sip_tag.h:261
SIPTAG_UNKNOWN
#define SIPTAG_UNKNOWN(x)
Tag list item for pointer to a unknown headers structure sip_unknown_t.
Definition sip_tag.h:4881
sip_headers_as_url_query
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.
Definition sip_tag_class.c:302
SIPTAG_HEADER
#define SIPTAG_HEADER(x)
Tag list item for header string.
Definition sip_tag.h:124
SIPTAG_SIP
#define SIPTAG_SIP(x)
Tag list item for sip_t object.
Definition sip_tag.h:92
TAG_END
#define 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

## sip_method_code()

sip_method_t sip_method_code | ( | char const * | name | ) |

Return code corresponding to the method code.

Return code corresponding to the method code.

## sip_method_name()

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

Return string corresponding to the method.

Return string corresponding to the method.

## sip_now()

sip_time_t sip_now | ( | void |  | ) |

Return current time.

Return current time.

## sip_update_default_mclass()

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);
}
sip_extend_mclass
msg_mclass_t * sip_extend_mclass(msg_mclass_t *input)
Extend SIP parser class with extension headers.
Definition sip_parser.c:127
sip_update_default_mclass
int sip_update_default_mclass(msg_mclass_t const *mclass)
Update the default SIP parser.
Definition sip_parser.c:98
su_deinit
void su_deinit(void)
su_init
int su_init(void)

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.

## sip_url_query_as_taglist()

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.

## Variable Documentation

## sip_parser_version

char const sip_parser_version[]

extern

SIP parser version.

SIP parser version.

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