← Back to branch summary

~ubuntu-branches/ubuntu/trusty/sflphone/trusty

« back to all changes in this revision

Viewing changes to daemon/libs/pjproject-2.1.0/pjsip/include/pjsip/sip_util.h

  • Committer: Package Import Robot
  • Author(s): Mark Purcell
  • Date: 2014-01-28 18:23:36 UTC
  • mfrom: (4.3.4 sid)
  • Revision ID: package-import@ubuntu.com-20140128182336-jrsv0k9u6cawc068
Tags: 1.3.0-1
http://bugs.debian.org/735846
http://bugs.debian.org/727164
http://bugs.debian.org/718178
http://bugs.debian.org/736583
http://bugs.debian.org/722040
http://bugs.debian.org/736746
* New upstream release 
  - Fixes "New Upstream Release" (Closes: #735846)
  - Fixes "Ringtone does not stop" (Closes: #727164)
  - Fixes "[sflphone-kde] crash on startup" (Closes: #718178)
  - Fixes "sflphone GUI crashes when call is hung up" (Closes: #736583)
* Build-Depends: ensure GnuTLS 2.6
  - libucommon-dev (>= 6.0.7-1.1), libccrtp-dev (>= 2.0.6-3)
  - Fixes "FTBFS Build-Depends libgnutls{26,28}-dev" (Closes: #722040)
* Fix "boost 1.49 is going away" unversioned Build-Depends: (Closes: #736746)
* Add Build-Depends: libsndfile-dev, nepomuk-core-dev

Show diffs side-by-side

added added

removed removed

Lines of Context:
daemon/libs/pjproject-2.1.0/pjsip/include/pjsip/sip_util.h
 
1
/* $Id: sip_util.h 4347 2013-02-13 10:19:25Z nanang $ */
 
2
/* 
 
3
 * Copyright (C) 2008-2011 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
#ifndef __PJSIP_SIP_MISC_H__
 
21
#define __PJSIP_SIP_MISC_H__
 
22
 
 
23
#include <pjsip/sip_msg.h>
 
24
#include <pjsip/sip_transport.h>
 
25
#include <pjsip/sip_resolve.h>
 
26
 
 
27
PJ_BEGIN_DECL
 
28
 
 
29
/**
 
30
 * @defgroup PJSIP_ENDPT_TARGET_URI Target URI Management
 
31
 * @ingroup PJSIP_CORE_CORE
 
32
 * @brief Management of target URI's in case of redirection
 
33
 * @{
 
34
 * This module provides utility functions to manage target set for UAC.
 
35
 * The target set is provided as pjsip_target_set structure. Initially,
 
36
 * the target set for UAC contains only one target, that is the target of
 
37
 * the initial request. When 3xx/redirection class response is received, 
 
38
 * the UAC can use the functionality of this module to add the URI's listed
 
39
 * in the Contact header(s) in the response to the target set, and retry 
 
40
 * sending the request to the next destination/target. The UAC may retry 
 
41
 * this sequentially until one of the target answers with succesful/2xx 
 
42
 * response, or one target returns global error/6xx response, or all targets
 
43
 * are exhausted.
 
44
 *
 
45
 * This module is currently used by the \ref PJSIP_INV.
 
46
 */
 
47
 
 
48
/**
 
49
 * This structure describes a target, which can be chained together to form
 
50
 * a target set. Each target contains an URI, priority (as q-value), and 
 
51
 * the last status code and reason phrase received from the target, if the 
 
52
 * target has been contacted. If the target has not been contacted, the 
 
53
 * status code field will be zero.
 
54
 */
 
55
typedef struct pjsip_target
 
56
{
 
57
    PJ_DECL_LIST_MEMBER(struct pjsip_target);/**< Standard list element */
 
58
    pjsip_uri          *uri;    /**< The target URI                 */
 
59
    int                 q1000;  /**< q-value multiplied by 1000     */
 
60
    pjsip_status_code   code;   /**< Last status code received      */
 
61
    pj_str_t            reason; /**< Last reason phrase received    */
 
62
} pjsip_target;
 
63
 
 
64
 
 
65
/**
 
66
 * This describes a target set. A target set contains a linked-list of
 
67
 * pjsip_target.
 
68
 */
 
69
typedef struct pjsip_target_set
 
70
{
 
71
    pjsip_target     head;          /**< Target linked-list head    */
 
72
    pjsip_target    *current;       /**< Current target.            */
 
73
} pjsip_target_set;
 
74
 
 
75
 
 
76
/**
 
77
 * These enumerations specify the action to be performed to a redirect
 
78
 * response.
 
79
 */
 
80
typedef enum pjsip_redirect_op
 
81
{
 
82
    /**
 
83
     * Reject the redirection to the current target. The UAC will
 
84
     * select the next target from the target set if exists.
 
85
     */
 
86
    PJSIP_REDIRECT_REJECT,
 
87
 
 
88
    /**
 
89
     * Accept the redirection to the current target. The INVITE request
 
90
     * will be resent to the current target.
 
91
     */
 
92
    PJSIP_REDIRECT_ACCEPT,
 
93
 
 
94
    /**
 
95
     * Accept the redirection to the current target and replace the To
 
96
     * header in the INVITE request with the current target. The INVITE
 
97
     * request will be resent to the current target.
 
98
     */
 
99
    PJSIP_REDIRECT_ACCEPT_REPLACE,
 
100
 
 
101
    /**
 
102
     * Defer the redirection decision, for example to request permission
 
103
     * from the end user.
 
104
     */
 
105
    PJSIP_REDIRECT_PENDING,
 
106
 
 
107
    /**
 
108
     * Stop the whole redirection process altogether. This will cause
 
109
     * the invite session to be disconnected.
 
110
     */
 
111
    PJSIP_REDIRECT_STOP
 
112
 
 
113
} pjsip_redirect_op;
 
114
 
 
115
 
 
116
/**
 
117
 * Initialize target set. This will empty the list of targets in the
 
118
 * target set.
 
119
 *
 
120
 * @param tset      The target set.
 
121
 */
 
122
PJ_INLINE(void) pjsip_target_set_init(pjsip_target_set *tset)
 
123
{
 
124
    pj_list_init(&tset->head);
 
125
    tset->current = NULL;
 
126
}
 
127
 
 
128
 
 
129
/**
 
130
 * Add an URI to the target set, if the URI is not already in the target set.
 
131
 * The URI comparison rule of pjsip_uri_cmp() will be used to determine the
 
132
 * equality of this URI compared to existing URI's in the target set. The
 
133
 * URI will be cloned using the specified memory pool before it is added to
 
134
 * the list.
 
135
 *
 
136
 * The first URI added to the target set will also be made current target
 
137
 * by this function.
 
138
 *
 
139
 * @param tset      The target set.
 
140
 * @param pool      The memory pool to be used to duplicate the URI.
 
141
 * @param uri       The URI to be checked and added.
 
142
 * @param q1000     The q-value multiplied by 1000.
 
143
 *
 
144
 * @return          PJ_SUCCESS if the URI was added to the target set,
 
145
 *                  or PJ_EEXISTS if the URI already exists in the target
 
146
 *                  set, or other error codes.
 
147
 */
 
148
PJ_DECL(pj_status_t) pjsip_target_set_add_uri(pjsip_target_set *tset,
 
149
                                              pj_pool_t *pool,
 
150
                                              const pjsip_uri *uri,
 
151
                                              int q1000);
 
152
 
 
153
/**
 
154
 * Extract URI's in the Contact headers of the specified (response) message
 
155
 * and add them to the target set. This function will also check if the 
 
156
 * URI's already exist in the target set before adding them to the list.
 
157
 *
 
158
 * @param tset      The target set.
 
159
 * @param pool      The memory pool to be used to duplicate the URI's.
 
160
 * @param msg       SIP message from which the Contact headers will be
 
161
 *                  scanned and the URI's to be extracted, checked, and
 
162
 *                  added to the target set.
 
163
 *
 
164
 * @return          PJ_SUCCESS if at least one URI was added to the 
 
165
 *                  target set, or PJ_EEXISTS if all URI's in the message 
 
166
 *                  already exists in the target set or if the message
 
167
 *                  doesn't contain usable Contact headers, or other error
 
168
 *                  codes.
 
169
 */
 
170
PJ_DECL(pj_status_t) pjsip_target_set_add_from_msg(pjsip_target_set *tset,
 
171
                                                   pj_pool_t *pool,
 
172
                                                   const pjsip_msg *msg);
 
173
 
 
174
/**
 
175
 * Get the next target to be retried. This function will scan the target set
 
176
 * for target which hasn't been tried, and return one target with the
 
177
 * highest q-value, if such target exists. This function will return NULL
 
178
 * if there is one target with 2xx or 6xx code or if all targets have been
 
179
 * tried.
 
180
 *
 
181
 * @param tset      The target set.
 
182
 *
 
183
 * @return          The next target to be tried, or NULL if all targets have
 
184
 *                  been tried or at least one target returns 2xx or 6xx
 
185
 *                  response.
 
186
 */
 
187
PJ_DECL(pjsip_target*) 
 
188
pjsip_target_set_get_next(const pjsip_target_set *tset);
 
189
 
 
190
 
 
191
/**
 
192
 * Set the specified target as the current target in the target set. The
 
193
 * current target may be used by application to keep track on which target
 
194
 * is currently being operated on.
 
195
 *
 
196
 * @param tset      The target set.
 
197
 * @param target    The target to be set as current target.
 
198
 *
 
199
 * @return          PJ_SUCCESS or the appropriate error code.
 
200
 */
 
201
PJ_DECL(pj_status_t) pjsip_target_set_set_current(pjsip_target_set *tset,
 
202
                                                  pjsip_target *target);
 
203
 
 
204
 
 
205
/**
 
206
 * Set the status code and reason phrase of the specified target.
 
207
 *
 
208
 * @param target    The target.
 
209
 * @param pool      The memory pool to be used to duplicate the reason phrase.
 
210
 * @param code      The SIP status code to be set to the target.
 
211
 * @param reason    The reason phrase  to be set to the target.
 
212
 *
 
213
 * @return          PJ_SUCCESS on successful operation or the appropriate
 
214
 *                  error code.
 
215
 */
 
216
PJ_DECL(pj_status_t) pjsip_target_assign_status(pjsip_target *target,
 
217
                                                pj_pool_t *pool,
 
218
                                                int status_code,
 
219
                                                const pj_str_t *reason);
 
220
 
 
221
/**
 
222
 * @}
 
223
 */
 
224
 
 
225
/**
 
226
 * @defgroup PJSIP_ENDPT_STATELESS Message Creation and Stateless Operations
 
227
 * @ingroup PJSIP_CORE_CORE
 
228
 * @brief Utilities to create various messages and base function to send messages.
 
229
 * @{
 
230
 */
 
231
 
 
232
/**
 
233
 * Create an independent request message. This can be used to build any
 
234
 * request outside a dialog, such as OPTIONS, MESSAGE, etc. To create a request
 
235
 * inside a dialog, application should use #pjsip_dlg_create_request.
 
236
 *
 
237
 * This function adds the following headers in the request:
 
238
 *  - From, To, Call-ID, and CSeq,
 
239
 *  - Contact header, if contact is specified.
 
240
 *  - A blank Via header.
 
241
 *  - Additional request headers (such as Max-Forwards) which are copied
 
242
 *    from endpoint configuration.
 
243
 *
 
244
 * In addition, the function adds a unique tag in the From header.
 
245
 *
 
246
 * Once a transmit data is created, the reference counter is initialized to 1.
 
247
 *
 
248
 * @param endpt     Endpoint instance.
 
249
 * @param method    SIP Method.
 
250
 * @param target    Target URI.
 
251
 * @param from      URL to put in From header.
 
252
 * @param to        URL to put in To header.
 
253
 * @param contact   Contact to be put as Contact header value, hence
 
254
 *                  the format must follow RFC 3261 Section 20.10:
 
255
 *                  When the header field value contains a display 
 
256
 *                  name, the URI including all URI parameters is 
 
257
 *                  enclosed in "<" and ">".  If no "<" and ">" are 
 
258
 *                  present, all parameters after the URI are header
 
259
 *                  parameters, not URI parameters.  The display name 
 
260
 *                  can be tokens, or a quoted string, if a larger 
 
261
 *                  character set is desired.
 
262
 * @param call_id   Optional Call-ID (put NULL to generate unique Call-ID).
 
263
 * @param cseq      Optional CSeq (put -1 to generate random CSeq).
 
264
 * @param text      Optional text body (put NULL to omit body).
 
265
 * @param p_tdata   Pointer to receive the transmit data.
 
266
 *
 
267
 * @return          PJ_SUCCESS, or the appropriate error code.
 
268
 */
 
269
PJ_DECL(pj_status_t) pjsip_endpt_create_request( pjsip_endpoint *endpt, 
 
270
                                                 const pjsip_method *method,
 
271
                                                 const pj_str_t *target,
 
272
                                                 const pj_str_t *from,
 
273
                                                 const pj_str_t *to, 
 
274
                                                 const pj_str_t *contact,
 
275
                                                 const pj_str_t *call_id,
 
276
                                                 int cseq, 
 
277
                                                 const pj_str_t *text,
 
278
                                                 pjsip_tx_data **p_tdata);
 
279
 
 
280
/**
 
281
 * Create an independent request message from the specified headers. This
 
282
 * function will clone the headers and put them in the request.
 
283
 *
 
284
 * This function adds the following headers in the request:
 
285
 *  - From, To, Call-ID, and CSeq,
 
286
 *  - Contact header, if contact is specified.
 
287
 *  - A blank Via header.
 
288
 *  - Additional request headers (such as Max-Forwards) which are copied
 
289
 *    from endpoint configuration.
 
290
 *
 
291
 * In addition, the function adds a unique tag in the From header.
 
292
 *
 
293
 * Once a transmit data is created, the reference counter is initialized to 1.
 
294
 *
 
295
 * @param endpt     Endpoint instance.
 
296
 * @param method    SIP Method.
 
297
 * @param target    Target URI.
 
298
 * @param from      From header.
 
299
 * @param to        To header.
 
300
 * @param contact   Contact header.
 
301
 * @param call_id   Optional Call-ID (put NULL to generate unique Call-ID).
 
302
 * @param cseq      Optional CSeq (put -1 to generate random CSeq).
 
303
 * @param text      Optional text body (put NULL to omit body).
 
304
 * @param p_tdata   Pointer to receive the transmit data.
 
305
 *
 
306
 * @return          PJ_SUCCESS, or the appropriate error code.
 
307
 */
 
308
PJ_DECL(pj_status_t)
 
309
pjsip_endpt_create_request_from_hdr( pjsip_endpoint *endpt,
 
310
                                     const pjsip_method *method,
 
311
                                     const pjsip_uri *target,
 
312
                                     const pjsip_from_hdr *from,
 
313
                                     const pjsip_to_hdr *to,
 
314
                                     const pjsip_contact_hdr *contact,
 
315
                                     const pjsip_cid_hdr *call_id,
 
316
                                     int cseq,
 
317
                                     const pj_str_t *text,
 
318
                                     pjsip_tx_data **p_tdata);
 
319
 
 
320
/**
 
321
 * Construct a minimal response message for the received request. This function
 
322
 * will construct all the Via, Record-Route, Call-ID, From, To, CSeq, and 
 
323
 * Call-ID headers from the request.
 
324
 *
 
325
 * Note: the txdata reference counter is set to ZERO!.
 
326
 *
 
327
 * @param endpt     The endpoint.
 
328
 * @param rdata     The request receive data.
 
329
 * @param st_code   Status code to be put in the response.
 
330
 * @param st_text   Optional status text, or NULL to get the default text.
 
331
 * @param p_tdata   Pointer to receive the transmit data.
 
332
 *
 
333
 * @return          PJ_SUCCESS, or the appropriate error code.
 
334
 */
 
335
PJ_DECL(pj_status_t) pjsip_endpt_create_response( pjsip_endpoint *endpt,
 
336
                                                  const pjsip_rx_data *rdata,
 
337
                                                  int st_code,
 
338
                                                  const pj_str_t *st_text,
 
339
                                                  pjsip_tx_data **p_tdata);
 
340
 
 
341
/**
 
342
 * Construct a full ACK request for the received non-2xx final response.
 
343
 * This utility function is normally called by the transaction to construct
 
344
 * an ACK request to 3xx-6xx final response.
 
345
 * The generation of ACK message for 2xx final response is different than
 
346
 * this one.
 
347
 * 
 
348
 * @param endpt     The endpoint.
 
349
 * @param tdata     This contains the original INVITE request
 
350
 * @param rdata     The final response.
 
351
 * @param ack       The ACK request created.
 
352
 *
 
353
 * @return          PJ_SUCCESS, or the appropriate error code.
 
354
 */
 
355
PJ_DECL(pj_status_t) pjsip_endpt_create_ack( pjsip_endpoint *endpt,
 
356
                                             const pjsip_tx_data *tdata,
 
357
                                             const pjsip_rx_data *rdata,
 
358
                                             pjsip_tx_data **ack);
 
359
 
 
360
 
 
361
/**
 
362
 * Construct CANCEL request for the previously sent request.
 
363
 *
 
364
 * @param endpt     The endpoint.
 
365
 * @param tdata     The transmit buffer for the request being cancelled.
 
366
 * @param p_tdata   Pointer to receive the transmit data.
 
367
 *
 
368
 * @return          PJ_SUCCESS, or the appropriate error code.
 
369
 */
 
370
PJ_DECL(pj_status_t) pjsip_endpt_create_cancel( pjsip_endpoint *endpt,
 
371
                                                const pjsip_tx_data *tdata,
 
372
                                                pjsip_tx_data **p_tdata);
 
373
 
 
374
 
 
375
/**
 
376
 * Find which destination to be used to send the request message, based
 
377
 * on the request URI and Route headers in the message. The procedure
 
378
 * used here follows the guidelines on sending the request in RFC 3261
 
379
 * chapter 8.1.2.
 
380
 *
 
381
 * Note there was a change in the behavior of this function since version
 
382
 * 0.5.10.2. Previously this function may modify the request when strict
 
383
 * route is present (to update request URI and route-set). This is no
 
384
 * longer the case now, and this process is done in separate function
 
385
 * (see #pjsip_process_route_set()).
 
386
 *
 
387
 * @param tdata     The transmit data containing the request message.
 
388
 * @param dest_info On return, it contains information about destination
 
389
 *                  host to contact, along with the preferable transport
 
390
 *                  type, if any. Caller will then normally proceed with
 
391
 *                  resolving this host with server resolution procedure
 
392
 *                  described in RFC 3263.
 
393
 *
 
394
 * @return          PJ_SUCCESS, or the appropriate error code.
 
395
 *
 
396
 * @see pjsip_process_route_set
 
397
 */
 
398
PJ_DECL(pj_status_t) pjsip_get_request_dest(const pjsip_tx_data *tdata,
 
399
                                            pjsip_host_info *dest_info );
 
400
 
 
401
 
 
402
/**
 
403
 * Process route-set found in the request and calculate destination to be
 
404
 * used to send the request message, based on the request URI and Route 
 
405
 * headers in the message. The procedure used here follows the guidelines
 
406
 * on sending the request in RFC 3261 chapter 8.1.2.
 
407
 *
 
408
 * This function may modify the message (request line and Route headers),
 
409
 * if the Route information specifies strict routing and the request
 
410
 * URI in the message is different than the calculated target URI. In that
 
411
 * case, the target URI will be put as the request URI of the request and
 
412
 * current request URI will be put as the last entry of the Route headers.
 
413
 *
 
414
 * @param tdata     The transmit data containing the request message.
 
415
 * @param dest_info On return, it contains information about destination
 
416
 *                  host to contact, along with the preferable transport
 
417
 *                  type, if any. Caller will then normally proceed with
 
418
 *                  resolving this host with server resolution procedure
 
419
 *                  described in RFC 3263.
 
420
 *
 
421
 * @return          PJ_SUCCESS, or the appropriate error code.
 
422
 *
 
423
 * @see pjsip_get_request_addr
 
424
 */
 
425
PJ_DECL(pj_status_t) pjsip_process_route_set(pjsip_tx_data *tdata,
 
426
                                             pjsip_host_info *dest_info );
 
427
 
 
428
 
 
429
/**
 
430
 * Swap the request URI and strict route back to the original position
 
431
 * before #pjsip_process_route_set() function is called. If no strict
 
432
 * route URI was found by #pjsip_process_route_set(), this function will
 
433
 * do nothing.
 
434
 *
 
435
 * This function should only used internally by PJSIP client authentication
 
436
 * module.
 
437
 *
 
438
 * @param tdata     Transmit data containing request message.
 
439
 */
 
440
PJ_DECL(void) pjsip_restore_strict_route_set(pjsip_tx_data *tdata);
 
441
 
 
442
 
 
443
/**
 
444
 * This structure holds the state of outgoing stateless request.
 
445
 */
 
446
typedef struct pjsip_send_state
 
447
{
 
448
    /** Application token, which was specified when the function
 
449
     *  #pjsip_endpt_send_request_stateless() is called.
 
450
     */
 
451
    void *token;
 
452
 
 
453
    /** Endpoint instance. 
 
454
     */
 
455
    pjsip_endpoint *endpt;
 
456
 
 
457
    /** Transmit data buffer being sent. 
 
458
     */
 
459
    pjsip_tx_data *tdata;
 
460
 
 
461
    /** Current transport being used. 
 
462
     */
 
463
    pjsip_transport *cur_transport;
 
464
 
 
465
    /** The application callback which was specified when the function
 
466
     *  #pjsip_endpt_send_request_stateless() was called.
 
467
     */
 
468
    void (*app_cb)(struct pjsip_send_state*,
 
469
                   pj_ssize_t sent,
 
470
                   pj_bool_t *cont);
 
471
} pjsip_send_state;
 
472
 
 
473
 
 
474
/**
 
475
 * Declaration for callback function to be specified in 
 
476
 * #pjsip_endpt_send_request_stateless(), #pjsip_endpt_send_response(), or
 
477
 * #pjsip_endpt_send_response2().
 
478
 *
 
479
 * @param st        Structure to keep transmission state.
 
480
 * @param sent      Number of bytes sent.
 
481
 * @param cont      When current transmission fails, specify whether
 
482
 *                  the function should fallback to next destination.
 
483
 */
 
484
typedef void (*pjsip_send_callback)(pjsip_send_state *st, pj_ssize_t sent,
 
485
                                    pj_bool_t *cont);
 
486
 
 
487
/**
 
488
 * Send outgoing request statelessly The function will take care of which 
 
489
 * destination and transport to use based on the information in the message,
 
490
 * taking care of URI in the request line and Route header.
 
491
 *
 
492
 * This function is different than #pjsip_transport_send() in that this 
 
493
 * function adds/modify the Via header as necessary.
 
494
 *
 
495
 * @param endpt     The endpoint instance.
 
496
 * @param tdata     The transmit data to be sent.
 
497
 * @param token     Arbitrary token to be given back on the callback.
 
498
 * @param cb        Optional callback to notify transmission status (also
 
499
 *                  gives chance for application to discontinue retrying
 
500
 *                  sending to alternate address).
 
501
 *
 
502
 * @return          PJ_SUCCESS, or the appropriate error code.
 
503
 */
 
504
PJ_DECL(pj_status_t) 
 
505
pjsip_endpt_send_request_stateless( pjsip_endpoint *endpt,
 
506
                                    pjsip_tx_data *tdata,
 
507
                                    void *token,
 
508
                                    pjsip_send_callback cb);
 
509
 
 
510
/**
 
511
 * This is a low-level function to send raw data to a destination.
 
512
 *
 
513
 * See also #pjsip_endpt_send_raw_to_uri().
 
514
 *
 
515
 * @param endpt     The SIP endpoint instance.
 
516
 * @param tp_type   Transport type.
 
517
 * @param sel       Optional pointer to transport selector instance if
 
518
 *                  application wants to use a specific transport instance
 
519
 *                  rather then letting transport manager finds the suitable
 
520
 *                  transport..
 
521
 * @param raw_data  The data to be sent.
 
522
 * @param data_len  The length of the data.
 
523
 * @param addr      Destination address.
 
524
 * @param addr_len  Length of destination address.
 
525
 * @param token     Arbitrary token to be returned back to callback.
 
526
 * @param cb        Optional callback to be called to notify caller about
 
527
 *                  the completion status of the pending send operation.
 
528
 *
 
529
 * @return          If the message has been sent successfully, this function
 
530
 *                  will return PJ_SUCCESS and the callback will not be 
 
531
 *                  called. If message cannot be sent immediately, this
 
532
 *                  function will return PJ_EPENDING, and application will
 
533
 *                  be notified later about the completion via the callback.
 
534
 *                  Any statuses other than PJ_SUCCESS or PJ_EPENDING
 
535
 *                  indicates immediate failure, and in this case the 
 
536
 *                  callback will not be called.
 
537
 */
 
538
PJ_DECL(pj_status_t) pjsip_endpt_send_raw(pjsip_endpoint *endpt,
 
539
                                          pjsip_transport_type_e tp_type,
 
540
                                          const pjsip_tpselector *sel,
 
541
                                          const void *raw_data,
 
542
                                          pj_size_t data_len,
 
543
                                          const pj_sockaddr_t *addr,
 
544
                                          int addr_len,
 
545
                                          void *token,
 
546
                                          pjsip_tp_send_callback cb);
 
547
 
 
548
/**
 
549
 * Send raw data to the specified destination URI. The actual destination
 
550
 * address will be calculated from the URI, using normal SIP URI to host
 
551
 * resolution.
 
552
 *
 
553
 * See also #pjsip_endpt_send_raw().
 
554
 *
 
555
 * @param endpt     The SIP endpoint instance.
 
556
 * @param dst_uri   Destination address URI.
 
557
 * @param sel       Optional pointer to transport selector instance if
 
558
 *                  application wants to use a specific transport instance
 
559
 *                  rather then letting transport manager finds the suitable
 
560
 *                  transport..
 
561
 * @param raw_data  The data to be sent.
 
562
 * @param data_len  The length of the data.
 
563
 * @param token     Arbitrary token to be returned back to callback.
 
564
 * @param cb        Optional callback to be called to notify caller about
 
565
 *                  the completion status of the pending send operation.
 
566
 *
 
567
 * @return          If the message has been sent successfully, this function
 
568
 *                  will return PJ_SUCCESS and the callback will not be 
 
569
 *                  called. If message cannot be sent immediately, this
 
570
 *                  function will return PJ_EPENDING, and application will
 
571
 *                  be notified later about the completion via the callback.
 
572
 *                  Any statuses other than PJ_SUCCESS or PJ_EPENDING
 
573
 *                  indicates immediate failure, and in this case the 
 
574
 *                  callback will not be called.
 
575
 */
 
576
PJ_DECL(pj_status_t) pjsip_endpt_send_raw_to_uri(pjsip_endpoint *endpt,
 
577
                                                 const pj_str_t *dst_uri,
 
578
                                                 const pjsip_tpselector *sel,
 
579
                                                 const void *raw_data,
 
580
                                                 pj_size_t data_len,
 
581
                                                 void *token,
 
582
                                                 pjsip_tp_send_callback cb);
 
583
 
 
584
/**
 
585
 * This structure describes destination information to send response.
 
586
 * It is initialized by calling #pjsip_get_response_addr().
 
587
 *
 
588
 * If the response message should be sent using transport from which
 
589
 * the request was received, then transport, addr, and addr_len fields
 
590
 * are initialized.
 
591
 *
 
592
 * The dst_host field is also initialized. It should be used when server
 
593
 * fails to send the response using the transport from which the request
 
594
 * was received, or when the transport is NULL, which means server
 
595
 * must send the response to this address (this situation occurs when
 
596
 * maddr parameter is set, or when rport param is not set in the request).
 
597
 */
 
598
typedef struct pjsip_response_addr
 
599
{
 
600
    pjsip_transport *transport; /**< Immediate transport to be used. */
 
601
    pj_sockaddr      addr;      /**< Immediate address to send to.   */
 
602
    int              addr_len;  /**< Address length.                 */
 
603
    pjsip_host_info  dst_host;  /**< Destination host to contact.    */
 
604
} pjsip_response_addr;
 
605
 
 
606
/**
 
607
 * Determine which address (and transport) to use to send response message
 
608
 * based on the received request. This function follows the specification
 
609
 * in section 18.2.2 of RFC 3261 and RFC 3581 for calculating the destination
 
610
 * address and transport.
 
611
 *
 
612
 * The information about destination to send the response will be returned
 
613
 * in res_addr argument. Please see #pjsip_response_addr for more info.
 
614
 *
 
615
 * @param pool      The pool.
 
616
 * @param rdata     The incoming request received by the server.
 
617
 * @param res_addr  On return, it will be initialized with information about
 
618
 *                  destination address and transport to send the response.
 
619
 *
 
620
 * @return          zero (PJ_OK) if successfull.
 
621
 */
 
622
PJ_DECL(pj_status_t) pjsip_get_response_addr(pj_pool_t *pool,
 
623
                                             pjsip_rx_data *rdata,
 
624
                                             pjsip_response_addr *res_addr);
 
625
 
 
626
/**
 
627
 * Send response in tdata statelessly. The function will take care of which 
 
628
 * response destination and transport to use based on the information in the 
 
629
 * Via header (such as the presence of rport, symmetric transport, etc.).
 
630
 *
 
631
 * This function will create a new ephemeral transport if no existing 
 
632
 * transports can be used to send the message to the destination. The ephemeral
 
633
 * transport will be destroyed after some period if it is not used to send any 
 
634
 * more messages.
 
635
 *
 
636
 * The behavior of this function complies with section 18.2.2 of RFC 3261
 
637
 * and RFC 3581.
 
638
 *
 
639
 * @param endpt     The endpoint instance.
 
640
 * @param res_addr  The information about the address and transport to send
 
641
 *                  the response to. Application can get this information
 
642
 *                  by calling #pjsip_get_response_addr().
 
643
 * @param tdata     The response message to be sent.
 
644
 * @param token     Token to be passed back when the callback is called.
 
645
 * @param cb        Optional callback to notify the transmission status
 
646
 *                  to application, and to inform whether next address or
 
647
 *                  transport will be tried.
 
648
 * 
 
649
 * @return          PJ_SUCCESS if response has been successfully created and
 
650
 *                  sent to transport layer, or a non-zero error code. 
 
651
 *                  However, even when it returns PJ_SUCCESS, there is no 
 
652
 *                  guarantee that the response has been successfully sent.
 
653
 */
 
654
PJ_DECL(pj_status_t) pjsip_endpt_send_response( pjsip_endpoint *endpt,
 
655
                                                pjsip_response_addr *res_addr,
 
656
                                                pjsip_tx_data *tdata,
 
657
                                                void *token,
 
658
                                                pjsip_send_callback cb);
 
659
 
 
660
/**
 
661
 * This is a convenient function which wraps #pjsip_get_response_addr() and
 
662
 * #pjsip_endpt_send_response() in a single function.
 
663
 *
 
664
 * @param endpt     The endpoint instance.
 
665
 * @param rdata     The original request to be responded.
 
666
 * @param tdata     The response message to be sent.
 
667
 * @param token     Token to be passed back when the callback is called.
 
668
 * @param cb        Optional callback to notify the transmission status
 
669
 *                  to application, and to inform whether next address or
 
670
 *                  transport will be tried.
 
671
 * 
 
672
 * @return          PJ_SUCCESS if response has been successfully created and
 
673
 *                  sent to transport layer, or a non-zero error code. 
 
674
 *                  However, even when it returns PJ_SUCCESS, there is no 
 
675
 *                  guarantee that the response has been successfully sent.
 
676
 */
 
677
PJ_DECL(pj_status_t) pjsip_endpt_send_response2(pjsip_endpoint *endpt,
 
678
                                                pjsip_rx_data *rdata,
 
679
                                                pjsip_tx_data *tdata,
 
680
                                                void *token,
 
681
                                                pjsip_send_callback cb);
 
682
 
 
683
/**
 
684
 * This composite function sends response message statelessly to an incoming
 
685
 * request message. Internally it calls #pjsip_endpt_create_response() and
 
686
 * #pjsip_endpt_send_response().
 
687
 *
 
688
 * @param endpt     The endpoint instance.
 
689
 * @param rdata     The incoming request message.
 
690
 * @param st_code   Status code of the response.
 
691
 * @param st_text   Optional status text of the response.
 
692
 * @param hdr_list  Optional header list to be added to the response.
 
693
 * @param body      Optional message body to be added to the response.
 
694
 *
 
695
 * @return          PJ_SUCCESS if response message has successfully been
 
696
 *                  sent.
 
697
 */
 
698
PJ_DECL(pj_status_t) pjsip_endpt_respond_stateless(pjsip_endpoint *endpt,
 
699
                                                   pjsip_rx_data *rdata,
 
700
                                                   int st_code,
 
701
                                                   const pj_str_t *st_text,
 
702
                                                   const pjsip_hdr *hdr_list,
 
703
                                                   const pjsip_msg_body *body);
 
704
                                                    
 
705
/**
 
706
 * @}
 
707
 */
 
708
 
 
709
/**
 
710
 * @defgroup PJSIP_TRANSACT_UTIL Stateful Operations
 
711
 * @ingroup PJSIP_TRANSACT
 
712
 * @brief Utility function to send requests/responses statefully.
 
713
 * @{
 
714
 */
 
715
 
 
716
/**
 
717
 * This composite function creates and sends response statefully for the
 
718
 * incoming request.
 
719
 *
 
720
 * @param endpt     The endpoint instance.
 
721
 * @param tsx_user  The module to be registered as transaction user.
 
722
 * @param rdata     The incoming request message.
 
723
 * @param st_code   Status code of the response.
 
724
 * @param st_text   Optional status text of the response.
 
725
 * @param hdr_list  Optional header list to be added to the response.
 
726
 * @param body      Optional message body to be added to the response.
 
727
 * @param p_tsx     Optional pointer to receive the transaction which was
 
728
 *                  created to send the response.
 
729
 *
 
730
 * @return          PJ_SUCCESS if response message has successfully been
 
731
 *                  created.
 
732
 */
 
733
PJ_DECL(pj_status_t) pjsip_endpt_respond( pjsip_endpoint *endpt,
 
734
                                          pjsip_module *tsx_user,
 
735
                                          pjsip_rx_data *rdata,
 
736
                                          int st_code,
 
737
                                          const pj_str_t *st_text,
 
738
                                          const pjsip_hdr *hdr_list,
 
739
                                          const pjsip_msg_body *body,
 
740
                                          pjsip_transaction **p_tsx );
 
741
 
 
742
/**
 
743
 * Type of callback to be specified in #pjsip_endpt_send_request().
 
744
 *
 
745
 * @param token     The token that was given in #pjsip_endpt_send_request()
 
746
 * @param e         Completion event.
 
747
 */
 
748
typedef void (*pjsip_endpt_send_callback)(void *token, pjsip_event *e);
 
749
 
 
750
/**
 
751
 * Send outgoing request and initiate UAC transaction for the request.
 
752
 * This is an auxiliary function to be used by application to send arbitrary
 
753
 * requests outside a dialog. To send a request within a dialog, application
 
754
 * should use #pjsip_dlg_send_request instead.
 
755
 *
 
756
 * @param endpt     The endpoint instance.
 
757
 * @param tdata     The transmit data to be sent.
 
758
 * @param timeout   Optional timeout for final response to be received, or -1 
 
759
 *                  if the transaction should not have a timeout restriction.
 
760
 *                  The value is in miliseconds.
 
761
 * @param token     Optional token to be associated with the transaction, and 
 
762
 *                  to be passed to the callback.
 
763
 * @param cb        Optional callback to be called when the transaction has
 
764
 *                  received a final response. The callback will be called with
 
765
 *                  the previously registered token and the event that triggers
 
766
 *                  the completion of the transaction.
 
767
 *
 
768
 * @return          PJ_SUCCESS, or the appropriate error code.
 
769
 */
 
770
PJ_DECL(pj_status_t) pjsip_endpt_send_request( pjsip_endpoint *endpt,
 
771
                                               pjsip_tx_data *tdata,
 
772
                                               pj_int32_t timeout,
 
773
                                               void *token,
 
774
                                               pjsip_endpt_send_callback cb);
 
775
 
 
776
/**
 
777
 * @}
 
778
 */
 
779
 
 
780
/**
 
781
 * @defgroup PJSIP_PROXY_CORE Core Proxy Layer
 
782
 * @brief Core proxy operations
 
783
 * @{
 
784
 */
 
785
 
 
786
/**
 
787
 * Create new request message to be forwarded upstream to new destination URI 
 
788
 * in uri. The new request is a full/deep clone of the request received in 
 
789
 * rdata, unless if other copy mechanism is specified in the options. 
 
790
 * The branch parameter, if not NULL, will be used as the branch-param in 
 
791
 * the Via header. If it is NULL, then a unique branch parameter will be used.
 
792
 *
 
793
 * Note: this function DOES NOT perform Route information preprocessing as
 
794
 *        described in RFC 3261 Section 16.4. Application must take care of
 
795
 *        removing/updating the Route headers according of the rules as
 
796
 *        described in that section.
 
797
 *
 
798
 * @param endpt     The endpoint instance.
 
799
 * @param rdata     The incoming request message.
 
800
 * @param uri       The URI where the request will be forwarded to.
 
801
 * @param branch    Optional branch parameter. Application may specify its
 
802
 *                  own branch, for example if it wishes to perform loop
 
803
 *                  detection. If the branch parameter is not specified,
 
804
 *                  this function will generate its own by calling 
 
805
 *                  #pjsip_calculate_branch_id() function.
 
806
 * @param options   Optional option flags when duplicating the message.
 
807
 * @param tdata     The result.
 
808
 *
 
809
 * @return          PJ_SUCCESS on success.
 
810
 */
 
811
PJ_DECL(pj_status_t) pjsip_endpt_create_request_fwd(pjsip_endpoint *endpt,
 
812
                                                    pjsip_rx_data *rdata, 
 
813
                                                    const pjsip_uri *uri,
 
814
                                                    const pj_str_t *branch,
 
815
                                                    unsigned options,
 
816
                                                    pjsip_tx_data **tdata);
 
817
 
 
818
 
 
819
 
 
820
/**
 
821
 * Create new response message to be forwarded downstream by the proxy from 
 
822
 * the response message found in rdata. Note that this function practically 
 
823
 * will clone the response as is, i.e. without checking the validity of the 
 
824
 * response or removing top most Via header. This function will perform 
 
825
 * full/deep clone of the response, unless other copy mechanism is used in 
 
826
 * the options.
 
827
 *
 
828
 * @param endpt     The endpoint instance.
 
829
 * @param rdata     The incoming response message.
 
830
 * @param options   Optional option flags when duplicate the message.
 
831
 * @param tdata     The result
 
832
 *
 
833
 * @return          PJ_SUCCESS on success.
 
834
 */
 
835
PJ_DECL(pj_status_t) pjsip_endpt_create_response_fwd( pjsip_endpoint *endpt,
 
836
                                                      pjsip_rx_data *rdata, 
 
837
                                                      unsigned options,
 
838
                                                      pjsip_tx_data **tdata);
 
839
 
 
840
 
 
841
 
 
842
/**
 
843
 * Create a globally unique branch parameter based on the information in 
 
844
 * the incoming request message, for the purpose of creating a new request
 
845
 * for forwarding. This is the default implementation used by 
 
846
 * #pjsip_endpt_create_request_fwd() function if the branch parameter is
 
847
 * not specified.
 
848
 *
 
849
 * The default implementation here will just create an MD5 hash of the
 
850
 * top-most Via.
 
851
 *
 
852
 * Note that the returned string was allocated from rdata's pool.
 
853
 *
 
854
 * @param rdata     The incoming request message.
 
855
 *
 
856
 * @return          Unique branch-ID string.
 
857
 */
 
858
PJ_DECL(pj_str_t) pjsip_calculate_branch_id( pjsip_rx_data *rdata );
 
859
 
 
860
 
 
861
/**
 
862
 * @}
 
863
 */
 
864
 
 
865
PJ_END_DECL
 
866
 
 
867
#endif  /* __PJSIP_SIP_MISC_H__ */
 
868