share/man/man3sip/sip_get_header.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_GET_HEADER 3SIP "Feb 09, 2007"
   7 .SH NAME
   8 sip_get_header \- get a SIP header from a message
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lsip\fR [ \fIlibrary\fR ... ]
  13 #include <sip.h>
  14
  15 \fBconst struct sip_header *\fR\fIsip_get_header\fR(\fBsip_msg_t\fR \fIsip_msg\fR,
  16      \fBchar *\fR\fIheader_name\fR, \fBsip_header_t\fR \fIold_header\fR, \fBint *\fR\fIerror\fR);
  17 .fi
  18
  19 .SH DESCRIPTION
  20 .sp
  21 .LP
  22 The \fBsip_get_header()\fR function returns the header specified by
  23 \fIheader_name\fR (long or compact form) from the \fBSIP\fR message
  24 \fIsip_msg\fR. If \fIheader_name\fR is \fBNULL\fR, the first header in the
  25 \fBSIP\fR message is returned. The \fBold_header\fR, if non-null, specifies the
  26 starting position in \fIsip_msg\fR from which the search is started. Otherwise,
  27 the search begins at the start of the \fBSIP\fR message. For example, to get
  28 the first \fBVIA\fR header from the \fBSIP\fR message \fIsip_msg\fR:
  29 .sp
  30 .in +2
  31 .nf
  32 via_hdr = sip_get_header(sip_msg, "VIA", NULL, &error);
  33 .fi
  34 .in -2
  35
  36 .sp
  37 .LP
  38 To get the next \fBVIA\fR header from \fIsip_msg\fR:
  39 .sp
  40 .in +2
  41 .nf
  42 via_hdr = sip_get_header(sip_msg, "VIA", via_hdr, &error);
  43 .fi
  44 .in -2
  45
  46 .sp
  47 .LP
  48 The \fBsip_get_header()\fR function ignores any header that is marked as
  49 deleted.
  50 .SH RETURN VALUES
  51 .sp
  52 .LP
  53 On success, the \fBsip_get_header()\fR function returns the queried header. On
  54 failure, it returns \fBNULL\fR.
  55 .sp
  56 .LP
  57 The value of \fBerrno\fR is not changed by these calls in the event of an
  58 error.
  59 .SH ERRORS
  60 .sp
  61 .LP
  62 The following value may be returned:
  63 .sp
  64 .ne 2
  65 .na
  66 \fB\fBEINVAL\fR\fR
  67 .ad
  68 .RS 10n
  69 The \fIheader_name\fR specified in the \fBSIP\fR message is not present or has
  70 been deleted; or, the \fIheader_name\fR is not specified and there are no
  71 "un-deleted" headers in the \fBSIP\fR message.
  72 .RE
  73
  74 .SH ATTRIBUTES
  75 .sp
  76 .LP
  77 See \fBattributes\fR(5) for descriptions of the following attributes:
  78 .sp
  79
  80 .sp
  81 .TS
  82 box;
  83 c | c
  84 l | l .
  85 ATTRIBUTE TYPE  ATTRIBUTE VALUE
  86 _
  87 Interface Stability     Committed
  88 _
  89 MT-Level        MT-Safe
  90 .TE
  91
  92 .SH SEE ALSO
  93 .sp
  94 .LP
  95 \fBlibsip\fR(3LIB)