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