Tue Mar 2 17:32:36 2010

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 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
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)
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 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(), dbinit(), dictate_exec(), extenspy_exec(), festival_exec(), handle_cli_file_convert(), handle_pri_set_debug_file(), 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 CVS 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 CVS from modifying them in this file; under normal circumstances they would not be present and CVS would expand the Revision keyword into the file's revision number.

Definition at line 163 of file asterisk.h.

#define bcopy   0x__dont_use_bcopy__use_memmove_instead()

Definition at line 223 of file asterisk.h.

#define bzero   0x__dont_use_bzero__use_memset_instead""

Definition at line 222 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 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 'show profile <name>'

The counter accumulates positive or negative values supplied by 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 532 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, profile_entry::scale, and profile_entry::value.

Referenced by extension_match_core().

00533 {
00534    int l = sizeof(struct profile_data);
00535    int n = 10; /* default entries */
00536 
00537    if (prof_data == NULL) {
00538       prof_data = ast_calloc(1, l + n*sizeof(struct profile_entry));
00539       if (prof_data == NULL)
00540          return -1;
00541       prof_data->entries = 0;
00542       prof_data->max_size = n;
00543    }
00544    if (prof_data->entries >= prof_data->max_size) {
00545       void *p;
00546       n = prof_data->max_size + 20;
00547       p = ast_realloc(prof_data, l + n*sizeof(struct profile_entry));
00548       if (p == NULL)
00549          return -1;
00550       prof_data = p;
00551       prof_data->max_size = n;
00552    }
00553    n = prof_data->entries++;
00554    prof_data->e[n].name = ast_strdup(name);
00555    prof_data->e[n].value = 0;
00556    prof_data->e[n].events = 0;
00557    prof_data->e[n].mark = 0;
00558    prof_data->e[n].scale = scale;
00559    return n;
00560 }

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 322 of file asterisk.c.

References AST_RWLIST_TRAVERSE_SAFE_BEGIN, AST_RWLIST_TRAVERSE_SAFE_END, AST_RWLIST_UNLOCK, and AST_RWLIST_WRLOCK.

Referenced by manager_modulecheck().

00323 {
00324    struct file_version *iterator;
00325 
00326    AST_RWLIST_WRLOCK(&file_versions);
00327    AST_RWLIST_TRAVERSE_SAFE_BEGIN(&file_versions, iterator, list) {
00328       if (!strcasecmp(iterator->file, file))
00329          break;
00330    }
00331    AST_RWLIST_TRAVERSE_SAFE_END;
00332    AST_RWLIST_UNLOCK(&file_versions);
00333    if (iterator)
00334       return iterator->version;
00335    return NULL;
00336 }

int64_t ast_mark ( int  ,
int  start1_stop0 
)

Definition at line 597 of file asterisk.c.

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

Referenced by extension_match_core().

00598 {
00599    if (!prof_data || i < 0 || i > prof_data->entries) /* invalid index */
00600       return 0;
00601    if (startstop == 1)
00602       prof_data->e[i].mark = rdtsc();
00603    else {
00604       prof_data->e[i].mark = (rdtsc() - prof_data->e[i].mark);
00605       if (prof_data->e[i].scale > 1)
00606          prof_data->e[i].mark /= prof_data->e[i].scale;
00607       prof_data->e[i].value += prof_data->e[i].mark;
00608       prof_data->e[i].events++;
00609    }
00610    return prof_data->e[i].mark;
00611 }

int64_t ast_profile ( int  ,
int64_t   
)

Definition at line 562 of file asterisk.c.

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

00563 {
00564    if (!prof_data || i < 0 || i > prof_data->entries) /* invalid index */
00565       return 0;
00566    if (prof_data->e[i].scale > 1)
00567       delta /= prof_data->e[i].scale;
00568    prof_data->e[i].value += delta;
00569    prof_data->e[i].events++;
00570    return prof_data->e[i].value;
00571 }

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 773 of file asterisk.c.

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

Referenced by do_reload(), and load_module().

00774 {
00775    struct ast_atexit *ae;
00776 
00777    if (!(ae = ast_calloc(1, sizeof(*ae))))
00778       return -1;
00779 
00780    ae->func = func;
00781 
00782    ast_unregister_atexit(func);  
00783 
00784    AST_RWLIST_WRLOCK(&atexits);
00785    AST_RWLIST_INSERT_HEAD(&atexits, ae, list);
00786    AST_RWLIST_UNLOCK(&atexits);
00787 
00788    return 0;
00789 }

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 CVS 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 282 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().

00283 {
00284    struct file_version *new;
00285    char *work;
00286    size_t version_length;
00287 
00288    work = ast_strdupa(version);
00289    work = ast_strip(ast_strip_quoted(work, "$", "$"));
00290    version_length = strlen(work) + 1;
00291    
00292    if (!(new = ast_calloc(1, sizeof(*new) + version_length)))
00293       return;
00294 
00295    new->file = file;
00296    new->version = (char *) new + sizeof(*new);
00297    memcpy(new->version, work, version_length);
00298    AST_RWLIST_WRLOCK(&file_versions);
00299    AST_RWLIST_INSERT_HEAD(&file_versions, new, list);
00300    AST_RWLIST_UNLOCK(&file_versions);
00301 }

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 1297 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().

01298 {
01299    struct sched_param sched;
01300    memset(&sched, 0, sizeof(sched));
01301 #ifdef __linux__
01302    if (pri) {  
01303       sched.sched_priority = 10;
01304       if (sched_setscheduler(0, SCHED_RR, &sched)) {
01305          ast_log(LOG_WARNING, "Unable to set high priority\n");
01306          return -1;
01307       } else
01308          if (option_verbose)
01309             ast_verbose("Set to realtime thread\n");
01310    } else {
01311       sched.sched_priority = 0;
01312       /* According to the manpage, these parameters can never fail. */
01313       sched_setscheduler(0, SCHED_OTHER, &sched);
01314    }
01315 #else
01316    if (pri) {
01317       if (setpriority(PRIO_PROCESS, 0, -10) == -1) {
01318          ast_log(LOG_WARNING, "Unable to set high priority\n");
01319          return -1;
01320       } else
01321          if (option_verbose)
01322             ast_verbose("Set to high priority\n");
01323    } else {
01324       /* According to the manpage, these parameters can never fail. */
01325       setpriority(PRIO_PROCESS, 0, 0);
01326    }
01327 #endif
01328    return 0;
01329 }

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 791 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, and ast_atexit::func.

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

00792 {
00793    struct ast_atexit *ae = NULL;
00794 
00795    AST_RWLIST_WRLOCK(&atexits);
00796    AST_RWLIST_TRAVERSE_SAFE_BEGIN(&atexits, ae, list) {
00797       if (ae->func == func) {
00798          AST_RWLIST_REMOVE_CURRENT(list);
00799          break;
00800       }
00801    }
00802    AST_RWLIST_TRAVERSE_SAFE_END;
00803    AST_RWLIST_UNLOCK(&atexits);
00804 
00805    free(ae);
00806 }

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 303 of file asterisk.c.

References ast_free, AST_RWLIST_REMOVE_CURRENT, AST_RWLIST_TRAVERSE_SAFE_BEGIN, AST_RWLIST_TRAVERSE_SAFE_END, AST_RWLIST_UNLOCK, and AST_RWLIST_WRLOCK.

00304 {
00305    struct file_version *find;
00306 
00307    AST_RWLIST_WRLOCK(&file_versions);
00308    AST_RWLIST_TRAVERSE_SAFE_BEGIN(&file_versions, find, list) {
00309       if (!strcasecmp(find->file, file)) {
00310          AST_RWLIST_REMOVE_CURRENT(list);
00311          break;
00312       }
00313    }
00314    AST_RWLIST_TRAVERSE_SAFE_END;
00315    AST_RWLIST_UNLOCK(&file_versions);
00316 
00317    if (find)
00318       ast_free(find);
00319 }

Generated on 2 Mar 2010 for Asterisk - the Open Source PBX by  doxygen 1.6.1