share/man/man3sip/sip_create_dialog_req.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_CREATE_DIALOG_REQ 3SIP "Aug 6, 2007"
   7 .SH NAME
   8 sip_create_dialog_req, sip_create_dialog_req_nocontact \- create an in-dialog
   9 request
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 \fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lsip\fR [ \fIlibrary\fR ... ]
  14 #include <sip.h>
  15
  16 \fBsip_msg_t\fR \fBsip_create_dialog_req\fR(\fBsip_method_t\fR \fImethod\fR,
  17      \fBsip_dialog_t\fR \fIdialog\fR, \fBchar *\fR\fItransport\fR, \fBchar *\fR\fIsent_by\fR,
  18      \fBint\fR \fIsent_by_port\fR, \fBchar *\fR\fIvia_param\fR, \fBuint32_t\fR \fIsmaxforward\fR,
  19      \fBint\fR \fIcseq\fR);
  20 .fi
  21
  22 .LP
  23 .nf
  24 \fBsip_msg_t\fR \fBsip_create_dialog_req_nocontact\fR(\fBsip_method_t\fR \fImethod\fR,
  25      \fBsip_dialog_t\fR \fIdialog\fR, \fBchar *\fR\fItransport\fR, \fBchar *\fR\fIsent_by\fR,
  26      \fBint\fR \fIsent_by_port\fR, \fBchar *\fR\fIvia_param\fR, \fBuint32_t\fR \fIsmaxforward\fR,
  27      \fBint\fR \fIcseq\fR);
  28 .fi
  29
  30 .SH DESCRIPTION
  31 .sp
  32 .LP
  33 The \fBsip_create_dialog_req()\fR function creates and returns a \fBSIP\fR
  34 request with the state information contained in \fIdialog\fR. The method in the
  35 resulting request is from \fImethod\fR. The method can be one of the following:
  36 .br
  37 .in +2
  38 \fBINVITE\fR
  39 .in -2
  40 .br
  41 .in +2
  42 \fBACK\fR
  43 .in -2
  44 .br
  45 .in +2
  46 \fBOPTIONS\fR
  47 .in -2
  48 .br
  49 .in +2
  50 \fBBYE\fR
  51 .in -2
  52 .br
  53 .in +2
  54 \fBCANCEL\fR
  55 .in -2
  56 .br
  57 .in +2
  58 \fBREGISTER\fR
  59 .in -2
  60 .br
  61 .in +2
  62 \fBREFER\fR
  63 .in -2
  64 .br
  65 .in +2
  66 \fBINFO\fR
  67 .in -2
  68 .br
  69 .in +2
  70 \fBSUBSCRIBE\fR
  71 .in -2
  72 .br
  73 .in +2
  74 \fBNOTIFY\fR
  75 .in -2
  76 .br
  77 .in +2
  78 \fBPRACK\fR
  79 .in -2
  80 .sp
  81 .LP
  82 The resulting request line in the \fBSIP\fR message has the \fBSIP\fR-Version
  83 of "2.0". The \fBURI\fR in the request line is from the remote target in the
  84 \fIdialog\fR or from the route set in the \fIdialog\fR, if present. See RFC
  85 3261 (section 12.2) for details. The \fBFROM\fR, \fBTO\fR, and \fBCALL-ID\fR
  86 headers are added from the \fIdialog\fR. The \fBMAX-FORWARDS\fR header is added
  87 using the value in \fImaxforward\fR. The \fBCSEQ\fR header is added using the
  88 \fBSIP\fR method in \fImethod\fR and the sequence number value in \fIcseq\fR.
  89 If \fIcseq\fR is \fB-1\fR, the sequence number is obtained from the local
  90 sequence number in the \fIdialog\fR. The local sequence number in the
  91 \fIdialog\fR is incremented and is used in the \fBCSEQ\fR header. The \fBVIA\fR
  92 header added is created using the \fItransport\fR, \fIsent_by\fR,
  93 \fIsent_by_port\fR (if \fInon-zero\fR), and \fIvia_param\fR (if any). If
  94 \fIdialog\fR has a non-empty route set, the resulting \fBSIP\fR request has the
  95 route set from the \fIdialog\fR.
  96 .sp
  97 .LP
  98 The \fBsip_create_dialog_req_nocontact()\fR function is similar to
  99 \fBsip_create_dialog_req()\fR, except that it does not add the contact header.
 100 .SH RETURN VALUES
 101 .sp
 102 .LP
 103 The \fBsip_create_dialog_req()\fR and \fBsip_create_dialog_req_nocontact()\fR
 104 functions return the resulting \fBSIP\fR message on success and \fBNULL\fR on
 105 failure.
 106 .sp
 107 .LP
 108 The value of \fBerrno\fR is not changed by these calls in the event of an
 109 error.
 110 .SH ATTRIBUTES
 111 .sp
 112 .LP
 113 See \fBattributes\fR(5) for descriptions of the following attributes:
 114 .sp
 115
 116 .sp
 117 .TS
 118 box;
 119 c | c
 120 l | l .
 121 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 122 _
 123 Interface Stability     Committed
 124 _
 125 MT-Level        MT-Safe
 126 .TE
 127
 128 .SH SEE ALSO
 129 .sp
 130 .LP
 131 \fBlibsip\fR(3LIB), \fBattributes\fR(5)