← Back to branch summary

~noskcaj/ubuntu/saucy/sflphone/merge-1.2.3-2

« back to all changes in this revision

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

  • Committer: Jackson Doak
  • Date: 2013-07-10 21:04:46 UTC
  • mfrom: (20.1.3 sid)
  • Revision ID: noskcaj@ubuntu.com-20130710210446-y8f587vza807icr9
https://launchpad.net/bugs/1196978
Properly merged from upstream.

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__ */