Wed Jan 8 2020 09:49:57

Asterisk developer's documentation


asterisk.h File Reference

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

Go to the source code of this file.

Macros

#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. More...
 
#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 More...
 
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. More...
 
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. More...
 
int ast_register_cleanup (void(*func)(void))
 Register a function to be executed before Asterisk gracefully exits. More...
 
void ast_register_file_version (const char *file, const char *version)
 Register the version of a source code file with the core. More...
 
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. More...
 
void ast_unregister_atexit (void(*func)(void))
 Unregister a function registered with ast_register_atexit(). More...
 
void ast_unregister_file_version (const char *file)
 Unregister a source code file from the core. More...
 

Detailed Description

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

Definition in file asterisk.h.

Macro Definition Documentation

#define AST_DIR_MODE   0777

Definition at line 33 of file asterisk.h.

#define ASTERISK_FILE_VERSION (   file,
  version 
)

Register/unregister a source code file with the core.

Parameters
filethe source file name
versionthe 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 180 of file asterisk.h.

#define bcopy   0x__dont_use_bcopy__use_memmove_instead()

Definition at line 240 of file asterisk.h.

#define bzero   0x__dont_use_bzero__use_memset_instead""

Definition at line 239 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 '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 710 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().

711 {
712  int l = sizeof(struct profile_data);
713  int n = 10; /* default entries */
714 
715  if (prof_data == NULL) {
716  prof_data = ast_calloc(1, l + n*sizeof(struct profile_entry));
717  if (prof_data == NULL)
718  return -1;
719  prof_data->entries = 0;
720  prof_data->max_size = n;
721  }
722  if (prof_data->entries >= prof_data->max_size) {
723  void *p;
724  n = prof_data->max_size + 20;
725  p = ast_realloc(prof_data, l + n*sizeof(struct profile_entry));
726  if (p == NULL)
727  return -1;
728  prof_data = p;
729  prof_data->max_size = n;
730  }
731  n = prof_data->entries++;
732  prof_data->e[n].name = ast_strdup(name);
733  prof_data->e[n].value = 0;
734  prof_data->e[n].events = 0;
735  prof_data->e[n].mark = 0;
736  prof_data->e[n].scale = scale;
737  return n;
738 }
const char * name
Definition: asterisk.c:692
#define ast_strdup(a)
Definition: astmm.h:109
static struct profile_data * prof_data
Definition: asterisk.c:705
int64_t mark
Definition: asterisk.c:694
int max_size
Definition: asterisk.c:701
uint64_t scale
Definition: asterisk.c:693
int64_t events
Definition: asterisk.c:696
static const char name[]
int64_t value
Definition: asterisk.c:695
Definition: asterisk.c:691
#define ast_calloc(a, b)
Definition: astmm.h:82
struct profile_entry e[0]
Definition: asterisk.c:702
#define ast_realloc(a, b)
Definition: astmm.h:103
char* ast_complete_source_filename ( const char *  partial,
int  n 
)

Definition at line 357 of file asterisk.c.

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

Referenced by handle_verbose().

358 {
359  struct file_version *find;
360  size_t len = strlen(partial);
361  int count = 0;
362  char *res = NULL;
363 
365  AST_RWLIST_TRAVERSE(&file_versions, find, list) {
366  if (!strncasecmp(find->file, partial, len) && ++count > n) {
367  res = ast_strdup(find->file);
368  break;
369  }
370  }
372  return res;
373 }
#define ast_strdup(a)
Definition: astmm.h:109
#define AST_RWLIST_UNLOCK(head)
Attempts to unlock a read/write based list.
Definition: linkedlists.h:150
#define AST_RWLIST_RDLOCK(head)
Read locks a list.
Definition: linkedlists.h:77
#define AST_RWLIST_TRAVERSE
Definition: linkedlists.h:493
static int len(struct ast_channel *chan, const char *cmd, char *data, char *buf, size_t buflen)
int ast_fd_init ( void  )

Provided by astfd.c

Definition at line 289 of file astfd.c.

Referenced by main().

290 {
291  return 0;
292 }
const char* ast_file_version_find ( const char *  file)

Find version for given module name.

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

Definition at line 376 of file asterisk.c.

References AST_RWLIST_TRAVERSE, AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, and ast_atexit::list.

Referenced by manager_modulecheck().

377 {
378  struct file_version *iterator;
379 
381  AST_RWLIST_TRAVERSE(&file_versions, iterator, list) {
382  if (!strcasecmp(iterator->file, file))
383  break;
384  }
386  if (iterator)
387  return iterator->version;
388  return NULL;
389 }
#define AST_RWLIST_WRLOCK(head)
Write locks a list.
Definition: linkedlists.h:51
#define AST_RWLIST_UNLOCK(head)
Attempts to unlock a read/write based list.
Definition: linkedlists.h:150
#define AST_RWLIST_TRAVERSE
Definition: linkedlists.h:493
int64_t ast_mark ( int  ,
int  start1_stop0 
)

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

776 {
777  if (!prof_data || i < 0 || i > prof_data->entries) /* invalid index */
778  return 0;
779  if (startstop == 1)
780  prof_data->e[i].mark = rdtsc();
781  else {
782  prof_data->e[i].mark = (rdtsc() - prof_data->e[i].mark);
783  if (prof_data->e[i].scale > 1)
784  prof_data->e[i].mark /= prof_data->e[i].scale;
785  prof_data->e[i].value += prof_data->e[i].mark;
786  prof_data->e[i].events++;
787  }
788  return prof_data->e[i].mark;
789 }
static struct profile_data * prof_data
Definition: asterisk.c:705
int64_t mark
Definition: asterisk.c:694
uint64_t scale
Definition: asterisk.c:693
int64_t events
Definition: asterisk.c:696
int64_t value
Definition: asterisk.c:695
struct profile_entry e[0]
Definition: asterisk.c:702
static __inline uint64_t rdtsc(void)
Definition: asterisk.c:769
int ast_pbx_init ( void  )

Provided by pbx.c

Definition at line 11407 of file pbx.c.

References ao2_container_alloc, ast_register_atexit(), HASH_EXTENHINT_SIZE, hint_cmp(), hint_hash(), hints, pbx_shutdown(), statecbs, and statecbs_cmp().

Referenced by main().

11408 {
11411 
11413 
11414  return (hints && statecbs) ? 0 : -1;
11415 }
static int hint_cmp(void *obj, void *arg, int flags)
Definition: pbx.c:11375
static int hint_hash(const void *obj, const int flags)
Definition: pbx.c:11355
static struct ao2_container * hints
Definition: pbx.c:1314
static int statecbs_cmp(void *obj, void *arg, int flags)
Definition: pbx.c:11383
#define HASH_EXTENHINT_SIZE
Definition: pbx.c:1028
int ast_register_atexit(void(*func)(void))
Register a function to be executed before Asterisk exits.
Definition: asterisk.c:998
static void pbx_shutdown(void)
Definition: pbx.c:11391
#define ao2_container_alloc(arg1, arg2, arg3)
Definition: astobj2.h:734
static struct ao2_container * statecbs
Definition: pbx.c:1316
int64_t ast_profile ( int  ,
int64_t   
)

Definition at line 740 of file asterisk.c.

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

741 {
742  if (!prof_data || i < 0 || i > prof_data->entries) /* invalid index */
743  return 0;
744  if (prof_data->e[i].scale > 1)
745  delta /= prof_data->e[i].scale;
746  prof_data->e[i].value += delta;
747  prof_data->e[i].events++;
748  return prof_data->e[i].value;
749 }
static struct profile_data * prof_data
Definition: asterisk.c:705
uint64_t scale
Definition: asterisk.c:693
int64_t events
Definition: asterisk.c:696
int64_t value
Definition: asterisk.c:695
struct profile_entry e[0]
Definition: asterisk.c:702
int ast_register_atexit ( void(*)(void)  func)
int ast_register_cleanup ( void(*)(void)  func)

Register a function to be executed before Asterisk gracefully exits.

Since
1.8.29 If Asterisk is immediately shutdown (core stop now, or sending the TERM signal), the callback is not run. When the callbacks are run, they are run in sequence with ast_register_atexit() callbacks, in the reverse order of registration.
Parameters
funcThe callback function to use.
Return values
0on success.
-1on error.

Definition at line 1003 of file asterisk.c.

References ast_atexit::func, and register_atexit().

Referenced by ast_autoservice_init().

1004 {
1005  return register_atexit(func, 1);
1006 }
static int register_atexit(void(*func)(void), int is_cleanup)
Definition: asterisk.c:979
void ast_register_file_version ( const char *  file,
const char *  version 
)

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

Parameters
filethe source file name
versionthe 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 318 of file asterisk.c.

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

319 {
320  struct file_version *new;
321  char *work;
322  size_t version_length;
323 
324  work = ast_strdupa(version);
325  work = ast_strip(ast_strip_quoted(work, "$", "$"));
326  version_length = strlen(work) + 1;
327 
328  if (!(new = ast_calloc(1, sizeof(*new) + version_length)))
329  return;
330 
331  new->file = file;
332  new->version = (char *) new + sizeof(*new);
333  memcpy(new->version, work, version_length);
337 }
uint32_t version
#define AST_RWLIST_WRLOCK(head)
Write locks a list.
Definition: linkedlists.h:51
#define AST_RWLIST_UNLOCK(head)
Attempts to unlock a read/write based list.
Definition: linkedlists.h:150
#define AST_RWLIST_INSERT_HEAD
Definition: linkedlists.h:703
char * ast_strip_quoted(char *s, const char *beg_quotes, const char *end_quotes)
Strip leading/trailing whitespace and quotes from a string.
Definition: utils.c:1431
char * ast_strip(char *s)
Strip leading/trailing whitespace from a string.
Definition: strings.h:155
#define ast_strdupa(s)
duplicate a string in memory from the stack
Definition: utils.h:663
#define ast_calloc(a, b)
Definition: astmm.h:82
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 1650 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().

1651 {
1652  struct sched_param sched;
1653  memset(&sched, 0, sizeof(sched));
1654 #ifdef __linux__
1655  if (pri) {
1656  sched.sched_priority = 10;
1657  if (sched_setscheduler(0, SCHED_RR, &sched)) {
1658  ast_log(LOG_WARNING, "Unable to set high priority\n");
1659  return -1;
1660  } else
1661  if (option_verbose)
1662  ast_verbose("Set to realtime thread\n");
1663  } else {
1664  sched.sched_priority = 0;
1665  /* According to the manpage, these parameters can never fail. */
1666  sched_setscheduler(0, SCHED_OTHER, &sched);
1667  }
1668 #else
1669  if (pri) {
1670  if (setpriority(PRIO_PROCESS, 0, -10) == -1) {
1671  ast_log(LOG_WARNING, "Unable to set high priority\n");
1672  return -1;
1673  } else
1674  if (option_verbose)
1675  ast_verbose("Set to high priority\n");
1676  } else {
1677  /* According to the manpage, these parameters can never fail. */
1678  setpriority(PRIO_PROCESS, 0, 0);
1679  }
1680 #endif
1681  return 0;
1682 }
#define LOG_WARNING
Definition: logger.h:144
void ast_verbose(const char *fmt,...)
Definition: logger.c:1568
Definition: sched.c:57
int option_verbose
Definition: asterisk.c:181
void ast_log(int level, const char *file, int line, const char *function, const char *fmt,...)
Used for sending a log message This is the standard logger function. Probably the only way you will i...
Definition: logger.c:1207
#define sched_setscheduler
Definition: asterisk.h:44
#define setpriority
Definition: asterisk.h:43
void ast_unregister_atexit ( void(*)(void)  func)

Unregister a function registered with ast_register_atexit().

Parameters
funcThe callback function to unregister.

Definition at line 1008 of file asterisk.c.

References __ast_unregister_atexit(), AST_LIST_LOCK, AST_LIST_UNLOCK, and ast_atexit::func.

Referenced by do_reload(), and unload_module().

1009 {
1013 }
static void __ast_unregister_atexit(void(*func)(void))
Definition: asterisk.c:965
#define AST_LIST_LOCK(head)
Locks a list.
Definition: linkedlists.h:39
#define AST_LIST_UNLOCK(head)
Attempts to unlock a list.
Definition: linkedlists.h:139
void ast_unregister_file_version ( const char *  file)

Unregister a source code file from the core.

Parameters
filethe 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 339 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, and ast_atexit::list.

340 {
341  struct file_version *find;
342 
345  if (!strcasecmp(find->file, file)) {
347  break;
348  }
349  }
352 
353  if (find)
354  ast_free(find);
355 }
#define AST_RWLIST_WRLOCK(head)
Write locks a list.
Definition: linkedlists.h:51
#define AST_RWLIST_UNLOCK(head)
Attempts to unlock a read/write based list.
Definition: linkedlists.h:150
#define AST_RWLIST_REMOVE_CURRENT
Definition: linkedlists.h:565
#define AST_RWLIST_TRAVERSE_SAFE_BEGIN
Definition: linkedlists.h:542
#define ast_free(a)
Definition: astmm.h:97
#define AST_RWLIST_TRAVERSE_SAFE_END
Definition: linkedlists.h:602