share/man/man3sip/sip_get_dialog_state.3sip

   1 '\" te
   2 .\"  Copyright (c) 2008, 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_GET_DIALOG_STATE 3SIP "Jan 11, 2008"
   7 .SH NAME
   8 sip_get_dialog_state, sip_get_dialog_callid, sip_get_dialog_local_tag,
   9 sip_get_dialog_remote_tag, sip_get_dialog_local_uri, sip_get_dialog_remote_uri,
  10 sip_get_dialog_local_contact_uri, sip_get_dialog_remote_target_uri,
  11 sip_get_dialog_route_set, sip_get_dialog_local_cseq,
  12 sip_get_dialog_remote_cseq, sip_get_dialog_type, sip_get_dialog_method,
  13 sip_is_dialog_secure, sip_get_dialog_msgcnt \- get dialog attributes
  14 .SH SYNOPSIS
  15 .LP
  16 .nf
  17 \fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lsip\fR [ \fIlibrary\fR ... ]
  18 #include <sip.h>
  19
  20 \fBint\fR \fBsip_get_dialog_state\fR(\fBsip_dialog_t\fR \fIdialog\fR, \fBint *\fR\fIerror\fR);
  21 .fi
  22
  23 .LP
  24 .nf
  25 \fBconst sip_str_t *\fR\fIsip_get_dialog_callid\fR(\fBsip_dialog_t\fR \fIdialog\fR,
  26      \fBint *\fR\fIerror\fR);
  27 .fi
  28
  29 .LP
  30 .nf
  31 \fBconst sip_str_t *\fR\fBsip_get_dialog_local_tag\fR(\fBsip_dialog_t\fR \fIdialog\fR,
  32      \fBint *\fR\fIerror\fR);
  33 .fi
  34
  35 .LP
  36 .nf
  37 \fBconst sip_str_t *\fR\fBsip_get_dialog_remote_tag\fR(\fBsip_dialog_t\fR \fIdialog\fR,
  38      \fBint *\fR\fIerror\fR);
  39 .fi
  40
  41 .LP
  42 .nf
  43 \fBconst struct sip_uri *\fR\fBsip_get_dialog_local_uri\fR(\fBsip_dialog_t\fR \fIdialog\fR,
  44      \fBint *\fR\fIerror\fR);
  45 .fi
  46
  47 .LP
  48 .nf
  49 \fBconst struct sip_uri *\fR\fBsip_get_dialog_remote_uri\fR(\fBsip_dialog_t\fR \fIdialog\fR,
  50      \fBint *\fR\fIerror\fR);
  51 .fi
  52
  53 .LP
  54 .nf
  55 \fBconst struct sip_uri *\fR\fBsip_get_dialog_local_contact_uri\fR(
  56      \fBsip_dialog_t\fR \fIdialog\fR, \fBint *\fR\fIerror\fR);
  57 .fi
  58
  59 .LP
  60 .nf
  61 \fBconst struct sip_uri *\fR\fBsip_get_dialog_remote_target_uri\fR(
  62      \fBsip_dialog_t\fR \fIdialog\fR, \fBint *\fR\fIerror\fR);
  63 .fi
  64
  65 .LP
  66 .nf
  67 \fBconst sip_str_t *\fR\fBsip_get_dialog_route_set\fR(\fBsip_dialog_t\fR \fIdialog\fR,
  68      \fBint *\fR\fIerror\fR);
  69 .fi
  70
  71 .LP
  72 .nf
  73 \fBboolean_t\fR \fBsip_is_dialog_secure\fR(\fBsip_dialog_t\fR \fIdialog\fR,
  74      \fBint *\fR\fIerror\fR);
  75 .fi
  76
  77 .LP
  78 .nf
  79 \fBuint32_t\fR \fBsip_get_dialog_local_cseq\fR(\fBsip_dialog_t\fR \fIdialog\fR,
  80      \fBint *\fR\fIerror\fR);
  81 .fi
  82
  83 .LP
  84 .nf
  85 \fBuint32_t\fR \fBsip_get_dialog_remote_cseq\fR(\fBsip_dialog_t\fR \fIdialog\fR,
  86      \fBint *\fR\fIerror\fR);
  87 .fi
  88
  89 .LP
  90 .nf
  91 \fBint\fR \fBsip_get_dialog_type\fR(\fBsip_dialog_t\fR \fIdialog\fR,\fBint *\fR\fIerror\fR);
  92 .fi
  93
  94 .LP
  95 .nf
  96 \fBint\fR \fBsip_get_dialog_method\fR(\fBsip_dialog_t\fR \fIdialog\fR,\fBint *\fR\fIerror\fR);
  97 .fi
  98
  99 .LP
 100 .nf
 101 \fBint\fR \fBsip_get_dialog_msgcnt\fR(\fBsip_dialog_t\fR \fIdialog\fR,\fBint *\fR\fIerror\fR);
 102 .fi
 103
 104 .SH DESCRIPTION
 105 .sp
 106 .LP
 107 For functions that return a pointer of type \fBsip_str_t\fR, \fBsip_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 The \fBsip_get_dialog_state()\fR returns the state of the \fIdialog\fR. A
 126 \fIdialog\fR can be in one of the following states:
 127 .br
 128 .in +2
 129 \fBSIP_DLG_NEW\fR
 130 .in -2
 131 .br
 132 .in +2
 133 \fBSIP_DLG_EARLY\fR
 134 .in -2
 135 .br
 136 .in +2
 137 \fBSIP_DLG_CONFIRMED\fR
 138 .in -2
 139 .br
 140 .in +2
 141 \fBSIP_DLG_DESTROYED\fR
 142 .in -2
 143 .sp
 144 .LP
 145 The \fBsip_get_dialog_callid()\fR function returns the call ID value maintained
 146 in the \fIdialog\fR.
 147 .sp
 148 .LP
 149 The \fBsip_get_dialog_local_tag()\fR and \fBsip_get_dialog_remote_tag()\fR
 150 functions return the local and remote tag values, maintained in the
 151 \fIdialog\fR.
 152 .sp
 153 .LP
 154 The \fBsip_get_dialog_local_uri()\fR, \fBsip_get_dialog_remote_uri()\fR,
 155 \fBsip_get_dialog_local_contact_uri()\fR, and
 156 \fBsip_get_dialog_remote_target_uri()\fR functions return the local, remote,
 157 local contract, and the remote target \fBURI\fRs, maintained in the
 158 \fIdialog\fR.
 159 .sp
 160 .LP
 161 The \fBsip_get_dialog_route_set()\fR function returns the route set, if any,
 162 maintained in the \fIdialog\fR.
 163 .sp
 164 .LP
 165 The \fBsip_get_dialog_local_cseq()\fR and \fBsip_get_dialog_remote_cseq()\fR
 166 functions return the local and remote \fBCSEQ\fR numbers maintained in the
 167 \fIdialog\fR.
 168 .sp
 169 .LP
 170 The \fBsip_get_dialog_type()\fR function returns one of the following dialog
 171 types, depending on whether it is created by the client or the server.
 172 .sp
 173 .ne 2
 174 .na
 175 \fB\fBSIP_UAC_DIALOG\fR\fR
 176 .ad
 177 .RS 18n
 178 created by client
 179 .RE
 180
 181 .sp
 182 .ne 2
 183 .na
 184 \fB\fBSIP_UAS_DIALOG\fR\fR
 185 .ad
 186 .RS 18n
 187 created by server
 188 .RE
 189
 190 .sp
 191 .LP
 192 The \fBsip_get_dialog_method()\fR function returns the \fBSIP\fR method,
 193 \fBINVITE\fR or \fBSUBSCRIBE\fR, of the request that created the dialog.
 194 .sp
 195 .LP
 196 The \fBsip_is_dialog_secure()\fR function returns \fBB_TRUE\fR if the
 197 \fIdialog\fR is secure and \fBB_FALSE\fR otherwise.
 198 .sp
 199 .LP
 200 The \fBsip_get_dialog_msgcnt()\fR function returns the number of SIP messages
 201 (requests and responses) that were sent and received within the context of the
 202 given dialog.
 203 .SH RETURN VALUES
 204 .sp
 205 .LP
 206 The \fBsip_get_dialog_state()\fR, \fBsip_get_dialog_local_cseq()\fR,
 207 \fBsip_get_dialog_remote_cseq()\fR, \fBsip_get_dialog_type()\fR,
 208 \fBsip_get_dialog_method()\fR, and \fBsip_get_dialog_msgcnt()\fR functions
 209 return the required value on success and \fB-1\fR on failure.
 210 .sp
 211 .LP
 212 The \fBsip_get_dialog_callid()\fR, \fBsip_get_dialog_local_tag()\fR,
 213 \fBsip_get_dialog_remote_tag()\fR, \fBsip_get_dialog_local_uri()\fR,
 214 \fBsip_get_dialog_remote_uri()\fR, \fBsip_get_dialog_local_contact_uri()\fR,
 215 \fBsip_get_dialog_remote_target_uri()\fR, and \fBsip_get_dialog_route_set()\fR
 216 functions return the required value on success and \fBNULL\fR on failure.
 217 .sp
 218 .LP
 219 The value of \fBerrno\fR is not changed by these calls in the event of an
 220 error.
 221 .SH ERRORS
 222 .sp
 223 .LP
 224 These functions take an \fIerror\fR argument.
 225 .sp
 226 .LP
 227 If the error is non-null, one of the following values is set:
 228 .sp
 229 .ne 2
 230 .na
 231 \fB\fBEINVAL\fR\fR
 232 .ad
 233 .sp .6
 234 .RS 4n
 235 The \fIdialog\fR is \fBNULL\fR or the stack is not configured to manage
 236 dialogs.
 237 .RE
 238
 239 .sp
 240 .ne 2
 241 .na
 242 \fB\fBENOTSUP\fR\fR
 243 .ad
 244 .sp .6
 245 .RS 4n
 246 The input \fBSIP\fR message cannot be modified.
 247 .RE
 248
 249 .sp
 250 .ne 2
 251 .na
 252 \fB\fBENOMEM\fR\fR
 253 .ad
 254 .sp .6
 255 .RS 4n
 256 The memory allocation fails when the request/response line or the headers in
 257 the \fBACK\fR request are created.
 258 .RE
 259
 260 .sp
 261 .LP
 262 On success, the value of the location pointed to by \fIerror\fR is set to
 263 \fB0\fR.
 264 .SH ATTRIBUTES
 265 .sp
 266 .LP
 267 See \fBattributes\fR(5) for descriptions of the following attributes:
 268 .sp
 269
 270 .sp
 271 .TS
 272 box;
 273 c | c
 274 l | l .
 275 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 276 _
 277 Interface Stability     Committed
 278 _
 279 MT-Level        MT-Safe
 280 .TE
 281
 282 .SH SEE ALSO
 283 .sp
 284 .LP
 285 \fBlibsip\fR(3LIB)