Tue Jul 14 23:09:39 2009

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 int __ast_fdleak_open(const char *file, int line, const char *func, const char *path, int flags, ...);
00057 int __ast_fdleak_pipe(int *fds, const char *file, int line, const char *func);
00058 int __ast_fdleak_socket(int domain, int type, int protocol, const char *file, int line, const char *func);
00059 int __ast_fdleak_close(int fd);
00060 FILE *__ast_fdleak_fopen(const char *path, const char *mode, const char *file, int line, const char *func);
00061 int __ast_fdleak_fclose(FILE *ptr);
00062 int __ast_fdleak_dup2(int oldfd, int newfd, const char *file, int line, const char *func);
00063 int __ast_fdleak_dup(int oldfd, const char *file, int line, const char *func);
00064 #endif
00065 
00066 /* provided in asterisk.c */
00067 extern char ast_config_AST_CONFIG_DIR[PATH_MAX];
00068 extern char ast_config_AST_CONFIG_FILE[PATH_MAX];
00069 extern char ast_config_AST_MODULE_DIR[PATH_MAX];
00070 extern char ast_config_AST_SPOOL_DIR[PATH_MAX];
00071 extern char ast_config_AST_MONITOR_DIR[PATH_MAX];
00072 extern char ast_config_AST_VAR_DIR[PATH_MAX];
00073 extern char ast_config_AST_DATA_DIR[PATH_MAX];
00074 extern char ast_config_AST_LOG_DIR[PATH_MAX];
00075 extern char ast_config_AST_AGI_DIR[PATH_MAX];
00076 extern char ast_config_AST_DB[PATH_MAX];
00077 extern char ast_config_AST_KEY_DIR[PATH_MAX];
00078 extern char ast_config_AST_PID[PATH_MAX];
00079 extern char ast_config_AST_SOCKET[PATH_MAX];
00080 extern char ast_config_AST_RUN_DIR[PATH_MAX];
00081 extern char ast_config_AST_RUN_USER[PATH_MAX];
00082 extern char ast_config_AST_RUN_GROUP[PATH_MAX];
00083 extern char ast_config_AST_CTL_PERMISSIONS[PATH_MAX];
00084 extern char ast_config_AST_CTL_OWNER[PATH_MAX];
00085 extern char ast_config_AST_CTL_GROUP[PATH_MAX];
00086 extern char ast_config_AST_CTL[PATH_MAX];
00087 extern char ast_config_AST_SYSTEM_NAME[20];
00088 
00089 int ast_set_priority(int);       /*!< Provided by asterisk.c */
00090 int load_modules(unsigned int);        /*!< Provided by loader.c */
00091 int load_pbx(void);           /*!< Provided by pbx.c */
00092 int init_logger(void);           /*!< Provided by logger.c */
00093 void close_logger(void);         /*!< Provided by logger.c */
00094 int reload_logger(int);          /*!< Provided by logger.c */
00095 int init_framer(void);           /*!< Provided by frame.c */
00096 int ast_term_init(void);         /*!< Provided by term.c */
00097 int astdb_init(void);            /*!< Provided by db.c */
00098 void ast_channels_init(void);       /*!< Provided by channel.c */
00099 void ast_builtins_init(void);       /*!< Provided by cli.c */
00100 int dnsmgr_init(void);           /*!< Provided by dnsmgr.c */ 
00101 void dnsmgr_start_refresh(void);    /*!< Provided by dnsmgr.c */
00102 int dnsmgr_reload(void);         /*!< Provided by dnsmgr.c */
00103 void threadstorage_init(void);         /*!< Provided by threadstorage.c */
00104 int astobj2_init(void);          /*! Provided by astobj2.c */
00105 void ast_autoservice_init(void);    /*!< Provided by autoservice.c */
00106 int ast_fd_init(void);           /*!< Provided by astfd.c */
00107 
00108 /* Many headers need 'ast_channel' to be defined */
00109 struct ast_channel;
00110 
00111 /* Many headers need 'ast_module' to be defined */
00112 struct ast_module;
00113 
00114 /*!
00115  * \brief Reload asterisk modules.
00116  * \param name the name of the module to reload
00117  *
00118  * This function reloads the specified module, or if no modules are specified,
00119  * it will reload all loaded modules.
00120  *
00121  * \note Modules are reloaded using their reload() functions, not unloading
00122  * them and loading them again.
00123  * 
00124  * \return Zero if the specified module was not found, 1 if the module was
00125  * found but cannot be reloaded, -1 if a reload operation is already in
00126  * progress, and 2 if the specfied module was found and reloaded.
00127  */
00128 int ast_module_reload(const char *name);
00129 
00130 /*!
00131  * \brief Process reload requests received during startup.
00132  *
00133  * This function requests that the loader execute the pending reload requests
00134  * that were queued during server startup.
00135  *
00136  * \note This function will do nothing if the server has not completely started
00137  *       up.  Once called, the reload queue is emptied, and further invocations
00138  *       will have no affect.
00139  */
00140 void ast_process_pending_reloads(void);
00141 
00142 /*!
00143  * \brief Register a function to be executed before Asterisk exits.
00144  * \param func The callback function to use.
00145  *
00146  * \return Zero on success, -1 on error.
00147  */
00148 int ast_register_atexit(void (*func)(void));
00149 
00150 /*!   
00151  * \brief Unregister a function registered with ast_register_atexit().
00152  * \param func The callback function to unregister.   
00153  */
00154 void ast_unregister_atexit(void (*func)(void));
00155 
00156 #if !defined(LOW_MEMORY)
00157 /*!
00158  * \brief Register the version of a source code file with the core.
00159  * \param file the source file name
00160  * \param version the version string (typically a CVS revision keyword string)
00161  * \return nothing
00162  *
00163  * This function should not be called directly, but instead the
00164  * ASTERISK_FILE_VERSION macro should be used to register a file with the core.
00165  */
00166 void ast_register_file_version(const char *file, const char *version);
00167 
00168 /*!
00169  * \brief Unregister a source code file from the core.
00170  * \param file the source file name
00171  * \return nothing
00172  *
00173  * This function should not be called directly, but instead the
00174  * ASTERISK_FILE_VERSION macro should be used to automatically unregister
00175  * the file when the module is unloaded.
00176  */
00177 void ast_unregister_file_version(const char *file);
00178 
00179 /*!
00180  * \brief Register/unregister a source code file with the core.
00181  * \param file the source file name
00182  * \param version the version string (typically a CVS revision keyword string)
00183  *
00184  * This macro will place a file-scope constructor and destructor into the
00185  * source of the module using it; this will cause the version of this file
00186  * to registered with the Asterisk core (and unregistered) at the appropriate
00187  * times.
00188  *
00189  * Example:
00190  *
00191  * \code
00192  * ASTERISK_FILE_VERSION(__FILE__, "\$Revision\$")
00193  * \endcode
00194  *
00195  * \note The dollar signs above have been protected with backslashes to keep
00196  * CVS from modifying them in this file; under normal circumstances they would
00197  * not be present and CVS would expand the Revision keyword into the file's
00198  * revision number.
00199  */
00200 #ifdef MTX_PROFILE
00201 #define  HAVE_MTX_PROFILE  /* used in lock.h */
00202 #define ASTERISK_FILE_VERSION(file, version) \
00203    static int mtx_prof = -1;       /* profile mutex */   \
00204    static void __attribute__((constructor)) __register_file_version(void) \
00205    { \
00206       mtx_prof = ast_add_profile("mtx_lock_" file, 0);   \
00207       ast_register_file_version(file, version); \
00208    } \
00209    static void __attribute__((destructor)) __unregister_file_version(void) \
00210    { \
00211       ast_unregister_file_version(file); \
00212    }
00213 #else /* !MTX_PROFILE */
00214 #define ASTERISK_FILE_VERSION(file, version) \
00215    static void __attribute__((constructor)) __register_file_version(void) \
00216    { \
00217       ast_register_file_version(file, version); \
00218    } \
00219    static void __attribute__((destructor)) __unregister_file_version(void) \
00220    { \
00221       ast_unregister_file_version(file); \
00222    }
00223 #endif /* !MTX_PROFILE */
00224 #else /* LOW_MEMORY */
00225 #define ASTERISK_FILE_VERSION(file, x)
00226 #endif /* LOW_MEMORY */
00227 
00228 #if !defined(LOW_MEMORY)
00229 /*!
00230  * \brief support for event profiling
00231  *
00232  * (note, this must be documented a lot more)
00233  * ast_add_profile allocates a generic 'counter' with a given name,
00234  * which can be shown with the command 'show profile <name>'
00235  *
00236  * The counter accumulates positive or negative values supplied by
00237  * ast_add_profile(), dividing them by the 'scale' value passed in the
00238  * create call, and also counts the number of 'events'.
00239  * Values can also be taked by the TSC counter on ia32 architectures,
00240  * in which case you can mark the start of an event calling ast_mark(id, 1)
00241  * and then the end of the event with ast_mark(id, 0).
00242  * For non-i386 architectures, these two calls return 0.
00243  */
00244 int ast_add_profile(const char *, uint64_t scale);
00245 int64_t ast_profile(int, int64_t);
00246 int64_t ast_mark(int, int start1_stop0);
00247 #else /* LOW_MEMORY */
00248 #define ast_add_profile(a, b) 0
00249 #define ast_profile(a, b) do { } while (0)
00250 #define ast_mark(a, b) do { } while (0)
00251 #endif /* LOW_MEMORY */
00252 
00253 #endif /* _ASTERISK_H */

Generated on Tue Jul 14 23:09:39 2009 for Asterisk - the Open Source PBX by  doxygen 1.4.7