'\" te
.\"  Copyright (c) 2007, Sun Microsystems, Inc.  All Rights Reserved
.TH sip_parse_uri 3SIP "25 Jan 2007" "SunOS 5.11" "Session Initiation Protocol Library Functions"
.SH NAME
sip_parse_uri, sip_free_parsed_uri \- parse a URI and free a parsed URI
.SH SYNOPSIS
.LP
.nf
\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lsip\fR [ \fIlibrary\fR ... ]
#include <sip.h>

\fBsip_uri_t\fR \fIsip_parse_uri\fR(\fBsip_str_t *\fR\fIuri_str\fR, 
     \fBint *\fR\fIerror\fR);
.fi

.LP
.nf
\fBvoid\fR \fIsip_free_parsed_uri\fR(\fBsip_uri_t\fR \fIsip_uri\fR);
.fi

.SH DESCRIPTION
.sp
.LP
For functions that return a pointer of type \fIsip_str_t\fR, \fIsip_str_t\fR is supplied by:
.sp
.in +2
.nf
typedef struct sip_str {
     char *sip_str_ptr;
     int  sip_str_len;
}sip_str_t;
.fi
.in -2

.sp
.LP
The \fIsip_str_ptr\fR parameter points to the start of the returned value and \fIsip_str_len\fR supplies the length of the returned value.
.sp
.LP
For example, given the following request line in a \fBSIP\fR message input to \fBsip_get_request_uri_str()\fR:
.sp
.in +2
.nf
INVITE sip:marconi@radio.org SIP/2.0
.fi
.in -2

.sp
.LP
the return is a pointer to \fIsip_str_t\fR with the \fIsip_str_ptr\fR member pointing to "\fBs\fR" of \fBsip:marconi@radio.org\fR and \fIsip_str_len\fR being set to \fB21\fR, the length of \fBsip:marconi@radio.org\fR.
.sp
.LP
The \fBsip_parse_uri()\fR function takes a \fBURI\fR string in the form \fIsip_str_t\fR and returns a parsed \fBURI\fR \fIsip_uri\fR. The syntax of the \fBURI\fR is as specified in RFC 3261, section 25.1. If the parser encounters an error when parsing a component, it sets the appropriate error bit in the error flags and proceeds to the next component, if present.
.sp
.LP
The \fBsip_free_parsed_uri()\fR function takes a parsed \fBURI\fR \fIsip_uri\fR, obtained from \fBsip_parse_uri()\fR, and frees any associated memory.
.SH RETURN VALUES
.sp
.LP
The \fBsip_parse_uri()\fR function returns the parsed \fBURI\fR \fIsip_uri\fR on success. It returns a \fBNULL\fR if memory cannot be allocated for the parsed \fBURI\fR.
.sp
.LP
The value of \fBerrno\fR is not changed by these calls in the event of an error.
.SH ERRORS
.sp
.LP
If the error is non-null, the following values is set:
.sp
.ne 2
.mk
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 10n
.rt  
The \fBSIP\fR header value of the \fBSIP\fR message is \fBNULL\fR or there is no \fBURI\fR.
.sp
The input \fBURI\fR is null or the requested \fBURI\fR component is invalid. The error flag is set for the requested component.
.sp
The \fBURI\fR parameters or headers are requested from a non-\fBSIP[S]\fR \fBURI\fR; or the '\fBopaque\fR', '\fBquery\fR', '\fBpath\fR', '\fBreg-name\fR' components are requested from a \fBSIP[S]\fR \fBURI\fR.
.RE

.sp
.LP
On success, the value of the location pointed to by \fIerror\fR is set to \fB0\fR.
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Interface StabilityCommitted
_
MT-LevelMT-Safe
.TE

.SH SEE ALSO
.sp
.LP
\fBlibsip\fR(3LIB)