1
/* $Id: sip_100rel.h 3553 2011-05-05 06:14:19Z nanang $ */
3
* Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com)
4
* Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org>
6
* This program is free software; you can redistribute it and/or modify
7
* it under the terms of the GNU General Public License as published by
8
* the Free Software Foundation; either version 2 of the License, or
9
* (at your option) any later version.
11
* This program is distributed in the hope that it will be useful,
12
* but WITHOUT ANY WARRANTY; without even the implied warranty of
13
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14
* GNU General Public License for more details.
16
* You should have received a copy of the GNU General Public License
17
* along with this program; if not, write to the Free Software
18
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
20
#ifndef __SIP_100REL_H__
21
#define __SIP_100REL_H__
25
* @brief PRACK (Reliability of Provisional Responses)
29
#include <pjsip-ua/sip_inv.h>
33
* @defgroup PJSIP_100REL 100rel/PRACK - Reliability of Provisional Responses
34
* @ingroup PJSIP_HIGH_UA
35
* @brief PRACK - Reliability of Provisional Responses
38
* This module provides management of Reliability of Provisional Responses
39
* (\a 100rel and \a PRACK), as described in RFC 3262.
41
* Other than the #pjsip_100rel_init_module() function, the 100rel API
42
* exported by this module are not intended to be used by application, but
43
* rather they will be invoked by the \ref PJSIP_INV.
45
* \section pjsip_100rel_using Using Reliable Provisional Response
47
* \subsection pjsip_100rel_init Initializing 100rel Module
49
* Application must explicitly initialize 100rel module by calling
50
* #pjsip_100rel_init_module() in application initialization function.
52
* Once the 100rel module is initialized, it will register \a PRACK method
53
* in \a Allow header, and \a 100rel tag in \a Supported header.
55
* \subsection pjsip_100rel_sess Using 100rel in a Session
57
* For UAC, \a 100rel support will be enabled in the session if \a 100rel
58
* support is enabled in the library (default is yes).
59
* Outgoing INVITE request will include \a 100rel tag in \a Supported
60
* header and \a PRACK method in \a Allow header. When callee endpoint
61
* sends reliable provisional responses, the UAC will automatically send
62
* \a PRACK request to acknowledge the response. If callee endpoint doesn't
63
* send reliable provisional response, the response will be handled using
64
* normal, non-100rel procedure (that is, \a PRACK will not be sent).
66
* If the UAC wants to <b>mandate</b> \a 100rel support, it can specify
67
* #PJSIP_INV_REQUIRE_100REL in the \a options argument when calling
68
* #pjsip_inv_create_uac(). In this case, PJSIP will add \a 100rel tag
69
* in the \a Require header of the outgoing INVITE request.
71
* For UAS, if it wants to support \a 100rel but not to mandate it,
72
* it must specify #PJSIP_INV_SUPPORT_100REL flag in the \a options
73
* argument when calling #pjsip_inv_verify_request(), and pass the same
74
* \a options variable when calling #pjsip_inv_verify_request. If UAC had
75
* specified \a 100rel in it's list of extensions in \a Require header,
76
* the UAS will send provisional responses reliably. If UAC only listed
77
* \a 100rel in its \a Supported header but not in \a Require header,
78
* or if UAC does not list \a 100rel support at all, the UAS WILL NOT
79
* send provisional responses reliably.
80
* The snippet below can be used to accomplish this task:
85
options |= PJSIP_INV_SUPPORT_100REL;
87
status = pjsip_inv_verify_request(rdata, &options, answer, NULL,
89
if (status != PJ_SUCCESS) {
90
// INVITE request cannot be handled.
91
// Reject the request with the response in resp.
96
// Create UAS dialog, populate Contact header, etc.
99
// Create UAS invite session
100
status = pjsip_inv_create_uas( dlg, rdata, answer, options, &inv);
106
* For another requirement, if UAS wants to <b>mandate</b> \a 100rel support,
107
* it can specify #PJSIP_INV_REQUIRE_100REL flag when calling
108
* #pjsip_inv_verify_request(), and pass the \a options when calling
109
* #pjsip_inv_verify_request. In this case,
110
* \a 100rel extension will be used if UAC specifies \a 100rel in its
111
* \a Supported header. If UAC does not list \a 100rel in \a Supported header,
112
* the incoming INVITE request will be rejected with 421 (Extension Required)
113
* response. For the sample code, it should be identical to the snippet
114
* above, except that application must specify #PJSIP_INV_REQUIRE_100REL
115
* flag in the \a options instead of #PJSIP_INV_SUPPORT_100REL.
117
* For yet another requirement, if UAS <b>does not</b> want to support
118
* \a 100rel extension, it can reject incoming INVITE request with
119
* 420 (Bad Extension) response whenever incoming INVITE request has
120
* \a 100rel tag in its \a Require header. This can be done by specifying
121
* zero as the \a options when calling #pjsip_inv_verify_request().
128
* PRACK method constant.
129
* @see pjsip_get_prack_method()
131
PJ_DECL_DATA(const pjsip_method) pjsip_prack_method;
135
* Get #pjsip_invite_method constant.
137
PJ_DECL(const pjsip_method*) pjsip_get_prack_method(void);
141
* Initialize 100rel module. This function must be called once during
142
* application initialization, to register 100rel module to SIP endpoint.
144
* @param endpt The SIP endpoint instance.
146
* @return PJ_SUCCESS if module is successfully initialized.
148
PJ_DECL(pj_status_t) pjsip_100rel_init_module(pjsip_endpoint *endpt);
152
* Add 100rel support to the specified invite session. This function will
153
* be called internally by the invite session if it detects that the
154
* session needs 100rel support.
156
* @param inv The invite session.
158
* @return PJ_SUCCESS on successful.
160
PJ_DECL(pj_status_t) pjsip_100rel_attach(pjsip_inv_session *inv);
164
* Check if incoming response has reliable provisional response feature.
166
* @param rdata Receive data buffer containing the response.
168
* @return PJ_TRUE if the provisional response is reliable.
170
PJ_DECL(pj_bool_t) pjsip_100rel_is_reliable(pjsip_rx_data *rdata);
174
* Create PRACK request for the incoming reliable provisional response.
175
* Note that PRACK request MUST be sent using #pjsip_100rel_send_prack().
177
* @param inv The invite session.
178
* @param rdata The incoming reliable provisional response.
179
* @param p_tdata Upon return, it will be initialized with the
182
* @return PJ_SUCCESS on successful.
184
PJ_DECL(pj_status_t) pjsip_100rel_create_prack(pjsip_inv_session *inv,
185
pjsip_rx_data *rdata,
186
pjsip_tx_data **p_tdata);
189
* Send PRACK request.
191
* @param inv The invite session.
192
* @param tdata The PRACK request.
194
* @return PJ_SUCCESS on successful.
196
PJ_DECL(pj_status_t) pjsip_100rel_send_prack(pjsip_inv_session *inv,
197
pjsip_tx_data *tdata);
201
* Handle incoming PRACK request.
203
* @param inv The invite session.
204
* @param rdata Incoming PRACK request.
206
* @return PJ_SUCCESS on successful.
208
PJ_DECL(pj_status_t) pjsip_100rel_on_rx_prack(pjsip_inv_session *inv,
209
pjsip_rx_data *rdata);
213
* Transmit INVITE response (provisional or final) reliably according to
214
* 100rel specification. The 100rel module will take care of retransmitting
215
* or enqueueing the response according to the current state of the
216
* reliable response processing. This function will be called internally
219
* @param inv The invite session.
220
* @param tdata The INVITE response.
222
* @return PJ_SUCCESS on successful.
224
PJ_DECL(pj_status_t) pjsip_100rel_tx_response(pjsip_inv_session *inv,
225
pjsip_tx_data *tdata);
229
* Notify 100rel module that the invite session has been disconnected.
231
* @param inv The invite session.
233
* @return PJ_SUCCESS on successful.
235
PJ_DECL(pj_status_t) pjsip_100rel_end_session(pjsip_inv_session *inv);
245
#endif /* __SIP_100REL_H__ */