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