Add support for ICE/STUN/TURN in res_rtp_asterisk and chan_sip.
[asterisk/asterisk.git] / res / pjproject / pjlib-util / include / pjlib-util / string.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 __PJLIB_UTIL_STRING_H__
21 #define __PJLIB_UTIL_STRING_H__
22
23 /**
24  * @file string.h
25  * @brief More string functions.
26  */
27
28 #include <pj/types.h>
29 #include <pjlib-util/scanner.h>
30
31 /**
32  * @defgroup PJLIB_UTIL_STRING String Escaping Utilities
33  * @ingroup PJLIB_TEXT
34  * @{
35  */
36
37 PJ_BEGIN_DECL
38
39 /**
40  * Unescape string. If source string does not contain any escaped
41  * characters, the function would simply return the original string.
42  * Otherwise a new string will be allocated.
43  *
44  * @param pool      Pool to allocate the string.
45  * @param src       Source string to unescape.
46  *
47  * @return          String with no escaped characters.
48  */
49 PJ_DECL(pj_str_t) pj_str_unescape( pj_pool_t *pool, const pj_str_t *src);
50
51 /**
52  * Unescape string to destination.
53  *
54  * @param dst       Target string.
55  * @param src       Source string.
56  *
57  * @return          Target string.
58  */
59 PJ_DECL(pj_str_t*) pj_strcpy_unescape(pj_str_t *dst, const pj_str_t *src);
60
61 /**
62  * Copy string to destination while escaping reserved characters, up to
63  * the specified maximum length.
64  *
65  * @param dst       Target string.
66  * @param src       Source string.
67  * @param max       Maximum length to copy to target string.
68  * @param unres     Unreserved characters, which are allowed to appear 
69  *                  unescaped.
70  *
71  * @return          The target string if all characters have been copied 
72  *                  successfully, or NULL if there's not enough buffer to
73  *                  escape the strings.
74  */
75 PJ_DECL(pj_str_t*) pj_strncpy_escape(pj_str_t *dst, const pj_str_t *src,
76                                      pj_ssize_t max, const pj_cis_t *unres);
77
78
79 /**
80  * Copy string to destination while escaping reserved characters, up to
81  * the specified maximum length.
82  *
83  * @param dst       Target string.
84  * @param src       Source string.
85  * @param max       Maximum length to copy to target string.
86  * @param unres     Unreserved characters, which are allowed to appear 
87  *                  unescaped.
88  *
89  * @return          The length of the destination, or -1 if there's not
90  *                  enough buffer.
91  */
92 PJ_DECL(pj_ssize_t) pj_strncpy2_escape(char *dst, const pj_str_t *src,
93                                        pj_ssize_t max, const pj_cis_t *unres);
94
95 PJ_END_DECL
96
97
98 /**
99  * @}
100  */
101
102 #endif  /* __PJLIB_UTIL_STRING_H__ */