major re-work of dialplan functions, including:
[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 typedef int (*ast_devstate_cb_type)(const char *dev, int state, void *data);
55
56 /*! Data structure associated with a custom function */
57 struct ast_custom_function {
58         char *name;
59         char *synopsis;
60         char *desc;
61         char *syntax;
62         char *(*read)(struct ast_channel *, char *, char *, char *, size_t);
63         void (*write)(struct ast_channel *, char *, char *, const char *);
64         struct ast_custom_function *next;
65 };
66
67 /*! Data structure associated with an asterisk switch */
68 struct ast_switch {
69         /*! NULL */
70         struct ast_switch *next;        
71         /*! Name of the switch */
72         const char *name;                               
73         /*! Description of the switch */
74         const char *description;                
75         
76         int (*exists)(struct ast_channel *chan, const char *context, const char *exten, int priority, const char *callerid, const char *data);
77         
78         int (*canmatch)(struct ast_channel *chan, const char *context, const char *exten, int priority, const char *callerid, const char *data);
79         
80         int (*exec)(struct ast_channel *chan, const char *context, const char *exten, int priority, const char *callerid, int newstack, const char *data);
81
82         int (*matchmore)(struct ast_channel *chan, const char *context, const char *exten, int priority, const char *callerid, const char *data);
83 };
84
85 struct ast_timing {
86         int hastime;                            /* If time construct exists */
87         unsigned int monthmask;                 /* Mask for month */
88         unsigned int daymask;                   /* Mask for date */
89         unsigned int dowmask;                   /* Mask for day of week (mon-sun) */
90         unsigned int minmask[24];               /* Mask for minute */
91 };
92
93 extern int ast_build_timing(struct ast_timing *i, char *info);
94 extern int ast_check_timing(struct ast_timing *i);
95
96 struct ast_pbx {
97         int dtimeout;                                   /* Timeout between digits (seconds) */
98         int rtimeout;                                   /* Timeout for response
99                                                            (seconds) */
100 };
101
102
103 /*! Register an alternative switch */
104 /*!
105  * \param sw switch to register
106  * This function registers a populated ast_switch structure with the
107  * asterisk switching architecture.
108  * It returns 0 on success, and other than 0 on failure
109  */
110 extern int ast_register_switch(struct ast_switch *sw);
111
112 /*! Unregister an alternative switch */
113 /*!
114  * \param sw switch to unregister
115  * Unregisters a switch from asterisk.
116  * Returns nothing
117  */
118 extern void ast_unregister_switch(struct ast_switch *sw);
119
120 /*! Look up an application */
121 /*!
122  * \param app name of the app
123  * This function searches for the ast_app structure within
124  * the apps that are registered for the one with the name
125  * you passed in.
126  * Returns the ast_app structure that matches on success, or NULL on failure
127  */
128 extern struct ast_app *pbx_findapp(const char *app);
129
130 /*! executes an application */
131 /*!
132  * \param c channel to execute on
133  * \param app which app to execute
134  * \param data the data passed into the app
135  * \param newstack stack pointer
136  * This application executes an application on a given channel.  It
137  * saves the stack and executes the given appliation passing in
138  * the given data.
139  * It returns 0 on success, and -1 on failure
140  */
141 int pbx_exec(struct ast_channel *c, struct ast_app *app, void *data, int newstack);
142
143 /*! Register a new context */
144 /*!
145  * \param extcontexts pointer to the ast_context structure pointer
146  * \param name name of the new context
147  * \param registrar registrar of the context
148  * This will first search for a context with your name.  If it exists already, it will not
149  * create a new one.  If it does not exist, it will create a new one with the given name
150  * and registrar.
151  * It returns NULL on failure, and an ast_context structure on success
152  */
153 struct ast_context *ast_context_create(struct ast_context **extcontexts, const char *name, const char *registrar);
154
155 /*! Merge the temporary contexts into a global contexts list and delete from the global list the ones that are being added */
156 /*!
157  * \param extcontexts pointer to the ast_context structure pointer
158  * \param registar 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
159  */
160 void ast_merge_contexts_and_delete(struct ast_context **extcontexts, const char *registrar);
161
162 /*! Destroy a context (matches the specified context (or ANY context if NULL) */
163 /*!
164  * \param con context to destroy
165  * \param registrar who registered it
166  * You can optionally leave out either parameter.  It will find it
167  * based on either the ast_context or the registrar name.
168  * Returns nothing
169  */
170 void ast_context_destroy(struct ast_context *con, const char *registrar);
171
172 /*! Find a context */
173 /*!
174  * \param name name of the context to find
175  * Will search for the context with the given name.
176  * Returns the ast_context on success, NULL on failure.
177  */
178 struct ast_context *ast_context_find(const char *name);
179
180 /*! Create a new thread and start the PBX (or whatever) */
181 /*!
182  * \param c channel to start the pbx on
183  * Starts a pbx thread on a given channel
184  * It returns -1 on failure, and 0 on success
185  */
186 int ast_pbx_start(struct ast_channel *c);
187
188 /*! Execute the PBX in the current thread */
189 /*!
190  * \param c channel to run the pbx on
191  * This executes the PBX on a given channel.  It allocates a new
192  * PBX structure for the channel, and provides all PBX functionality.
193  */
194 int ast_pbx_run(struct ast_channel *c);
195
196 /*! 
197  * \param context context to add the extension to
198  * \param replace
199  * \param extension extension to add
200  * \param priority priority level of extension addition
201  * \param callerid callerid of extension
202  * \param application application to run on the extension with that priority level
203  * \param data data to pass to the application
204  * \param datad
205  * \param registrar who registered the extension
206  * Add and extension to an extension context.  
207  * Callerid is a pattern to match CallerID, or NULL to match any callerid
208  * Returns 0 on success, -1 on failure
209  */
210 int ast_add_extension(const char *context, int replace, const char *extension, int priority, const char *label, const char *callerid,
211         const char *application, void *data, void (*datad)(void *), const char *registrar);
212
213 /*! 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 */
214 /*! 
215  * For details about the arguements, check ast_add_extension()
216  */
217 int ast_add_extension2(struct ast_context *con,
218                                       int replace, const char *extension, int priority, const char *label, const char *callerid, 
219                                           const char *application, void *data, void (*datad)(void *),
220                                           const char *registrar);
221
222 /*! Add an application.  The function 'execute' should return non-zero if the line needs to be hung up.  */
223 /*!
224   \param app Short name of the application
225   \param execute a function callback to execute the application
226   \param synopsis a short description of the application
227   \param description long description of the application
228    Include a one-line synopsis (e.g. 'hangs up a channel') and a more lengthy, multiline
229    description with more detail, including under what conditions the application
230    will return 0 or -1.
231    This registers an application with asterisks internal application list.  Please note:
232    The individual applications themselves are responsible for registering and unregistering
233    CLI commands.
234    It returns 0 on success, -1 on failure.
235 */
236 int ast_register_application(const char *app, int (*execute)(struct ast_channel *, void *),
237                              const char *synopsis, const char *description);
238
239 /*! Remove an application */
240 /*!
241  * \param app name of the application (does not have to be the same string as the one that was registered)
242  * This unregisters an application from asterisk's internal registration mechanisms.
243  * It returns 0 on success, and -1 on failure.
244  */
245 int ast_unregister_application(const char *app);
246
247 /*! Uses hint and devicestate callback to get the state of an extension */
248 /*!
249  * \param c this is not important
250  * \param context which context to look in
251  * \param exten which extension to get state
252  * Returns extension state !! = AST_EXTENSION_???
253  */
254 int ast_extension_state(struct ast_channel *c, char *context, char *exten);
255
256 /*! Tells Asterisk the State for Device is changed */
257 /*!
258  * \param fmt devicename like a dialstring with format parameters
259  * Asterisk polls the new extensionstates and calls the registered
260  * callbacks for the changed extensions
261  * Returns 0 on success, -1 on failure
262  */
263 int ast_device_state_changed(const char *fmt, ...)
264         __attribute__ ((format (printf, 1, 2)));
265
266 /*! Registers a state change callback */
267 /*!
268  * \param context which context to look in
269  * \param exten which extension to get state
270  * \param callback callback to call if state changed
271  * \param data to pass to callback
272  * The callback is called if the state for extension is changed
273  * Return -1 on failure, ID on success
274  */ 
275 int ast_extension_state_add(const char *context, const char *exten, 
276                             ast_state_cb_type callback, void *data);
277
278 /*! Registers a device state change callback */
279 /*!
280  * \param data to pass to callback
281  * The callback is called if the state for extension is changed
282  * Return -1 on failure, ID on success
283  */ 
284 int ast_devstate_add(ast_devstate_cb_type callback, void *data);
285 void ast_devstate_del(ast_devstate_cb_type callback, void *data);
286
287 /*! Deletes a registered state change callback by ID */
288 /*!
289  * \param id of the callback to delete
290  * Removes the callback from list of callbacks
291  * Return 0 on success, -1 on failure
292  */
293 int ast_extension_state_del(int id, ast_state_cb_type callback);
294
295 /*! If an extension exists, return non-zero */
296 /*!
297  * \param hint buffer for hint
298  * \param maxlen size of hint buffer
299  * \param hint buffer for name portion of hint
300  * \param maxlen size of name buffer
301  * \param c this is not important
302  * \param context which context to look in
303  * \param exten which extension to search for
304  * If an extension within the given context with the priority PRIORITY_HINT
305  * is found a non zero value will be returned.
306  * Otherwise, 0 is returned.
307  */
308 int ast_get_hint(char *hint, int maxlen, char *name, int maxnamelen, struct ast_channel *c, const char *context, const char *exten);
309
310 /*! If an extension exists, return non-zero */
311 /*  work */
312 /*!
313  * \param c this is not important
314  * \param context which context to look in
315  * \param exten which extension to search for
316  * \param priority priority of the action within the extension
317  * \param callerid callerid to search for
318  * If an extension within the given context(or callerid) with the given priority is found a non zero value will be returned.
319  * Otherwise, 0 is returned.
320  */
321 int ast_exists_extension(struct ast_channel *c, const char *context, const char *exten, int priority, const char *callerid);
322
323 /*! If an extension exists, return non-zero */
324 /*  work */
325 /*!
326  * \param c this is not important
327  * \param context which context to look in
328  * \param exten which extension to search for
329  * \param labellabel of the action within the extension to match to priority
330  * \param callerid callerid to search for
331  * If an priority which matches given label in extension or -1 if not found.
332 \ */
333 int ast_findlabel_extension(struct ast_channel *c, const char *context, const char *exten, const char *label, const char *callerid);
334
335 int ast_findlabel_extension2(struct ast_channel *c, struct ast_context *con, const char *exten, const char *label, const char *callerid);
336
337 /*! Looks for a valid matching extension */
338 /*!
339   \param c not really important
340   \param context context to serach within
341   \param exten extension to check
342   \param priority priority of extension path
343   \param callerid callerid of extension being searched for
344    If "exten" *could be* a valid extension in this context with or without
345    some more digits, return non-zero.  Basically, when this returns 0, no matter
346    what you add to exten, it's not going to be a valid extension anymore
347 */
348 int ast_canmatch_extension(struct ast_channel *c, const char *context, const char *exten, int priority, const char *callerid);
349
350 /*! Looks to see if adding anything to this extension might match something. (exists ^ canmatch) */
351 /*!
352   \param c not really important
353   \param context context to serach within
354   \param exten extension to check
355   \param priority priority of extension path
356   \param callerid callerid of extension being searched for
357    If "exten" *could match* a valid extension in this context with
358    some more digits, return non-zero.  Does NOT return non-zero if this is
359    an exact-match only.  Basically, when this returns 0, no matter
360    what you add to exten, it's not going to be a valid extension anymore
361 */
362 int ast_matchmore_extension(struct ast_channel *c, const char *context, const char *exten, int priority, const char *callerid);
363
364 /*! Determine if a given extension matches a given pattern (in NXX format) */
365 /*!
366  * \param pattern pattern to match
367  * \param extension extension to check against the pattern.
368  * Checks whether or not the given extension matches the given pattern.
369  * Returns 1 on match, 0 on failure
370  */
371 int ast_extension_match(const char *pattern, const char *extension);
372 int ast_extension_close(const char *pattern, const char *data, int needmore);
373 /*! Launch a new extension (i.e. new stack) */
374 /*!
375  * \param c not important
376  * \param context which context to generate the extension within
377  * \param exten new extension to add
378  * \param priority priority of new extension
379  * \param callerid callerid of extension
380  * This adds a new extension to the asterisk extension list.
381  * It returns 0 on success, -1 on failure.
382  */
383 int ast_spawn_extension(struct ast_channel *c, const char *context, const char *exten, int priority, const char *callerid);
384
385 /*! Execute an extension. */
386 /*!
387   \param c channel to execute upon
388   \param context which context extension is in
389   \param exten extension to execute
390   \param priority priority to execute within the given extension
391    If it's not available, do whatever you should do for
392    default extensions and halt the thread if necessary.  This function does not
393    return, except on error.
394 */
395 int ast_exec_extension(struct ast_channel *c, const char *context, const char *exten, int priority, const char *callerid);
396
397 /*! Add an include */
398 /*!
399   \param context context to add include to
400   \param include new include to add
401   \param registrar who's registering it
402    Adds an include taking a char * string as the context parameter
403    Returns 0 on success, -1 on error
404 */
405 int ast_context_add_include(const char *context, const char *include, const char *registrar);
406
407 /*! Add an include */
408 /*!
409   \param con context to add the include to
410   \param include include to add
411   \param registrar who registered the context
412    Adds an include taking a struct ast_context as the first parameter
413    Returns 0 on success, -1 on failure
414 */
415 int ast_context_add_include2(struct ast_context *con, const char *include, const char *registrar);
416
417 /*! Removes an include */
418 /*!
419  * See add_include
420  */
421 int ast_context_remove_include(const char *context, const char *include,const  char *registrar);
422 /*! Removes an include by an ast_context structure */
423 /*!
424  * See add_include2
425  */
426 int ast_context_remove_include2(struct ast_context *con, const char *include, const char *registrar);
427
428 /*! Verifies includes in an ast_contect structure */
429 /*!
430  * \param con context in which to verify the includes
431  * Returns 0 if no problems found, -1 if there were any missing context
432  */
433 int ast_context_verify_includes(struct ast_context *con);
434           
435 /*! Add a switch */
436 /*!
437  * \param context context to which to add the switch
438  * \param sw switch to add
439  * \param data data to pass to switch
440  * \param eval whether to evaluate variables when running switch
441  * \param registrar whoever registered the switch
442  * This function registers a switch with the asterisk switch architecture
443  * It returns 0 on success, -1 on failure
444  */
445 int ast_context_add_switch(const char *context, const char *sw, const char *data, int eval, const char *registrar);
446 /*! Adds a switch (first param is a ast_context) */
447 /*!
448  * See ast_context_add_switch()
449  */
450 int ast_context_add_switch2(struct ast_context *con, const char *sw, const char *data, int eval, const char *registrar);
451
452 /*! Remove a switch */
453 /*!
454  * Removes a switch with the given parameters
455  * Returns 0 on success, -1 on failure
456  */
457 int ast_context_remove_switch(const char *context, const char *sw, const char *data, const char *registrar);
458 int ast_context_remove_switch2(struct ast_context *con, const char *sw, const char *data, const char *registrar);
459
460 /*! Simply remove extension from context */
461 /*!
462  * \param context context to remove extension from
463  * \param extension which extension to remove
464  * \param priority priority of extension to remove
465  * \param registrar registrar of the extension
466  * This function removes an extension from a given context.
467  * Returns 0 on success, -1 on failure
468  */
469 int ast_context_remove_extension(const char *context, const char *extension, int priority,
470         const char *registrar);
471 int ast_context_remove_extension2(struct ast_context *con, const char *extension,
472         int priority, const char *registrar);
473
474 /*! Add an ignorepat */
475 /*!
476  * \param context which context to add the ignorpattern to
477  * \param ignorpat ignorepattern to set up for the extension
478  * \param registrar registrar of the ignore pattern
479  * Adds an ignore pattern to a particular context.
480  * Returns 0 on success, -1 on failure
481  */
482 int ast_context_add_ignorepat(const char *context, const char *ignorepat, const char *registrar);
483 int ast_context_add_ignorepat2(struct ast_context *con, const char *ignorepat, const char *registrar);
484
485 /* Remove an ignorepat */
486 /*!
487  * \param context context from which to remove the pattern
488  * \param ignorepat the pattern to remove
489  * \param registrar the registrar of the ignore pattern
490  * This removes the given ignorepattern
491  * Returns 0 on success, -1 on failure
492  */
493 int ast_context_remove_ignorepat(const char *context, const char *ignorepat, const char *registrar);
494 int ast_context_remove_ignorepat2(struct ast_context *con, const char *ignorepat, const char *registrar);
495
496 /*! Checks to see if a number should be ignored */
497 /*!
498  * \param context context to search within
499  * \param extension to check whether it should be ignored or not
500  * Check if a number should be ignored with respect to dialtone cancellation.  
501  * Returns 0 if the pattern should not be ignored, or non-zero if the pattern should be ignored 
502  */
503 int ast_ignore_pattern(const char *context, const char *pattern);
504
505 /* Locking functions for outer modules, especially for completion functions */
506 /*! Locks the contexts */
507 /*! Locks the context list
508  * Returns 0 on success, -1 on error
509  */
510 int ast_lock_contexts(void);
511
512 /*! Unlocks contexts */
513 /*!
514  * Returns 0 on success, -1 on failure
515  */
516 int ast_unlock_contexts(void);
517
518 /*! Locks a given context */
519 /*!
520  * \param con context to lock
521  * Locks the context.
522  * Returns 0 on success, -1 on failure
523  */
524 int ast_lock_context(struct ast_context *con);
525 /*! Unlocks the given context */
526 /*!
527  * \param con context to unlock
528  * Unlocks the given context
529  * Returns 0 on success, -1 on failure
530  */
531 int ast_unlock_context(struct ast_context *con);
532
533
534 int ast_async_goto(struct ast_channel *chan, const char *context, const char *exten, int priority);
535
536 int ast_async_goto_by_name(const char *chan, const char *context, const char *exten, int priority);
537
538 /* Synchronously or asynchronously make an outbound call and send it to a
539    particular extension */
540 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, const char *variable, const char *account, struct ast_channel **locked_channel);
541
542 /* Synchronously or asynchronously make an outbound call and send it to a
543    particular application with given extension */
544 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, const char *variable, const char *account, struct ast_channel **locked_channel);
545
546 /* Functions for returning values from structures */
547 const char *ast_get_context_name(struct ast_context *con);
548 const char *ast_get_extension_name(struct ast_exten *exten);
549 const char *ast_get_include_name(struct ast_include *include);
550 const char *ast_get_ignorepat_name(struct ast_ignorepat *ip);
551 const char *ast_get_switch_name(struct ast_sw *sw);
552 const char *ast_get_switch_data(struct ast_sw *sw);
553
554 /* Other extension stuff */
555 int ast_get_extension_priority(struct ast_exten *exten);
556 int ast_get_extension_matchcid(struct ast_exten *e);
557 const char *ast_get_extension_cidmatch(struct ast_exten *e);
558 const char *ast_get_extension_app(struct ast_exten *e);
559 const char *ast_get_extension_label(struct ast_exten *e);
560 void *ast_get_extension_app_data(struct ast_exten *e);
561
562 /* Registrar info functions ... */
563 const char *ast_get_context_registrar(struct ast_context *c);
564 const char *ast_get_extension_registrar(struct ast_exten *e);
565 const char *ast_get_include_registrar(struct ast_include *i);
566 const char *ast_get_ignorepat_registrar(struct ast_ignorepat *ip);
567 const char *ast_get_switch_registrar(struct ast_sw *sw);
568
569 /* Walking functions ... */
570 struct ast_context *ast_walk_contexts(struct ast_context *con);
571 struct ast_exten *ast_walk_context_extensions(struct ast_context *con,
572         struct ast_exten *priority);
573 struct ast_exten *ast_walk_extension_priorities(struct ast_exten *exten,
574         struct ast_exten *priority);
575 struct ast_include *ast_walk_context_includes(struct ast_context *con,
576         struct ast_include *inc);
577 struct ast_ignorepat *ast_walk_context_ignorepats(struct ast_context *con,
578         struct ast_ignorepat *ip);
579 struct ast_sw *ast_walk_context_switches(struct ast_context *con, struct ast_sw *sw);
580
581 int pbx_builtin_serialize_variables(struct ast_channel *chan, char *buf, size_t size);
582 extern char *pbx_builtin_getvar_helper(struct ast_channel *chan, const char *name);
583 extern void pbx_builtin_setvar_helper(struct ast_channel *chan, const char *name, const char *value);
584 extern void pbx_retrieve_variable(struct ast_channel *c, const char *var, char **ret, char *workspace, int workspacelen, struct varshead *headp);
585 extern void pbx_builtin_clear_globals(void);
586 extern int pbx_builtin_setvar(struct ast_channel *chan, void *data);
587 extern void pbx_substitute_variables_helper(struct ast_channel *c,const char *cp1,char *cp2,int count);
588 extern void pbx_substitute_variables_varshead(struct varshead *headp, const char *cp1, char *cp2, int count);
589
590 int ast_extension_patmatch(const char *pattern, const char *data);
591
592 /* Set "autofallthrough" flag, if newval is <0, does not acutally set.  If
593   set to 1, sets to auto fall through.  If newval set to 0, sets to no auto
594   fall through (reads extension instead).  Returns previous value. */
595 extern int pbx_set_autofallthrough(int newval);
596 int ast_goto_if_exists(struct ast_channel *chan, char* context, char *exten, int priority);
597 /* I can find neither parsable nor parseable at dictionary.com, but google gives me 169000 hits for parseable and only 49,800 for parsable */
598 int ast_parseable_goto(struct ast_channel *chan, const char *goto_string);
599 int ast_explicit_goto(struct ast_channel *chan, const char *context, const char *exten, int priority);
600 int ast_async_goto_if_exists(struct ast_channel *chan, char* context, char *exten, int priority);
601
602 struct ast_custom_function* ast_custom_function_find(char *name);
603 int ast_custom_function_unregister(struct ast_custom_function *acf);
604 int ast_custom_function_register(struct ast_custom_function *acf);
605
606 #if defined(__cplusplus) || defined(c_plusplus)
607 }
608 #endif
609
610
611 #endif