share/man/man3sip/sip_is_sip_uri.3sip

   1 '\" te
   2 .\"  Copyright (c) 2007, Sun Microsystems, Inc.  All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH SIP_IS_SIP_URI 3SIP "Feb 10, 2007"
   7 .SH NAME
   8 sip_is_sip_uri, sip_get_uri_scheme, sip_get_uri_host, sip_get_uri_user,
   9 sip_get_uri_password, sip_get_uri_port, sip_get_uri_params,
  10 sip_get_uri_headers, sip_get_uri_opaque, sip_get_uri_query, sip_get_uri_path,
  11 sip_get_uri_regname, sip_is_uri_teluser, sip_get_uri_errflags,
  12 sip_uri_errflags_to_str \- get URI related attributes
  13 .SH SYNOPSIS
  14 .LP
  15 .nf
  16 \fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lsip\fR [ \fIlibrary\fR ... ]
  17 #include <sip.h>
  18
  19 \fBboolean_t\fR \fIsip_is_sip_uri\fR(\fBconst struct sip_uri *\fR\fIsip_uri\fR);
  20 .fi
  21
  22 .LP
  23 .nf
  24 \fBconst sip_str_t *\fR\fIsip_get_uri_scheme\fR(\fBconst struct sip_uri *\fR\fIsip_uri\fR,
  25      \fBint *\fR\fIerror\fR);
  26 .fi
  27
  28 .LP
  29 .nf
  30 \fBconst sip_str_t *\fR\fIsip_get_uri_user\fR(\fBconst struct sip_uri *\fR\fIsip_uri\fR,
  31      \fBint *\fR\fIerror\fR);
  32 .fi
  33
  34 .LP
  35 .nf
  36 \fBconst sip_str_t *\fR\fIsip_get_uri_password\fR(\fBconst struct sip_uri *\fR\fIsip_uri\fR,
  37      \fBint *\fR\fIerror\fR);
  38 .fi
  39
  40 .LP
  41 .nf
  42 \fBconst sip_str_t *\fR\fIsip_get_uri_host\fR(\fBconst struct sip_uri *\fR\fIsip_uri\fR,
  43      \fBint *\fR\fIerror\fR);
  44 .fi
  45
  46 .LP
  47 .nf
  48 \fBint\fR \fIsip_get_uri_port\fR(\fBconst struct sip_uri *\fR\fIsip_uri\fR,
  49      \fBint *\fR\fIerror\fR);
  50 .fi
  51
  52 .LP
  53 .nf
  54 \fBconst sip_param_t *\fR\fIsip_get_uri_params\fR(\fBconst struct sip_uri *\fR\fIsip_uri\fR,
  55      \fBint *\fR\fIerror\fR);
  56 .fi
  57
  58 .LP
  59 .nf
  60 \fBconst sip_str_t *\fR\fIsip_get_uri_headers\fR(\fBconst struct sip_uri *\fR\fIsip_uri\fR,
  61      \fBint *\fR\fIerror\fR);
  62 .fi
  63
  64 .LP
  65 .nf
  66 \fBconst sip_str_t *\fR\fIsip_get_uri_opaque\fR(\fBconst struct sip_uri *\fR\fIsip_uri\fR,
  67      \fBint *\fR\fIerror\fR);
  68 .fi
  69
  70 .LP
  71 .nf
  72 \fBconst sip_str_t *\fR\fIsip_get_uri_query\fR(\fBconst struct sip_uri *\fR\fIsip_uri\fR,
  73      \fBint *\fR\fIerror\fR);
  74 .fi
  75
  76 .LP
  77 .nf
  78 \fBconst sip_str_t *\fR\fIsip_get_uri_path\fR(\fBconst struct sip_uri *\fR\fIsip_uri\fR,
  79      \fBint *\fR\fIerror\fR);
  80 .fi
  81
  82 .LP
  83 .nf
  84 \fBconst sip_str_t *\fR\fIsip_get_uri_regname\fR(\fBconst struct sip_uri *\fR\fIsip_uri\fR,
  85      \fBint *\fR\fIerror\fR);
  86 .fi
  87
  88 .LP
  89 .nf
  90 \fBboolean_t\fR \fIsip_is_uri_teluser\fR(\fBconst struct sip_uri *\fR\fIsip_uri\fR);
  91 .fi
  92
  93 .LP
  94 .nf
  95 \fBint\fR \fIsip_get_uri_errflags\fR(\fBconst struct sip_uri *\fR\fIsip_uri\fR,
  96      \fBint *\fR\fIerror\fR);
  97 .fi
  98
  99 .LP
 100 .nf
 101 \fBchar *\fR\fIsip_uri_errflags_to_str\fR(\fBint\fR \fIuri_errflags\fR);
 102 .fi
 103
 104 .SH DESCRIPTION
 105 .sp
 106 .LP
 107 For functions that return a pointer of type \fIsip_str_t\fR, \fIsip_str_t\fR is
 108 supplied by:
 109 .sp
 110 .in +2
 111 .nf
 112 typedef struct sip_str {
 113      char *sip_str_ptr;
 114      int  sip_str_len;
 115 }sip_str_t;
 116 .fi
 117 .in -2
 118
 119 .sp
 120 .LP
 121 The \fIsip_str_ptr\fR parameter points to the start of the returned value and
 122 \fIsip_str_len\fR supplies the length of the returned value.
 123 .sp
 124 .LP
 125 For example, given the following request line in a \fBSIP\fR message input to
 126 \fBsip_get_request_uri_str()\fR:
 127 .sp
 128 .in +2
 129 .nf
 130 INVITE sip:marconi@radio.org SIP/2.0
 131 .fi
 132 .in -2
 133
 134 .sp
 135 .LP
 136 the return is a pointer to \fIsip_str_t\fR with the \fIsip_str_ptr\fR member
 137 pointing to "\fBs\fR" of \fBsip:marconi@radio.org\fR and \fIsip_str_len\fR
 138 being set to \fB21\fR, the length of \fBsip:marconi@radio.org\fR.
 139 .sp
 140 .LP
 141 The \fBsip_is_sip_uri()\fR function takes a parsed \fBURI\fR \fIsip_uri\fR and
 142 returns \fBB_TRUE\fR if it is a \fBSIP[S]\fR \fBURI\fR and \fBB_FALSE\fR if it
 143 is not. A \fBURI\fR is a \fBSIP[S]\fR \fBURI\fR if the scheme in the \fBURI\fR
 144 is either "\fBsip\fR" or "\fBsips\fR".
 145 .sp
 146 .LP
 147 The \fBsip_get_uri_user()\fR function takes a parsed \fBURI\fR \fIsip_uri\fR
 148 and returns the value of the "\fBuser\fR" component, if present.
 149 .sp
 150 .LP
 151 The \fBsip_get_uri_password()\fR function takes a parsed \fBURI\fR
 152 \fIsip_uri\fR and returns the value of the "\fBpassword\fR" component, if
 153 present.
 154 .sp
 155 .LP
 156 The \fBsip_get_uri_host()\fR function takes a parsed \fBURI\fR \fIsip_uri\fR
 157 and returns the value of the "\fBhost\fR" component, if present.
 158 .sp
 159 .LP
 160 The \fBsip_get_uri_port()\fR function takes a parsed \fBURI\fR \fIsip_uri\fR
 161 and returns the value of the "\fBport\fR" component, if present.
 162 .sp
 163 .LP
 164 The \fBsip_get_uri_params()\fR function takes a parsed \fBURI\fR \fIsip_uri\fR
 165 and returns the list of \fBURI\fR parameters, if present, from a \fBSIP[S]\fR
 166 \fBURI\fR.
 167 .sp
 168 .LP
 169 The \fBsip_get_uri_headers()\fR function takes a parsed \fBURI\fR \fIsip_uri\fR
 170 and returns '\fBheaders\fR' from a \fBSIP[S]\fR \fBURI\fR.
 171 .sp
 172 .LP
 173 The \fBsip_get_uri_query()\fR function takes a parsed \fBURI\fR \fIsip_uri\fR
 174 and returns the value of the '\fBquery\fR' component, if present.
 175 .sp
 176 .LP
 177 The \fBsip_get_uri_path()\fR function takes a parsed \fBURI\fR \fIsip_uri\fR
 178 and returns the value of the '\fBpath\fR' component, if present.
 179 .sp
 180 .LP
 181 The \fBsip_get_uri_regname()\fR function takes a parsed \fBURI\fR \fIsip_uri\fR
 182 and returns the value of the '\fBregname\fR' component, if present.
 183 .sp
 184 .LP
 185 The \fBsip_is_uri_teluser()\fR function returns \fBB_TRUE\fR if the user
 186 component is a telephone-subscriber. Otherwise, \fBB_FALSE\fR is returned.
 187 .sp
 188 .LP
 189 The \fBsip_get_uri_errflags()\fR function returns the error flags from a parsed
 190 \fBURI\fR \fIsip_uri\fR. The returned value is a bitmask with the appropriate
 191 bit set when the parser, \fBsip_parse_uri()\fR, encounters an error. The
 192 following are the possible error values that could be set:
 193 .sp
 194 .in +2
 195 .nf
 196 Bit value      Error                 Comments
 197 _______________________________________________________________
 198 0x00000001     SIP_URIERR_SCHEME     invalid scheme
 199 0x00000002     SIP_URIERR_USER       invalid user name
 200 0x00000004     SIP_URIERR_PASS       invalid password
 201 0x00000008     SIP_URIERR_HOST       invalid host
 202 0x00000010     SIP_URIERR_PORT       invalid port number
 203 0x00000020     SIP_URIERR_PARAM      invalid URI parameters
 204 0x00000040     SIP_URIERR_HEADER     invalid URI headers
 205 0x00000080     SIP_URIERR_OPAQUE     invalid opaque
 206 0x00000100     SIP_URIERR_QUERY      invalid query
 207 0x00000200     SIP_URIERR_PATH       invalid path
 208 0x00000400     SIP_URIERR_REGNAME    invalid reg-name
 209 .fi
 210 .in -2
 211
 212 .sp
 213 .LP
 214 The \fBsip_uri_errflags_to_str()\fR function takes the error flags from a
 215 parsed \fBURI\fR \fIsip_uri\fR and forms a string with all the error bits that
 216 are set. For example, if \fBSIP_URIERR_PASS\fR and \fBSIP_URIERR_PORT\fR are
 217 set in a parsed \fBURI\fR \fIsip_uri\fR, the \fBsip_uri_errflags_to_str()\fR
 218 function returns a string such as:
 219 .sp
 220 .in +2
 221 .nf
 222 "Error(s) in PASSWORD, PORT part(s)"
 223 .fi
 224 .in -2
 225
 226 .sp
 227 .LP
 228 The caller is responsible for freeing the returned string.
 229 .SH RETURN VALUES
 230 .sp
 231 .LP
 232 The \fBsip_get_uri_scheme()\fR, \fBsip_get_uri_user()\fR,
 233 \fBsip_get_uri_password()\fR, \fBsip_get_uri_host()\fR,
 234 \fBsip_get_uri_params()\fR, \fBsip_get_uri_headers()\fR,
 235 \fBsip_get_uri_opaque()\fR, \fBsip_get_uri_query()\fR,
 236 \fBsip_get_uri_path()\fR, \fBsip_get_uri_regname()\fR, and
 237 \fBsip_uri_errflags_to_str()\fR functions return the requested value on success
 238 and \fBNULL\fR on failure.
 239 .sp
 240 .LP
 241 The \fBsip_get_uri_port()\fR function returns \fIport\fR from the \fBURI\fR or
 242 \fB0\fR if the port is not present. The returned port is in host byte order.
 243 .sp
 244 .LP
 245 The value of \fBerrno\fR is not changed by these calls in the event of an
 246 error.
 247 .SH ERRORS
 248 .sp
 249 .LP
 250 If the error is non-null, the following value is set:
 251 .sp
 252 .ne 2
 253 .na
 254 \fB\fBEINVAL\fR\fR
 255 .ad
 256 .RS 10n
 257 The \fBSIP\fR header value of the \fBSIP\fR message is \fBNULL\fR or there is
 258 no \fBURI\fR.
 259 .sp
 260 The input \fBURI\fR is null or the requested \fBURI\fR component is invalid.
 261 The error flag is set for the requested component.
 262 .sp
 263 The \fBURI\fR parameters or headers are requested from a non-\fBSIP[S]\fR
 264 \fBURI\fR; or the '\fBopaque\fR', '\fBquery\fR', '\fBpath\fR', '\fBreg-name\fR'
 265 components are requested from a \fBSIP[S]\fR \fBURI\fR.
 266 .RE
 267
 268 .sp
 269 .LP
 270 On success, the value of the location pointed to by \fIerror\fR is set to
 271 \fB0\fR.
 272 .SH ATTRIBUTES
 273 .sp
 274 .LP
 275 See \fBattributes\fR(5) for descriptions of the following attributes:
 276 .sp
 277
 278 .sp
 279 .TS
 280 box;
 281 c | c
 282 l | l .
 283 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 284 _
 285 Interface Stability     Committed
 286 _
 287 MT-Level        MT-Safe
 288 .TE
 289
 290 .SH SEE ALSO
 291 .sp
 292 .LP
 293 \fBlibsip\fR(3LIB)