libosip  5.3.0
How-To parse SIP message.

Parser API

For the SIP parser, the API is documented in osip_message.h

Basic Parser operations

Because the SIP message can contains binary data in its body part, the length of the buffer must be given to the API.

int i;
if (i!=0) { fprintf(stderr, "cannot allocate\n"); return -1; }
i=osip_message_parse(sip, buffer, length_of_buffer);
if (i!=0) { fprintf(stderr, "cannot parse sip message\n"); }
int osip_message_parse(osip_message_t *sip, const char *buf, size_t length)
Definition: osip_message_parse.c:939
void osip_message_free(osip_message_t *sip)
Definition: osip_message.c:105
int osip_message_init(osip_message_t **sip)
Definition: osip_message.c:29
Definition: osip_message.h:54

When converting SIP message, the final length of the allocated buffer will be returned in the third argument. You then have the knowledge of the length of the data received.

char *dest=NULL;
int length=0;
i = osip_message_to_str(sip, &dest, &length);
if (i!=0) { fprintf(stderr, "cannot get printable message\n"); return -1; }
fprintf(stdout, "message:\n%s\n", dest);
int osip_message_to_str(osip_message_t *sip, char **dest, size_t *message_length)
Definition: osip_message_to_str.c:748

When using libosip2 and its transaction management features, you'll generally only need to create a suitable events. Thus, you'll probably use this API (only for SIP message that you receive!):

int length = size_of_buffer;
evt = osip_parse(buffer, i);
osip_event_t * osip_parse(const char *buf, size_t length)
Definition: osip_event.c:28
Definition: osip.h:627

Note**: It is important to understand that the libosip2 parser will not check completely if the message is compliant and well formed. The application layer is still responsible for this.

The libosip2 parser will not detect all errors (like missing headers) and it will be up to you to verify at every action that things are as you are expecting them to be!

Built-in Header Operations

osip_message_t structure contains pointers to most common headers. Other headers (Any of them, even ones not being defined by rfc) will be saved into a list of other headers.

struct osip_message {
Definition: osip_call_id.h:44
Definition: osip_content_length.h:44
Definition: osip_content_type.h:46
Definition: osip_cseq.h:44
Definition: osip_from.h:47
Definition: osip_list.h:87
osip_content_length_t * content_length
Definition: osip_message.h:77
osip_list_t proxy_authorizations
Definition: osip_message.h:89
osip_list_t authentication_infos
Definition: osip_message.h:68
osip_list_t proxy_authenticates
Definition: osip_message.h:85
osip_list_t contacts
Definition: osip_message.h:73
osip_list_t allows
Definition: osip_message.h:67
osip_to_t * to
Definition: osip_message.h:92
osip_list_t vias
Definition: osip_message.h:93
osip_list_t record_routes
Definition: osip_message.h:90
osip_list_t content_encodings
Definition: osip_message.h:75
osip_cseq_t * cseq
Definition: osip_message.h:79
osip_list_t error_infos
Definition: osip_message.h:81
osip_list_t authorizations
Definition: osip_message.h:70
osip_list_t accepts
Definition: osip_message.h:63
osip_mime_version_t * mime_version
Definition: osip_message.h:84
osip_content_type_t * content_type
Definition: osip_message.h:78
osip_list_t accept_languages
Definition: osip_message.h:65
osip_call_id_t * call_id
Definition: osip_message.h:71
osip_from_t * from
Definition: osip_message.h:83
osip_list_t accept_encodings
Definition: osip_message.h:64
osip_list_t routes
Definition: osip_message.h:91
osip_list_t call_infos
Definition: osip_message.h:72
osip_list_t www_authenticates
Definition: osip_message.h:94
osip_list_t alert_infos
Definition: osip_message.h:66
osip_list_t proxy_authentication_infos
Definition: osip_message.h:87

Other Header Operations

Any other headers will be saved into a list of other headers.

struct osip_message {
osip_list_t headers
Definition: osip_message.h:96

Note**: Those headers, even if not built-in, may have the same syntax as other headers (many contains URI for example)ยต. So you can easily re-use already existing headers API to analyse them.

osip_message_set_header (msg, "Refer-to", refer_to_header);
int osip_message_set_header(osip_message_t *sip, const char *hname, const char *hvalue)
Definition: osip_header.c:31
osip_message_set_header (msg, "Subscription-State", subscription_state_header);
osip_message_set_header (msg, "Require", "timer");
osip_message_set_header (msg, "RAck", rack_header);
osip_message_set_header (msg, "Min-SE", min_se_header);
osip_message_set_header (msg, "x-header", x_header);
osip_message_header_get_byname (msg, "min-se", 0, &min_se_header);
if (min_se_header != NULL && min_se_header->hvalue != NULL) {
int osip_message_header_get_byname(const osip_message_t *sip, const char *hname, int pos, osip_header_t **dest)
Definition: osip_header.c:186

Note**: if you are looking for all headers with same name, you need to find the first one and re-use the return position as a parameter to search for the next one.

int pos=0;
while (1) {
pos = osip_message_header_get_byname (msg, "x-header", pos, &min_se_new);
if (min_se_new == NULL) {
break; //no more headers

In some case, short name are used in SIP message for some headers. For example, "x" is equivalent to "session-expires". In that case, you need to search for both:

osip_message_header_get_byname (msg, "session-expires", 0, &exp);
if (exp == NULL)
osip_message_header_get_byname (msg, "x", 0, &exp);

Known header parser

You can browse the API documentation to know more about header parser. libosipparser2 provides specific parser for the built-in headers (like via, from, to, call-id, route, etc... see above for full list)

oSIP osip_accept header definition.
oSIP osip_accept_encoding header definition.
oSIP osip_accept_language header definition.
oSIP osip_alert_info header definition.
oSIP osip_allow header definition.
oSIP osip_authentication_info header definition.
oSIP osip_authorization header definition.
oSIP osip_call_id header definition.
oSIP osip_call_info header definition.
oSIP osip_contact header definition.
oSIP osip_content_disposition header definition.
oSIP osip_content_encoding header definition.
oSIP osip_content_length header definition.
oSIP osip_content_type header definition.
oSIP osip_cseq header definition.
oSIP osip_error_info header definition.
oSIP osip_from header definition.
oSIP osip_header definition.
oSIP osip_mime_version header definition.
oSIP osip_proxy_authenticate header definition.
oSIP osip_proxy_authentication_info header definition.
oSIP osip_proxy_authorization header definition.
oSIP osip_record_route header definition.
oSIP osip_route header definition.
oSIP osip_to header definition.
oSIP osip_via header definition.
oSIP osip_www_authenticate header definition.

Here are some sample code for Via.

osip_via_t *dest;
osip_message_get_via (msg, 0, &dest);
int osip_message_get_via(const osip_message_t *sip, int pos, osip_via_t **dest)
Definition: osip_via.c:86
Definition: osip_via.h:46
char tmp[200];
snprintf (tmp, 200, "SIP/2.0/UDP %s:%s;rport;branch=z9hG4bK%u", ip, port, osip_build_random_number ());
int osip_message_set_via(osip_message_t *sip, const char *hvalue)
Definition: osip_via.c:31
osip_via_t *header;
char tmp[200];
snprintf (tmp, 200, "SIP/2.0/UDP %s:%s;rport;branch=z9hG4bK%u", ip, port, osip_build_random_number ());
osip_via_init (&header);
osip_via_parse (header, tmp);
int osip_via_init(osip_via_t **via)
Definition: osip_via.c:101
int osip_via_parse(osip_via_t *via, const char *hvalue)
Definition: osip_via.c:128