Thu Apr 8 01:21:45 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 531 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().

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

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

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

int64_t ast_mark ( int  ,
int  start1_stop0 
)

Definition at line 596 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().

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

int64_t ast_profile ( int  ,
int64_t   
)

Definition at line 561 of file asterisk.c.

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

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

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 772 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(), load_module(), and main().

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

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

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

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

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

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

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

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 302 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.

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

Generated on 8 Apr 2010 for Asterisk - the Open Source PBX by  doxygen 1.6.1