Allow media to go directly between IAX endpoints while signalling still
[asterisk/asterisk.git] / include / asterisk / utils.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 1999 - 2006, Digium, Inc.
5  *
6  * Mark Spencer <markster@digium.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18
19 /*! \file
20  * \brief Utility functions
21  */
22
23 #ifndef _ASTERISK_UTILS_H
24 #define _ASTERISK_UTILS_H
25
26 #include "asterisk/compat.h"
27
28 #include <stdlib.h>
29 #include <netinet/in.h>
30 #include <arpa/inet.h>  /* we want to override inet_ntoa */
31 #include <netdb.h>
32 #include <limits.h>
33
34 #include "asterisk/lock.h"
35 #include "asterisk/time.h"
36 #include "asterisk/strings.h"
37 #include "asterisk/logger.h"
38
39 /*! \note
40  \verbatim
41    Note:
42    It is very important to use only unsigned variables to hold
43    bit flags, as otherwise you can fall prey to the compiler's
44    sign-extension antics if you try to use the top two bits in
45    your variable.
46
47    The flag macros below use a set of compiler tricks to verify
48    that the caller is using an "unsigned int" variable to hold
49    the flags, and nothing else. If the caller uses any other
50    type of variable, a warning message similar to this:
51
52    warning: comparison of distinct pointer types lacks cast
53    will be generated.
54
55    The "dummy" variable below is used to make these comparisons.
56
57    Also note that at -O2 or above, this type-safety checking
58    does _not_ produce any additional object code at all.
59  \endverbatim
60 */
61
62 extern unsigned int __unsigned_int_flags_dummy;
63
64 #define ast_test_flag(p,flag)           ({ \
65                                         typeof ((p)->flags) __p = (p)->flags; \
66                                         typeof (__unsigned_int_flags_dummy) __x = 0; \
67                                         (void) (&__p == &__x); \
68                                         ((p)->flags & (flag)); \
69                                         })
70
71 #define ast_set_flag(p,flag)            do { \
72                                         typeof ((p)->flags) __p = (p)->flags; \
73                                         typeof (__unsigned_int_flags_dummy) __x = 0; \
74                                         (void) (&__p == &__x); \
75                                         ((p)->flags |= (flag)); \
76                                         } while(0)
77
78 #define ast_clear_flag(p,flag)          do { \
79                                         typeof ((p)->flags) __p = (p)->flags; \
80                                         typeof (__unsigned_int_flags_dummy) __x = 0; \
81                                         (void) (&__p == &__x); \
82                                         ((p)->flags &= ~(flag)); \
83                                         } while(0)
84
85 #define ast_copy_flags(dest,src,flagz)  do { \
86                                         typeof ((dest)->flags) __d = (dest)->flags; \
87                                         typeof ((src)->flags) __s = (src)->flags; \
88                                         typeof (__unsigned_int_flags_dummy) __x = 0; \
89                                         (void) (&__d == &__x); \
90                                         (void) (&__s == &__x); \
91                                         (dest)->flags &= ~(flagz); \
92                                         (dest)->flags |= ((src)->flags & (flagz)); \
93                                         } while (0)
94
95 #define ast_set2_flag(p,value,flag)     do { \
96                                         typeof ((p)->flags) __p = (p)->flags; \
97                                         typeof (__unsigned_int_flags_dummy) __x = 0; \
98                                         (void) (&__p == &__x); \
99                                         if (value) \
100                                                 (p)->flags |= (flag); \
101                                         else \
102                                                 (p)->flags &= ~(flag); \
103                                         } while (0)
104
105 #define ast_set_flags_to(p,flag,value)  do { \
106                                         typeof ((p)->flags) __p = (p)->flags; \
107                                         typeof (__unsigned_int_flags_dummy) __x = 0; \
108                                         (void) (&__p == &__x); \
109                                         (p)->flags &= ~(flag); \
110                                         (p)->flags |= (value); \
111                                         } while (0)
112
113 /* Non-type checking variations for non-unsigned int flags.  You
114    should only use non-unsigned int flags where required by 
115    protocol etc and if you know what you're doing :)  */
116 #define ast_test_flag_nonstd(p,flag)            ({ \
117                                         ((p)->flags & (flag)); \
118                                         })
119
120 #define ast_set_flag_nonstd(p,flag)             do { \
121                                         ((p)->flags |= (flag)); \
122                                         } while(0)
123
124 #define ast_clear_flag_nonstd(p,flag)           do { \
125                                         ((p)->flags &= ~(flag)); \
126                                         } while(0)
127
128 #define ast_copy_flags_nonstd(dest,src,flagz)   do { \
129                                         (dest)->flags &= ~(flagz); \
130                                         (dest)->flags |= ((src)->flags & (flagz)); \
131                                         } while (0)
132
133 #define ast_set2_flag_nonstd(p,value,flag)      do { \
134                                         if (value) \
135                                                 (p)->flags |= (flag); \
136                                         else \
137                                                 (p)->flags &= ~(flag); \
138                                         } while (0)
139
140 #define AST_FLAGS_ALL UINT_MAX
141
142 struct ast_flags {
143         unsigned int flags;
144 };
145
146 struct ast_hostent {
147         struct hostent hp;
148         char buf[1024];
149 };
150
151 struct hostent *ast_gethostbyname(const char *host, struct ast_hostent *hp);
152
153 /* ast_md5_hash 
154         \brief Produces MD5 hash based on input string */
155 void ast_md5_hash(char *output, char *input);
156 /* ast_sha1_hash
157         \brief Produces SHA1 hash based on input string */
158 void ast_sha1_hash(char *output, char *input);
159
160 int ast_base64encode(char *dst, const unsigned char *src, int srclen, int max);
161 int ast_base64decode(unsigned char *dst, const char *src, int max);
162
163 /*! ast_uri_encode
164         \brief Turn text string to URI-encoded %XX version 
165         At this point, we're converting from ISO-8859-x (8-bit), not UTF8
166         as in the SIP protocol spec 
167         If doreserved == 1 we will convert reserved characters also.
168         RFC 2396, section 2.4
169         outbuf needs to have more memory allocated than the instring
170         to have room for the expansion. Every char that is converted
171         is replaced by three ASCII characters.
172         \param string   String to be converted
173         \param outbuf   Resulting encoded string
174         \param buflen   Size of output buffer
175         \param doreserved       Convert reserved characters
176 */
177
178 char *ast_uri_encode(const char *string, char *outbuf, int buflen, int doreserved);
179
180 /*!     \brief Decode URI, URN, URL (overwrite string)
181         \param s        String to be decoded 
182  */
183 void ast_uri_decode(char *s);
184
185 static force_inline void ast_slinear_saturated_add(short *input, short *value)
186 {
187         int res;
188
189         res = (int) *input + *value;
190         if (res > 32767)
191                 *input = 32767;
192         else if (res < -32767)
193                 *input = -32767;
194         else
195                 *input = (short) res;
196 }
197         
198 static force_inline void ast_slinear_saturated_multiply(short *input, short *value)
199 {
200         int res;
201
202         res = (int) *input * *value;
203         if (res > 32767)
204                 *input = 32767;
205         else if (res < -32767)
206                 *input = -32767;
207         else
208                 *input = (short) res;
209 }
210
211 static force_inline void ast_slinear_saturated_divide(short *input, short *value)
212 {
213         *input /= *value;
214 }
215
216 int test_for_thread_safety(void);
217
218 const char *ast_inet_ntoa(char *buf, int bufsiz, struct in_addr ia);
219
220 #ifdef inet_ntoa
221 #undef inet_ntoa
222 #endif
223 #define inet_ntoa __dont__use__inet_ntoa__use__ast_inet_ntoa__instead__
224
225 int ast_utils_init(void);
226 int ast_wait_for_input(int fd, int ms);
227
228 /*! ast_carefulwrite
229         \brief Try to write string, but wait no more than ms milliseconds
230         before timing out.
231
232         \note If you are calling ast_carefulwrite, it is assumed that you are calling
233         it on a file descriptor that _DOES_ have NONBLOCK set.  This way,
234         there is only one system call made to do a write, unless we actually
235         have a need to wait.  This way, we get better performance.
236 */
237 int ast_carefulwrite(int fd, char *s, int len, int timeoutms);
238
239 /*! Compares the source address and port of two sockaddr_in */
240 static force_inline int inaddrcmp(const struct sockaddr_in *sin1, const struct sockaddr_in *sin2)
241 {
242         return ((sin1->sin_addr.s_addr != sin2->sin_addr.s_addr) 
243                 || (sin1->sin_port != sin2->sin_port));
244 }
245
246 #define AST_STACKSIZE 256 * 1024
247
248 void ast_register_thread(char *name);
249 void ast_unregister_thread(void *id);
250
251 #define ast_pthread_create(a,b,c,d) ast_pthread_create_stack(a,b,c,d,0, \
252          __FILE__, __FUNCTION__, __LINE__, #c)
253 int ast_pthread_create_stack(pthread_t *thread, pthread_attr_t *attr, void *(*start_routine)(void *), void *data, size_t stacksize,
254         const char *file, const char *caller, int line, const char *start_fn);
255
256 /*!
257         \brief Process a string to find and replace characters
258         \param start The string to analyze
259         \param find The character to find
260         \param replace_with The character that will replace the one we are looking for
261 */
262 char *ast_process_quotes_and_slashes(char *start, char find, char replace_with);
263
264 #ifndef HAVE_GETLOADAVG
265 int getloadavg(double *list, int nelem);
266 #endif
267
268 #ifdef linux
269 #define ast_random random
270 #else
271 long int ast_random(void);
272 #endif
273
274 #ifndef __AST_DEBUG_MALLOC
275
276 /*!
277   \brief A wrapper for malloc()
278
279   ast_malloc() is a wrapper for malloc() that will generate an Asterisk log
280   message in the case that the allocation fails.
281
282   The argument and return value are the same as malloc()
283 */
284 #define ast_malloc(len) \
285         _ast_malloc((len), __FILE__, __LINE__, __PRETTY_FUNCTION__)
286
287 AST_INLINE_API(
288 void * __attribute__((malloc)) _ast_malloc(size_t len, const char *file, int lineno, const char *func),
289 {
290         void *p;
291
292         p = malloc(len);
293
294         if (!p)
295                 ast_log(LOG_ERROR, "Memory Allocation Failure - '%d' bytes in function %s at line %d of %s\n", (int)len, func, lineno, file);
296
297         return p;
298 }
299 )
300
301 /*!
302   \brief A wrapper for calloc()
303
304   ast_calloc() is a wrapper for calloc() that will generate an Asterisk log
305   message in the case that the allocation fails.
306
307   The arguments and return value are the same as calloc()
308 */
309 #define ast_calloc(num, len) \
310         _ast_calloc((num), (len), __FILE__, __LINE__, __PRETTY_FUNCTION__)
311
312 AST_INLINE_API(
313 void * __attribute__((malloc)) _ast_calloc(size_t num, size_t len, const char *file, int lineno, const char *func),
314 {
315         void *p;
316
317         p = calloc(num, len);
318
319         if (!p)
320                 ast_log(LOG_ERROR, "Memory Allocation Failure - '%d' bytes in function %s at line %d of %s\n", (int)len, func, lineno, file);
321
322         return p;
323 }
324 )
325
326 /*!
327   \brief A wrapper for realloc()
328
329   ast_realloc() is a wrapper for realloc() that will generate an Asterisk log
330   message in the case that the allocation fails.
331
332   The arguments and return value are the same as realloc()
333 */
334 #define ast_realloc(p, len) \
335         _ast_realloc((p), (len), __FILE__, __LINE__, __PRETTY_FUNCTION__)
336
337 AST_INLINE_API(
338 void * __attribute__((malloc)) _ast_realloc(void *p, size_t len, const char *file, int lineno, const char *func),
339 {
340         void *newp;
341
342         newp = realloc(p, len);
343
344         if (!newp)
345                 ast_log(LOG_ERROR, "Memory Allocation Failure - '%d' bytes in function %s at line %d of %s\n", (int)len, func, lineno, file);
346
347         return newp;
348 }
349 )
350
351 /*!
352   \brief A wrapper for strdup()
353
354   ast_strdup() is a wrapper for strdup() that will generate an Asterisk log
355   message in the case that the allocation fails.
356
357   ast_strdup(), unlike strdup(), can safely accept a NULL argument. If a NULL
358   argument is provided, ast_strdup will return NULL without generating any
359   kind of error log message.
360
361   The argument and return value are the same as strdup()
362 */
363 #define ast_strdup(str) \
364         _ast_strdup((str), __FILE__, __LINE__, __PRETTY_FUNCTION__)
365
366 AST_INLINE_API(
367 char * __attribute__((malloc)) _ast_strdup(const char *str, const char *file, int lineno, const char *func),
368 {
369         char *newstr = NULL;
370
371         if (str) {
372                 newstr = strdup(str);
373
374                 if (!newstr)
375                         ast_log(LOG_ERROR, "Memory Allocation Failure - Could not duplicate '%s' in function %s at line %d of %s\n", str, func, lineno, file);
376         }
377
378         return newstr;
379 }
380 )
381
382 /*!
383   \brief A wrapper for strndup()
384
385   ast_strndup() is a wrapper for strndup() that will generate an Asterisk log
386   message in the case that the allocation fails.
387
388   ast_strndup(), unlike strndup(), can safely accept a NULL argument for the
389   string to duplicate. If a NULL argument is provided, ast_strdup will return  
390   NULL without generating any kind of error log message.
391
392   The arguments and return value are the same as strndup()
393 */
394 #define ast_strndup(str, len) \
395         _ast_strndup((str), (len), __FILE__, __LINE__, __PRETTY_FUNCTION__)
396
397 AST_INLINE_API(
398 char * __attribute__((malloc)) _ast_strndup(const char *str, size_t len, const char *file, int lineno, const char *func),
399 {
400         char *newstr = NULL;
401
402         if (str) {
403                 newstr = strndup(str, len);
404
405                 if (!newstr)
406                         ast_log(LOG_ERROR, "Memory Allocation Failure - Could not duplicate '%d' bytes of '%s' in function %s at line %d of %s\n", (int)len, str, func, lineno, file);
407         }
408
409         return newstr;
410 }
411 )
412
413 #else
414
415 /* If astmm is in use, let it handle these.  Otherwise, it will report that
416    all allocations are coming from this header file */
417
418 #define ast_malloc(a)           malloc(a)
419 #define ast_calloc(a,b)         calloc(a,b)
420 #define ast_realloc(a,b)        realloc(a,b)
421 #define ast_strdup(a)           strdup(a)
422 #define ast_strndup(a,b)        strndup(a,b)
423
424 #endif /* AST_DEBUG_MALLOC */
425
426 #if !defined(ast_strdupa) && defined(__GNUC__)
427 /*!
428   \brief duplicate a string in memory from the stack
429   \param s The string to duplicate
430
431   This macro will duplicate the given string.  It returns a pointer to the stack
432   allocatted memory for the new string.
433 */
434 #define ast_strdupa(s)                                                    \
435         (__extension__                                                    \
436         ({                                                                \
437                 const char *__old = (s);                                  \
438                 size_t __len = strlen(__old) + 1;                         \
439                 char *__new = __builtin_alloca(__len);                    \
440                 if (__builtin_expect(!__new, 0))                          \
441                         ast_log(LOG_ERROR, "Stack Allocation Error in"    \
442                                 "function '%s' at line '%d' of '%s'!\n",  \
443                                 __PRETTY_FUNCTION__, __LINE__, __FILE__); \
444                 else                                                      \
445                         memcpy (__new, __old, __len);                     \
446                 __new;                                                    \
447         }))
448 #endif
449
450 #endif /* _ASTERISK_UTILS_H */