Fri Feb 10 06:34:56 2012

Asterisk developer's documentation

asterisk.h File Reference

Asterisk main include file. File version handling, generic pbx functions. More...

#include "asterisk/autoconfig.h"
#include "asterisk/compat.h"

Include dependency graph for asterisk.h:

Go to the source code of this file.

Defines

#define __stringify(x)   __stringify_1(x)
#define __stringify_1(x)   #x
#define AST_DIR_MODE   0777
#define AST_FILE_MODE   0666
#define ASTERISK_FILE_VERSION(file, version)
 Register/unregister a source code file with the core.
#define bcopy   0x__dont_use_bcopy__use_memmove_instead()
#define bzero   0x__dont_use_bzero__use_memset_instead""
#define DEFAULT_LANGUAGE   "en"
#define DEFAULT_SAMPLE_RATE   8000
#define DEFAULT_SAMPLES_PER_MS   ((DEFAULT_SAMPLE_RATE)/1000)
#define sched_setscheduler   __PLEASE_USE_ast_set_priority_INSTEAD_OF_sched_setscheduler__
#define setpriority   __PLEASE_USE_ast_set_priority_INSTEAD_OF_setpriority__

Functions

int ast_add_profile (const char *, uint64_t scale)
 support for event profiling
char * ast_complete_source_filename (const char *partial, int n)
int ast_fd_init (void)
const char * ast_file_version_find (const char *file)
 Find version for given module name.
int64_t ast_mark (int, int start1_stop0)
int ast_pbx_init (void)
int64_t ast_profile (int, int64_t)
int ast_register_atexit (void(*func)(void))
 Register a function to be executed before Asterisk exits.
void ast_register_file_version (const char *file, const char *version)
 Register the version of a source code file with the core.
int ast_set_priority (int)
 We set ourselves to a high priority, that we might pre-empt everything else. If your PBX has heavy activity on it, this is a good thing.
void ast_unregister_atexit (void(*func)(void))
 Unregister a function registered with ast_register_atexit().
void ast_unregister_file_version (const char *file)
 Unregister a source code file from the core.

Detailed Description

Asterisk main include file. File version handling, generic pbx functions.

Definition in file asterisk.h.

Define Documentation

#define __stringify ( x   )     __stringify_1(x)

Definition at line 229 of file asterisk.h.

#define __stringify_1 ( x   )     #x

Definition at line 228 of file asterisk.h.

#define AST_DIR_MODE   0777

Definition at line 33 of file asterisk.h.

#define AST_FILE_MODE   0666

Definition at line 36 of file asterisk.h.

Referenced by __ast_play_and_record(), action_createconfig(), ast_lock_path_lockfile(), ast_monitor_start(), chanspy_exec(), copy(), dictate_exec(), extenspy_exec(), festival_exec(), handle_cli_file_convert(), handle_recordfile(), load_module(), record_exec(), recordthread(), sms_log(), and try_firmware().

#define ASTERISK_FILE_VERSION ( file,
version   ) 

Register/unregister a source code file with the core.

Parameters:
file the source file name
version the version string (typically a SVN revision keyword string)
This macro will place a file-scope constructor and destructor into the source of the module using it; this will cause the version of this file to registered with the Asterisk core (and unregistered) at the appropriate times.

Example:

 ASTERISK_FILE_VERSION(__FILE__, "\$Revision\$")

Note:
The dollar signs above have been protected with backslashes to keep SVN from modifying them in this file; under normal circumstances they would not be present and SVN would expand the Revision keyword into the file's revision number.

Definition at line 164 of file asterisk.h.

#define bcopy   0x__dont_use_bcopy__use_memmove_instead()

Definition at line 225 of file asterisk.h.

#define bzero   0x__dont_use_bzero__use_memset_instead""

Definition at line 224 of file asterisk.h.

#define DEFAULT_LANGUAGE   "en"

Definition at line 39 of file asterisk.h.

Referenced by fileexists_core().

#define DEFAULT_SAMPLE_RATE   8000

Definition at line 41 of file asterisk.h.

Referenced by ast_dsp_new(), check_header(), ogg_vorbis_open(), ogg_vorbis_rewrite(), setformat(), and write_header().

#define DEFAULT_SAMPLES_PER_MS   ((DEFAULT_SAMPLE_RATE)/1000)

Definition at line 42 of file asterisk.h.

Referenced by ast_stream_fastforward(), ast_stream_rewind(), and isAnsweringMachine().

#define sched_setscheduler   __PLEASE_USE_ast_set_priority_INSTEAD_OF_sched_setscheduler__

Definition at line 44 of file asterisk.h.

Referenced by ast_set_priority().

#define setpriority   __PLEASE_USE_ast_set_priority_INSTEAD_OF_setpriority__

Definition at line 43 of file asterisk.h.

Referenced by ast_set_priority().

Function Documentation

int ast_add_profile ( const char *  name,
uint64_t  scale 
)

support for event profiling

(note, this must be documented a lot more) ast_add_profile allocates a generic 'counter' with a given name, which can be shown with the command 'core show profile <name>'

The counter accumulates positive or negative values supplied by

See also:
ast_add_profile(), dividing them by the 'scale' value passed in the create call, and also counts the number of 'events'. Values can also be taked by the TSC counter on ia32 architectures, in which case you can mark the start of an event calling ast_mark(id, 1) and then the end of the event with ast_mark(id, 0). For non-i386 architectures, these two calls return 0.
support for event profiling

Returns:
Returns the identifier of the counter.

Definition at line 707 of file asterisk.c.

References ast_calloc, ast_realloc, ast_strdup, profile_data::e, profile_data::entries, profile_entry::events, profile_entry::mark, profile_data::max_size, profile_entry::name, prof_data, profile_entry::scale, and profile_entry::value.

Referenced by extension_match_core().

00708 {
00709    int l = sizeof(struct profile_data);
00710    int n = 10; /* default entries */
00711 
00712    if (prof_data == NULL) {
00713       prof_data = ast_calloc(1, l + n*sizeof(struct profile_entry));
00714       if (prof_data == NULL)
00715          return -1;
00716       prof_data->entries = 0;
00717       prof_data->max_size = n;
00718    }
00719    if (prof_data->entries >= prof_data->max_size) {
00720       void *p;
00721       n = prof_data->max_size + 20;
00722       p = ast_realloc(prof_data, l + n*sizeof(struct profile_entry));
00723       if (p == NULL)
00724          return -1;
00725       prof_data = p;
00726       prof_data->max_size = n;
00727    }
00728    n = prof_data->entries++;
00729    prof_data->e[n].name = ast_strdup(name);
00730    prof_data->e[n].value = 0;
00731    prof_data->e[n].events = 0;
00732    prof_data->e[n].mark = 0;
00733    prof_data->e[n].scale = scale;
00734    return n;
00735 }

char* ast_complete_source_filename ( const char *  partial,
int  n 
)

Definition at line 356 of file asterisk.c.

References AST_RWLIST_RDLOCK, AST_RWLIST_TRAVERSE, AST_RWLIST_UNLOCK, ast_strdup, file_version::file, len(), and ast_atexit::list.

Referenced by handle_verbose().

00357 {
00358    struct file_version *find;
00359    size_t len = strlen(partial);
00360    int count = 0;
00361    char *res = NULL;
00362 
00363    AST_RWLIST_RDLOCK(&file_versions);
00364    AST_RWLIST_TRAVERSE(&file_versions, find, list) {
00365       if (!strncasecmp(find->file, partial, len) && ++count > n) {
00366          res = ast_strdup(find->file);
00367          break;
00368       }
00369    }
00370    AST_RWLIST_UNLOCK(&file_versions);
00371    return res;
00372 }

int ast_fd_init ( void   ) 

Provided by astfd.c

Definition at line 275 of file astfd.c.

Referenced by main().

00276 {
00277    return 0;
00278 }

const char* ast_file_version_find ( const char *  file  ) 

Find version for given module name.

Parameters:
file Module name (i.e. chan_sip.so)
Returns:
version string or NULL if the module is not found

Definition at line 375 of file asterisk.c.

References AST_RWLIST_TRAVERSE, AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, file_version::file, ast_atexit::list, and file_version::version.

Referenced by manager_modulecheck().

00376 {
00377    struct file_version *iterator;
00378 
00379    AST_RWLIST_WRLOCK(&file_versions);
00380    AST_RWLIST_TRAVERSE(&file_versions, iterator, list) {
00381       if (!strcasecmp(iterator->file, file))
00382          break;
00383    }
00384    AST_RWLIST_UNLOCK(&file_versions);
00385    if (iterator)
00386       return iterator->version;
00387    return NULL;
00388 }

int64_t ast_mark ( int  ,
int  start1_stop0 
)

Definition at line 772 of file asterisk.c.

References profile_data::e, profile_data::entries, profile_entry::events, profile_entry::mark, prof_data, rdtsc(), profile_entry::scale, and profile_entry::value.

Referenced by __ast_pthread_mutex_lock(), and extension_match_core().

00773 {
00774    if (!prof_data || i < 0 || i > prof_data->entries) /* invalid index */
00775       return 0;
00776    if (startstop == 1)
00777       prof_data->e[i].mark = rdtsc();
00778    else {
00779       prof_data->e[i].mark = (rdtsc() - prof_data->e[i].mark);
00780       if (prof_data->e[i].scale > 1)
00781          prof_data->e[i].mark /= prof_data->e[i].scale;
00782       prof_data->e[i].value += prof_data->e[i].mark;
00783       prof_data->e[i].events++;
00784    }
00785    return prof_data->e[i].mark;
00786 }

int ast_pbx_init ( void   ) 

Provided by pbx.c

Definition at line 10833 of file pbx.c.

References ao2_container_alloc, HASH_EXTENHINT_SIZE, hint_cmp(), hint_hash(), hintdevice_cmp_multiple(), hintdevice_hash_cb(), hints, statecbs, and statecbs_cmp().

Referenced by main().

10834 {
10835    hints = ao2_container_alloc(HASH_EXTENHINT_SIZE, hint_hash, hint_cmp);
10836    hintdevices = ao2_container_alloc(HASH_EXTENHINT_SIZE, hintdevice_hash_cb, hintdevice_cmp_multiple);
10837    statecbs = ao2_container_alloc(1, NULL, statecbs_cmp);
10838 
10839    return (hints && hintdevices && statecbs) ? 0 : -1;
10840 }

int64_t ast_profile ( int  ,
int64_t   
)

Definition at line 737 of file asterisk.c.

References profile_data::e, profile_data::entries, profile_entry::events, prof_data, profile_entry::scale, and profile_entry::value.

00738 {
00739    if (!prof_data || i < 0 || i > prof_data->entries) /* invalid index */
00740       return 0;
00741    if (prof_data->e[i].scale > 1)
00742       delta /= prof_data->e[i].scale;
00743    prof_data->e[i].value += delta;
00744    prof_data->e[i].events++;
00745    return prof_data->e[i].value;
00746 }

int ast_register_atexit ( void(*)(void)  func  ) 

Register a function to be executed before Asterisk exits.

Parameters:
func The callback function to use.
Return values:
0 on success.
-1 on error.

Definition at line 948 of file asterisk.c.

References ast_calloc, AST_RWLIST_INSERT_HEAD, AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, ast_unregister_atexit(), ast_atexit::func, and ast_atexit::list.

Referenced by ast_cel_engine_init(), astdb_init(), do_reload(), load_module(), and main().

00949 {
00950    struct ast_atexit *ae;
00951 
00952    if (!(ae = ast_calloc(1, sizeof(*ae))))
00953       return -1;
00954 
00955    ae->func = func;
00956 
00957    ast_unregister_atexit(func);  
00958 
00959    AST_RWLIST_WRLOCK(&atexits);
00960    AST_RWLIST_INSERT_HEAD(&atexits, ae, list);
00961    AST_RWLIST_UNLOCK(&atexits);
00962 
00963    return 0;
00964 }

void ast_register_file_version ( const char *  file,
const char *  version 
)

Register the version of a source code file with the core.

Parameters:
file the source file name
version the version string (typically a SVN revision keyword string)
Returns:
nothing
This function should not be called directly, but instead the ASTERISK_FILE_VERSION macro should be used to register a file with the core.

Definition at line 317 of file asterisk.c.

References ast_calloc, AST_RWLIST_INSERT_HEAD, AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, ast_strdupa, ast_strip(), and ast_strip_quoted().

00318 {
00319    struct file_version *new;
00320    char *work;
00321    size_t version_length;
00322 
00323    work = ast_strdupa(version);
00324    work = ast_strip(ast_strip_quoted(work, "$", "$"));
00325    version_length = strlen(work) + 1;
00326    
00327    if (!(new = ast_calloc(1, sizeof(*new) + version_length)))
00328       return;
00329 
00330    new->file = file;
00331    new->version = (char *) new + sizeof(*new);
00332    memcpy(new->version, work, version_length);
00333    AST_RWLIST_WRLOCK(&file_versions);
00334    AST_RWLIST_INSERT_HEAD(&file_versions, new, list);
00335    AST_RWLIST_UNLOCK(&file_versions);
00336 }

int ast_set_priority ( int   ) 

We set ourselves to a high priority, that we might pre-empt everything else. If your PBX has heavy activity on it, this is a good thing.

Provided by asterisk.c

Definition at line 1581 of file asterisk.c.

References ast_log(), ast_verbose, LOG_WARNING, sched_setscheduler, and setpriority.

Referenced by app_exec(), ast_safe_system(), canary_thread(), icesencode(), launch_script(), main(), mp3play(), NBScatplay(), send_waveform_to_fd(), spawn_mp3(), and spawn_ras().

01582 {
01583    struct sched_param sched;
01584    memset(&sched, 0, sizeof(sched));
01585 #ifdef __linux__
01586    if (pri) {  
01587       sched.sched_priority = 10;
01588       if (sched_setscheduler(0, SCHED_RR, &sched)) {
01589          ast_log(LOG_WARNING, "Unable to set high priority\n");
01590          return -1;
01591       } else
01592          if (option_verbose)
01593             ast_verbose("Set to realtime thread\n");
01594    } else {
01595       sched.sched_priority = 0;
01596       /* According to the manpage, these parameters can never fail. */
01597       sched_setscheduler(0, SCHED_OTHER, &sched);
01598    }
01599 #else
01600    if (pri) {
01601       if (setpriority(PRIO_PROCESS, 0, -10) == -1) {
01602          ast_log(LOG_WARNING, "Unable to set high priority\n");
01603          return -1;
01604       } else
01605          if (option_verbose)
01606             ast_verbose("Set to high priority\n");
01607    } else {
01608       /* According to the manpage, these parameters can never fail. */
01609       setpriority(PRIO_PROCESS, 0, 0);
01610    }
01611 #endif
01612    return 0;
01613 }

void ast_unregister_atexit ( void(*)(void)  func  ) 

Unregister a function registered with ast_register_atexit().

Parameters:
func The callback function to unregister.

Definition at line 966 of file asterisk.c.

References AST_RWLIST_REMOVE_CURRENT, AST_RWLIST_TRAVERSE_SAFE_BEGIN, AST_RWLIST_TRAVERSE_SAFE_END, AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, free, ast_atexit::func, and ast_atexit::list.

Referenced by ast_register_atexit(), do_reload(), and unload_module().

00967 {
00968    struct ast_atexit *ae = NULL;
00969 
00970    AST_RWLIST_WRLOCK(&atexits);
00971    AST_RWLIST_TRAVERSE_SAFE_BEGIN(&atexits, ae, list) {
00972       if (ae->func == func) {
00973          AST_RWLIST_REMOVE_CURRENT(list);
00974          break;
00975       }
00976    }
00977    AST_RWLIST_TRAVERSE_SAFE_END;
00978    AST_RWLIST_UNLOCK(&atexits);
00979 
00980    free(ae);
00981 }

void ast_unregister_file_version ( const char *  file  ) 

Unregister a source code file from the core.

Parameters:
file the source file name
Returns:
nothing
This function should not be called directly, but instead the ASTERISK_FILE_VERSION macro should be used to automatically unregister the file when the module is unloaded.

Definition at line 338 of file asterisk.c.

References ast_free, AST_RWLIST_REMOVE_CURRENT, AST_RWLIST_TRAVERSE_SAFE_BEGIN, AST_RWLIST_TRAVERSE_SAFE_END, AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, file_version::file, and ast_atexit::list.

00339 {
00340    struct file_version *find;
00341 
00342    AST_RWLIST_WRLOCK(&file_versions);
00343    AST_RWLIST_TRAVERSE_SAFE_BEGIN(&file_versions, find, list) {
00344       if (!strcasecmp(find->file, file)) {
00345          AST_RWLIST_REMOVE_CURRENT(list);
00346          break;
00347       }
00348    }
00349    AST_RWLIST_TRAVERSE_SAFE_END;
00350    AST_RWLIST_UNLOCK(&file_versions);
00351 
00352    if (find)
00353       ast_free(find);
00354 }

Generated on Fri Feb 10 06:34:56 2012 for Asterisk - The Open Source Telephony Project by  doxygen 1.5.6