Thu Mar 25 10:39:14 2010

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 
00114 /* Many headers need 'ast_channel' to be defined */
00115 struct ast_channel;
00116 
00117 /* Many headers need 'ast_module' to be defined */
00118 struct ast_module;
00119 
00120 /*!
00121  * \brief Reload asterisk modules.
00122  * \param name the name of the module to reload
00123  *
00124  * This function reloads the specified module, or if no modules are specified,
00125  * it will reload all loaded modules.
00126  *
00127  * \note Modules are reloaded using their reload() functions, not unloading
00128  * them and loading them again.
00129  * 
00130  * \return Zero if the specified module was not found, 1 if the module was
00131  * found but cannot be reloaded, -1 if a reload operation is already in
00132  * progress, and 2 if the specfied module was found and reloaded.
00133  */
00134 int ast_module_reload(const char *name);
00135 
00136 /*!
00137  * \brief Process reload requests received during startup.
00138  *
00139  * This function requests that the loader execute the pending reload requests
00140  * that were queued during server startup.
00141  *
00142  * \note This function will do nothing if the server has not completely started
00143  *       up.  Once called, the reload queue is emptied, and further invocations
00144  *       will have no affect.
00145  */
00146 void ast_process_pending_reloads(void);
00147 
00148 /*!
00149  * \brief Register a function to be executed before Asterisk exits.
00150  * \param func The callback function to use.
00151  *
00152  * \return Zero on success, -1 on error.
00153  */
00154 int ast_register_atexit(void (*func)(void));
00155 
00156 /*!   
00157  * \brief Unregister a function registered with ast_register_atexit().
00158  * \param func The callback function to unregister.   
00159  */
00160 void ast_unregister_atexit(void (*func)(void));
00161 
00162 #if !defined(LOW_MEMORY)
00163 /*!
00164  * \brief Register the version of a source code file with the core.
00165  * \param file the source file name
00166  * \param version the version string (typically a CVS revision keyword string)
00167  * \return nothing
00168  *
00169  * This function should not be called directly, but instead the
00170  * ASTERISK_FILE_VERSION macro should be used to register a file with the core.
00171  */
00172 void ast_register_file_version(const char *file, const char *version);
00173 
00174 /*!
00175  * \brief Unregister a source code file from the core.
00176  * \param file the source file name
00177  * \return nothing
00178  *
00179  * This function should not be called directly, but instead the
00180  * ASTERISK_FILE_VERSION macro should be used to automatically unregister
00181  * the file when the module is unloaded.
00182  */
00183 void ast_unregister_file_version(const char *file);
00184 
00185 /*!
00186  * \brief Register/unregister a source code file with the core.
00187  * \param file the source file name
00188  * \param version the version string (typically a CVS revision keyword string)
00189  *
00190  * This macro will place a file-scope constructor and destructor into the
00191  * source of the module using it; this will cause the version of this file
00192  * to registered with the Asterisk core (and unregistered) at the appropriate
00193  * times.
00194  *
00195  * Example:
00196  *
00197  * \code
00198  * ASTERISK_FILE_VERSION(__FILE__, "\$Revision\$")
00199  * \endcode
00200  *
00201  * \note The dollar signs above have been protected with backslashes to keep
00202  * CVS from modifying them in this file; under normal circumstances they would
00203  * not be present and CVS would expand the Revision keyword into the file's
00204  * revision number.
00205  */
00206 #ifdef MTX_PROFILE
00207 #define  HAVE_MTX_PROFILE  /* used in lock.h */
00208 #define ASTERISK_FILE_VERSION(file, version) \
00209    static int mtx_prof = -1;       /* profile mutex */   \
00210    static void __attribute__((constructor)) __register_file_version(void) \
00211    { \
00212       mtx_prof = ast_add_profile("mtx_lock_" file, 0);   \
00213       ast_register_file_version(file, version); \
00214    } \
00215    static void __attribute__((destructor)) __unregister_file_version(void) \
00216    { \
00217       ast_unregister_file_version(file); \
00218    }
00219 #else /* !MTX_PROFILE */
00220 #define ASTERISK_FILE_VERSION(file, version) \
00221    static void __attribute__((constructor)) __register_file_version(void) \
00222    { \
00223       ast_register_file_version(file, version); \
00224    } \
00225    static void __attribute__((destructor)) __unregister_file_version(void) \
00226    { \
00227       ast_unregister_file_version(file); \
00228    }
00229 #endif /* !MTX_PROFILE */
00230 #else /* LOW_MEMORY */
00231 #define ASTERISK_FILE_VERSION(file, x)
00232 #endif /* LOW_MEMORY */
00233 
00234 #if !defined(LOW_MEMORY)
00235 /*!
00236  * \brief support for event profiling
00237  *
00238  * (note, this must be documented a lot more)
00239  * ast_add_profile allocates a generic 'counter' with a given name,
00240  * which can be shown with the command 'show profile <name>'
00241  *
00242  * The counter accumulates positive or negative values supplied by
00243  * ast_add_profile(), dividing them by the 'scale' value passed in the
00244  * create call, and also counts the number of 'events'.
00245  * Values can also be taked by the TSC counter on ia32 architectures,
00246  * in which case you can mark the start of an event calling ast_mark(id, 1)
00247  * and then the end of the event with ast_mark(id, 0).
00248  * For non-i386 architectures, these two calls return 0.
00249  */
00250 int ast_add_profile(const char *, uint64_t scale);
00251 int64_t ast_profile(int, int64_t);
00252 int64_t ast_mark(int, int start1_stop0);
00253 #else /* LOW_MEMORY */
00254 #define ast_add_profile(a, b) 0
00255 #define ast_profile(a, b) do { } while (0)
00256 #define ast_mark(a, b) do { } while (0)
00257 #endif /* LOW_MEMORY */
00258 
00259 #endif /* _ASTERISK_H */

Generated on Thu Mar 25 10:39:14 2010 for Asterisk - the Open Source PBX by  doxygen 1.4.7