Mon Mar 19 11:30:30 2012

Asterisk developer's documentation


utils.h

Go to the documentation of this file.
00001 /*
00002  * Asterisk -- An open source telephony toolkit.
00003  *
00004  * Copyright (C) 1999 - 2006, Digium, Inc.
00005  *
00006  * Mark Spencer <markster@digium.com>
00007  *
00008  * See http://www.asterisk.org for more information about
00009  * the Asterisk project. Please do not directly contact
00010  * any of the maintainers of this project for assistance;
00011  * the project provides a web site, mailing lists and IRC
00012  * channels for your use.
00013  *
00014  * This program is free software, distributed under the terms of
00015  * the GNU General Public License Version 2. See the LICENSE file
00016  * at the top of the source tree.
00017  */
00018 
00019 /*! \file
00020  * \brief Utility functions
00021  */
00022 
00023 #ifndef _ASTERISK_UTILS_H
00024 #define _ASTERISK_UTILS_H
00025 
00026 #include "asterisk/network.h"
00027 
00028 #include <time.h> /* we want to override localtime_r */
00029 #include <unistd.h>
00030 #include <string.h>
00031 
00032 #include "asterisk/lock.h"
00033 #include "asterisk/time.h"
00034 #include "asterisk/logger.h"
00035 #include "asterisk/localtime.h"
00036 #include "asterisk/stringfields.h"
00037 
00038 /*!
00039 \note \verbatim
00040    Note:
00041    It is very important to use only unsigned variables to hold
00042    bit flags, as otherwise you can fall prey to the compiler's
00043    sign-extension antics if you try to use the top two bits in
00044    your variable.
00045 
00046    The flag macros below use a set of compiler tricks to verify
00047    that the caller is using an "unsigned int" variable to hold
00048    the flags, and nothing else. If the caller uses any other
00049    type of variable, a warning message similar to this:
00050 
00051    warning: comparison of distinct pointer types lacks cast
00052    will be generated.
00053 
00054    The "dummy" variable below is used to make these comparisons.
00055 
00056    Also note that at -O2 or above, this type-safety checking
00057    does _not_ produce any additional object code at all.
00058  \endverbatim
00059 */
00060 
00061 extern unsigned int __unsigned_int_flags_dummy;
00062 
00063 #define ast_test_flag(p,flag)       ({ \
00064                typeof ((p)->flags) __p = (p)->flags; \
00065                typeof (__unsigned_int_flags_dummy) __x = 0; \
00066                (void) (&__p == &__x); \
00067                ((p)->flags & (flag)); \
00068                })
00069 
00070 #define ast_set_flag(p,flag)     do { \
00071                typeof ((p)->flags) __p = (p)->flags; \
00072                typeof (__unsigned_int_flags_dummy) __x = 0; \
00073                (void) (&__p == &__x); \
00074                ((p)->flags |= (flag)); \
00075                } while(0)
00076 
00077 #define ast_clear_flag(p,flag)      do { \
00078                typeof ((p)->flags) __p = (p)->flags; \
00079                typeof (__unsigned_int_flags_dummy) __x = 0; \
00080                (void) (&__p == &__x); \
00081                ((p)->flags &= ~(flag)); \
00082                } while(0)
00083 
00084 #define ast_copy_flags(dest,src,flagz) do { \
00085                typeof ((dest)->flags) __d = (dest)->flags; \
00086                typeof ((src)->flags) __s = (src)->flags; \
00087                typeof (__unsigned_int_flags_dummy) __x = 0; \
00088                (void) (&__d == &__x); \
00089                (void) (&__s == &__x); \
00090                (dest)->flags &= ~(flagz); \
00091                (dest)->flags |= ((src)->flags & (flagz)); \
00092                } while (0)
00093 
00094 #define ast_set2_flag(p,value,flag) do { \
00095                typeof ((p)->flags) __p = (p)->flags; \
00096                typeof (__unsigned_int_flags_dummy) __x = 0; \
00097                (void) (&__p == &__x); \
00098                if (value) \
00099                   (p)->flags |= (flag); \
00100                else \
00101                   (p)->flags &= ~(flag); \
00102                } while (0)
00103 
00104 #define ast_set_flags_to(p,flag,value) do { \
00105                typeof ((p)->flags) __p = (p)->flags; \
00106                typeof (__unsigned_int_flags_dummy) __x = 0; \
00107                (void) (&__p == &__x); \
00108                (p)->flags &= ~(flag); \
00109                (p)->flags |= (value); \
00110                } while (0)
00111 
00112 
00113 /* The following 64-bit flag code can most likely be erased after app_dial
00114    is reorganized to either reduce the large number of options, or handle
00115    them in some other way. At the time of this writing, app_dial would be
00116    the only user of 64-bit option flags */
00117 
00118 extern uint64_t __unsigned_int_flags_dummy64;
00119 
00120 #define ast_test_flag64(p,flag)     ({ \
00121                typeof ((p)->flags) __p = (p)->flags; \
00122                typeof (__unsigned_int_flags_dummy64) __x = 0; \
00123                (void) (&__p == &__x); \
00124                ((p)->flags & (flag)); \
00125                })
00126 
00127 #define ast_set_flag64(p,flag)      do { \
00128                typeof ((p)->flags) __p = (p)->flags; \
00129                typeof (__unsigned_int_flags_dummy64) __x = 0; \
00130                (void) (&__p == &__x); \
00131                ((p)->flags |= (flag)); \
00132                } while(0)
00133 
00134 #define ast_clear_flag64(p,flag)       do { \
00135                typeof ((p)->flags) __p = (p)->flags; \
00136                typeof (__unsigned_int_flags_dummy64) __x = 0; \
00137                (void) (&__p == &__x); \
00138                ((p)->flags &= ~(flag)); \
00139                } while(0)
00140 
00141 #define ast_copy_flags64(dest,src,flagz)  do { \
00142                typeof ((dest)->flags) __d = (dest)->flags; \
00143                typeof ((src)->flags) __s = (src)->flags; \
00144                typeof (__unsigned_int_flags_dummy64) __x = 0; \
00145                (void) (&__d == &__x); \
00146                (void) (&__s == &__x); \
00147                (dest)->flags &= ~(flagz); \
00148                (dest)->flags |= ((src)->flags & (flagz)); \
00149                } while (0)
00150 
00151 #define ast_set2_flag64(p,value,flag)  do { \
00152                typeof ((p)->flags) __p = (p)->flags; \
00153                typeof (__unsigned_int_flags_dummy64) __x = 0; \
00154                (void) (&__p == &__x); \
00155                if (value) \
00156                   (p)->flags |= (flag); \
00157                else \
00158                   (p)->flags &= ~(flag); \
00159                } while (0)
00160 
00161 #define ast_set_flags_to64(p,flag,value)  do { \
00162                typeof ((p)->flags) __p = (p)->flags; \
00163                typeof (__unsigned_int_flags_dummy64) __x = 0; \
00164                (void) (&__p == &__x); \
00165                (p)->flags &= ~(flag); \
00166                (p)->flags |= (value); \
00167                } while (0)
00168 
00169 
00170 /* Non-type checking variations for non-unsigned int flags.  You
00171    should only use non-unsigned int flags where required by 
00172    protocol etc and if you know what you're doing :)  */
00173 #define ast_test_flag_nonstd(p,flag) \
00174                ((p)->flags & (flag))
00175 
00176 #define ast_set_flag_nonstd(p,flag)       do { \
00177                ((p)->flags |= (flag)); \
00178                } while(0)
00179 
00180 #define ast_clear_flag_nonstd(p,flag)     do { \
00181                ((p)->flags &= ~(flag)); \
00182                } while(0)
00183 
00184 #define ast_copy_flags_nonstd(dest,src,flagz)   do { \
00185                (dest)->flags &= ~(flagz); \
00186                (dest)->flags |= ((src)->flags & (flagz)); \
00187                } while (0)
00188 
00189 #define ast_set2_flag_nonstd(p,value,flag)   do { \
00190                if (value) \
00191                   (p)->flags |= (flag); \
00192                else \
00193                   (p)->flags &= ~(flag); \
00194                } while (0)
00195 
00196 #define AST_FLAGS_ALL UINT_MAX
00197 
00198 /*! \brief Structure used to handle boolean flags 
00199 */
00200 struct ast_flags {
00201    unsigned int flags;
00202 };
00203 
00204 /*! \brief Structure used to handle a large number of boolean flags == used only in app_dial?
00205 */
00206 struct ast_flags64 {
00207    uint64_t flags;
00208 };
00209 
00210 struct ast_hostent {
00211    struct hostent hp;
00212    char buf[1024];
00213 };
00214 
00215 /*! \brief Thread-safe gethostbyname function to use in Asterisk */
00216 struct hostent *ast_gethostbyname(const char *host, struct ast_hostent *hp);
00217 
00218 /*!  \brief Produces MD5 hash based on input string */
00219 void ast_md5_hash(char *output, const char *input);
00220 /*! \brief Produces SHA1 hash based on input string */
00221 void ast_sha1_hash(char *output, const char *input);
00222 
00223 int ast_base64encode_full(char *dst, const unsigned char *src, int srclen, int max, int linebreaks);
00224 
00225 #undef MIN
00226 #define MIN(a, b) ({ typeof(a) __a = (a); typeof(b) __b = (b); ((__a > __b) ? __b : __a);})
00227 #undef MAX
00228 #define MAX(a, b) ({ typeof(a) __a = (a); typeof(b) __b = (b); ((__a < __b) ? __b : __a);})
00229 
00230 /*!
00231  * \brief Encode data in base64
00232  * \param dst the destination buffer
00233  * \param src the source data to be encoded
00234  * \param srclen the number of bytes present in the source buffer
00235  * \param max the maximum number of bytes to write into the destination
00236  *        buffer, *including* the terminating NULL character.
00237  */
00238 int ast_base64encode(char *dst, const unsigned char *src, int srclen, int max);
00239 
00240 /*!
00241  * \brief Decode data from base64
00242  * \param dst the destination buffer
00243  * \param src the source buffer
00244  * \param max The maximum number of bytes to write into the destination
00245  *            buffer.  Note that this function will not ensure that the
00246  *            destination buffer is NULL terminated.  So, in general,
00247  *            this parameter should be sizeof(dst) - 1.
00248  */
00249 int ast_base64decode(unsigned char *dst, const char *src, int max);
00250 
00251 /*! \brief Turn text string to URI-encoded %XX version 
00252  *
00253  * \note 
00254  *  At this point, this function is encoding agnostic; it does not
00255  *  check whether it is fed legal UTF-8. We escape control
00256  *  characters (\x00-\x1F\x7F), '%', and all characters above 0x7F.
00257  *  If do_special_char == 1 we will convert all characters except alnum
00258  *  and the mark set.
00259  *  Outbuf needs to have more memory allocated than the instring
00260  *  to have room for the expansion. Every char that is converted
00261  *  is replaced by three ASCII characters.
00262  *
00263  *  \param string String to be converted
00264  *  \param outbuf Resulting encoded string
00265  *  \param buflen Size of output buffer
00266  *  \param do_special_char Convert all non alphanum characters execept
00267  *         those in the mark set as defined by rfc 3261 section 25.1
00268  */
00269 char *ast_uri_encode(const char *string, char *outbuf, int buflen, int do_special_char);
00270 
00271 /*!   \brief Decode URI, URN, URL (overwrite string)
00272    \param s String to be decoded 
00273  */
00274 void ast_uri_decode(char *s);
00275 
00276 /*!
00277  * \brief Escape characters found in a quoted string.
00278  *
00279  * \note This function escapes quoted characters based on the 'qdtext' set of
00280  * allowed characters from RFC 3261 section 25.1.
00281  *
00282  * \param string string to be escaped
00283  * \param outbuf resulting escaped string
00284  * \param buflen size of output buffer
00285  * \return a pointer to the escaped string
00286  */
00287 char *ast_escape_quoted(const char *string, char *outbuf, int buflen);
00288 
00289 static force_inline void ast_slinear_saturated_add(short *input, short *value)
00290 {
00291    int res;
00292 
00293    res = (int) *input + *value;
00294    if (res > 32767)
00295       *input = 32767;
00296    else if (res < -32767)
00297       *input = -32767;
00298    else
00299       *input = (short) res;
00300 }
00301 
00302 static force_inline void ast_slinear_saturated_subtract(short *input, short *value)
00303 {
00304    int res;
00305 
00306    res = (int) *input - *value;
00307    if (res > 32767)
00308       *input = 32767;
00309    else if (res < -32767)
00310       *input = -32767;
00311    else
00312       *input = (short) res;
00313 }
00314    
00315 static force_inline void ast_slinear_saturated_multiply(short *input, short *value)
00316 {
00317    int res;
00318 
00319    res = (int) *input * *value;
00320    if (res > 32767)
00321       *input = 32767;
00322    else if (res < -32767)
00323       *input = -32767;
00324    else
00325       *input = (short) res;
00326 }
00327 
00328 static force_inline void ast_slinear_saturated_divide(short *input, short *value)
00329 {
00330    *input /= *value;
00331 }
00332 
00333 #ifdef localtime_r
00334 #undef localtime_r
00335 #endif
00336 #define localtime_r __dont_use_localtime_r_use_ast_localtime_instead__
00337 
00338 int ast_utils_init(void);
00339 int ast_wait_for_input(int fd, int ms);
00340 
00341 /*!
00342    \brief Try to write string, but wait no more than ms milliseconds
00343    before timing out.
00344 
00345    \note If you are calling ast_carefulwrite, it is assumed that you are calling
00346    it on a file descriptor that _DOES_ have NONBLOCK set.  This way,
00347    there is only one system call made to do a write, unless we actually
00348    have a need to wait.  This way, we get better performance.
00349 */
00350 int ast_carefulwrite(int fd, char *s, int len, int timeoutms);
00351 
00352 /*!
00353  * \brief Write data to a file stream with a timeout
00354  *
00355  * \param f the file stream to write to
00356  * \param fd the file description to poll on to know when the file stream can
00357  *        be written to without blocking.
00358  * \param s the buffer to write from
00359  * \param len the number of bytes to write
00360  * \param timeoutms The maximum amount of time to block in this function trying
00361  *        to write, specified in milliseconds.
00362  *
00363  * \note This function assumes that the associated file stream has been set up
00364  *       as non-blocking.
00365  *
00366  * \retval 0 success
00367  * \retval -1 error
00368  */
00369 int ast_careful_fwrite(FILE *f, int fd, const char *s, size_t len, int timeoutms);
00370 
00371 /*
00372  * Thread management support (should be moved to lock.h or a different header)
00373  */
00374 
00375 #define AST_STACKSIZE (((sizeof(void *) * 8 * 8) - 16) * 1024)
00376 
00377 #if defined(LOW_MEMORY)
00378 #define AST_BACKGROUND_STACKSIZE (((sizeof(void *) * 8 * 2) - 16) * 1024)
00379 #else
00380 #define AST_BACKGROUND_STACKSIZE AST_STACKSIZE
00381 #endif
00382 
00383 void ast_register_thread(char *name);
00384 void ast_unregister_thread(void *id);
00385 
00386 int ast_pthread_create_stack(pthread_t *thread, pthread_attr_t *attr, void *(*start_routine)(void *),
00387               void *data, size_t stacksize, const char *file, const char *caller,
00388               int line, const char *start_fn);
00389 
00390 int ast_pthread_create_detached_stack(pthread_t *thread, pthread_attr_t *attr, void*(*start_routine)(void *),
00391              void *data, size_t stacksize, const char *file, const char *caller,
00392              int line, const char *start_fn);
00393 
00394 #define ast_pthread_create(a, b, c, d)             \
00395    ast_pthread_create_stack(a, b, c, d,         \
00396       0, __FILE__, __FUNCTION__, __LINE__, #c)
00397 
00398 #define ast_pthread_create_detached(a, b, c, d)       \
00399    ast_pthread_create_detached_stack(a, b, c, d,      \
00400       0, __FILE__, __FUNCTION__, __LINE__, #c)
00401 
00402 #define ast_pthread_create_background(a, b, c, d)     \
00403    ast_pthread_create_stack(a, b, c, d,         \
00404       AST_BACKGROUND_STACKSIZE,        \
00405       __FILE__, __FUNCTION__, __LINE__, #c)
00406 
00407 #define ast_pthread_create_detached_background(a, b, c, d)  \
00408    ast_pthread_create_detached_stack(a, b, c, d,      \
00409       AST_BACKGROUND_STACKSIZE,        \
00410       __FILE__, __FUNCTION__, __LINE__, #c)
00411 
00412 /* End of thread management support */
00413 
00414 /*!
00415    \brief Process a string to find and replace characters
00416    \param start The string to analyze
00417    \param find The character to find
00418    \param replace_with The character that will replace the one we are looking for
00419 */
00420 char *ast_process_quotes_and_slashes(char *start, char find, char replace_with);
00421 
00422 long int ast_random(void);
00423 
00424 
00425 /*! 
00426  * \brief free() wrapper
00427  *
00428  * ast_free_ptr should be used when a function pointer for free() needs to be passed
00429  * as the argument to a function. Otherwise, astmm will cause seg faults.
00430  */
00431 #ifdef __AST_DEBUG_MALLOC
00432 static void ast_free_ptr(void *ptr) attribute_unused;
00433 static void ast_free_ptr(void *ptr)
00434 {
00435    ast_free(ptr);
00436 }
00437 #else
00438 #define ast_free free
00439 #define ast_free_ptr ast_free
00440 #endif
00441 
00442 #ifndef __AST_DEBUG_MALLOC
00443 
00444 #define MALLOC_FAILURE_MSG \
00445    ast_log(LOG_ERROR, "Memory Allocation Failure in function %s at line %d of %s\n", func, lineno, file);
00446 /*!
00447  * \brief A wrapper for malloc()
00448  *
00449  * ast_malloc() is a wrapper for malloc() that will generate an Asterisk log
00450  * message in the case that the allocation fails.
00451  *
00452  * The argument and return value are the same as malloc()
00453  */
00454 #define ast_malloc(len) \
00455    _ast_malloc((len), __FILE__, __LINE__, __PRETTY_FUNCTION__)
00456 
00457 AST_INLINE_API(
00458 void * attribute_malloc _ast_malloc(size_t len, const char *file, int lineno, const char *func),
00459 {
00460    void *p;
00461 
00462    if (!(p = malloc(len)))
00463       MALLOC_FAILURE_MSG;
00464 
00465    return p;
00466 }
00467 )
00468 
00469 /*!
00470  * \brief A wrapper for calloc()
00471  *
00472  * ast_calloc() is a wrapper for calloc() that will generate an Asterisk log
00473  * message in the case that the allocation fails.
00474  *
00475  * The arguments and return value are the same as calloc()
00476  */
00477 #define ast_calloc(num, len) \
00478    _ast_calloc((num), (len), __FILE__, __LINE__, __PRETTY_FUNCTION__)
00479 
00480 AST_INLINE_API(
00481 void * attribute_malloc _ast_calloc(size_t num, size_t len, const char *file, int lineno, const char *func),
00482 {
00483    void *p;
00484 
00485    if (!(p = calloc(num, len)))
00486       MALLOC_FAILURE_MSG;
00487 
00488    return p;
00489 }
00490 )
00491 
00492 /*!
00493  * \brief A wrapper for calloc() for use in cache pools
00494  *
00495  * ast_calloc_cache() is a wrapper for calloc() that will generate an Asterisk log
00496  * message in the case that the allocation fails. When memory debugging is in use,
00497  * the memory allocated by this function will be marked as 'cache' so it can be
00498  * distinguished from normal memory allocations.
00499  *
00500  * The arguments and return value are the same as calloc()
00501  */
00502 #define ast_calloc_cache(num, len) \
00503    _ast_calloc((num), (len), __FILE__, __LINE__, __PRETTY_FUNCTION__)
00504 
00505 /*!
00506  * \brief A wrapper for realloc()
00507  *
00508  * ast_realloc() is a wrapper for realloc() that will generate an Asterisk log
00509  * message in the case that the allocation fails.
00510  *
00511  * The arguments and return value are the same as realloc()
00512  */
00513 #define ast_realloc(p, len) \
00514    _ast_realloc((p), (len), __FILE__, __LINE__, __PRETTY_FUNCTION__)
00515 
00516 AST_INLINE_API(
00517 void * attribute_malloc _ast_realloc(void *p, size_t len, const char *file, int lineno, const char *func),
00518 {
00519    void *newp;
00520 
00521    if (!(newp = realloc(p, len)))
00522       MALLOC_FAILURE_MSG;
00523 
00524    return newp;
00525 }
00526 )
00527 
00528 /*!
00529  * \brief A wrapper for strdup()
00530  *
00531  * ast_strdup() is a wrapper for strdup() that will generate an Asterisk log
00532  * message in the case that the allocation fails.
00533  *
00534  * ast_strdup(), unlike strdup(), can safely accept a NULL argument. If a NULL
00535  * argument is provided, ast_strdup will return NULL without generating any
00536  * kind of error log message.
00537  *
00538  * The argument and return value are the same as strdup()
00539  */
00540 #define ast_strdup(str) \
00541    _ast_strdup((str), __FILE__, __LINE__, __PRETTY_FUNCTION__)
00542 
00543 AST_INLINE_API(
00544 char * attribute_malloc _ast_strdup(const char *str, const char *file, int lineno, const char *func),
00545 {
00546    char *newstr = NULL;
00547 
00548    if (str) {
00549       if (!(newstr = strdup(str)))
00550          MALLOC_FAILURE_MSG;
00551    }
00552 
00553    return newstr;
00554 }
00555 )
00556 
00557 /*!
00558  * \brief A wrapper for strndup()
00559  *
00560  * ast_strndup() is a wrapper for strndup() that will generate an Asterisk log
00561  * message in the case that the allocation fails.
00562  *
00563  * ast_strndup(), unlike strndup(), can safely accept a NULL argument for the
00564  * string to duplicate. If a NULL argument is provided, ast_strdup will return  
00565  * NULL without generating any kind of error log message.
00566  *
00567  * The arguments and return value are the same as strndup()
00568  */
00569 #define ast_strndup(str, len) \
00570    _ast_strndup((str), (len), __FILE__, __LINE__, __PRETTY_FUNCTION__)
00571 
00572 AST_INLINE_API(
00573 char * attribute_malloc _ast_strndup(const char *str, size_t len, const char *file, int lineno, const char *func),
00574 {
00575    char *newstr = NULL;
00576 
00577    if (str) {
00578       if (!(newstr = strndup(str, len)))
00579          MALLOC_FAILURE_MSG;
00580    }
00581 
00582    return newstr;
00583 }
00584 )
00585 
00586 /*!
00587  * \brief A wrapper for asprintf()
00588  *
00589  * ast_asprintf() is a wrapper for asprintf() that will generate an Asterisk log
00590  * message in the case that the allocation fails.
00591  *
00592  * The arguments and return value are the same as asprintf()
00593  */
00594 #define ast_asprintf(ret, fmt, ...) \
00595    _ast_asprintf((ret), __FILE__, __LINE__, __PRETTY_FUNCTION__, fmt, __VA_ARGS__)
00596 
00597 int __attribute__((format(printf, 5, 6)))
00598    _ast_asprintf(char **ret, const char *file, int lineno, const char *func, const char *fmt, ...);
00599 
00600 /*!
00601  * \brief A wrapper for vasprintf()
00602  *
00603  * ast_vasprintf() is a wrapper for vasprintf() that will generate an Asterisk log
00604  * message in the case that the allocation fails.
00605  *
00606  * The arguments and return value are the same as vasprintf()
00607  */
00608 #define ast_vasprintf(ret, fmt, ap) \
00609    _ast_vasprintf((ret), __FILE__, __LINE__, __PRETTY_FUNCTION__, (fmt), (ap))
00610 
00611 AST_INLINE_API(
00612 __attribute__((format(printf, 5, 0)))
00613 int _ast_vasprintf(char **ret, const char *file, int lineno, const char *func, const char *fmt, va_list ap),
00614 {
00615    int res;
00616 
00617    if ((res = vasprintf(ret, fmt, ap)) == -1)
00618       MALLOC_FAILURE_MSG;
00619 
00620    return res;
00621 }
00622 )
00623 
00624 #endif /* AST_DEBUG_MALLOC */
00625 
00626 #if !defined(ast_strdupa) && defined(__GNUC__)
00627 /*!
00628   \brief duplicate a string in memory from the stack
00629   \param s The string to duplicate
00630 
00631   This macro will duplicate the given string.  It returns a pointer to the stack
00632   allocatted memory for the new string.
00633 */
00634 #define ast_strdupa(s)                                                    \
00635    (__extension__                                                    \
00636    ({                                                                \
00637       const char *__old = (s);                                  \
00638       size_t __len = strlen(__old) + 1;                         \
00639       char *__new = __builtin_alloca(__len);                    \
00640       memcpy (__new, __old, __len);                             \
00641       __new;                                                    \
00642    }))
00643 #endif
00644 
00645 /*!
00646   \brief Disable PMTU discovery on a socket
00647   \param sock The socket to manipulate
00648   \return Nothing
00649 
00650   On Linux, UDP sockets default to sending packets with the Dont Fragment (DF)
00651   bit set. This is supposedly done to allow the application to do PMTU
00652   discovery, but Asterisk does not do this.
00653 
00654   Because of this, UDP packets sent by Asterisk that are larger than the MTU
00655   of any hop in the path will be lost. This function can be called on a socket
00656   to ensure that the DF bit will not be set.
00657  */
00658 void ast_enable_packet_fragmentation(int sock);
00659 
00660 /*!
00661   \brief Recursively create directory path
00662   \param path The directory path to create
00663   \param mode The permissions with which to try to create the directory
00664   \return 0 on success or an error code otherwise
00665 
00666   Creates a directory path, creating parent directories as needed.
00667  */
00668 int ast_mkdir(const char *path, int mode);
00669 
00670 #define ARRAY_LEN(a) (size_t) (sizeof(a) / sizeof(0[a]))
00671 
00672 
00673 /* Definition for Digest authorization */
00674 struct ast_http_digest {
00675    AST_DECLARE_STRING_FIELDS(
00676       AST_STRING_FIELD(username);
00677       AST_STRING_FIELD(nonce);
00678       AST_STRING_FIELD(uri);
00679       AST_STRING_FIELD(realm);
00680       AST_STRING_FIELD(domain);
00681       AST_STRING_FIELD(response);
00682       AST_STRING_FIELD(cnonce);
00683       AST_STRING_FIELD(opaque);
00684       AST_STRING_FIELD(nc);
00685    );
00686    int qop;    /* Flag set to 1, if we send/recv qop="quth" */
00687 };
00688 
00689 /*!
00690  *\brief Parse digest authorization header.
00691  *\return Returns -1 if we have no auth or something wrong with digest.
00692  *\note This function may be used for Digest request and responce header.
00693  * request arg is set to nonzero, if we parse Digest Request.
00694  * pedantic arg can be set to nonzero if we need to do addition Digest check.
00695  */
00696 int ast_parse_digest(const char *digest, struct ast_http_digest *d, int request, int pedantic);
00697 
00698 
00699 #ifdef AST_DEVMODE
00700 #define ast_assert(a) _ast_assert(a, # a, __FILE__, __LINE__, __PRETTY_FUNCTION__)
00701 static void force_inline _ast_assert(int condition, const char *condition_str, 
00702    const char *file, int line, const char *function)
00703 {
00704    if (__builtin_expect(!condition, 1)) {
00705       /* Attempt to put it into the logger, but hope that at least someone saw the
00706        * message on stderr ... */
00707       ast_log(__LOG_ERROR, file, line, function, "FRACK!, Failed assertion %s (%d)\n",
00708          condition_str, condition);
00709       fprintf(stderr, "FRACK!, Failed assertion %s (%d) at line %d in %s of %s\n",
00710          condition_str, condition, line, function, file);
00711       /* Give the logger a chance to get the message out, just in case we abort(), or
00712        * Asterisk crashes due to whatever problem just happened after we exit ast_assert(). */
00713       usleep(1);
00714 #ifdef DO_CRASH
00715       abort();
00716       /* Just in case abort() doesn't work or something else super silly,
00717        * and for Qwell's amusement. */
00718       *((int*)0)=0;
00719 #endif
00720    }
00721 }
00722 #else
00723 #define ast_assert(a)
00724 #endif
00725 
00726 #include "asterisk/strings.h"
00727 
00728 /*!
00729  * \brief Return the number of bytes used in the alignment of type.
00730  * \param type
00731  * \return The number of bytes required for alignment.
00732  *
00733  * This is really just __alignof__(), but tucked away in this header so we
00734  * don't have to look at the nasty underscores in the source.
00735  */
00736 #define ast_alignof(type) __alignof__(type)
00737 
00738 /*!
00739  * \brief Increase offset so it is a multiple of the required alignment of type.
00740  * \param offset The value that should be increased.
00741  * \param type The data type that offset should be aligned to.
00742  * \return The smallest multiple of alignof(type) larger than or equal to offset.
00743  * \see ast_make_room_for()
00744  *
00745  * Many systems prefer integers to be stored on aligned on memory locations.
00746  * This macro will increase an offset so a value of the supplied type can be
00747  * safely be stored on such a memory location.
00748  *
00749  * Examples:
00750  * ast_align_for(0x17, int64_t) ==> 0x18
00751  * ast_align_for(0x18, int64_t) ==> 0x18
00752  * ast_align_for(0x19, int64_t) ==> 0x20
00753  *
00754  * Don't mind the ugliness, the compiler will optimize it.
00755  */
00756 #define ast_align_for(offset, type) (((offset + __alignof__(type) - 1) / __alignof__(type)) * __alignof__(type))
00757 
00758 /*!
00759  * \brief Increase offset by the required alignment of type and make sure it is
00760  *        a multiple of said alignment.
00761  * \param offset The value that should be increased.
00762  * \param type The data type that room should be reserved for.
00763  * \return The smallest multiple of alignof(type) larger than or equal to offset
00764  *         plus alignof(type).
00765  * \see ast_align_for()
00766  *
00767  * A use case for this is when prepending length fields of type int to a buffer.
00768  * If you keep the offset a multiple of the alignment of the integer type,
00769  * a next block of length+buffer will have the length field automatically
00770  * aligned.
00771  *
00772  * Examples:
00773  * ast_make_room_for(0x17, int64_t) ==> 0x20
00774  * ast_make_room_for(0x18, int64_t) ==> 0x20
00775  * ast_make_room_for(0x19, int64_t) ==> 0x28
00776  *
00777  * Don't mind the ugliness, the compiler will optimize it.
00778  */
00779 #define ast_make_room_for(offset, type) (((offset + (2 * __alignof__(type) - 1)) / __alignof__(type)) * __alignof__(type))
00780 
00781 /*!
00782  * \brief An Entity ID is essentially a MAC address, brief and unique 
00783  */
00784 struct ast_eid {
00785    unsigned char eid[6];
00786 } __attribute__((__packed__));
00787 
00788 /*!
00789  * \brief Global EID
00790  *
00791  * This is set in asterisk.conf, or determined automatically by taking the mac
00792  * address of an Ethernet interface on the system.
00793  */
00794 extern struct ast_eid ast_eid_default;
00795 
00796 /*!
00797  * \brief Fill in an ast_eid with the default eid of this machine
00798  * \since 1.6.1
00799  */
00800 void ast_set_default_eid(struct ast_eid *eid);
00801 
00802 /*!
00803  * /brief Convert an EID to a string
00804  * \since 1.6.1
00805  */
00806 char *ast_eid_to_str(char *s, int maxlen, struct ast_eid *eid);
00807 
00808 /*!
00809  * \brief Convert a string into an EID
00810  *
00811  * This function expects an EID in the format:
00812  *    00:11:22:33:44:55
00813  *
00814  * \return 0 success, non-zero failure
00815  * \since 1.6.1
00816  */
00817 int ast_str_to_eid(struct ast_eid *eid, const char *s);
00818 
00819 /*!
00820  * \brief Compare two EIDs
00821  *
00822  * \return 0 if the two are the same, non-zero otherwise
00823  * \since 1.6.1
00824  */
00825 int ast_eid_cmp(const struct ast_eid *eid1, const struct ast_eid *eid2);
00826 
00827 /*!\brief Resolve a binary to a full pathname
00828  * \param binary Name of the executable to resolve
00829  * \param fullpath Buffer to hold the complete pathname
00830  * \param fullpath_size Size of \a fullpath
00831  * \retval NULL \a binary was not found or the environment variable PATH is not set
00832  * \return \a fullpath
00833  */
00834 char *ast_utils_which(const char *binary, char *fullpath, size_t fullpath_size);
00835 
00836 #endif /* _ASTERISK_UTILS_H */

Generated on Mon Mar 19 11:30:30 2012 for Asterisk - The Open Source Telephony Project by  doxygen 1.4.7