← Back to branch summary

~ubuntu-branches/ubuntu/wily/sflphone/wily

« back to all changes in this revision

Viewing changes to sflphone-common/libs/pjproject/pjsip/include/pjsip-ua/sip_100rel.h

  • Committer: Package Import Robot
  • Author(s): Francois Marier
  • Date: 2011-11-25 13:24:12 UTC
  • mfrom: (4.1.10 sid)
  • Revision ID: package-import@ubuntu.com-20111125132412-dc4qvhyosk74cd42
Tags: 1.0.1-4
http://bugs.debian.org/649726
Don't assume that arch:all packages will get built (closes: #649726)

Show diffs side-by-side

added added

removed removed

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