Thu Sep 7 01:03:05 2017

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

Generated on 7 Sep 2017 for Asterisk - The Open Source Telephony Project by  doxygen 1.6.1