Add support for ICE/STUN/TURN in res_rtp_asterisk and chan_sip.
[asterisk/asterisk.git] / res / pjproject / pjsip / include / pjsip / sip_uri.h
1 /* $Id$ */
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_URI_H__
21 #define __PJSIP_SIP_URI_H__
22
23 /**
24  * @file sip_uri.h
25  * @brief SIP URL Structures and Manipulations
26  */
27
28 #include <pjsip/sip_types.h>
29 #include <pjsip/sip_config.h>
30 #include <pj/list.h>
31 #include <pjlib-util/scanner.h>
32
33 PJ_BEGIN_DECL
34
35
36 /**
37  * @defgroup PJSIP_URI URI
38  * @brief URI types and manipulations.
39  * @ingroup PJSIP_MSG
40  */
41
42 /**
43  * @addtogroup PJSIP_URI_PARAM URI Parameter Container
44  * @ingroup PJSIP_URI
45  * @brief Generic parameter elements container.
46  * @{
47  */
48
49 /**
50  * Generic parameter, normally used in other_param or header_param.
51  */
52 typedef struct pjsip_param
53 {
54     PJ_DECL_LIST_MEMBER(struct pjsip_param);    /**< Generic list member.   */
55     pj_str_t        name;                       /**< Param/header name.     */
56     pj_str_t        value;                      /**< Param/header value.    */
57 } pjsip_param;
58
59
60 /**
61  * Find the specified parameter name in the list. The name will be compared
62  * in case-insensitive comparison.
63  *
64  * @param param_list    List of parameters to find.
65  * @param name          Parameter/header name to find.
66  *
67  * @return              The parameter if found, or NULL.
68  */
69 PJ_DECL(pjsip_param*) pjsip_param_find( const pjsip_param *param_list,
70                                         const pj_str_t *name );
71
72
73 /**
74  * Alias for pjsip_param_find()
75  */
76 PJ_INLINE(pjsip_param*) pjsip_param_cfind(const pjsip_param *param_list,
77                                           const pj_str_t *name)
78 {
79     return pjsip_param_find(param_list, name);
80 }
81
82 /**
83  * Compare two parameter lists.
84  *
85  * @param param_list1   First parameter list.
86  * @param param_list2   Second parameter list.
87  * @param ig_nf         If set to 1, do not compare parameters that only
88  *                      appear in one of the list.
89  *
90  * @return              Zero if the parameter list are equal, non-zero
91  *                      otherwise.
92  */
93 PJ_DECL(int) pjsip_param_cmp(const pjsip_param *param_list1,
94                              const pjsip_param *param_list2,
95                              pj_bool_t ig_nf);
96
97 /**
98  * Duplicate the parameters.
99  *
100  * @param pool          Pool to allocate memory from.
101  * @param dst_list      Destination list.
102  * @param src_list      Source list.
103  */
104 PJ_DECL(void) pjsip_param_clone(pj_pool_t *pool, pjsip_param *dst_list,
105                                 const pjsip_param *src_list);
106
107 /**
108  * Duplicate the parameters.
109  *
110  * @param pool          Pool to allocate memory from.
111  * @param dst_list      Destination list.
112  * @param src_list      Source list.
113  */
114 PJ_DECL(void) pjsip_param_shallow_clone(pj_pool_t *pool, 
115                                         pjsip_param *dst_list,
116                                         const pjsip_param *src_list);
117
118 /**
119  * Print parameters.
120  *
121  * @param param_list    The parameter list.
122  * @param buf           Buffer.
123  * @param size          Size of buffer.
124  * @param pname_unres   Specification of allowed characters in pname.
125  * @param pvalue_unres  Specification of allowed characters in pvalue.
126  * @param sep           Separator character (either ';', ',', or '?').
127  *                      When separator is set to '?', this function will
128  *                      automatically adjust the separator character to
129  *                      '&' after the first parameter is printed.
130  *
131  * @return              The number of bytes printed, or -1 on errr.
132  */
133 PJ_DECL(pj_ssize_t) pjsip_param_print_on(const pjsip_param *param_list,
134                                          char *buf, pj_size_t size,
135                                          const pj_cis_t *pname_unres,
136                                          const pj_cis_t *pvalue_unres,
137                                          int sep);
138
139 /**
140  * @}
141  */
142
143 /**
144  * @defgroup PJSIP_URI_GENERIC Generic URI
145  * @ingroup PJSIP_URI
146  * @brief Generic representation for all types of URI.
147  * @{
148  */
149
150 /**
151  * URI context.
152  */
153 typedef enum pjsip_uri_context_e
154 {
155     PJSIP_URI_IN_REQ_URI,       /**< The URI is in Request URI. */
156     PJSIP_URI_IN_FROMTO_HDR,    /**< The URI is in From/To header. */
157     PJSIP_URI_IN_CONTACT_HDR,   /**< The URI is in Contact header. */
158     PJSIP_URI_IN_ROUTING_HDR,   /**< The URI is in Route/Record-Route header. */
159     PJSIP_URI_IN_OTHER          /**< Other context (web page, business card, etc.) */
160 } pjsip_uri_context_e;
161
162 /**
163  * URI 'virtual' function table.
164  * All types of URI in this library (such as sip:, sips:, tel:, and name-addr) 
165  * will have pointer to this table as their first struct member. This table
166  * provides polimorphic behaviour to the URI.
167  */
168 typedef struct pjsip_uri_vptr
169 {
170     /** 
171      * Get URI scheme. 
172      * @param uri the URI (self).
173      * @return the URI scheme.
174      */
175     const pj_str_t* (*p_get_scheme)(const void *uri);
176
177     /**
178      * Get the URI object contained by this URI, or the URI itself if
179      * it doesn't contain another URI.
180      * @param uri the URI (self).
181      */
182     void* (*p_get_uri)(void *uri);
183
184     /**
185      * Print URI components to the buffer, following the rule of which 
186      * components are allowed for the context.
187      * @param context the context where the URI will be placed.
188      * @param uri the URI (self).
189      * @param buf the buffer.
190      * @param size the size of the buffer.
191      * @return the length printed.
192      */
193     pj_ssize_t (*p_print)(pjsip_uri_context_e context,
194                           const void *uri, 
195                           char *buf, pj_size_t size);
196
197     /** 
198      * Compare two URIs according to the context.
199      * @param context the context.
200      * @param uri1 the first URI (self).
201      * @param uri2 the second URI.
202      * @return PJ_SUCCESS if equal, or otherwise the error status which
203      *              should point to the mismatch part.
204      */
205     pj_status_t (*p_compare)(pjsip_uri_context_e context, 
206                              const void *uri1, const void *uri2);
207
208     /** 
209      * Clone URI. 
210      * @param pool the pool.
211      * @param the URI to clone (self).
212      * @return new URI.
213      */
214     void *(*p_clone)(pj_pool_t *pool, const void *uri);
215
216 } pjsip_uri_vptr;
217
218
219 /**
220  * The declaration of 'base class' for all URI scheme.
221  */
222 struct pjsip_uri
223 {
224     /** All URIs must have URI virtual function table as their first member. */
225     pjsip_uri_vptr *vptr;
226 };
227
228 /**
229  * This macro checks that the URL is a "sip:" or "sips:" URL.
230  * @param url The URL (pointer to)
231  * @return non-zero if TRUE.
232  */
233 #define PJSIP_URI_SCHEME_IS_SIP(url)    \
234     (pj_strnicmp2(pjsip_uri_get_scheme(url), "sip", 3)==0)
235
236 /**
237  * This macro checks that the URL is a "sips:" URL (not SIP).
238  * @param url The URL (pointer to)
239  * @return non-zero if TRUE.
240  */
241 #define PJSIP_URI_SCHEME_IS_SIPS(url)   \
242     (pj_strnicmp2(pjsip_uri_get_scheme(url), "sips", 4)==0)
243
244 /**
245  * This macro checks that the URL is a "tel:" URL.
246  * @param url The URL (pointer to)
247  * @return non-zero if TRUE.
248  */
249 #define PJSIP_URI_SCHEME_IS_TEL(url)    \
250     (pj_strnicmp2(pjsip_uri_get_scheme(url), "tel", 3)==0)
251
252
253 /**
254  * Generic function to get the URI scheme.
255  * @param uri       the URI object.
256  * @return          the URI scheme.
257  */
258 PJ_INLINE(const pj_str_t*) pjsip_uri_get_scheme(const void *uri)
259 {
260     return (*((pjsip_uri*)uri)->vptr->p_get_scheme)(uri);
261 }
262
263 /**
264  * Generic function to get the URI object contained by this URI, or the URI 
265  * itself if it doesn't contain another URI.
266  *
267  * @param uri       the URI.
268  * @return          the URI.
269  */
270 PJ_INLINE(void*) pjsip_uri_get_uri(const void *uri)
271 {
272     return (*((pjsip_uri*)uri)->vptr->p_get_uri)((void*)uri);
273 }
274
275 /**
276  * Generic function to compare two URIs.
277  *
278  * @param context   Comparison context.
279  * @param uri1      The first URI.
280  * @param uri2      The second URI.
281  * @return          PJ_SUCCESS if equal, or otherwise the error status which
282  *                  should point to the mismatch part.
283  */
284 PJ_INLINE(pj_status_t) pjsip_uri_cmp(pjsip_uri_context_e context, 
285                                      const void *uri1, const void *uri2)
286 {
287     return (*((const pjsip_uri*)uri1)->vptr->p_compare)(context, uri1, uri2);
288 }
289
290 /**
291  * Generic function to print an URI object.
292  *
293  * @param context   Print context.
294  * @param uri       The URI to print.
295  * @param buf       The buffer.
296  * @param size      Size of the buffer.
297  * @return          Length printed.
298  */
299 PJ_INLINE(int) pjsip_uri_print(pjsip_uri_context_e context,
300                                const void *uri,
301                                char *buf, pj_size_t size)
302 {
303     return (*((const pjsip_uri*)uri)->vptr->p_print)(context, uri, buf, size);
304 }
305
306 /**
307  * Generic function to clone an URI object.
308  *
309  * @param pool      Pool.
310  * @param uri       URI to clone.
311  * @return          New URI.
312  */
313 PJ_INLINE(void*) pjsip_uri_clone( pj_pool_t *pool, const void *uri )
314 {
315     return (*((const pjsip_uri*)uri)->vptr->p_clone)(pool, uri);
316 }
317
318
319
320 /**
321  * @}
322  */
323
324 /**
325  * @defgroup PJSIP_SIP_URI SIP URI Scheme and Name address
326  * @ingroup PJSIP_URI
327  * @brief SIP URL structure ("sip:" and "sips:")
328  * @{
329  */
330
331
332 /**
333  * SIP and SIPS URL scheme.
334  */
335 typedef struct pjsip_sip_uri
336 {
337     pjsip_uri_vptr *vptr;               /**< Pointer to virtual function table.*/
338     pj_str_t        user;               /**< Optional user part. */
339     pj_str_t        passwd;             /**< Optional password part. */
340     pj_str_t        host;               /**< Host part, always exists. */
341     int             port;               /**< Optional port number, or zero. */
342     pj_str_t        user_param;         /**< Optional user parameter */
343     pj_str_t        method_param;       /**< Optional method parameter. */
344     pj_str_t        transport_param;    /**< Optional transport parameter. */
345     int             ttl_param;          /**< Optional TTL param, or -1. */
346     int             lr_param;           /**< Optional loose routing param, or zero */
347     pj_str_t        maddr_param;        /**< Optional maddr param */
348     pjsip_param     other_param;        /**< Other parameters grouped together. */
349     pjsip_param     header_param;       /**< Optional header parameter. */
350 } pjsip_sip_uri;
351
352
353 /**
354  * SIP name-addr, which typically appear in From, To, and Contact header.
355  * The SIP name-addr contains a generic URI and a display name.
356  */
357 typedef struct pjsip_name_addr
358 {
359     /** Pointer to virtual function table. */
360     pjsip_uri_vptr  *vptr;
361
362     /** Optional display name. */
363     pj_str_t         display;
364
365     /** URI part. */
366     pjsip_uri       *uri;
367
368 } pjsip_name_addr;
369
370
371 /**
372  * Create new SIP URL and initialize all fields with zero or NULL.
373  * @param pool      The pool.
374  * @param secure    Flag to indicate whether secure transport should be used.
375  * @return SIP URL.
376  */
377 PJ_DECL(pjsip_sip_uri*) pjsip_sip_uri_create( pj_pool_t *pool, 
378                                               pj_bool_t secure );
379
380 /**
381  * Change the SIP URI scheme to sip or sips based on the secure flag.
382  * This would not change anything except the scheme.
383  * @param uri       The URI
384  * @param secure    Non-zero if sips is wanted.
385  */
386 PJ_DECL(void) pjsip_sip_uri_set_secure( pjsip_sip_uri *uri, 
387                                         pj_bool_t secure );
388
389 /**
390  * Initialize SIP URL (all fields are set to NULL or zero).
391  * @param url       The URL.
392  * @param secure    Create sips URI?
393  */
394 PJ_DECL(void)  pjsip_sip_uri_init(pjsip_sip_uri *url, pj_bool_t secure);
395
396 /**
397  * Perform full assignment to the SIP URL.
398  * @param pool      The pool.
399  * @param url       Destination URL.
400  * @param rhs       The source URL.
401  */
402 PJ_DECL(void)  pjsip_sip_uri_assign(pj_pool_t *pool, pjsip_sip_uri *url, 
403                                     const pjsip_sip_uri *rhs);
404
405 /**
406  * Create new instance of name address and initialize all fields with zero or
407  * NULL.
408  * @param pool      The pool.
409  * @return          New SIP name address.
410  */
411 PJ_DECL(pjsip_name_addr*) pjsip_name_addr_create(pj_pool_t *pool);
412
413 /**
414  * Initialize with default value.
415  * @param name_addr The name address.
416  */
417 PJ_DECL(void) pjsip_name_addr_init(pjsip_name_addr *name_addr);
418
419 /**
420  * Perform full assignment to the name address.
421  * @param pool      The pool.
422  * @param addr      The destination name address.
423  * @param rhs       The source name address.
424  */
425 PJ_DECL(void)  pjsip_name_addr_assign(pj_pool_t *pool, 
426                                       pjsip_name_addr *addr, 
427                                       const pjsip_name_addr *rhs);
428
429 /**
430  * @}
431  */
432
433 /**
434  * @defgroup PJSIP_OTHER_URI Other URI schemes
435  * @ingroup PJSIP_URI
436  * @brief Container for non SIP/tel URI scheme (e.g. "http:", "mailto:")
437  * @{
438  */
439
440 /**
441  * Generic URI container for non SIP/tel URI scheme.
442  */
443 typedef struct pjsip_other_uri 
444 {
445     pjsip_uri_vptr *vptr;       /**< Pointer to virtual function table. */
446     pj_str_t scheme;            /**< The URI scheme (e.g. "mailto")     */
447     pj_str_t content;           /**< The whole URI content              */
448 } pjsip_other_uri;
449
450
451 /**
452  * Create a generic URI object.
453  *
454  * @param pool      The pool to allocate memory from.
455  *
456  * @return          The URI instance.
457  */
458 PJ_DECL(pjsip_other_uri*) pjsip_other_uri_create(pj_pool_t *pool);
459
460
461 /**
462  * @}
463  */
464
465 PJ_END_DECL
466
467 #endif  /* __PJSIP_URL_H__ */
468