Sat Aug 6 00:39:22 2011

Asterisk developer's documentation


asterisk.h

Go to the documentation of this file.
00001 /*
00002  * Asterisk -- A telephony toolkit for Linux.
00003  *
00004  * General Definitions for Asterisk top level program
00005  * 
00006  * Copyright (C) 1999-2006, Digium, Inc.
00007  *
00008  * Mark Spencer <markster@digium.com>
00009  *
00010  * This program is free software, distributed under the terms of
00011  * the GNU General Public License
00012  */
00013 
00014 /*! \file
00015  * \brief Asterisk main include file. File version handling, generic pbx functions.
00016  */
00017 
00018 #ifndef _ASTERISK_H
00019 #define _ASTERISK_H
00020 
00021 #include "asterisk/autoconfig.h"
00022 
00023 #if !defined(NO_MALLOC_DEBUG) && !defined(STANDALONE_AEL) && defined(MALLOC_DEBUG)
00024 #include "asterisk/astmm.h"
00025 #endif
00026 
00027 #include "asterisk/compat.h"
00028 
00029 #include "asterisk/paths.h"
00030 
00031 #define DEFAULT_LANGUAGE "en"
00032 
00033 #define DEFAULT_SAMPLE_RATE 8000
00034 #define DEFAULT_SAMPLES_PER_MS  ((DEFAULT_SAMPLE_RATE)/1000)
00035 #define  setpriority __PLEASE_USE_ast_set_priority_INSTEAD_OF_setpriority__
00036 #define  sched_setscheduler   __PLEASE_USE_ast_set_priority_INSTEAD_OF_sched_setscheduler__
00037 
00038 #if defined(DEBUG_FD_LEAKS) && !defined(STANDALONE) && !defined(STANDALONE_AEL)
00039 /* These includes are all about ordering */
00040 #include <stdio.h>
00041 #include <sys/types.h>
00042 #include <sys/stat.h>
00043 #include <sys/socket.h>
00044 #include <unistd.h>
00045 #include <fcntl.h>
00046 
00047 #define  open(a,...) __ast_fdleak_open(__FILE__,__LINE__,__PRETTY_FUNCTION__, a, __VA_ARGS__)
00048 #define pipe(a)   __ast_fdleak_pipe(a, __FILE__,__LINE__,__PRETTY_FUNCTION__)
00049 #define socket(a,b,c)   __ast_fdleak_socket(a, b, c, __FILE__,__LINE__,__PRETTY_FUNCTION__)
00050 #define close(a)  __ast_fdleak_close(a)
00051 #define  fopen(a,b)  __ast_fdleak_fopen(a, b, __FILE__,__LINE__,__PRETTY_FUNCTION__)
00052 #define  fclose(a)   __ast_fdleak_fclose(a)
00053 #define  dup2(a,b)   __ast_fdleak_dup2(a, b, __FILE__,__LINE__,__PRETTY_FUNCTION__)
00054 #define dup(a) __ast_fdleak_dup(a, __FILE__,__LINE__,__PRETTY_FUNCTION__)
00055 
00056 #if defined(__cplusplus) || defined(c_plusplus)
00057 extern "C" {
00058 #endif
00059 int __ast_fdleak_open(const char *file, int line, const char *func, const char *path, int flags, ...);
00060 int __ast_fdleak_pipe(int *fds, const char *file, int line, const char *func);
00061 int __ast_fdleak_socket(int domain, int type, int protocol, const char *file, int line, const char *func);
00062 int __ast_fdleak_close(int fd);
00063 FILE *__ast_fdleak_fopen(const char *path, const char *mode, const char *file, int line, const char *func);
00064 int __ast_fdleak_fclose(FILE *ptr);
00065 int __ast_fdleak_dup2(int oldfd, int newfd, const char *file, int line, const char *func);
00066 int __ast_fdleak_dup(int oldfd, const char *file, int line, const char *func);
00067 #if defined(__cplusplus) || defined(c_plusplus)
00068 }
00069 #endif
00070 #endif
00071 
00072 /* provided in asterisk.c */
00073 extern char ast_config_AST_CONFIG_DIR[PATH_MAX];
00074 extern char ast_config_AST_CONFIG_FILE[PATH_MAX];
00075 extern char ast_config_AST_MODULE_DIR[PATH_MAX];
00076 extern char ast_config_AST_SPOOL_DIR[PATH_MAX];
00077 extern char ast_config_AST_MONITOR_DIR[PATH_MAX];
00078 extern char ast_config_AST_VAR_DIR[PATH_MAX];
00079 extern char ast_config_AST_DATA_DIR[PATH_MAX];
00080 extern char ast_config_AST_LOG_DIR[PATH_MAX];
00081 extern char ast_config_AST_AGI_DIR[PATH_MAX];
00082 extern char ast_config_AST_DB[PATH_MAX];
00083 extern char ast_config_AST_KEY_DIR[PATH_MAX];
00084 extern char ast_config_AST_PID[PATH_MAX];
00085 extern char ast_config_AST_SOCKET[PATH_MAX];
00086 extern char ast_config_AST_RUN_DIR[PATH_MAX];
00087 extern char ast_config_AST_RUN_USER[PATH_MAX];
00088 extern char ast_config_AST_RUN_GROUP[PATH_MAX];
00089 extern char ast_config_AST_CTL_PERMISSIONS[PATH_MAX];
00090 extern char ast_config_AST_CTL_OWNER[PATH_MAX];
00091 extern char ast_config_AST_CTL_GROUP[PATH_MAX];
00092 extern char ast_config_AST_CTL[PATH_MAX];
00093 extern char ast_config_AST_SYSTEM_NAME[20];
00094 
00095 int ast_set_priority(int);       /*!< Provided by asterisk.c */
00096 int load_modules(unsigned int);        /*!< Provided by loader.c */
00097 int load_pbx(void);           /*!< Provided by pbx.c */
00098 int init_logger(void);           /*!< Provided by logger.c */
00099 void close_logger(void);         /*!< Provided by logger.c */
00100 int reload_logger(int);          /*!< Provided by logger.c */
00101 int init_framer(void);           /*!< Provided by frame.c */
00102 int ast_term_init(void);         /*!< Provided by term.c */
00103 int astdb_init(void);            /*!< Provided by db.c */
00104 void ast_channels_init(void);       /*!< Provided by channel.c */
00105 void ast_builtins_init(void);       /*!< Provided by cli.c */
00106 int dnsmgr_init(void);           /*!< Provided by dnsmgr.c */ 
00107 void dnsmgr_start_refresh(void);    /*!< Provided by dnsmgr.c */
00108 int dnsmgr_reload(void);         /*!< Provided by dnsmgr.c */
00109 void threadstorage_init(void);         /*!< Provided by threadstorage.c */
00110 int astobj2_init(void);          /*! Provided by astobj2.c */
00111 void ast_autoservice_init(void);    /*!< Provided by autoservice.c */
00112 int ast_fd_init(void);           /*!< Provided by astfd.c */
00113 int ast_test_init(void);                        /*!< Provided by test.c */
00114 int ast_pbx_init(void);                         /*!< Provided by pbx.c */
00115 
00116 /* Many headers need 'ast_channel' to be defined */
00117 struct ast_channel;
00118 
00119 /* Many headers need 'ast_module' to be defined */
00120 struct ast_module;
00121 
00122 /*!
00123  * \brief Reload asterisk modules.
00124  * \param name the name of the module to reload
00125  *
00126  * This function reloads the specified module, or if no modules are specified,
00127  * it will reload all loaded modules.
00128  *
00129  * \note Modules are reloaded using their reload() functions, not unloading
00130  * them and loading them again.
00131  * 
00132  * \return Zero if the specified module was not found, 1 if the module was
00133  * found but cannot be reloaded, -1 if a reload operation is already in
00134  * progress, and 2 if the specfied module was found and reloaded.
00135  */
00136 int ast_module_reload(const char *name);
00137 
00138 /*!
00139  * \brief Process reload requests received during startup.
00140  *
00141  * This function requests that the loader execute the pending reload requests
00142  * that were queued during server startup.
00143  *
00144  * \note This function will do nothing if the server has not completely started
00145  *       up.  Once called, the reload queue is emptied, and further invocations
00146  *       will have no affect.
00147  */
00148 void ast_process_pending_reloads(void);
00149 
00150 /*!
00151  * \brief Register a function to be executed before Asterisk exits.
00152  * \param func The callback function to use.
00153  *
00154  * \return Zero on success, -1 on error.
00155  */
00156 int ast_register_atexit(void (*func)(void));
00157 
00158 /*!   
00159  * \brief Unregister a function registered with ast_register_atexit().
00160  * \param func The callback function to unregister.   
00161  */
00162 void ast_unregister_atexit(void (*func)(void));
00163 
00164 #if !defined(LOW_MEMORY)
00165 /*!
00166  * \brief Register the version of a source code file with the core.
00167  * \param file the source file name
00168  * \param version the version string (typically a CVS revision keyword string)
00169  * \return nothing
00170  *
00171  * This function should not be called directly, but instead the
00172  * ASTERISK_FILE_VERSION macro should be used to register a file with the core.
00173  */
00174 void ast_register_file_version(const char *file, const char *version);
00175 
00176 /*!
00177  * \brief Unregister a source code file from the core.
00178  * \param file the source file name
00179  * \return nothing
00180  *
00181  * This function should not be called directly, but instead the
00182  * ASTERISK_FILE_VERSION macro should be used to automatically unregister
00183  * the file when the module is unloaded.
00184  */
00185 void ast_unregister_file_version(const char *file);
00186 
00187 /*!
00188  * \brief Register/unregister a source code file with the core.
00189  * \param file the source file name
00190  * \param version the version string (typically a CVS revision keyword string)
00191  *
00192  * This macro will place a file-scope constructor and destructor into the
00193  * source of the module using it; this will cause the version of this file
00194  * to registered with the Asterisk core (and unregistered) at the appropriate
00195  * times.
00196  *
00197  * Example:
00198  *
00199  * \code
00200  * ASTERISK_FILE_VERSION(__FILE__, "\$Revision\$")
00201  * \endcode
00202  *
00203  * \note The dollar signs above have been protected with backslashes to keep
00204  * CVS from modifying them in this file; under normal circumstances they would
00205  * not be present and CVS would expand the Revision keyword into the file's
00206  * revision number.
00207  */
00208 #ifdef MTX_PROFILE
00209 #define  HAVE_MTX_PROFILE  /* used in lock.h */
00210 #define ASTERISK_FILE_VERSION(file, version) \
00211    static int mtx_prof = -1;       /* profile mutex */   \
00212    static void __attribute__((constructor)) __register_file_version(void) \
00213    { \
00214       mtx_prof = ast_add_profile("mtx_lock_" file, 0);   \
00215       ast_register_file_version(file, version); \
00216    } \
00217    static void __attribute__((destructor)) __unregister_file_version(void) \
00218    { \
00219       ast_unregister_file_version(file); \
00220    }
00221 #else /* !MTX_PROFILE */
00222 #define ASTERISK_FILE_VERSION(file, version) \
00223    static void __attribute__((constructor)) __register_file_version(void) \
00224    { \
00225       ast_register_file_version(file, version); \
00226    } \
00227    static void __attribute__((destructor)) __unregister_file_version(void) \
00228    { \
00229       ast_unregister_file_version(file); \
00230    }
00231 #endif /* !MTX_PROFILE */
00232 #else /* LOW_MEMORY */
00233 #define ASTERISK_FILE_VERSION(file, x)
00234 #endif /* LOW_MEMORY */
00235 
00236 #if !defined(LOW_MEMORY)
00237 /*!
00238  * \brief support for event profiling
00239  *
00240  * (note, this must be documented a lot more)
00241  * ast_add_profile allocates a generic 'counter' with a given name,
00242  * which can be shown with the command 'show profile <name>'
00243  *
00244  * The counter accumulates positive or negative values supplied by
00245  * ast_add_profile(), dividing them by the 'scale' value passed in the
00246  * create call, and also counts the number of 'events'.
00247  * Values can also be taked by the TSC counter on ia32 architectures,
00248  * in which case you can mark the start of an event calling ast_mark(id, 1)
00249  * and then the end of the event with ast_mark(id, 0).
00250  * For non-i386 architectures, these two calls return 0.
00251  */
00252 int ast_add_profile(const char *, uint64_t scale);
00253 int64_t ast_profile(int, int64_t);
00254 int64_t ast_mark(int, int start1_stop0);
00255 #else /* LOW_MEMORY */
00256 #define ast_add_profile(a, b) 0
00257 #define ast_profile(a, b) do { } while (0)
00258 #define ast_mark(a, b) do { } while (0)
00259 #endif /* LOW_MEMORY */
00260 
00261 #endif /* _ASTERISK_H */

Generated on Sat Aug 6 00:39:22 2011 for Asterisk - the Open Source PBX by  doxygen 1.4.7