Tue Aug 20 16:34:39 2013

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 /*! ast_xml_escape
00277    \brief Escape reserved characters for use in XML.
00278 
00279    If \a outbuf is too short, the output string will be truncated.
00280    Regardless, the output will always be null terminated.
00281 
00282    \param string String to be converted
00283    \param outbuf Resulting encoded string
00284    \param buflen Size of output buffer
00285    \return 0 for success
00286    \return -1 if buflen is too short.
00287  */
00288 int ast_xml_escape(const char *string, char *outbuf, size_t buflen);
00289 
00290 /*!
00291  * \brief Escape characters found in a quoted string.
00292  *
00293  * \note This function escapes quoted characters based on the 'qdtext' set of
00294  * allowed characters from RFC 3261 section 25.1.
00295  *
00296  * \param string string to be escaped
00297  * \param outbuf resulting escaped string
00298  * \param buflen size of output buffer
00299  * \return a pointer to the escaped string
00300  */
00301 char *ast_escape_quoted(const char *string, char *outbuf, int buflen);
00302 
00303 static force_inline void ast_slinear_saturated_add(short *input, short *value)
00304 {
00305    int res;
00306 
00307    res = (int) *input + *value;
00308    if (res > 32767)
00309       *input = 32767;
00310    else if (res < -32767)
00311       *input = -32767;
00312    else
00313       *input = (short) res;
00314 }
00315 
00316 static force_inline void ast_slinear_saturated_subtract(short *input, short *value)
00317 {
00318    int res;
00319 
00320    res = (int) *input - *value;
00321    if (res > 32767)
00322       *input = 32767;
00323    else if (res < -32767)
00324       *input = -32767;
00325    else
00326       *input = (short) res;
00327 }
00328    
00329 static force_inline void ast_slinear_saturated_multiply(short *input, short *value)
00330 {
00331    int res;
00332 
00333    res = (int) *input * *value;
00334    if (res > 32767)
00335       *input = 32767;
00336    else if (res < -32767)
00337       *input = -32767;
00338    else
00339       *input = (short) res;
00340 }
00341 
00342 static force_inline void ast_slinear_saturated_divide(short *input, short *value)
00343 {
00344    *input /= *value;
00345 }
00346 
00347 #ifdef localtime_r
00348 #undef localtime_r
00349 #endif
00350 #define localtime_r __dont_use_localtime_r_use_ast_localtime_instead__
00351 
00352 int ast_utils_init(void);
00353 int ast_wait_for_input(int fd, int ms);
00354 
00355 /*!
00356    \brief Try to write string, but wait no more than ms milliseconds
00357    before timing out.
00358 
00359    \note If you are calling ast_carefulwrite, it is assumed that you are calling
00360    it on a file descriptor that _DOES_ have NONBLOCK set.  This way,
00361    there is only one system call made to do a write, unless we actually
00362    have a need to wait.  This way, we get better performance.
00363 */
00364 int ast_carefulwrite(int fd, char *s, int len, int timeoutms);
00365 
00366 /*!
00367  * \brief Write data to a file stream with a timeout
00368  *
00369  * \param f the file stream to write to
00370  * \param fd the file description to poll on to know when the file stream can
00371  *        be written to without blocking.
00372  * \param s the buffer to write from
00373  * \param len the number of bytes to write
00374  * \param timeoutms The maximum amount of time to block in this function trying
00375  *        to write, specified in milliseconds.
00376  *
00377  * \note This function assumes that the associated file stream has been set up
00378  *       as non-blocking.
00379  *
00380  * \retval 0 success
00381  * \retval -1 error
00382  */
00383 int ast_careful_fwrite(FILE *f, int fd, const char *s, size_t len, int timeoutms);
00384 
00385 /*
00386  * Thread management support (should be moved to lock.h or a different header)
00387  */
00388 
00389 #define AST_STACKSIZE (((sizeof(void *) * 8 * 8) - 16) * 1024)
00390 
00391 #if defined(LOW_MEMORY)
00392 #define AST_BACKGROUND_STACKSIZE (((sizeof(void *) * 8 * 2) - 16) * 1024)
00393 #else
00394 #define AST_BACKGROUND_STACKSIZE AST_STACKSIZE
00395 #endif
00396 
00397 void ast_register_thread(char *name);
00398 void ast_unregister_thread(void *id);
00399 
00400 int ast_pthread_create_stack(pthread_t *thread, pthread_attr_t *attr, void *(*start_routine)(void *),
00401               void *data, size_t stacksize, const char *file, const char *caller,
00402               int line, const char *start_fn);
00403 
00404 int ast_pthread_create_detached_stack(pthread_t *thread, pthread_attr_t *attr, void*(*start_routine)(void *),
00405              void *data, size_t stacksize, const char *file, const char *caller,
00406              int line, const char *start_fn);
00407 
00408 #define ast_pthread_create(a, b, c, d)             \
00409    ast_pthread_create_stack(a, b, c, d,         \
00410       0, __FILE__, __FUNCTION__, __LINE__, #c)
00411 
00412 #define ast_pthread_create_detached(a, b, c, d)       \
00413    ast_pthread_create_detached_stack(a, b, c, d,      \
00414       0, __FILE__, __FUNCTION__, __LINE__, #c)
00415 
00416 #define ast_pthread_create_background(a, b, c, d)     \
00417    ast_pthread_create_stack(a, b, c, d,         \
00418       AST_BACKGROUND_STACKSIZE,        \
00419       __FILE__, __FUNCTION__, __LINE__, #c)
00420 
00421 #define ast_pthread_create_detached_background(a, b, c, d)  \
00422    ast_pthread_create_detached_stack(a, b, c, d,      \
00423       AST_BACKGROUND_STACKSIZE,        \
00424       __FILE__, __FUNCTION__, __LINE__, #c)
00425 
00426 /* End of thread management support */
00427 
00428 /*!
00429    \brief Process a string to find and replace characters
00430    \param start The string to analyze
00431    \param find The character to find
00432    \param replace_with The character that will replace the one we are looking for
00433 */
00434 char *ast_process_quotes_and_slashes(char *start, char find, char replace_with);
00435 
00436 long int ast_random(void);
00437 
00438 
00439 /*! 
00440  * \brief free() wrapper
00441  *
00442  * ast_free_ptr should be used when a function pointer for free() needs to be passed
00443  * as the argument to a function. Otherwise, astmm will cause seg faults.
00444  */
00445 #ifdef __AST_DEBUG_MALLOC
00446 static void ast_free_ptr(void *ptr) attribute_unused;
00447 static void ast_free_ptr(void *ptr)
00448 {
00449    ast_free(ptr);
00450 }
00451 #else
00452 #define ast_free free
00453 #define ast_free_ptr ast_free
00454 #endif
00455 
00456 #ifndef __AST_DEBUG_MALLOC
00457 
00458 #define MALLOC_FAILURE_MSG \
00459    ast_log(LOG_ERROR, "Memory Allocation Failure in function %s at line %d of %s\n", func, lineno, file);
00460 /*!
00461  * \brief A wrapper for malloc()
00462  *
00463  * ast_malloc() is a wrapper for malloc() that will generate an Asterisk log
00464  * message in the case that the allocation fails.
00465  *
00466  * The argument and return value are the same as malloc()
00467  */
00468 #define ast_malloc(len) \
00469    _ast_malloc((len), __FILE__, __LINE__, __PRETTY_FUNCTION__)
00470 
00471 AST_INLINE_API(
00472 void * attribute_malloc _ast_malloc(size_t len, const char *file, int lineno, const char *func),
00473 {
00474    void *p;
00475 
00476    if (!(p = malloc(len)))
00477       MALLOC_FAILURE_MSG;
00478 
00479    return p;
00480 }
00481 )
00482 
00483 /*!
00484  * \brief A wrapper for calloc()
00485  *
00486  * ast_calloc() is a wrapper for calloc() that will generate an Asterisk log
00487  * message in the case that the allocation fails.
00488  *
00489  * The arguments and return value are the same as calloc()
00490  */
00491 #define ast_calloc(num, len) \
00492    _ast_calloc((num), (len), __FILE__, __LINE__, __PRETTY_FUNCTION__)
00493 
00494 AST_INLINE_API(
00495 void * attribute_malloc _ast_calloc(size_t num, size_t len, const char *file, int lineno, const char *func),
00496 {
00497    void *p;
00498 
00499    if (!(p = calloc(num, len)))
00500       MALLOC_FAILURE_MSG;
00501 
00502    return p;
00503 }
00504 )
00505 
00506 /*!
00507  * \brief A wrapper for calloc() for use in cache pools
00508  *
00509  * ast_calloc_cache() is a wrapper for calloc() that will generate an Asterisk log
00510  * message in the case that the allocation fails. When memory debugging is in use,
00511  * the memory allocated by this function will be marked as 'cache' so it can be
00512  * distinguished from normal memory allocations.
00513  *
00514  * The arguments and return value are the same as calloc()
00515  */
00516 #define ast_calloc_cache(num, len) \
00517    _ast_calloc((num), (len), __FILE__, __LINE__, __PRETTY_FUNCTION__)
00518 
00519 /*!
00520  * \brief A wrapper for realloc()
00521  *
00522  * ast_realloc() is a wrapper for realloc() that will generate an Asterisk log
00523  * message in the case that the allocation fails.
00524  *
00525  * The arguments and return value are the same as realloc()
00526  */
00527 #define ast_realloc(p, len) \
00528    _ast_realloc((p), (len), __FILE__, __LINE__, __PRETTY_FUNCTION__)
00529 
00530 AST_INLINE_API(
00531 void * attribute_malloc _ast_realloc(void *p, size_t len, const char *file, int lineno, const char *func),
00532 {
00533    void *newp;
00534 
00535    if (!(newp = realloc(p, len)))
00536       MALLOC_FAILURE_MSG;
00537 
00538    return newp;
00539 }
00540 )
00541 
00542 /*!
00543  * \brief A wrapper for strdup()
00544  *
00545  * ast_strdup() is a wrapper for strdup() that will generate an Asterisk log
00546  * message in the case that the allocation fails.
00547  *
00548  * ast_strdup(), unlike strdup(), can safely accept a NULL argument. If a NULL
00549  * argument is provided, ast_strdup will return NULL without generating any
00550  * kind of error log message.
00551  *
00552  * The argument and return value are the same as strdup()
00553  */
00554 #define ast_strdup(str) \
00555    _ast_strdup((str), __FILE__, __LINE__, __PRETTY_FUNCTION__)
00556 
00557 AST_INLINE_API(
00558 char * attribute_malloc _ast_strdup(const char *str, const char *file, int lineno, const char *func),
00559 {
00560    char *newstr = NULL;
00561 
00562    if (str) {
00563       if (!(newstr = strdup(str)))
00564          MALLOC_FAILURE_MSG;
00565    }
00566 
00567    return newstr;
00568 }
00569 )
00570 
00571 /*!
00572  * \brief A wrapper for strndup()
00573  *
00574  * ast_strndup() is a wrapper for strndup() that will generate an Asterisk log
00575  * message in the case that the allocation fails.
00576  *
00577  * ast_strndup(), unlike strndup(), can safely accept a NULL argument for the
00578  * string to duplicate. If a NULL argument is provided, ast_strdup will return  
00579  * NULL without generating any kind of error log message.
00580  *
00581  * The arguments and return value are the same as strndup()
00582  */
00583 #define ast_strndup(str, len) \
00584    _ast_strndup((str), (len), __FILE__, __LINE__, __PRETTY_FUNCTION__)
00585 
00586 AST_INLINE_API(
00587 char * attribute_malloc _ast_strndup(const char *str, size_t len, const char *file, int lineno, const char *func),
00588 {
00589    char *newstr = NULL;
00590 
00591    if (str) {
00592       if (!(newstr = strndup(str, len)))
00593          MALLOC_FAILURE_MSG;
00594    }
00595 
00596    return newstr;
00597 }
00598 )
00599 
00600 /*!
00601  * \brief A wrapper for asprintf()
00602  *
00603  * ast_asprintf() is a wrapper for asprintf() 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 asprintf()
00607  */
00608 #define ast_asprintf(ret, fmt, ...) \
00609    _ast_asprintf((ret), __FILE__, __LINE__, __PRETTY_FUNCTION__, fmt, __VA_ARGS__)
00610 
00611 int __attribute__((format(printf, 5, 6)))
00612    _ast_asprintf(char **ret, const char *file, int lineno, const char *func, const char *fmt, ...);
00613 
00614 /*!
00615  * \brief A wrapper for vasprintf()
00616  *
00617  * ast_vasprintf() is a wrapper for vasprintf() that will generate an Asterisk log
00618  * message in the case that the allocation fails.
00619  *
00620  * The arguments and return value are the same as vasprintf()
00621  */
00622 #define ast_vasprintf(ret, fmt, ap) \
00623    _ast_vasprintf((ret), __FILE__, __LINE__, __PRETTY_FUNCTION__, (fmt), (ap))
00624 
00625 AST_INLINE_API(
00626 __attribute__((format(printf, 5, 0)))
00627 int _ast_vasprintf(char **ret, const char *file, int lineno, const char *func, const char *fmt, va_list ap),
00628 {
00629    int res;
00630 
00631    if ((res = vasprintf(ret, fmt, ap)) == -1)
00632       MALLOC_FAILURE_MSG;
00633 
00634    return res;
00635 }
00636 )
00637 
00638 #endif /* AST_DEBUG_MALLOC */
00639 
00640 /*!
00641   \brief call __builtin_alloca to ensure we get gcc builtin semantics
00642   \param size The size of the buffer we want allocated
00643 
00644   This macro will attempt to allocate memory from the stack.  If it fails
00645   you won't get a NULL returned, but a SEGFAULT if you're lucky.
00646 */
00647 #define ast_alloca(size) __builtin_alloca(size)
00648 
00649 #if !defined(ast_strdupa) && defined(__GNUC__)
00650 /*!
00651   \brief duplicate a string in memory from the stack
00652   \param s The string to duplicate
00653 
00654   This macro will duplicate the given string.  It returns a pointer to stack
00655   allocated memory for the new string.
00656 */
00657 #define ast_strdupa(s)                                                    \
00658    (__extension__                                                    \
00659    ({                                                                \
00660       const char *__old = (s);                                  \
00661       size_t __len = strlen(__old) + 1;                         \
00662       char *__new = __builtin_alloca(__len);                    \
00663       memcpy (__new, __old, __len);                             \
00664       __new;                                                    \
00665    }))
00666 #endif
00667 
00668 /*!
00669   \brief Disable PMTU discovery on a socket
00670   \param sock The socket to manipulate
00671   \return Nothing
00672 
00673   On Linux, UDP sockets default to sending packets with the Dont Fragment (DF)
00674   bit set. This is supposedly done to allow the application to do PMTU
00675   discovery, but Asterisk does not do this.
00676 
00677   Because of this, UDP packets sent by Asterisk that are larger than the MTU
00678   of any hop in the path will be lost. This function can be called on a socket
00679   to ensure that the DF bit will not be set.
00680  */
00681 void ast_enable_packet_fragmentation(int sock);
00682 
00683 /*!
00684   \brief Recursively create directory path
00685   \param path The directory path to create
00686   \param mode The permissions with which to try to create the directory
00687   \return 0 on success or an error code otherwise
00688 
00689   Creates a directory path, creating parent directories as needed.
00690  */
00691 int ast_mkdir(const char *path, int mode);
00692 
00693 #define ARRAY_LEN(a) (size_t) (sizeof(a) / sizeof(0[a]))
00694 
00695 
00696 /* Definition for Digest authorization */
00697 struct ast_http_digest {
00698    AST_DECLARE_STRING_FIELDS(
00699       AST_STRING_FIELD(username);
00700       AST_STRING_FIELD(nonce);
00701       AST_STRING_FIELD(uri);
00702       AST_STRING_FIELD(realm);
00703       AST_STRING_FIELD(domain);
00704       AST_STRING_FIELD(response);
00705       AST_STRING_FIELD(cnonce);
00706       AST_STRING_FIELD(opaque);
00707       AST_STRING_FIELD(nc);
00708    );
00709    int qop;    /* Flag set to 1, if we send/recv qop="quth" */
00710 };
00711 
00712 /*!
00713  *\brief Parse digest authorization header.
00714  *\return Returns -1 if we have no auth or something wrong with digest.
00715  *\note This function may be used for Digest request and responce header.
00716  * request arg is set to nonzero, if we parse Digest Request.
00717  * pedantic arg can be set to nonzero if we need to do addition Digest check.
00718  */
00719 int ast_parse_digest(const char *digest, struct ast_http_digest *d, int request, int pedantic);
00720 
00721 
00722 #ifdef AST_DEVMODE
00723 void __ast_assert_failed(int condition, const char *condition_str, const char *file, int line, const char *function);
00724 #define ast_assert(a) _ast_assert(a, # a, __FILE__, __LINE__, __PRETTY_FUNCTION__)
00725 static void force_inline _ast_assert(int condition, const char *condition_str, const char *file, int line, const char *function)
00726 {
00727    if (__builtin_expect(!condition, 1)) {
00728       __ast_assert_failed(condition, condition_str, file, line, function);
00729    }
00730 }
00731 #else
00732 #define ast_assert(a)
00733 #endif
00734 
00735 /*!
00736  * \brief Force a crash if DO_CRASH is defined.
00737  *
00738  * \note If DO_CRASH is not defined then the function returns.
00739  *
00740  * \return Nothing
00741  */
00742 void ast_do_crash(void);
00743 
00744 #include "asterisk/strings.h"
00745 
00746 /*!
00747  * \brief Return the number of bytes used in the alignment of type.
00748  * \param type
00749  * \return The number of bytes required for alignment.
00750  *
00751  * This is really just __alignof__(), but tucked away in this header so we
00752  * don't have to look at the nasty underscores in the source.
00753  */
00754 #define ast_alignof(type) __alignof__(type)
00755 
00756 /*!
00757  * \brief Increase offset so it is a multiple of the required alignment of type.
00758  * \param offset The value that should be increased.
00759  * \param type The data type that offset should be aligned to.
00760  * \return The smallest multiple of alignof(type) larger than or equal to offset.
00761  * \see ast_make_room_for()
00762  *
00763  * Many systems prefer integers to be stored on aligned on memory locations.
00764  * This macro will increase an offset so a value of the supplied type can be
00765  * safely be stored on such a memory location.
00766  *
00767  * Examples:
00768  * ast_align_for(0x17, int64_t) ==> 0x18
00769  * ast_align_for(0x18, int64_t) ==> 0x18
00770  * ast_align_for(0x19, int64_t) ==> 0x20
00771  *
00772  * Don't mind the ugliness, the compiler will optimize it.
00773  */
00774 #define ast_align_for(offset, type) (((offset + __alignof__(type) - 1) / __alignof__(type)) * __alignof__(type))
00775 
00776 /*!
00777  * \brief Increase offset by the required alignment of type and make sure it is
00778  *        a multiple of said alignment.
00779  * \param offset The value that should be increased.
00780  * \param type The data type that room should be reserved for.
00781  * \return The smallest multiple of alignof(type) larger than or equal to offset
00782  *         plus alignof(type).
00783  * \see ast_align_for()
00784  *
00785  * A use case for this is when prepending length fields of type int to a buffer.
00786  * If you keep the offset a multiple of the alignment of the integer type,
00787  * a next block of length+buffer will have the length field automatically
00788  * aligned.
00789  *
00790  * Examples:
00791  * ast_make_room_for(0x17, int64_t) ==> 0x20
00792  * ast_make_room_for(0x18, int64_t) ==> 0x20
00793  * ast_make_room_for(0x19, int64_t) ==> 0x28
00794  *
00795  * Don't mind the ugliness, the compiler will optimize it.
00796  */
00797 #define ast_make_room_for(offset, type) (((offset + (2 * __alignof__(type) - 1)) / __alignof__(type)) * __alignof__(type))
00798 
00799 /*!
00800  * \brief An Entity ID is essentially a MAC address, brief and unique 
00801  */
00802 struct ast_eid {
00803    unsigned char eid[6];
00804 } __attribute__((__packed__));
00805 
00806 /*!
00807  * \brief Global EID
00808  *
00809  * This is set in asterisk.conf, or determined automatically by taking the mac
00810  * address of an Ethernet interface on the system.
00811  */
00812 extern struct ast_eid ast_eid_default;
00813 
00814 /*!
00815  * \brief Fill in an ast_eid with the default eid of this machine
00816  * \since 1.6.1
00817  */
00818 void ast_set_default_eid(struct ast_eid *eid);
00819 
00820 /*!
00821  * /brief Convert an EID to a string
00822  * \since 1.6.1
00823  */
00824 char *ast_eid_to_str(char *s, int maxlen, struct ast_eid *eid);
00825 
00826 /*!
00827  * \brief Convert a string into an EID
00828  *
00829  * This function expects an EID in the format:
00830  *    00:11:22:33:44:55
00831  *
00832  * \return 0 success, non-zero failure
00833  * \since 1.6.1
00834  */
00835 int ast_str_to_eid(struct ast_eid *eid, const char *s);
00836 
00837 /*!
00838  * \brief Compare two EIDs
00839  *
00840  * \return 0 if the two are the same, non-zero otherwise
00841  * \since 1.6.1
00842  */
00843 int ast_eid_cmp(const struct ast_eid *eid1, const struct ast_eid *eid2);
00844 
00845 /*!\brief Resolve a binary to a full pathname
00846  * \param binary Name of the executable to resolve
00847  * \param fullpath Buffer to hold the complete pathname
00848  * \param fullpath_size Size of \a fullpath
00849  * \retval NULL \a binary was not found or the environment variable PATH is not set
00850  * \return \a fullpath
00851  */
00852 char *ast_utils_which(const char *binary, char *fullpath, size_t fullpath_size);
00853 
00854 #endif /* _ASTERISK_UTILS_H */

Generated on 20 Aug 2013 for Asterisk - The Open Source Telephony Project by  doxygen 1.6.1