share/man/man3sip/sip_enable_trans_logging.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_ENABLE_TRANS_LOGGING 3SIP "April 9, 2016"
   7 .SH NAME
   8 sip_enable_trans_logging, sip_enable_dialog_logging,
   9 sip_disable_dialog_logging, sip_disable_trans_logging \- transaction and dialog
  10 logging operations
  11 .SH SYNOPSIS
  12 .LP
  13 .nf
  14 \fBcc\fR [ \fIflag\fR... ] \fIfile\fR... -\fBlsip\fR [ \fIlibrary\fR... ]
  15 #include <sip.h>
  16
  17 \fBint\fR \fBsip_enable_trans_logging\fR(\fBFILE *\fR\fIlogfile\fR, \fBint\fR \fIflags\fR);
  18 .fi
  19
  20 .LP
  21 .nf
  22 \fBint\fR \fBsip_enable_dialog_logging\fR(\fBFILE *\fR\fIlogfile\fR, \fBint\fR \fIflags\fR);
  23 .fi
  24
  25 .LP
  26 .nf
  27 \fBvoid\fR \fBsip_disable_dialog_logging\fR();
  28 .fi
  29
  30 .LP
  31 .nf
  32 \fBvoid\fR \fBsip_disable_trans_logging\fR();
  33 .fi
  34
  35 .SH DESCRIPTION
  36 .LP
  37 The \fBsip_enable_trans_logging()\fR and \fBsip_enable_dialog_logging()\fR
  38 functions enable transaction and dialog logging respectively. The \fIlogfile\fR
  39 argument points to a file to which the SIP messages are logged. The flags
  40 argument controls the amount of logging. The only flag defined in \fB<sip.h>\fR
  41 is \fBSIP_DETAIL_LOGGING\fR. Either transaction or dialog logging, or both, can
  42 be enabled at any time. For dialog logging to work, the SIP stack must be
  43 enabled to manage dialogs (using \fBSIP_STACK_DIALOGS\fR, see
  44 \fBsip_stack_init\fR(3SIP)) when the stack is initialized.
  45 .sp
  46 .LP
  47 All the messages exchanged within a transaction/dialog is captured and later
  48 dumped to a log file when the transaction or dialog is deleted or terminated.
  49 Upon termination, each dialog writes to the file the messages that were
  50 processed in its context. Similarly, upon termination each transaction writes
  51 to the file the messages that were processed in its context.
  52 .sp
  53 .LP
  54 The \fBsip_disable_trans_logging()\fR and \fBsip_disable_dialog_logging()\fR
  55 functions disable the transaction or dialog logging. These functions do not
  56 close the files. It is the responsibility of the application to close them.
  57 .sp
  58 .LP
  59 The log contains the state of the transaction or dialog at the time the message
  60 was processed.
  61 .SH RETURN VALUES
  62 .LP
  63 Upon successful completion, \fBsip_enable_trans_logging()\fR and
  64 \fBsip_enable_dialog_logging()\fR return 0. They return \fBEINVAL\fR if
  65 \fIlogfile\fR is \fINULL\fR or \fIflags\fR is unrecognized.
  66 .SH EXAMPLES
  67 .LP
  68 \fBExample 1 \fRDialog logging
  69 .sp
  70 .LP
  71 The following is an example of dialog logging.
  72
  73 .sp
  74 .in +2
  75 .nf
  76 FILE    *logfile;
  77
  78 logfile = fopen("/tmp/ApplicationA", "a+");
  79 sip_enable_dialog_logging(logfile, SIP_DETAIL_LOGGING);
  80
  81 /* Application sends INVITE, receives 180 and 200 response and dialog is
  82         created. */
  83 /* Application sends ACK request */
  84 /* Application sends BYE and receives 200 response */
  85
  86 /* Application disables logging */
  87 sip_disable_dialog_logging();
  88
  89 The log file will be of the following format.
  90
  91
  92 ************* Begin Dialog *************
  93 Digest       : 43854 43825 26120 9475 5415 21595 25658 18538
  94
  95 -----------------------------
  96 Dialog State            : SIP_DLG_NEW
  97
  98 Tue Nov 27 15:53:34 2007| Message - 1
  99 INVITE sip:user@example.com SIP/2.0
 100 From: "Me" < sip:me@mydomain.com > ; TAG=tag-from-01
 101 To: "You" < sip:you@yourdomain.com >
 102 Contact: < sip:myhome.host.com >
 103 MAX-FORWARDS: 70
 104 Call-ID: 1261K6A6492KF33549XM
 105 CSeq: 111 INVITE
 106 CONTENT-TYPE: application/sdp
 107 Via: SIP/2.0/UDP 192.0.0.1 : 5060 ;branch=z9hG4bK-via-EVERYTHINGIDO-05
 108 Record-Route: <sip:server1.com;lr>
 109 Record-Route: <sip:server2.com;lr>
 110 CONTENT-LENGTH : 0
 111
 112 Tue Nov 27 15:53:34 2007| Message - 2
 113 SIP/2.0 180 Ringing
 114 Via: SIP/2.0/UDP 192.0.0.1 : 5060 ;branch=z9hG4bK-via-EVERYTHINGIDO-05
 115 From: "Me" < sip:me@mydomain.com > ; TAG=tag-from-01
 116 To: "You" < sip:you@yourdomain.com >;tag=1
 117 Call-ID: 1261K6A6492KF33549XM
 118 CSeq: 111 INVITE
 119 Contact: <sip:whitestar2-0.East.Sun.COM:5060;transport=UDP>
 120 Record-Route: <sip:server1.com;lr>
 121 Record-Route: <sip:server2.com;lr>
 122 Content-Length: 0
 123
 124 -----------------------------
 125 Dialog State            : SIP_DLG_EARLY
 126
 127 /* Entire 200 OK SIP Response */
 128
 129 -----------------------------
 130 Dialog State            : SIP_DLG_CONFIRMED
 131
 132 /* Entire ACK Request */
 133
 134 /* Entire BYE Request */
 135 /* Entire 200 OK Response */
 136 -----------------------------
 137 ************* End Dialog *************
 138 .fi
 139 .in -2
 140
 141 .SH ATTRIBUTES
 142 .LP
 143 See \fBattributes\fR(5) for descriptions of the following attributes:
 144 .sp
 145
 146 .sp
 147 .TS
 148 box;
 149 c | c
 150 l | l .
 151 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 152 _
 153 Interface Stability     Committed
 154 _
 155 MT-Level        MT-Safe
 156 .TE
 157
 158 .SH SEE ALSO
 159 .LP
 160 \fBsip_stack_init\fR(3SIP), \fBattributes\fR(5)