/**
 * @ingroup libosip2 The GNU oSIP stack
 * @defgroup howto2_parser How-To parse SIP message.


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

Here is the sequence needed to parse a given buffer containing
a sip request or response. Because the SIP message can contains
binary data in its body part, the length of the buffer must be
given to the API.

<PRE>
        osip_message_t *sip;
	int i;

	i=osip_message_init(&sip);
	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"); }
	osip_message_free(sip);
</PRE>

Here is the sequence needed to convert the message into a printable
string. Note that in this sequence, dest is allocated dynamically
and must be released at the end of the call sequence to avoid
memory leaks.

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.

<PRE>
	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);
	osip_free(dest);
</PRE>

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!):

<PRE>
	osip_event_t *evt;
	int length = size_of_buffer;
	evt = osip_parse(buffer, i);
</PRE>

<B>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.</B> The following string shows
a request-URI containing a strange port number! 

<pre>INVITE sip:jack@atosc.org:abcd SIP/2.0</pre>

The libosip2 parser will not detect this as an error and it will
be up to you to verify at evry action that things are as you are
expecting them to be!

*/