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