Sat Apr 26 20:55:08 2008

Asterisk developer's documentation

---

pbx.h File Reference

Core PBX routines and definitions. More...

#include "asterisk/sched.h"
#include "asterisk/channel.h"

Include dependency graph for pbx.h:

Go to the source code of this file.

Data Structures
struct	ast_custom_function
struct	ast_pbx
struct	ast_switch
struct	ast_timing
struct	cfextension_states
Defines
#define	AST_MAX_APP   32
#define	AST_PBX_KEEP   0
#define	AST_PBX_KEEPALIVE   10
#define	AST_PBX_NO_HANGUP_PEER   11
#define	AST_PBX_REPLACE   1
#define	PRIORITY_HINT   -1
Typedefs
typedef int(*)	ast_state_cb_type (char *context, char *id, enum ast_extension_states state, void *data)
Enumerations
enum	ast_extension_states {   AST_EXTENSION_REMOVED = -2, AST_EXTENSION_DEACTIVATED = -1, AST_EXTENSION_NOT_INUSE = 0, AST_EXTENSION_INUSE = 1 << 0,   AST_EXTENSION_BUSY = 1 << 1, AST_EXTENSION_UNAVAILABLE = 1 << 2, AST_EXTENSION_RINGING = 1 << 3 }
enum	ast_pbx_result { AST_PBX_SUCCESS = 0, AST_PBX_FAILED = -1, AST_PBX_CALL_LIMIT = -2 }
Functions
int	ast_active_calls (void)
int	ast_add_extension (const char *context, int replace, const char *extension, int priority, const char *label, const char *callerid, const char *application, void *data, void(*datad)(void *), const char *registrar)
int	ast_add_extension2 (struct ast_context *con, int replace, const char *extension, int priority, const char *label, const char *callerid, const char *application, void *data, void(*datad)(void *), const char *registrar)
int	ast_async_goto (struct ast_channel *chan, const char *context, const char *exten, int priority)
int	ast_async_goto_by_name (const char *chan, const char *context, const char *exten, int priority)
int	ast_async_goto_if_exists (struct ast_channel *chan, char *context, char *exten, int priority)
int	ast_build_timing (struct ast_timing *i, char *info)
int	ast_canmatch_extension (struct ast_channel *c, const char *context, const char *exten, int priority, const char *callerid)
int	ast_check_timing (struct ast_timing *i)
int	ast_context_add_ignorepat (const char *context, const char *ignorepat, const char *registrar)
int	ast_context_add_ignorepat2 (struct ast_context *con, const char *ignorepat, const char *registrar)
int	ast_context_add_include (const char *context, const char *include, const char *registrar)
int	ast_context_add_include2 (struct ast_context *con, const char *include, const char *registrar)
int	ast_context_add_switch (const char *context, const char *sw, const char *data, int eval, const char *registrar)
int	ast_context_add_switch2 (struct ast_context *con, const char *sw, const char *data, int eval, const char *registrar)
ast_context *	ast_context_create (struct ast_context **extcontexts, const char *name, const char *registrar)
void	ast_context_destroy (struct ast_context *con, const char *registrar)
ast_context *	ast_context_find (const char *name)
int	ast_context_remove_extension (const char *context, const char *extension, int priority, const char *registrar)
int	ast_context_remove_extension2 (struct ast_context *con, const char *extension, int priority, const char *registrar)
int	ast_context_remove_ignorepat (const char *context, const char *ignorepat, const char *registrar)
int	ast_context_remove_ignorepat2 (struct ast_context *con, const char *ignorepat, const char *registrar)
int	ast_context_remove_include (const char *context, const char *include, const char *registrar)
int	ast_context_remove_include2 (struct ast_context *con, const char *include, const char *registrar)
int	ast_context_remove_switch (const char *context, const char *sw, const char *data, const char *registrar)
int	ast_context_remove_switch2 (struct ast_context *con, const char *sw, const char *data, const char *registrar)
int	ast_context_verify_includes (struct ast_context *con)
ast_custom_function *	ast_custom_function_find (char *name)
int	ast_custom_function_register (struct ast_custom_function *acf)
int	ast_custom_function_unregister (struct ast_custom_function *acf)
int	ast_exec_extension (struct ast_channel *c, const char *context, const char *exten, int priority, const char *callerid)
int	ast_exists_extension (struct ast_channel *c, const char *context, const char *exten, int priority, const char *callerid)
int	ast_explicit_goto (struct ast_channel *chan, const char *context, const char *exten, int priority)
int	ast_extension_close (const char *pattern, const char *data, int needmore)
int	ast_extension_match (const char *pattern, const char *extension)
int	ast_extension_patmatch (const char *pattern, const char *data)
int	ast_extension_state (struct ast_channel *c, char *context, char *exten)
const char *	ast_extension_state2str (int extension_state)
int	ast_extension_state_add (const char *context, const char *exten, ast_state_cb_type callback, void *data)
int	ast_extension_state_del (int id, ast_state_cb_type callback)
int	ast_findlabel_extension (struct ast_channel *c, const char *context, const char *exten, const char *label, const char *callerid)
int	ast_findlabel_extension2 (struct ast_channel *c, struct ast_context *con, const char *exten, const char *label, const char *callerid)
char *	ast_func_read (struct ast_channel *chan, const char *in, char *workspace, size_t len)
void	ast_func_write (struct ast_channel *chan, const char *in, const char *value)
const char *	ast_get_context_name (struct ast_context *con)
const char *	ast_get_context_registrar (struct ast_context *c)
const char *	ast_get_extension_app (struct ast_exten *e)
void *	ast_get_extension_app_data (struct ast_exten *e)
const char *	ast_get_extension_cidmatch (struct ast_exten *e)
const char *	ast_get_extension_label (struct ast_exten *e)
int	ast_get_extension_matchcid (struct ast_exten *e)
const char *	ast_get_extension_name (struct ast_exten *exten)
int	ast_get_extension_priority (struct ast_exten *exten)
const char *	ast_get_extension_registrar (struct ast_exten *e)
int	ast_get_hint (char *hint, int maxlen, char *name, int maxnamelen, struct ast_channel *c, const char *context, const char *exten)
const char *	ast_get_ignorepat_name (struct ast_ignorepat *ip)
const char *	ast_get_ignorepat_registrar (struct ast_ignorepat *ip)
const char *	ast_get_include_name (struct ast_include *include)
const char *	ast_get_include_registrar (struct ast_include *i)
const char *	ast_get_switch_data (struct ast_sw *sw)
const char *	ast_get_switch_name (struct ast_sw *sw)
const char *	ast_get_switch_registrar (struct ast_sw *sw)
int	ast_goto_if_exists (struct ast_channel *chan, char *context, char *exten, int priority)
void	ast_hint_state_changed (const char *device)
int	ast_ignore_pattern (const char *context, const char *pattern)
int	ast_lock_context (struct ast_context *con)
int	ast_lock_contexts (void)
int	ast_matchmore_extension (struct ast_channel *c, const char *context, const char *exten, int priority, const char *callerid)
void	ast_merge_contexts_and_delete (struct ast_context **extcontexts, const char *registrar)
int	ast_parseable_goto (struct ast_channel *chan, const char *goto_string)
int	ast_pbx_outgoing_app (const char *type, int format, void *data, int timeout, const char *app, const char *appdata, int *reason, int sync, const char *cid_num, const char *cid_name, struct ast_variable *vars, const char *account, struct ast_channel **locked_channel)
int	ast_pbx_outgoing_exten (const char *type, int format, void *data, int timeout, const char *context, const char *exten, int priority, int *reason, int sync, const char *cid_num, const char *cid_name, struct ast_variable *vars, const char *account, struct ast_channel **locked_channel)
enum ast_pbx_result	ast_pbx_run (struct ast_channel *c)
enum ast_pbx_result	ast_pbx_start (struct ast_channel *c)
int	ast_register_application (const char *app, int(*execute)(struct ast_channel *, void *), const char *synopsis, const char *description)
int	ast_register_switch (struct ast_switch *sw)
int	ast_spawn_extension (struct ast_channel *c, const char *context, const char *exten, int priority, const char *callerid)
int	ast_unlock_context (struct ast_context *con)
int	ast_unlock_contexts (void)
int	ast_unregister_application (const char *app)
void	ast_unregister_switch (struct ast_switch *sw)
ast_exten *	ast_walk_context_extensions (struct ast_context *con, struct ast_exten *priority)
ast_ignorepat *	ast_walk_context_ignorepats (struct ast_context *con, struct ast_ignorepat *ip)
ast_include *	ast_walk_context_includes (struct ast_context *con, struct ast_include *inc)
ast_sw *	ast_walk_context_switches (struct ast_context *con, struct ast_sw *sw)
ast_context *	ast_walk_contexts (struct ast_context *con)
ast_exten *	ast_walk_extension_priorities (struct ast_exten *exten, struct ast_exten *priority)
void	pbx_builtin_clear_globals (void)
char *	pbx_builtin_getvar_helper (struct ast_channel *chan, const char *name)
void	pbx_builtin_pushvar_helper (struct ast_channel *chan, const char *name, const char *value)
int	pbx_builtin_serialize_variables (struct ast_channel *chan, char *buf, size_t size)
int	pbx_builtin_setvar (struct ast_channel *chan, void *data)
void	pbx_builtin_setvar_helper (struct ast_channel *chan, const char *name, const char *value)
int	pbx_checkcondition (char *condition)
int	pbx_exec (struct ast_channel *c, struct ast_app *app, void *data, int newstack)
ast_app *	pbx_findapp (const char *app)
void	pbx_retrieve_variable (struct ast_channel *c, const char *var, char **ret, char *workspace, int workspacelen, struct varshead *headp)
int	pbx_set_autofallthrough (int newval)
void	pbx_substitute_variables_helper (struct ast_channel *c, const char *cp1, char *cp2, int count)
void	pbx_substitute_variables_varshead (struct varshead *headp, const char *cp1, char *cp2, int count)

---

Detailed Description

Core PBX routines and definitions.

Definition in file pbx.h.

---

Define Documentation

#define AST_MAX_APP   32

Max length of an application

Definition at line 37 of file pbx.h.

#define AST_PBX_KEEPALIVE   10

Special return values from applications to the PBX

Definition at line 40 of file pbx.h.

#define PRIORITY_HINT   -1

Special Priority for an hint

Definition at line 44 of file pbx.h.

---

Enumeration Type Documentation

enum ast_extension_states

Extension states

Enumerator:

AST_EXTENSION_REMOVED	Extension removed
AST_EXTENSION_DEACTIVATED	Extension hint removed
AST_EXTENSION_NOT_INUSE	No device INUSE or BUSY
AST_EXTENSION_INUSE	One or more devices INUSE
AST_EXTENSION_BUSY	All devices BUSY
AST_EXTENSION_UNAVAILABLE	All devices UNAVAILABLE/UNREGISTERED
AST_EXTENSION_RINGING	All devices RINGING

Definition at line 47 of file pbx.h.

                          {
   /*! Extension removed */
   AST_EXTENSION_REMOVED = -2,
   /*! Extension hint removed */
   AST_EXTENSION_DEACTIVATED = -1,
   /*! No device INUSE or BUSY  */
   AST_EXTENSION_NOT_INUSE = 0,
   /*! One or more devices INUSE */
   AST_EXTENSION_INUSE = 1 << 0,
   /*! All devices BUSY */
   AST_EXTENSION_BUSY = 1 << 1,
   /*! All devices UNAVAILABLE/UNREGISTERED */
   AST_EXTENSION_UNAVAILABLE = 1 << 2,
   /*! All devices RINGING */
   AST_EXTENSION_RINGING = 1 << 3,
};

---

Function Documentation

int ast_add_extension	(	const char *	context,
		int	replace,
		const char *	extension,
		int	priority,
		const char *	label,
		const char *	callerid,
		const char *	application,
		void *	data,
		void(*)(void *)	datad,
		const char *	registrar
	)

Parameters:

	context	context to add the extension to
	replace
	extension	extension to add
	priority	priority level of extension addition
	label	extension label
	callerid	callerid of extension
	application	application to run on the extension with that priority level
	data	data to pass to the application
	datad
	registrar	who registered the extension Add and extension to an extension context. Callerid is a pattern to match CallerID, or NULL to match any callerid Returns 0 on success, -1 on failure

int ast_add_extension2	(	struct ast_context *	con,
		int	replace,
		const char *	extension,
		int	priority,
		const char *	label,
		const char *	callerid,
		const char *	application,
		void *	data,
		void(*)(void *)	datad,
		const char *	registrar
	)

For details about the arguements, check ast_add_extension()

int ast_canmatch_extension	(	struct ast_channel *	c,
		const char *	context,
		const char *	exten,
		int	priority,
		const char *	callerid
	)

Parameters:

	c	not really important
	context	context to serach within
	exten	extension to check
	priority	priority of extension path
	callerid	callerid of extension being searched for If "exten" *could be* a valid extension in this context with or without some more digits, return non-zero. Basically, when this returns 0, no matter what you add to exten, it's not going to be a valid extension anymore

int ast_context_add_ignorepat	(	const char *	context,
		const char *	ignorepat,
		const char *	registrar
	)

Parameters:

	context	which context to add the ignorpattern to
	ignorepat	ignorepattern to set up for the extension
	registrar	registrar of the ignore pattern Adds an ignore pattern to a particular context. Returns 0 on success, -1 on failure

int ast_context_add_include	(	const char *	context,
		const char *	include,
		const char *	registrar
	)

Parameters:

	context	context to add include to
	include	new include to add
	registrar	who's registering it Adds an include taking a char * string as the context parameter Returns 0 on success, -1 on error

int ast_context_add_include2	(	struct ast_context *	con,
		const char *	include,
		const char *	registrar
	)

Parameters:

	con	context to add the include to
	include	include to add
	registrar	who registered the context Adds an include taking a struct ast_context as the first parameter Returns 0 on success, -1 on failure

int ast_context_add_switch	(	const char *	context,
		const char *	sw,
		const char *	data,
		int	eval,
		const char *	registrar
	)

Parameters:

	context	context to which to add the switch
	sw	switch to add
	data	data to pass to switch
	eval	whether to evaluate variables when running switch
	registrar	whoever registered the switch This function registers a switch with the asterisk switch architecture It returns 0 on success, -1 on failure

int ast_context_add_switch2	(	struct ast_context *	con,
		const char *	sw,
		const char *	data,
		int	eval,
		const char *	registrar
	)

See ast_context_add_switch()

struct ast_context* ast_context_create	(	struct ast_context **	extcontexts,
		const char *	name,
		const char *	registrar
	)

Parameters:

	extcontexts	pointer to the ast_context structure pointer
	name	name of the new context
	registrar	registrar of the context This will first search for a context with your name. If it exists already, it will not create a new one. If it does not exist, it will create a new one with the given name and registrar. It returns NULL on failure, and an ast_context structure on success

void ast_context_destroy	(	struct ast_context *	con,
		const char *	registrar
	)

Parameters:

	con	context to destroy
	registrar	who registered it You can optionally leave out either parameter. It will find it based on either the ast_context or the registrar name. Returns nothing

struct ast_context* ast_context_find

(

const char *

name

)

Parameters:

name

name of the context to find Will search for the context with the given name. Returns the ast_context on success, NULL on failure.

int ast_context_remove_extension	(	const char *	context,
		const char *	extension,
		int	priority,
		const char *	registrar
	)

Parameters:

	context	context to remove extension from
	extension	which extension to remove
	priority	priority of extension to remove
	registrar	registrar of the extension This function removes an extension from a given context. Returns 0 on success, -1 on failure

int ast_context_remove_ignorepat	(	const char *	context,
		const char *	ignorepat,
		const char *	registrar
	)

Parameters:

	context	context from which to remove the pattern
	ignorepat	the pattern to remove
	registrar	the registrar of the ignore pattern This removes the given ignorepattern Returns 0 on success, -1 on failure

int ast_context_remove_include	(	const char *	context,
		const char *	include,
		const char *	registrar
	)

See add_include

int ast_context_remove_include2	(	struct ast_context *	con,
		const char *	include,
		const char *	registrar
	)

See add_include2

int ast_context_remove_switch	(	const char *	context,
		const char *	sw,
		const char *	data,
		const char *	registrar
	)

Removes a switch with the given parameters Returns 0 on success, -1 on failure

int ast_context_verify_includes

(

struct ast_context *

con

)

Parameters:

con

context in which to verify the includes Returns 0 if no problems found, -1 if there were any missing context

int ast_exec_extension	(	struct ast_channel *	c,
		const char *	context,
		const char *	exten,
		int	priority,
		const char *	callerid
	)

Parameters:

	c	channel to execute upon
	context	which context extension is in
	exten	extension to execute
	priority	priority to execute within the given extension
	callerid	Caller-ID If it's not available, do whatever you should do for default extensions and halt the thread if necessary. This function does not return, except on error.

int ast_exists_extension	(	struct ast_channel *	c,
		const char *	context,
		const char *	exten,
		int	priority,
		const char *	callerid
	)

Parameters:

	c	this is not important
	context	which context to look in
	exten	which extension to search for
	priority	priority of the action within the extension
	callerid	callerid to search for If an extension within the given context(or callerid) with the given priority is found a non zero value will be returned. Otherwise, 0 is returned.

int ast_extension_match	(	const char *	pattern,
		const char *	extension
	)

Parameters:

	pattern	pattern to match
	extension	extension to check against the pattern. Checks whether or not the given extension matches the given pattern. Returns 1 on match, 0 on failure

int ast_extension_state	(	struct ast_channel *	c,
		char *	context,
		char *	exten
	)

Parameters:

	c	this is not important
	context	which context to look in
	exten	which extension to get state Returns extension state !! = AST_EXTENSION_???

const char* ast_extension_state2str

(

int

extension_state

)

Parameters:

extension_state

is the numerical state delivered by ast_extension_state Returns the state of an extension as string

int ast_extension_state_add	(	const char *	context,
		const char *	exten,
		ast_state_cb_type	callback,
		void *	data
	)

Parameters:

	context	which context to look in
	exten	which extension to get state
	callback	callback to call if state changed
	data	to pass to callback The callback is called if the state for extension is changed Return -1 on failure, ID on success

int ast_extension_state_del	(	int	id,
		ast_state_cb_type	callback
	)

Parameters:

	id	of the callback to delete
	callback	callback Removes the callback from list of callbacks Return 0 on success, -1 on failure

int ast_findlabel_extension	(	struct ast_channel *	c,
		const char *	context,
		const char *	exten,
		const char *	label,
		const char *	callerid
	)

Parameters:

	c	this is not important
	context	which context to look in
	exten	which extension to search for
	label	label of the action within the extension to match to priority
	callerid	callerid to search for If an priority which matches given label in extension or -1 if not found. \

char* ast_func_read	(	struct ast_channel *	chan,
		const char *	in,
		char *	workspace,
		size_t	len
	)

Parameters:

	chan	Channel to execute on
	in	Data containing the function call string
	workspace	A pointer to safe memory to use for a return value
	len	the number of bytes in workspace This application executes an function in read mode on a given channel. It returns a pointer to workspace if the buffer contains any new data or NULL if there was a problem.

void ast_func_write	(	struct ast_channel *	chan,
		const char *	in,
		const char *	value
	)

Parameters:

	chan	Channel to execute on
	in	Data containing the function call string
	value	A value parameter to pass for writing This application executes an function in write mode on a given channel. It has no return value.

int ast_get_hint	(	char *	hint,
		int	maxlen,
		char *	name,
		int	maxnamelen,
		struct ast_channel *	c,
		const char *	context,
		const char *	exten
	)

Parameters:

	hint	buffer for hint
	maxlen	size of hint buffer
	name	buffer for name portion of hint
	maxnamelen	size of name buffer
	c	this is not important
	context	which context to look in
	exten	which extension to search for If an extension within the given context with the priority PRIORITY_HINT is found a non zero value will be returned. Otherwise, 0 is returned.

int ast_ignore_pattern	(	const char *	context,
		const char *	pattern
	)

Parameters:

	context	context to search within
	pattern	to check whether it should be ignored or not Check if a number should be ignored with respect to dialtone cancellation. Returns 0 if the pattern should not be ignored, or non-zero if the pattern should be ignored

int ast_lock_context

(

struct ast_context *

con

)

Parameters:

con

context to lock Locks the context. Returns 0 on success, -1 on failure

int ast_lock_contexts

(

void

)

Locks the context list Returns 0 on success, -1 on error

int ast_matchmore_extension	(	struct ast_channel *	c,
		const char *	context,
		const char *	exten,
		int	priority,
		const char *	callerid
	)

Parameters:

	c	not really important
	context	context to serach within
	exten	extension to check
	priority	priority of extension path
	callerid	callerid of extension being searched for If "exten" *could match* a valid extension in this context with some more digits, return non-zero. Does NOT return non-zero if this is an exact-match only. Basically, when this returns 0, no matter what you add to exten, it's not going to be a valid extension anymore

void ast_merge_contexts_and_delete	(	struct ast_context **	extcontexts,
		const char *	registrar
	)

Parameters:

	extcontexts	pointer to the ast_context structure pointer
	registrar	of the context; if it's set the routine will delete all contexts that belong to that registrar; if NULL only the contexts that are specified in extcontexts

enum ast_pbx_result ast_pbx_run

(

struct ast_channel *

c

)

Parameters:

c

channel to run the pbx on

Returns:

Zero on success, non-zero on failure This executes the PBX on a given channel. It allocates a new PBX structure for the channel, and provides all PBX functionality.

enum ast_pbx_result ast_pbx_start

(

struct ast_channel *

c

)

Parameters:

c

channel to start the pbx on

Returns:

Zero on success, non-zero on failure

int ast_register_application	(	const char *	app,
		int(*)(struct ast_channel *, void *)	execute,
		const char *	synopsis,
		const char *	description
	)

Parameters:

	app	Short name of the application
	execute	a function callback to execute the application
	synopsis	a short description of the application
	description	long description of the application Include a one-line synopsis (e.g. 'hangs up a channel') and a more lengthy, multiline description with more detail, including under what conditions the application will return 0 or -1. This registers an application with asterisks internal application list. Please note: The individual applications themselves are responsible for registering and unregistering CLI commands. It returns 0 on success, -1 on failure.

int ast_register_switch

(

struct ast_switch *

sw

)

Parameters:

sw

switch to register This function registers a populated ast_switch structure with the asterisk switching architecture. It returns 0 on success, and other than 0 on failure

int ast_spawn_extension	(	struct ast_channel *	c,
		const char *	context,
		const char *	exten,
		int	priority,
		const char *	callerid
	)

Parameters:

	c	not important
	context	which context to generate the extension within
	exten	new extension to add
	priority	priority of new extension
	callerid	callerid of extension This adds a new extension to the asterisk extension list. It returns 0 on success, -1 on failure.

int ast_unlock_context

(

struct ast_context *

con

)

Parameters:

con

context to unlock Unlocks the given context Returns 0 on success, -1 on failure

int ast_unlock_contexts

(

void

)

Returns 0 on success, -1 on failure

int ast_unregister_application

(

const char *

app

)

Parameters:

app

name of the application (does not have to be the same string as the one that was registered) This unregisters an application from asterisk's internal registration mechanisms. It returns 0 on success, and -1 on failure.

void ast_unregister_switch

(

struct ast_switch *

sw

)

Parameters:

sw

switch to unregister Unregisters a switch from asterisk. Returns nothing

int pbx_exec	(	struct ast_channel *	c,
		struct ast_app *	app,
		void *	data,
		int	newstack
	)

Parameters:

	c	channel to execute on
	app	which app to execute
	data	the data passed into the app
	newstack	stack pointer This application executes an application on a given channel. It saves the stack and executes the given appliation passing in the given data. It returns 0 on success, and -1 on failure

struct ast_app* pbx_findapp

(

const char *

app

)

Parameters:

app

name of the app This function searches for the ast_app structure within the apps that are registered for the one with the name you passed in. Returns the ast_app structure that matches on success, or NULL on failure

---