15b3532972f658bd06d95360afea46738019e9f1
[asterisk/asterisk.git] / include / asterisk / pbx.h
1 /*
2  * Asterisk -- A telephony toolkit for Linux.
3  *
4  * Core PBX routines and definitions.
5  * 
6  * Copyright (C) 1999, Mark Spencer
7  *
8  * Mark Spencer <markster@linux-support.net>
9  *
10  * This program is free software, distributed under the terms of
11  * the GNU General Public License
12  */
13 #ifndef _ASTERISK_PBX_H
14 #define _ASTERISK_PBX_H
15
16 #include <asterisk/sched.h>
17 #include <asterisk/channel.h>
18
19 #if defined(__cplusplus) || defined(c_plusplus)
20 extern "C" {
21 #endif
22
23 #define AST_PBX_KEEP    0
24 #define AST_PBX_REPLACE 1
25
26 //! Max length of an application
27 #define AST_MAX_APP     32
28
29 //! Special return values from applications to the PBX
30 #define AST_PBX_KEEPALIVE       10              /* Destroy the thread, but don't hang up the channel */
31
32 struct ast_context;
33 struct ast_exten;     
34 struct ast_include;
35 struct ast_ignorepat;
36 struct ast_sw;
37
38 //! Data structure associated with an asterisk switch
39 struct ast_switch {
40         /*! NULL */
41         struct ast_switch *next;        
42         /*! Name of the switch */
43         char *name;                             
44         /*! Description of the switch */
45         char *description;              
46         
47         int (*exists)(struct ast_channel *chan, char *context, char *exten, int priority, char *callerid, char *data);
48         
49         int (*canmatch)(struct ast_channel *chan, char *context, char *exten, int priority, char *callerid, char *data);
50         
51         int (*exec)(struct ast_channel *chan, char *context, char *exten, int priority, char *callerid, int newstack, char *data);
52 };
53
54 //! Register an alternative switch
55 /*!
56  * \param sw switch to register
57  * This function registers a populated ast_switch structure with the
58  * asterisk switching architecture.
59  * It returns 0 on success, and other than 0 on failure
60  */
61 extern int ast_register_switch(struct ast_switch *sw);
62
63 //! Unregister an alternative switch
64 /*!
65  * \param sw switch to unregister
66  * Unregisters a switch from asterisk.
67  * Returns nothing
68  */
69 extern void ast_unregister_switch(struct ast_switch *sw);
70
71 //! Look up an application
72 /*!
73  * \param app name of the app
74  * This function searches for the ast_app structure within
75  * the apps that are registered for the one with the name
76  * you passed in.
77  * Returns the ast_app structure that matches on success, or NULL on failure
78  */
79 extern struct ast_app *pbx_findapp(char *app);
80
81 //! executes an application
82 /*!
83  * \param c channel to execute on
84  * \param app which app to execute
85  * \param data the data passed into the app
86  * \param newstack stack pointer
87  * This application executes an application on a given channel.  It
88  * saves the stack and executes the given appliation passing in
89  * the given data.
90  * It returns 0 on success, and -1 on failure
91  */
92 int pbx_exec(struct ast_channel *c, struct ast_app *app, void *data, int newstack);
93
94 //! Register a new context
95 /*!
96  * \param name name of the new context
97  * \param registrar registrar of the context
98  * This will first search for a context with your name.  If it exists already, it will not
99  * create a new one.  If it does not exist, it will create a new one with the given name
100  * and registrar.
101  * It returns NULL on failure, and an ast_context structure on success
102  */
103 struct ast_context *ast_context_create(char *name, char *registrar);
104
105 //! Destroy a context (matches the specified context (or ANY context if NULL)
106 /*!
107  * \param con context to destroy
108  * \param registrar who registered it
109  * You can optionally leave out either parameter.  It will find it
110  * based on either the ast_context or the registrar name.
111  * Returns nothing
112  */
113 void ast_context_destroy(struct ast_context *con, char *registrar);
114
115 //! Find a context
116 /*!
117  * \param name name of the context to find
118  * Will search for the context with the given name.
119  * Returns the ast_context on success, NULL on failure.
120  */
121 struct ast_context *ast_context_find(char *name);
122
123 //! Create a new thread and start the PBX (or whatever)
124 /*!
125  * \param c channel to start the pbx on
126  * Starts a pbx thread on a given channel
127  * It returns -1 on failure, and 0 on success
128  */
129 int ast_pbx_start(struct ast_channel *c);
130
131 //! Execute the PBX in the current thread
132 /*!
133  * \param c channel to run the pbx on
134  * This executes the PBX on a given channel.  It allocates a new
135  * PBX structure for the channel, and provides all PBX functionality.
136  */
137 int ast_pbx_run(struct ast_channel *c);
138
139 /*! 
140  * \param context context to add the extension to
141  * \param replace
142  * \param extension extension to add
143  * \param priority priority level of extension addition
144  * \param callerid callerid of extension
145  * \param application application to run on the extension with that priority level
146  * \param data data to pass to the application
147  * \param datad
148  * \param registrar who registered the extension
149  * Add and extension to an extension context.  
150  * Callerid is a pattern to match CallerID, or NULL to match any callerid
151  * Returns 0 on success, -1 on failure
152  */
153 int ast_add_extension(char *context, int replace, char *extension, int priority, char *callerid,
154         char *application, void *data, void (*datad)(void *), char *registrar);
155
156 //! Add an extension to an extension context, this time with an ast_context *.  CallerID is a pattern to match on callerid, or NULL to not care about callerid
157 /*! 
158  * For details about the arguements, check ast_add_extension()
159  */
160 int ast_add_extension2(struct ast_context *con,
161                                       int replace, char *extension, int priority, char *callerid, 
162                                           char *application, void *data, void (*datad)(void *),
163                                           char *registrar);
164
165 //! Add an application.  The function 'execute' should return non-zero if the line needs to be hung up. 
166 /*!
167   \param app Short name of the application
168   \param execute a function callback to execute the application
169   \param synopsis a short description of the application
170   \param description long description of the application
171    Include a one-line synopsis (e.g. 'hangs up a channel') and a more lengthy, multiline
172    description with more detail, including under what conditions the application
173    will return 0 or -1.
174    This registers an application with asterisks internal application list.  Please note:
175    The individual applications themselves are responsible for registering and unregistering
176    CLI commands.
177    It returns 0 on success, -1 on failure.
178 */
179 int ast_register_application(char *app, int (*execute)(struct ast_channel *, void *),
180                              char *synopsis, char *description);
181
182 //! Remove an application
183 /*!
184  * \param app name of the application (does not have to be the same string as the one that was registered)
185  * This unregisters an application from asterisk's internal registration mechanisms.
186  * It returns 0 on success, and -1 on failure.
187  */
188 int ast_unregister_application(char *app);
189
190 //! If an extension exists, return non-zero
191 // work
192 /*!
193  * \param c this is not important
194  * \param context which context to look in
195  * \param exten which extension to search for
196  * \param priority priority of the action within the extension
197  * \param callerid callerid to search for
198  * If an extension within the given context(or callerid) with the given priority is found a non zero value will be returned.
199  * Otherwise, 0 is returned.
200  */
201 int ast_exists_extension(struct ast_channel *c, char *context, char *exten, int priority, char *callerid);
202
203 //! Looks for a valid matching extension
204 /*!
205   \param c not really important
206   \param context context to serach within
207   \param exten extension to check
208   \param priority priority of extension path
209   \param callerid callerid of extension being searched for
210    If "exten" *could be* a valid extension in this context with or without
211    some more digits, return non-zero.  Basically, when this returns 0, no matter
212    what you add to exten, it's not going to be a valid extension anymore
213 */
214 int ast_canmatch_extension(struct ast_channel *c, char *context, char *exten, int priority, char *callerid);
215
216 //! Determine if a given extension matches a given pattern (in NXX format)
217 /*!
218  * \param pattern pattern to match
219  * \param extension extension to check against the pattern.
220  * Checks whether or not the given extension matches the given pattern.
221  * Returns 1 on match, 0 on failure
222  */
223 int ast_extension_match(char *pattern, char *extension);
224
225 //! Launch a new extension (i.e. new stack)
226 /*!
227  * \param c not important
228  * \param context which context to generate the extension within
229  * \param exten new extension to add
230  * \param priority priority of new extension
231  * \param callerid callerid of extension
232  * This adds a new extension to the asterisk extension list.
233  * It returns 0 on success, -1 on failure.
234  */
235 int ast_spawn_extension(struct ast_channel *c, char *context, char *exten, int priority, char *callerid);
236
237 //! Execute an extension.
238 /*!
239   \param c channel to execute upon
240   \param context which context extension is in
241   \param exten extension to execute
242   \param priority priority to execute within the given extension
243    If it's not available, do whatever you should do for
244    default extensions and halt the thread if necessary.  This function does not
245    return, except on error.
246 */
247 int ast_exec_extension(struct ast_channel *c, char *context, char *exten, int priority, char *callerid);
248
249 //! Add an include
250 /*!
251   \param context context to add include to
252   \param include new include to add
253   \param registrar who's registering it
254    Adds an include taking a char * string as the context parameter
255    Returns 0 on success, -1 on error
256 */
257 int ast_context_add_include(char *context, char *include, char *registrar);
258
259 //! Add an include
260 /*!
261   \param con context to add the include to
262   \param include include to add
263   \param registrar who registered the context
264    Adds an include taking a struct ast_context as the first parameter
265    Returns 0 on success, -1 on failure
266 */
267 int ast_context_add_include2(struct ast_context *con, char *include, char *registrar);
268
269 //! Removes an include
270 /*!
271  * See add_include
272  */
273 int ast_context_remove_include(char *context, char *include, char *registrar);
274 //! Removes an include by an ast_context structure
275 /*!
276  * See add_include2
277  */
278 int ast_context_remove_include2(struct ast_context *con, char *include, char *registrar);
279
280 //! Add a switch
281 /*!
282  * \param context context to which to add the switch
283  * \param sw switch to add
284  * \param data data to pass to switch
285  * \param registrar whoever registered the switch
286  * This function registers a switch with the asterisk switch architecture
287  * It returns 0 on success, -1 on failure
288  */
289 int ast_context_add_switch(char *context, char *sw, char *data, char *registrar);
290 //! Adds a switch (first param is a ast_context)
291 /*!
292  * See ast_context_add_switch()
293  */
294 int ast_context_add_switch2(struct ast_context *con, char *sw, char *data, char *registrar);
295
296 //! Remove a switch
297 /*!
298  * Removes a switch with the given parameters
299  * Returns 0 on success, -1 on failure
300  */
301 int ast_context_remove_switch(char *context, char *sw, char *data, char *registrar);
302 int ast_context_remove_switch2(struct ast_context *con, char *sw, char *data, char *registrar);
303
304 //! Simply remove extension from context
305 /*!
306  * \param context context to remove extension from
307  * \param extension which extension to remove
308  * \param priority priority of extension to remove
309  * \param registrar registrar of the extension
310  * This function removes an extension from a given context.
311  * Returns 0 on success, -1 on failure
312  */
313 int ast_context_remove_extension(char *context, char *extension, int priority,
314         char *registrar);
315 int ast_context_remove_extension2(struct ast_context *con, char *extension,
316         int priority, char *registrar);
317
318 //! Add an ignorepat
319 /*!
320  * \param context which context to add the ignorpattern to
321  * \param ignorpat ignorepattern to set up for the extension
322  * \param registrar registrar of the ignore pattern
323  * Adds an ignore pattern to a particular context.
324  * Returns 0 on success, -1 on failure
325  */
326 int ast_context_add_ignorepat(char *context, char *ignorepat, char *registrar);
327 int ast_context_add_ignorepat2(struct ast_context *con, char *ignorepat, char *registrar);
328
329 /* Remove an ignorepat */
330 /*!
331  * \param context context from which to remove the pattern
332  * \param ignorepat the pattern to remove
333  * \param registrar the registrar of the ignore pattern
334  * This removes the given ignorepattern
335  * Returns 0 on success, -1 on failure
336  */
337 int ast_context_remove_ignorepat(char *context, char *ignorepat, char *registrar);
338 int ast_context_remove_ignorepat2(struct ast_context *con, char *ignorepat, char *registrar);
339
340 //! Checks to see if a number should be ignored
341 /*!
342  * \param context context to search within
343  * \param extension to check whether it should be ignored or not
344  * Check if a number should be ignored with respect to dialtone cancellation.  
345  * Returns 0 if the pattern should not be ignored, or non-zero if the pattern should be ignored 
346  */
347 int ast_ignore_pattern(char *context, char *pattern);
348
349 /* Locking functions for outer modules, especially for completion functions */
350 //! Locks the contexts
351 /*! Locks the context list
352  * Returns 0 on success, -1 on error
353  */
354 int ast_lock_contexts(void);
355
356 //! Unlocks contexts
357 /*!
358  * Returns 0 on success, -1 on failure
359  */
360 int ast_unlock_contexts(void);
361
362 //! Locks a given context
363 /*!
364  * \param con context to lock
365  * Locks the context.
366  * Returns 0 on success, -1 on failure
367  */
368 int ast_lock_context(struct ast_context *con);
369 //! Unlocks the given context
370 /*!
371  * \param con context to unlock
372  * Unlocks the given context
373  * Returns 0 on success, -1 on failure
374  */
375 int ast_unlock_context(struct ast_context *con);
376
377
378 int ast_async_goto(struct ast_channel *chan, char *context, char *exten, int priority, int needlock);
379
380 int ast_async_goto_by_name(char *chan, char *context, char *exten, int priority);
381
382 /* Synchronously or asynchronously make an outbound call and send it to a
383    particular extension */
384 int ast_pbx_outgoing_exten(char *type, int format, void *data, int timeout, char *context, char *exten, int priority, int *reason, int sync);
385
386 /* Synchronously or asynchronously make an outbound call and send it to a
387    particular application with given extension */
388 int ast_pbx_outgoing_app(char *type, int format, void *data, int timeout, char *app, void *appdata, int *reason, int sync);
389
390 /* Functions for returning values from structures */
391 char *ast_get_context_name(struct ast_context *con);
392 char *ast_get_extension_name(struct ast_exten *exten);
393 char *ast_get_include_name(struct ast_include *include);
394 char *ast_get_ignorepat_name(struct ast_ignorepat *ip);
395 char *ast_get_switch_name(struct ast_sw *sw);
396 char *ast_get_switch_data(struct ast_sw *sw);
397
398 /* Other extension stuff */
399 int ast_get_extension_priority(struct ast_exten *exten);
400 char *ast_get_extension_app(struct ast_exten *e);
401 void *ast_get_extension_app_data(struct ast_exten *e);
402
403 /* Registrar info functions ... */
404 char *ast_get_context_registrar(struct ast_context *c);
405 char *ast_get_extension_registrar(struct ast_exten *e);
406 char *ast_get_include_registrar(struct ast_include *i);
407 char *ast_get_ignorepat_registrar(struct ast_ignorepat *ip);
408 char *ast_get_switch_registrar(struct ast_sw *sw);
409
410 /* Walking functions ... */
411 struct ast_context *ast_walk_contexts(struct ast_context *con);
412 struct ast_exten *ast_walk_context_extensions(struct ast_context *con,
413         struct ast_exten *priority);
414 struct ast_exten *ast_walk_extension_priorities(struct ast_exten *exten,
415         struct ast_exten *priority);
416 struct ast_include *ast_walk_context_includes(struct ast_context *con,
417         struct ast_include *inc);
418 struct ast_ignorepat *ast_walk_context_ignorepats(struct ast_context *con,
419         struct ast_ignorepat *ip);
420 struct ast_sw *ast_walk_context_switches(struct ast_context *con, struct ast_sw *sw);
421 #if defined(__cplusplus) || defined(c_plusplus)
422 }
423 #endif
424
425
426 #endif