/usr/include/pjsip-ua/sip_100rel.h is in libpjproject-dev 2.1.0.0.ast20130823-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 | /* $Id: sip_100rel.h 3553 2011-05-05 06:14:19Z nanang $ */
/*
* Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com)
* Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org>
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*/
#ifndef __SIP_100REL_H__
#define __SIP_100REL_H__
/**
* @file sip_100rel.h
* @brief PRACK (Reliability of Provisional Responses)
*/
#include <pjsip-ua/sip_inv.h>
/**
* @defgroup PJSIP_100REL 100rel/PRACK - Reliability of Provisional Responses
* @ingroup PJSIP_HIGH_UA
* @brief PRACK - Reliability of Provisional Responses
* @{
*
* This module provides management of Reliability of Provisional Responses
* (\a 100rel and \a PRACK), as described in RFC 3262.
*
* Other than the #pjsip_100rel_init_module() function, the 100rel API
* exported by this module are not intended to be used by application, but
* rather they will be invoked by the \ref PJSIP_INV.
*
* \section pjsip_100rel_using Using Reliable Provisional Response
*
* \subsection pjsip_100rel_init Initializing 100rel Module
*
* Application must explicitly initialize 100rel module by calling
* #pjsip_100rel_init_module() in application initialization function.
*
* Once the 100rel module is initialized, it will register \a PRACK method
* in \a Allow header, and \a 100rel tag in \a Supported header.
*
* \subsection pjsip_100rel_sess Using 100rel in a Session
*
* For UAC, \a 100rel support will be enabled in the session if \a 100rel
* support is enabled in the library (default is yes).
* Outgoing INVITE request will include \a 100rel tag in \a Supported
* header and \a PRACK method in \a Allow header. When callee endpoint
* sends reliable provisional responses, the UAC will automatically send
* \a PRACK request to acknowledge the response. If callee endpoint doesn't
* send reliable provisional response, the response will be handled using
* normal, non-100rel procedure (that is, \a PRACK will not be sent).
*
* If the UAC wants to <b>mandate</b> \a 100rel support, it can specify
* #PJSIP_INV_REQUIRE_100REL in the \a options argument when calling
* #pjsip_inv_create_uac(). In this case, PJSIP will add \a 100rel tag
* in the \a Require header of the outgoing INVITE request.
*
* For UAS, if it wants to support \a 100rel but not to mandate it,
* it must specify #PJSIP_INV_SUPPORT_100REL flag in the \a options
* argument when calling #pjsip_inv_verify_request(), and pass the same
* \a options variable when calling #pjsip_inv_verify_request. If UAC had
* specified \a 100rel in it's list of extensions in \a Require header,
* the UAS will send provisional responses reliably. If UAC only listed
* \a 100rel in its \a Supported header but not in \a Require header,
* or if UAC does not list \a 100rel support at all, the UAS WILL NOT
* send provisional responses reliably.
* The snippet below can be used to accomplish this task:
*
* \verbatim
unsigned options = 0;
options |= PJSIP_INV_SUPPORT_100REL;
status = pjsip_inv_verify_request(rdata, &options, answer, NULL,
endpt, &resp);
if (status != PJ_SUCCESS) {
// INVITE request cannot be handled.
// Reject the request with the response in resp.
...
return;
}
// Create UAS dialog, populate Contact header, etc.
...
// Create UAS invite session
status = pjsip_inv_create_uas( dlg, rdata, answer, options, &inv);
..
\endverbatim
*
* For another requirement, if UAS wants to <b>mandate</b> \a 100rel support,
* it can specify #PJSIP_INV_REQUIRE_100REL flag when calling
* #pjsip_inv_verify_request(), and pass the \a options when calling
* #pjsip_inv_verify_request. In this case,
* \a 100rel extension will be used if UAC specifies \a 100rel in its
* \a Supported header. If UAC does not list \a 100rel in \a Supported header,
* the incoming INVITE request will be rejected with 421 (Extension Required)
* response. For the sample code, it should be identical to the snippet
* above, except that application must specify #PJSIP_INV_REQUIRE_100REL
* flag in the \a options instead of #PJSIP_INV_SUPPORT_100REL.
*
* For yet another requirement, if UAS <b>does not</b> want to support
* \a 100rel extension, it can reject incoming INVITE request with
* 420 (Bad Extension) response whenever incoming INVITE request has
* \a 100rel tag in its \a Require header. This can be done by specifying
* zero as the \a options when calling #pjsip_inv_verify_request().
*/
PJ_BEGIN_DECL
/**
* PRACK method constant.
* @see pjsip_get_prack_method()
*/
PJ_DECL_DATA(const pjsip_method) pjsip_prack_method;
/**
* Get #pjsip_invite_method constant.
*/
PJ_DECL(const pjsip_method*) pjsip_get_prack_method(void);
/**
* Initialize 100rel module. This function must be called once during
* application initialization, to register 100rel module to SIP endpoint.
*
* @param endpt The SIP endpoint instance.
*
* @return PJ_SUCCESS if module is successfully initialized.
*/
PJ_DECL(pj_status_t) pjsip_100rel_init_module(pjsip_endpoint *endpt);
/**
* Add 100rel support to the specified invite session. This function will
* be called internally by the invite session if it detects that the
* session needs 100rel support.
*
* @param inv The invite session.
*
* @return PJ_SUCCESS on successful.
*/
PJ_DECL(pj_status_t) pjsip_100rel_attach(pjsip_inv_session *inv);
/**
* Check if incoming response has reliable provisional response feature.
*
* @param rdata Receive data buffer containing the response.
*
* @return PJ_TRUE if the provisional response is reliable.
*/
PJ_DECL(pj_bool_t) pjsip_100rel_is_reliable(pjsip_rx_data *rdata);
/**
* Create PRACK request for the incoming reliable provisional response.
* Note that PRACK request MUST be sent using #pjsip_100rel_send_prack().
*
* @param inv The invite session.
* @param rdata The incoming reliable provisional response.
* @param p_tdata Upon return, it will be initialized with the
* PRACK request.
*
* @return PJ_SUCCESS on successful.
*/
PJ_DECL(pj_status_t) pjsip_100rel_create_prack(pjsip_inv_session *inv,
pjsip_rx_data *rdata,
pjsip_tx_data **p_tdata);
/**
* Send PRACK request.
*
* @param inv The invite session.
* @param tdata The PRACK request.
*
* @return PJ_SUCCESS on successful.
*/
PJ_DECL(pj_status_t) pjsip_100rel_send_prack(pjsip_inv_session *inv,
pjsip_tx_data *tdata);
/**
* Handle incoming PRACK request.
*
* @param inv The invite session.
* @param rdata Incoming PRACK request.
*
* @return PJ_SUCCESS on successful.
*/
PJ_DECL(pj_status_t) pjsip_100rel_on_rx_prack(pjsip_inv_session *inv,
pjsip_rx_data *rdata);
/**
* Transmit INVITE response (provisional or final) reliably according to
* 100rel specification. The 100rel module will take care of retransmitting
* or enqueueing the response according to the current state of the
* reliable response processing. This function will be called internally
* by invite session.
*
* @param inv The invite session.
* @param tdata The INVITE response.
*
* @return PJ_SUCCESS on successful.
*/
PJ_DECL(pj_status_t) pjsip_100rel_tx_response(pjsip_inv_session *inv,
pjsip_tx_data *tdata);
/**
* Notify 100rel module that the invite session has been disconnected.
*
* @param inv The invite session.
*
* @return PJ_SUCCESS on successful.
*/
PJ_DECL(pj_status_t) pjsip_100rel_end_session(pjsip_inv_session *inv);
PJ_END_DECL
/**
* @}
*/
#endif /* __SIP_100REL_H__ */
|