← Back to branch summary

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

« back to all changes in this revision

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

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