e1d7f96e28ec5ca6e0b48c6e33042c9626b83bbf
[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 #define AST_PBX_NO_HANGUP_PEER       11
32
33 //! Special Priority for an hint
34 #define PRIORITY_HINT   -1
35
36 //! Extension states
37 //! No device INUSE or BUSY 
38 #define AST_EXTENSION_NOT_INUSE         0
39 //! One or more devices INUSE
40 #define AST_EXTENSION_INUSE             1
41 //! All devices BUSY
42 #define AST_EXTENSION_BUSY              2
43 //! All devices UNAVAILABLE/UNREGISTERED
44 #define AST_EXTENSION_UNAVAILABLE       3
45
46 struct ast_context;
47 struct ast_exten;     
48 struct ast_include;
49 struct ast_ignorepat;
50 struct ast_sw;
51
52 typedef int (*ast_state_cb_type)(char *context, char* id, int state, void *data);
53
54 //! Data structure associated with an asterisk switch
55 struct ast_switch {
56         /*! NULL */
57         struct ast_switch *next;        
58         /*! Name of the switch */
59         char *name;                             
60         /*! Description of the switch */
61         char *description;              
62         
63         int (*exists)(struct ast_channel *chan, char *context, char *exten, int priority, char *callerid, char *data);
64         
65         int (*canmatch)(struct ast_channel *chan, char *context, char *exten, int priority, char *callerid, char *data);
66         
67         int (*exec)(struct ast_channel *chan, char *context, char *exten, int priority, char *callerid, int newstack, char *data);
68
69         int (*matchmore)(struct ast_channel *chan, char *context, char *exten, int priority, char *callerid, char *data);
70 };
71
72 struct ast_pbx {
73         int dtimeout;                                   /* Timeout between digits (seconds) */
74         int rtimeout;                                   /* Timeout for response
75                                                            (seconds) */
76 };
77
78
79 //! Register an alternative switch
80 /*!
81  * \param sw switch to register
82  * This function registers a populated ast_switch structure with the
83  * asterisk switching architecture.
84  * It returns 0 on success, and other than 0 on failure
85  */
86 extern int ast_register_switch(struct ast_switch *sw);
87
88 //! Unregister an alternative switch
89 /*!
90  * \param sw switch to unregister
91  * Unregisters a switch from asterisk.
92  * Returns nothing
93  */
94 extern void ast_unregister_switch(struct ast_switch *sw);
95
96 //! Look up an application
97 /*!
98  * \param app name of the app
99  * This function searches for the ast_app structure within
100  * the apps that are registered for the one with the name
101  * you passed in.
102  * Returns the ast_app structure that matches on success, or NULL on failure
103  */
104 extern struct ast_app *pbx_findapp(char *app);
105
106 //! executes an application
107 /*!
108  * \param c channel to execute on
109  * \param app which app to execute
110  * \param data the data passed into the app
111  * \param newstack stack pointer
112  * This application executes an application on a given channel.  It
113  * saves the stack and executes the given appliation passing in
114  * the given data.
115  * It returns 0 on success, and -1 on failure
116  */
117 int pbx_exec(struct ast_channel *c, struct ast_app *app, void *data, int newstack);
118
119 //! Register a new context
120 /*!
121  * \param extcontexts pointer to the ast_context structure pointer
122  * \param name name of the new context
123  * \param registrar registrar of the context
124  * This will first search for a context with your name.  If it exists already, it will not
125  * create a new one.  If it does not exist, it will create a new one with the given name
126  * and registrar.
127  * It returns NULL on failure, and an ast_context structure on success
128  */
129 struct ast_context *ast_context_create(struct ast_context **extcontexts, char *name, char *registrar);
130
131 //! Merge the temporary contexts into a global contexts list and delete from the global list the ones that are being added
132 /*!
133  * \param extcontexts pointer to the ast_context structure pointer
134  */
135 void ast_merge_contexts_and_delete(struct ast_context **extcontexts);
136
137 //! Destroy a context (matches the specified context (or ANY context if NULL)
138 /*!
139  * \param con context to destroy
140  * \param registrar who registered it
141  * You can optionally leave out either parameter.  It will find it
142  * based on either the ast_context or the registrar name.
143  * Returns nothing
144  */
145 void ast_context_destroy(struct ast_context *con, char *registrar);
146
147 //! Find a context
148 /*!
149  * \param name name of the context to find
150  * Will search for the context with the given name.
151  * Returns the ast_context on success, NULL on failure.
152  */
153 struct ast_context *ast_context_find(char *name);
154
155 //! Create a new thread and start the PBX (or whatever)
156 /*!
157  * \param c channel to start the pbx on
158  * Starts a pbx thread on a given channel
159  * It returns -1 on failure, and 0 on success
160  */
161 int ast_pbx_start(struct ast_channel *c);
162
163 //! Execute the PBX in the current thread
164 /*!
165  * \param c channel to run the pbx on
166  * This executes the PBX on a given channel.  It allocates a new
167  * PBX structure for the channel, and provides all PBX functionality.
168  */
169 int ast_pbx_run(struct ast_channel *c);
170
171 /*! 
172  * \param context context to add the extension to
173  * \param replace
174  * \param extension extension to add
175  * \param priority priority level of extension addition
176  * \param callerid callerid of extension
177  * \param application application to run on the extension with that priority level
178  * \param data data to pass to the application
179  * \param datad
180  * \param registrar who registered the extension
181  * Add and extension to an extension context.  
182  * Callerid is a pattern to match CallerID, or NULL to match any callerid
183  * Returns 0 on success, -1 on failure
184  */
185 int ast_add_extension(char *context, int replace, char *extension, int priority, char *callerid,
186         char *application, void *data, void (*datad)(void *), char *registrar);
187
188 //! 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
189 /*! 
190  * For details about the arguements, check ast_add_extension()
191  */
192 int ast_add_extension2(struct ast_context *con,
193                                       int replace, char *extension, int priority, char *callerid, 
194                                           char *application, void *data, void (*datad)(void *),
195                                           char *registrar);
196
197 //! Add an application.  The function 'execute' should return non-zero if the line needs to be hung up. 
198 /*!
199   \param app Short name of the application
200   \param execute a function callback to execute the application
201   \param synopsis a short description of the application
202   \param description long description of the application
203    Include a one-line synopsis (e.g. 'hangs up a channel') and a more lengthy, multiline
204    description with more detail, including under what conditions the application
205    will return 0 or -1.
206    This registers an application with asterisks internal application list.  Please note:
207    The individual applications themselves are responsible for registering and unregistering
208    CLI commands.
209    It returns 0 on success, -1 on failure.
210 */
211 int ast_register_application(char *app, int (*execute)(struct ast_channel *, void *),
212                              char *synopsis, char *description);
213
214 //! Remove an application
215 /*!
216  * \param app name of the application (does not have to be the same string as the one that was registered)
217  * This unregisters an application from asterisk's internal registration mechanisms.
218  * It returns 0 on success, and -1 on failure.
219  */
220 int ast_unregister_application(char *app);
221
222 //! Uses hint and devicestate callback to get the state of an extension
223 /*!
224  * \param c this is not important
225  * \param context which context to look in
226  * \param exten which extension to get state
227  * Returns extension state !! = AST_EXTENSION_???
228  */
229 int ast_extension_state(struct ast_channel *c, char *context, char *exten);
230
231 //! Tells Asterisk the State for Device is changed
232 /*!
233  * \param fmt devicename like a dialstring with format parameters
234  * Asterisk polls the new extensionstates and calls the registered
235  * callbacks for the changed extensions
236  * Returns 0 on success, -1 on failure
237  */
238 int ast_device_state_changed(const char *fmt, ...)
239         __attribute__ ((format (printf, 1, 2)));
240
241 //! Registers a state change callback
242 /*!
243  * \param context which context to look in
244  * \param exten which extension to get state
245  * \param callback callback to call if state changed
246  * \param data to pass to callback
247  * The callback is called if the state for extension is changed
248  * Return -1 on failure, ID on success
249  */ 
250 int ast_extension_state_add(char *context, char *exten, 
251                             ast_state_cb_type callback, void *data);
252
253 //! Deletes a registered state change callback by ID
254 /*!
255  * \param id of the callback to delete
256  * Removes the callback from list of callbacks
257  * Return 0 on success, -1 on failure
258  */
259 int ast_extension_state_del(int id, ast_state_cb_type callback);
260
261 //! If an extension exists, return non-zero
262 /*!
263  * \param hint buffer for hint
264  * \param maxlen size of hint buffer
265  * \param c this is not important
266  * \param context which context to look in
267  * \param exten which extension to search for
268  * If an extension within the given context with the priority PRIORITY_HINT
269  * is found a non zero value will be returned.
270  * Otherwise, 0 is returned.
271  */
272 int ast_get_hint(char *hint, int maxlen, struct ast_channel *c, char *context, char *exten);
273
274 //! If an extension exists, return non-zero
275 // work
276 /*!
277  * \param c this is not important
278  * \param context which context to look in
279  * \param exten which extension to search for
280  * \param priority priority of the action within the extension
281  * \param callerid callerid to search for
282  * If an extension within the given context(or callerid) with the given priority is found a non zero value will be returned.
283  * Otherwise, 0 is returned.
284  */
285 int ast_exists_extension(struct ast_channel *c, char *context, char *exten, int priority, char *callerid);
286
287 //! Looks for a valid matching extension
288 /*!
289   \param c not really important
290   \param context context to serach within
291   \param exten extension to check
292   \param priority priority of extension path
293   \param callerid callerid of extension being searched for
294    If "exten" *could be* a valid extension in this context with or without
295    some more digits, return non-zero.  Basically, when this returns 0, no matter
296    what you add to exten, it's not going to be a valid extension anymore
297 */
298 int ast_canmatch_extension(struct ast_channel *c, char *context, char *exten, int priority, char *callerid);
299
300 //! Looks to see if adding anything to this extension might match something. (exists ^ canmatch)
301 /*!
302   \param c not really important
303   \param context context to serach within
304   \param exten extension to check
305   \param priority priority of extension path
306   \param callerid callerid of extension being searched for
307    If "exten" *could match* a valid extension in this context with
308    some more digits, return non-zero.  Does NOT return non-zero if this is
309    an exact-match only.  Basically, when this returns 0, no matter
310    what you add to exten, it's not going to be a valid extension anymore
311 */
312 int ast_matchmore_extension(struct ast_channel *c, char *context, char *exten, int priority, char *callerid);
313
314 //! Determine if a given extension matches a given pattern (in NXX format)
315 /*!
316  * \param pattern pattern to match
317  * \param extension extension to check against the pattern.
318  * Checks whether or not the given extension matches the given pattern.
319  * Returns 1 on match, 0 on failure
320  */
321 int ast_extension_match(char *pattern, char *extension);
322
323 //! Launch a new extension (i.e. new stack)
324 /*!
325  * \param c not important
326  * \param context which context to generate the extension within
327  * \param exten new extension to add
328  * \param priority priority of new extension
329  * \param callerid callerid of extension
330  * This adds a new extension to the asterisk extension list.
331  * It returns 0 on success, -1 on failure.
332  */
333 int ast_spawn_extension(struct ast_channel *c, char *context, char *exten, int priority, char *callerid);
334
335 //! Execute an extension.
336 /*!
337   \param c channel to execute upon
338   \param context which context extension is in
339   \param exten extension to execute
340   \param priority priority to execute within the given extension
341    If it's not available, do whatever you should do for
342    default extensions and halt the thread if necessary.  This function does not
343    return, except on error.
344 */
345 int ast_exec_extension(struct ast_channel *c, char *context, char *exten, int priority, char *callerid);
346
347 //! Add an include
348 /*!
349   \param context context to add include to
350   \param include new include to add
351   \param registrar who's registering it
352    Adds an include taking a char * string as the context parameter
353    Returns 0 on success, -1 on error
354 */
355 int ast_context_add_include(char *context, char *include, char *registrar);
356
357 //! Add an include
358 /*!
359   \param con context to add the include to
360   \param include include to add
361   \param registrar who registered the context
362    Adds an include taking a struct ast_context as the first parameter
363    Returns 0 on success, -1 on failure
364 */
365 int ast_context_add_include2(struct ast_context *con, char *include, char *registrar);
366
367 //! Removes an include
368 /*!
369  * See add_include
370  */
371 int ast_context_remove_include(char *context, char *include, char *registrar);
372 //! Removes an include by an ast_context structure
373 /*!
374  * See add_include2
375  */
376 int ast_context_remove_include2(struct ast_context *con, char *include, char *registrar);
377
378 //! Add a switch
379 /*!
380  * \param context context to which to add the switch
381  * \param sw switch to add
382  * \param data data to pass to switch
383  * \param registrar whoever registered the switch
384  * This function registers a switch with the asterisk switch architecture
385  * It returns 0 on success, -1 on failure
386  */
387 int ast_context_add_switch(char *context, char *sw, char *data, char *registrar);
388 //! Adds a switch (first param is a ast_context)
389 /*!
390  * See ast_context_add_switch()
391  */
392 int ast_context_add_switch2(struct ast_context *con, char *sw, char *data, char *registrar);
393
394 //! Remove a switch
395 /*!
396  * Removes a switch with the given parameters
397  * Returns 0 on success, -1 on failure
398  */
399 int ast_context_remove_switch(char *context, char *sw, char *data, char *registrar);
400 int ast_context_remove_switch2(struct ast_context *con, char *sw, char *data, char *registrar);
401
402 //! Simply remove extension from context
403 /*!
404  * \param context context to remove extension from
405  * \param extension which extension to remove
406  * \param priority priority of extension to remove
407  * \param registrar registrar of the extension
408  * This function removes an extension from a given context.
409  * Returns 0 on success, -1 on failure
410  */
411 int ast_context_remove_extension(char *context, char *extension, int priority,
412         char *registrar);
413 int ast_context_remove_extension2(struct ast_context *con, char *extension,
414         int priority, char *registrar);
415
416 //! Add an ignorepat
417 /*!
418  * \param context which context to add the ignorpattern to
419  * \param ignorpat ignorepattern to set up for the extension
420  * \param registrar registrar of the ignore pattern
421  * Adds an ignore pattern to a particular context.
422  * Returns 0 on success, -1 on failure
423  */
424 int ast_context_add_ignorepat(char *context, char *ignorepat, char *registrar);
425 int ast_context_add_ignorepat2(struct ast_context *con, char *ignorepat, char *registrar);
426
427 /* Remove an ignorepat */
428 /*!
429  * \param context context from which to remove the pattern
430  * \param ignorepat the pattern to remove
431  * \param registrar the registrar of the ignore pattern
432  * This removes the given ignorepattern
433  * Returns 0 on success, -1 on failure
434  */
435 int ast_context_remove_ignorepat(char *context, char *ignorepat, char *registrar);
436 int ast_context_remove_ignorepat2(struct ast_context *con, char *ignorepat, char *registrar);
437
438 //! Checks to see if a number should be ignored
439 /*!
440  * \param context context to search within
441  * \param extension to check whether it should be ignored or not
442  * Check if a number should be ignored with respect to dialtone cancellation.  
443  * Returns 0 if the pattern should not be ignored, or non-zero if the pattern should be ignored 
444  */
445 int ast_ignore_pattern(char *context, char *pattern);
446
447 /* Locking functions for outer modules, especially for completion functions */
448 //! Locks the contexts
449 /*! Locks the context list
450  * Returns 0 on success, -1 on error
451  */
452 int ast_lock_contexts(void);
453
454 //! Unlocks contexts
455 /*!
456  * Returns 0 on success, -1 on failure
457  */
458 int ast_unlock_contexts(void);
459
460 //! Locks a given context
461 /*!
462  * \param con context to lock
463  * Locks the context.
464  * Returns 0 on success, -1 on failure
465  */
466 int ast_lock_context(struct ast_context *con);
467 //! Unlocks the given context
468 /*!
469  * \param con context to unlock
470  * Unlocks the given context
471  * Returns 0 on success, -1 on failure
472  */
473 int ast_unlock_context(struct ast_context *con);
474
475
476 int ast_async_goto(struct ast_channel *chan, char *context, char *exten, int priority, int needlock);
477
478 int ast_async_goto_by_name(char *chan, char *context, char *exten, int priority);
479
480 /* Synchronously or asynchronously make an outbound call and send it to a
481    particular extension */
482 int ast_pbx_outgoing_exten(char *type, int format, void *data, int timeout, char *context, char *exten, int priority, int *reason, int sync, char *callerid, char *variable );
483
484 /* Synchronously or asynchronously make an outbound call and send it to a
485    particular application with given extension */
486 int ast_pbx_outgoing_app(char *type, int format, void *data, int timeout, char *app, char *appdata, int *reason, int sync, char *callerid);
487
488 /* Functions for returning values from structures */
489 char *ast_get_context_name(struct ast_context *con);
490 char *ast_get_extension_name(struct ast_exten *exten);
491 char *ast_get_include_name(struct ast_include *include);
492 char *ast_get_ignorepat_name(struct ast_ignorepat *ip);
493 char *ast_get_switch_name(struct ast_sw *sw);
494 char *ast_get_switch_data(struct ast_sw *sw);
495
496 /* Other extension stuff */
497 int ast_get_extension_priority(struct ast_exten *exten);
498 char *ast_get_extension_app(struct ast_exten *e);
499 void *ast_get_extension_app_data(struct ast_exten *e);
500
501 /* Registrar info functions ... */
502 char *ast_get_context_registrar(struct ast_context *c);
503 char *ast_get_extension_registrar(struct ast_exten *e);
504 char *ast_get_include_registrar(struct ast_include *i);
505 char *ast_get_ignorepat_registrar(struct ast_ignorepat *ip);
506 char *ast_get_switch_registrar(struct ast_sw *sw);
507
508 /* Walking functions ... */
509 struct ast_context *ast_walk_contexts(struct ast_context *con);
510 struct ast_exten *ast_walk_context_extensions(struct ast_context *con,
511         struct ast_exten *priority);
512 struct ast_exten *ast_walk_extension_priorities(struct ast_exten *exten,
513         struct ast_exten *priority);
514 struct ast_include *ast_walk_context_includes(struct ast_context *con,
515         struct ast_include *inc);
516 struct ast_ignorepat *ast_walk_context_ignorepats(struct ast_context *con,
517         struct ast_ignorepat *ip);
518 struct ast_sw *ast_walk_context_switches(struct ast_context *con, struct ast_sw *sw);
519
520 extern char *pbx_builtin_getvar_helper(struct ast_channel *chan, char *name);
521 extern void pbx_builtin_setvar_helper(struct ast_channel *chan, char *name, char *value);
522 extern void pbx_builtin_clear_globals(void);
523 extern void pbx_substitute_variables_helper(struct ast_channel *c,const char *cp1,char *cp2,int count);
524
525 #if defined(__cplusplus) || defined(c_plusplus)
526 }
527 #endif
528
529
530 #endif