'\" te
.\"  Copyright (c) 2007, Sun Microsystems, Inc.  All Rights Reserved
.TH sip_get_request_method 3SIP "25 Jan 2007" "SunOS 5.11" "Session Initiation Protocol Library Functions"
.SH NAME
sip_get_request_method, sip_get_response_code, sip_get_response_phrase, sip_get_sip_version \- obtain attributes from the start line in a SIP message
.SH SYNOPSIS
.LP
.nf
\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lsip\fR [ \fIlibrary\fR ... ]
#include <sip.h>

\fBsip_method_t\fR \fIsip_get_request_method\fR(\fBconst sip_msg_t\fR \fIsip_msg\fR, 
     \fBint *\fR\fIerror\fR);
.fi

.LP
.nf
\fBint\fR \fIsip_get_response_code\fR(\fBsip_msg_t\fR \fIsip_msg\fR, 
     \fBint *\fR\fIerror\fR);
.fi

.LP
.nf
\fBconst sip_str_t *\fR\fIsip_get_response_phrase\fR(\fBsip_msg_t\fR \fIsip_msg\fR, 
     \fBint *\fR\fIerror\fR);
.fi

.LP
.nf
\fBconst sip_str_t*\fR\fIsip_get_sip_version\fR(\fBsip_msg_t\fR \fIsip_msg\fR, 
     \fBint *\fR\fIerror\fR);
.fi

.SH DESCRIPTION
.sp
.LP
For functions that return a pointer of type \fBsip_str_t\fR, \fBsip_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 \fIsip_msg\fR that is input to \fBsip_get_request_uri_str()\fR:
.sp
.in +2
.nf
FROM : <Alice sip:alice@atlanta.com>;tag=1928301774
.fi
.in -2

.sp
.LP
the return is a pointer to \fIsip_str_t\fR with the \fIsip_str_ptr\fR member pointing to "\fBA\fR" of \fBAlice\fR and \fIsip_str_len\fR being set to \fB5\fR, the length of \fBAlice\fR.
.sp
.LP
Access functions for headers that can have multiple values take the value as the input, while those that can have only one value take the \fBSIP\fR message \fIsip_msg\fR as the input.
.sp
.LP
The \fBsip_get_request_method()\fR function will return the \fBSIP\fR method from the request line in the  \fBSIP\fR message \fIsip_msg\fR. The method can be one of the following:
.br
.in +2
INVITE
.in -2
.br
.in +2
ACK
.in -2
.br
.in +2
OPTIONS
.in -2
.br
.in +2
BYE
.in -2
.br
.in +2
CANCEL
.in -2
.br
.in +2
REGISTER
.in -2
.br
.in +2
REFER
.in -2
.br
.in +2
INFO
.in -2
.br
.in +2
SUBSCRIBE
.in -2
.br
.in +2
NOTIFY
.in -2
.br
.in +2
PRACK
.in -2
.br
.in +2
UNKNOWN
.in -2
.sp
.LP
The \fBsip_get_response_code()\fR function will return the response code \fIresponse\fR from the request line in the  \fBSIP\fR message \fIsip_msg\fR.
.sp
.LP
The \fBsip_get_respose_phrase()\fR function will return the response phrase \fIresponse\fR from the request line in the  \fBSIP\fR message \fIsip_msg\fR.
.sp
.LP
The \fBsip_get_sip_version()\fR function will return the version of the \fBSIP\fR protocol from the request or the response line in the \fBSIP\fR message \fIsip_msg\fR.
.SH RETURN VALUES
.sp
.LP
For functions that return a pointer to \fIsip_str_t\fR, the return value is the specified value on success or \fBNULL\fR in case of error. For functions that return an integer, the return value is the specified value on success and \fB-1\fR on error.
.sp
.LP
The value of \fBerrno\fR is not changed by these calls in the event of an error.
.SH ERRORS
.sp
.LP
These functions take a pointer to an integer \fIerror\fR as an argument. If the error is non-null, one of the following values is set:
.sp
.ne 2
.mk
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 10n
.rt  
The input \fBSIP\fR message \fIsip_msg\fR or the header value is null; or the specified header/header value is deleted.
.RE

.sp
.ne 2
.mk
.na
\fB\fBEPROTO\fR\fR
.ad
.RS 10n
.rt  
The header value is not present or invalid. The parser could not parse it correctly.
.RE

.sp
.ne 2
.mk
.na
\fB\fBENOMEM\fR\fR
.ad
.RS 10n
.rt  
There is an error allocating memory for the return value.
.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)