Merged revisions 205409 via svnmerge from
[asterisk/asterisk.git] / include / asterisk / pbx.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 1999 - 2006, Digium, Inc.
5  *
6  * Mark Spencer <markster@digium.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18
19 /*! \file
20  * \brief Core PBX routines and definitions.
21  */
22
23 #ifndef _ASTERISK_PBX_H
24 #define _ASTERISK_PBX_H
25
26 #include "asterisk/sched.h"
27 #include "asterisk/devicestate.h"
28 #include "asterisk/chanvars.h"
29 #include "asterisk/hashtab.h"
30 #include "asterisk/stringfields.h"
31 #include "asterisk/xmldoc.h"
32
33 #if defined(__cplusplus) || defined(c_plusplus)
34 extern "C" {
35 #endif
36
37 #define AST_MAX_APP     32      /*!< Max length of an application */
38
39 #define AST_PBX_GOTO_FAILED -3
40 #define AST_PBX_KEEP    0
41 #define AST_PBX_REPLACE 1
42
43 /*! \brief Special return values from applications to the PBX
44  * @{ */
45 #define AST_PBX_HANGUP                -1    /*!< Jump to the 'h' exten */
46 #define AST_PBX_OK                     0    /*!< No errors */
47 #define AST_PBX_ERROR                  1    /*!< Jump to the 'e' exten */
48 #define AST_PBX_INCOMPLETE             12   /*!< Return to PBX matching, allowing more digits for the extension */
49 /*! @} */
50
51 #define PRIORITY_HINT   -1      /*!< Special Priority for a hint */
52
53 /*! \brief Extension states 
54         \note States can be combined 
55         - \ref AstExtState
56 */
57 enum ast_extension_states {
58         AST_EXTENSION_REMOVED = -2,     /*!< Extension removed */
59         AST_EXTENSION_DEACTIVATED = -1, /*!< Extension hint removed */
60         AST_EXTENSION_NOT_INUSE = 0,    /*!< No device INUSE or BUSY  */
61         AST_EXTENSION_INUSE = 1 << 0,   /*!< One or more devices INUSE */
62         AST_EXTENSION_BUSY = 1 << 1,    /*!< All devices BUSY */
63         AST_EXTENSION_UNAVAILABLE = 1 << 2, /*!< All devices UNAVAILABLE/UNREGISTERED */
64         AST_EXTENSION_RINGING = 1 << 3, /*!< All devices RINGING */
65         AST_EXTENSION_ONHOLD = 1 << 4,  /*!< All devices ONHOLD */
66 };
67
68
69 struct ast_context;
70 struct ast_exten;     
71 struct ast_include;
72 struct ast_ignorepat;
73 struct ast_sw;
74
75 /*! \brief Typedef for devicestate and hint callbacks */
76 typedef int (*ast_state_cb_type)(char *context, char* id, enum ast_extension_states state, void *data);
77
78 /*! \brief Data structure associated with a custom dialplan function */
79 struct ast_custom_function {
80         const char *name;                       /*!< Name */
81         AST_DECLARE_STRING_FIELDS(
82                 AST_STRING_FIELD(synopsis);     /*!< Synopsis text for 'show functions' */
83                 AST_STRING_FIELD(desc);         /*!< Description (help text) for 'show functions &lt;name&gt;' */
84                 AST_STRING_FIELD(syntax);       /*!< Syntax text for 'core show functions' */
85                 AST_STRING_FIELD(arguments);    /*!< Arguments description */
86                 AST_STRING_FIELD(seealso);      /*!< See also */
87         );
88         enum ast_doc_src docsrc;                /*!< Where the documentation come from */
89         /*! Read function, if read is supported */
90         int (*read)(struct ast_channel *, const char *, char *, char *, size_t);
91         /*! Read function, if read is supported.  Note: only one of read or read2
92          * needs to be implemented.  In new code, read2 should be implemented as
93          * the way forward, but they should return identical results, within the
94          * constraints of buffer size, if both are implemented.  That is, if the
95          * read function is handed a 16-byte buffer, and the result is 17 bytes
96          * long, then the first 15 bytes (remember NULL terminator) should be
97          * the same for both the read and the read2 methods. */
98         int (*read2)(struct ast_channel *, const char *, char *, struct ast_str **, ssize_t);
99         /*! If no read2 function is provided, what maximum size? */
100         size_t read_max;
101         /*! Write function, if write is supported */
102         int (*write)(struct ast_channel *, const char *, char *, const char *);
103         struct ast_module *mod;         /*!< Module this custom function belongs to */
104         AST_RWLIST_ENTRY(ast_custom_function) acflist;
105 };
106
107 /*! \brief All switch functions have the same interface, so define a type for them */
108 typedef int (ast_switch_f)(struct ast_channel *chan, const char *context,
109         const char *exten, int priority, const char *callerid, const char *data);
110
111 /*!< Data structure associated with an Asterisk switch */
112 struct ast_switch {
113         AST_LIST_ENTRY(ast_switch) list;
114         const char *name;                       /*!< Name of the switch */
115         const char *description;                /*!< Description of the switch */
116         
117         ast_switch_f *exists;
118         ast_switch_f *canmatch;
119         ast_switch_f *exec;
120         ast_switch_f *matchmore;
121 };
122
123 struct ast_timing {
124         int hastime;                    /*!< If time construct exists */
125         unsigned int monthmask;         /*!< Mask for month */
126         unsigned int daymask;           /*!< Mask for date */
127         unsigned int dowmask;           /*!< Mask for day of week (sun-sat) */
128         unsigned int minmask[48];       /*!< Mask for minute */
129         char *timezone;                 /*!< NULL, or zoneinfo style timezone */
130 };
131
132 /*!\brief Construct a timing bitmap, for use in time-based conditionals.
133  * \param i Pointer to an ast_timing structure.
134  * \param info Standard string containing a timerange, weekday range, monthday range, and month range, as well as an optional timezone.
135  * \retval Returns 1 on success or 0 on failure.
136  */
137 int ast_build_timing(struct ast_timing *i, const char *info);
138
139 /*!\brief Evaluate a pre-constructed bitmap as to whether the current time falls within the range specified.
140  * \param i Pointer to an ast_timing structure.
141  * \retval Returns 1, if the time matches or 0, if the current time falls outside of the specified range.
142  */
143 int ast_check_timing(const struct ast_timing *i);
144
145 /*!\brief Deallocates memory structures associated with a timing bitmap.
146  * \param i Pointer to an ast_timing structure.
147  * \retval 0 success
148  * \retval non-zero failure (number suitable to pass to \see strerror)
149  */
150 int ast_destroy_timing(struct ast_timing *i);
151
152 struct ast_pbx {
153         int dtimeoutms;                         /*!< Timeout between digits (milliseconds) */
154         int rtimeoutms;                         /*!< Timeout for response (milliseconds) */
155 };
156
157
158 /*!
159  * \brief Register an alternative dialplan switch
160  *
161  * \param sw switch to register
162  *
163  * This function registers a populated ast_switch structure with the
164  * asterisk switching architecture.
165  *
166  * \retval 0 success
167  * \retval non-zero failure
168  */
169 int ast_register_switch(struct ast_switch *sw);
170
171 /*!
172  * \brief Unregister an alternative switch
173  *
174  * \param sw switch to unregister
175  * 
176  * Unregisters a switch from asterisk.
177  *
178  * \return nothing
179  */
180 void ast_unregister_switch(struct ast_switch *sw);
181
182 /*!
183  * \brief Look up an application
184  *
185  * \param app name of the app
186  *
187  * This function searches for the ast_app structure within
188  * the apps that are registered for the one with the name
189  * you passed in.
190  *
191  * \return the ast_app structure that matches on success, or NULL on failure
192  */
193 struct ast_app *pbx_findapp(const char *app);
194
195 /*!
196  * \brief Execute an application
197  *
198  * \param c channel to execute on
199  * \param app which app to execute
200  * \param data the data passed into the app
201  *
202  * This application executes an application on a given channel.  It
203  * saves the stack and executes the given application passing in
204  * the given data.
205  *
206  * \retval 0 success
207  * \retval -1 failure
208  */
209 int pbx_exec(struct ast_channel *c, struct ast_app *app, const char *data);
210
211 /*!
212  * \brief Register a new context or find an existing one
213  *
214  * \param extcontexts pointer to the ast_context structure pointer
215  * \param exttable pointer to the hashtable that contains all the elements in extcontexts
216  * \param name name of the new context
217  * \param registrar registrar of the context
218  *
219  * This function allows you to play in two environments: the global contexts (active dialplan)
220  * or an external context set of your choosing. To act on the external set, make sure extcontexts
221  * and exttable are set; for the globals, make sure both extcontexts and exttable are NULL.
222  *
223  * This will first search for a context with your name.  If it exists already, it will not
224  * create a new one.  If it does not exist, it will create a new one with the given name
225  * and registrar.
226  *
227  * \return NULL on failure, and an ast_context structure on success
228  */
229 struct ast_context *ast_context_find_or_create(struct ast_context **extcontexts, struct ast_hashtab *exttable, const char *name, const char *registrar);
230
231 /*!
232  * \brief Merge the temporary contexts into a global contexts list and delete from the 
233  *        global list the ones that are being added
234  *
235  * \param extcontexts pointer to the ast_context structure
236  * \param exttable pointer to the ast_hashtab structure that contains all the elements in extcontexts
237  * \param registrar of the context; if it's set the routine will delete all contexts 
238  *        that belong to that registrar; if NULL only the contexts that are specified 
239  *        in extcontexts
240  */
241 void ast_merge_contexts_and_delete(struct ast_context **extcontexts, struct ast_hashtab *exttable, const char *registrar);
242
243 /*!
244  * \brief Destroy a context (matches the specified context (or ANY context if NULL)
245  *
246  * \param con context to destroy
247  * \param registrar who registered it
248  *
249  * You can optionally leave out either parameter.  It will find it
250  * based on either the ast_context or the registrar name.
251  *
252  * \return nothing
253  */
254 void ast_context_destroy(struct ast_context *con, const char *registrar);
255
256 /*!
257  * \brief Find a context
258  *
259  * \param name name of the context to find
260  *
261  * Will search for the context with the given name.
262  *
263  * \return the ast_context on success, NULL on failure.
264  */
265 struct ast_context *ast_context_find(const char *name);
266
267 /*! \brief The result codes when starting the PBX on a channel with \see ast_pbx_start.
268         AST_PBX_CALL_LIMIT refers to the maxcalls call limit in asterisk.conf
269  */
270 enum ast_pbx_result {
271         AST_PBX_SUCCESS = 0,
272         AST_PBX_FAILED = -1,
273         AST_PBX_CALL_LIMIT = -2,
274 };
275
276 /*!
277  * \brief Create a new thread and start the PBX
278  *
279  * \param c channel to start the pbx on
280  *
281  * \see ast_pbx_run for a synchronous function to run the PBX in the
282  * current thread, as opposed to starting a new one.
283  *
284  * \retval Zero on success
285  * \retval non-zero on failure
286  */
287 enum ast_pbx_result ast_pbx_start(struct ast_channel *c);
288
289 /*!
290  * \brief Execute the PBX in the current thread
291  *
292  * \param c channel to run the pbx on
293  *
294  * This executes the PBX on a given channel. It allocates a new
295  * PBX structure for the channel, and provides all PBX functionality.
296  * See ast_pbx_start for an asynchronous function to run the PBX in a
297  * new thread as opposed to the current one.
298  * 
299  * \retval Zero on success
300  * \retval non-zero on failure
301  */
302 enum ast_pbx_result ast_pbx_run(struct ast_channel *c);
303
304 /*!
305  * \brief Options for ast_pbx_run()
306  */
307 struct ast_pbx_args {
308         union {
309                 /*! Pad this out so that we have plenty of room to add options
310                  *  but still maintain ABI compatibility over time. */
311                 uint64_t __padding;
312                 struct {
313                         /*! Do not hangup the channel when the PBX is complete. */
314                         unsigned int no_hangup_chan:1;
315                 };
316         };
317 };
318
319 /*!
320  * \brief Execute the PBX in the current thread
321  *
322  * \param c channel to run the pbx on
323  * \param args options for the pbx
324  *
325  * This executes the PBX on a given channel. It allocates a new
326  * PBX structure for the channel, and provides all PBX functionality.
327  * See ast_pbx_start for an asynchronous function to run the PBX in a
328  * new thread as opposed to the current one.
329  * 
330  * \retval Zero on success
331  * \retval non-zero on failure
332  */
333 enum ast_pbx_result ast_pbx_run_args(struct ast_channel *c, struct ast_pbx_args *args);
334
335 /*! 
336  * \brief Add and extension to an extension context.  
337  * 
338  * \param context context to add the extension to
339  * \param replace
340  * \param extension extension to add
341  * \param priority priority level of extension addition
342  * \param label extension label
343  * \param callerid pattern to match CallerID, or NULL to match any CallerID
344  * \param application application to run on the extension with that priority level
345  * \param data data to pass to the application
346  * \param datad
347  * \param registrar who registered the extension
348  *
349  * \retval 0 success 
350  * \retval -1 failure
351  */
352 int ast_add_extension(const char *context, int replace, const char *extension, 
353         int priority, const char *label, const char *callerid,
354         const char *application, void *data, void (*datad)(void *), const char *registrar);
355
356 /*! 
357  * \brief Add an extension to an extension context, this time with an ast_context *.
358  *
359  * \note For details about the arguments, check ast_add_extension()
360  */
361 int ast_add_extension2(struct ast_context *con, int replace, const char *extension,
362         int priority, const char *label, const char *callerid, 
363         const char *application, void *data, void (*datad)(void *), const char *registrar);
364
365 /*!
366  * \brief Map devstate to an extension state.
367  *
368  * \param[in] device state
369  *
370  * \return the extension state mapping.
371  */
372 enum ast_extension_states ast_devstate_to_extenstate(enum ast_device_state devstate);
373
374 /*! 
375  * \brief Uses hint and devicestate callback to get the state of an extension
376  *
377  * \param c this is not important
378  * \param context which context to look in
379  * \param exten which extension to get state
380  *
381  * \return extension state as defined in the ast_extension_states enum
382  */
383 int ast_extension_state(struct ast_channel *c, const char *context, const char *exten);
384
385 /*! 
386  * \brief Return string representation of the state of an extension
387  * 
388  * \param extension_state is the numerical state delivered by ast_extension_state
389  *
390  * \return the state of an extension as string
391  */
392 const char *ast_extension_state2str(int extension_state);
393
394 /*!
395  * \brief Registers a state change callback
396  * 
397  * \param context which context to look in
398  * \param exten which extension to get state
399  * \param callback callback to call if state changed
400  * \param data to pass to callback
401  *
402  * The callback is called if the state of an extension is changed.
403  *
404  * \retval -1 on failure
405  * \retval ID on success
406  */ 
407 int ast_extension_state_add(const char *context, const char *exten, 
408                             ast_state_cb_type callback, void *data);
409
410 /*! 
411  * \brief Deletes a registered state change callback by ID
412  * 
413  * \param id of the callback to delete
414  * \param callback callback
415  *
416  * Removes the callback from list of callbacks
417  *
418  * \retval 0 success 
419  * \retval -1 failure
420  */
421 int ast_extension_state_del(int id, ast_state_cb_type callback);
422
423 /*! 
424  * \brief If an extension hint exists, return non-zero
425  * 
426  * \param hint buffer for hint
427  * \param hintsize size of hint buffer, in bytes
428  * \param name buffer for name portion of hint
429  * \param namesize size of name buffer
430  * \param c Channel from which to return the hint.  This is only important when the hint or name contains an expression to be expanded.
431  * \param context which context to look in
432  * \param exten which extension to search for
433  *
434  * \return If an extension within the given context with the priority PRIORITY_HINT
435  * is found, a non zero value will be returned.
436  * Otherwise, 0 is returned.
437  */
438 int ast_get_hint(char *hint, int hintsize, char *name, int namesize,
439         struct ast_channel *c, const char *context, const char *exten);
440
441 /*! 
442  * \brief If an extension hint exists, return non-zero
443  * 
444  * \param hint buffer for hint
445  * \param hintsize Maximum size of hint buffer (<0 to prevent growth, >0 to limit growth to that number of bytes, or 0 for unlimited growth)
446  * \param name buffer for name portion of hint
447  * \param namesize Maximum size of name buffer (<0 to prevent growth, >0 to limit growth to that number of bytes, or 0 for unlimited growth)
448  * \param c Channel from which to return the hint.  This is only important when the hint or name contains an expression to be expanded.
449  * \param context which context to look in
450  * \param exten which extension to search for
451  *
452  * \return If an extension within the given context with the priority PRIORITY_HINT
453  * is found, a non zero value will be returned.
454  * Otherwise, 0 is returned.
455  */
456 int ast_str_get_hint(struct ast_str **hint, ssize_t hintsize, struct ast_str **name, ssize_t namesize,
457         struct ast_channel *c, const char *context, const char *exten);
458
459 /*!
460  * \brief Determine whether an extension exists
461  *
462  * \param c this is not important
463  * \param context which context to look in
464  * \param exten which extension to search for
465  * \param priority priority of the action within the extension
466  * \param callerid callerid to search for
467  *
468  * \note It is possible for autoservice to be started and stopped on c during this
469  * function call, it is important that c is not locked prior to calling this. Otherwise
470  * a deadlock may occur
471  *
472  * \return If an extension within the given context(or callerid) with the given priority 
473  *         is found a non zero value will be returned. Otherwise, 0 is returned.
474  */
475 int ast_exists_extension(struct ast_channel *c, const char *context, const char *exten, 
476         int priority, const char *callerid);
477
478 /*! 
479  * \brief Find the priority of an extension that has the specified label
480  * 
481  * \param c this is not important
482  * \param context which context to look in
483  * \param exten which extension to search for
484  * \param label label of the action within the extension to match to priority
485  * \param callerid callerid to search for
486  *
487  * \note It is possible for autoservice to be started and stopped on c during this
488  * function call, it is important that c is not locked prior to calling this. Otherwise
489  * a deadlock may occur
490  *
491  * \retval the priority which matches the given label in the extension
492  * \retval -1 if not found.
493  */
494 int ast_findlabel_extension(struct ast_channel *c, const char *context, 
495         const char *exten, const char *label, const char *callerid);
496
497 /*!
498  * \brief Find the priority of an extension that has the specified label
499  *
500  * \note It is possible for autoservice to be started and stopped on c during this
501  * function call, it is important that c is not locked prior to calling this. Otherwise
502  * a deadlock may occur
503  *
504  * \note This function is the same as ast_findlabel_extension, except that it accepts
505  * a pointer to an ast_context structure to specify the context instead of the
506  * name of the context. Otherwise, the functions behave the same.
507  */
508 int ast_findlabel_extension2(struct ast_channel *c, struct ast_context *con, 
509         const char *exten, const char *label, const char *callerid);
510
511 /*! 
512  * \brief Looks for a valid matching extension
513  * 
514  * \param c not really important
515  * \param context context to serach within
516  * \param exten extension to check
517  * \param priority priority of extension path
518  * \param callerid callerid of extension being searched for
519  *
520  * \note It is possible for autoservice to be started and stopped on c during this
521  * function call, it is important that c is not locked prior to calling this. Otherwise
522  * a deadlock may occur
523  *
524  * \return If "exten" *could be* a valid extension in this context with or without
525  * some more digits, return non-zero.  Basically, when this returns 0, no matter
526  * what you add to exten, it's not going to be a valid extension anymore
527  */
528 int ast_canmatch_extension(struct ast_channel *c, const char *context, 
529         const char *exten, int priority, const char *callerid);
530
531 /*! 
532  * \brief Looks to see if adding anything to this extension might match something. (exists ^ canmatch)
533  *
534  * \param c not really important XXX
535  * \param context context to serach within
536  * \param exten extension to check
537  * \param priority priority of extension path
538  * \param callerid callerid of extension being searched for
539  *
540  * \note It is possible for autoservice to be started and stopped on c during this
541  * function call, it is important that c is not locked prior to calling this. Otherwise
542  * a deadlock may occur
543  *
544  * \return If "exten" *could match* a valid extension in this context with
545  * some more digits, return non-zero.  Does NOT return non-zero if this is
546  * an exact-match only.  Basically, when this returns 0, no matter
547  * what you add to exten, it's not going to be a valid extension anymore
548  */
549 int ast_matchmore_extension(struct ast_channel *c, const char *context, 
550         const char *exten, int priority, const char *callerid);
551
552 /*! 
553  * \brief Determine if a given extension matches a given pattern (in NXX format)
554  * 
555  * \param pattern pattern to match
556  * \param extension extension to check against the pattern.
557  *
558  * Checks whether or not the given extension matches the given pattern.
559  *
560  * \retval 1 on match
561  * \retval 0 on failure
562  */
563 int ast_extension_match(const char *pattern, const char *extension);
564
565 int ast_extension_close(const char *pattern, const char *data, int needmore);
566
567 /*! 
568  * \brief Determine if one extension should match before another
569  * 
570  * \param a extension to compare with b
571  * \param b extension to compare with a
572  *
573  * Checks whether or extension a should match before extension b
574  *
575  * \retval 0 if the two extensions have equal matching priority
576  * \retval 1 on a > b
577  * \retval -1 on a < b
578  */
579 int ast_extension_cmp(const char *a, const char *b);
580
581 /*! 
582  * \brief Launch a new extension (i.e. new stack)
583  * 
584  * \param c not important
585  * \param context which context to generate the extension within
586  * \param exten new extension to add
587  * \param priority priority of new extension
588  * \param callerid callerid of extension
589  * \param found
590  * \param combined_find_spawn 
591  *
592  * This adds a new extension to the asterisk extension list.
593  *
594  * \note It is possible for autoservice to be started and stopped on c during this
595  * function call, it is important that c is not locked prior to calling this. Otherwise
596  * a deadlock may occur
597  *
598  * \retval 0 on success 
599  * \retval -1 on failure.
600  */
601 int ast_spawn_extension(struct ast_channel *c, const char *context, 
602       const char *exten, int priority, const char *callerid, int *found, int combined_find_spawn);
603
604 /*! 
605  * \brief Add a context include
606  *
607  * \param context context to add include to
608  * \param include new include to add
609  * \param registrar who's registering it
610  *
611  * Adds an include taking a char * string as the context parameter
612  *
613  * \retval 0 on success 
614  * \retval -1 on error
615 */
616 int ast_context_add_include(const char *context, const char *include, 
617         const char *registrar);
618
619 /*! 
620  * \brief Add a context include
621  * 
622  * \param con context to add the include to
623  * \param include include to add
624  * \param registrar who registered the context
625  *
626  * Adds an include taking a struct ast_context as the first parameter
627  *
628  * \retval 0 on success 
629  * \retval -1 on failure
630  */
631 int ast_context_add_include2(struct ast_context *con, const char *include, 
632         const char *registrar);
633
634 /*! 
635  * \brief Remove a context include
636  * 
637  * \note See ast_context_add_include for information on arguments
638  *
639  * \retval 0 on success
640  * \retval -1 on failure
641  */
642 int ast_context_remove_include(const char *context, const char *include, 
643         const char *registrar);
644
645 /*! 
646  * \brief Removes an include by an ast_context structure 
647  * 
648  * \note See ast_context_add_include2 for information on arguments
649  *
650  * \retval 0 on success
651  * \retval -1 on success
652  */
653 int ast_context_remove_include2(struct ast_context *con, const char *include, 
654         const char *registrar);
655
656 /*! 
657  * \brief Verifies includes in an ast_contect structure
658  * 
659  * \param con context in which to verify the includes
660  *
661  * \retval 0 if no problems found 
662  * \retval -1 if there were any missing context
663  */
664 int ast_context_verify_includes(struct ast_context *con);
665           
666 /*! 
667  * \brief Add a switch
668  * 
669  * \param context context to which to add the switch
670  * \param sw switch to add
671  * \param data data to pass to switch
672  * \param eval whether to evaluate variables when running switch
673  * \param registrar whoever registered the switch
674  *
675  * This function registers a switch with the asterisk switch architecture
676  *
677  * \retval 0 on success 
678  * \retval -1 on failure
679  */
680 int ast_context_add_switch(const char *context, const char *sw, const char *data, 
681         int eval, const char *registrar);
682
683 /*! 
684  * \brief Adds a switch (first param is a ast_context)
685  * 
686  * \note See ast_context_add_switch() for argument information, with the exception of
687  *       the first argument. In this case, it's a pointer to an ast_context structure
688  *       as opposed to the name.
689  */
690 int ast_context_add_switch2(struct ast_context *con, const char *sw, const char *data, 
691         int eval, const char *registrar);
692
693 /*! 
694  * \brief Remove a switch
695  * 
696  * Removes a switch with the given parameters
697  *
698  * \retval 0 on success 
699  * \retval -1 on failure
700  */
701 int ast_context_remove_switch(const char *context, const char *sw, 
702         const char *data, const char *registrar);
703
704 int ast_context_remove_switch2(struct ast_context *con, const char *sw, 
705         const char *data, const char *registrar);
706
707 /*! 
708  * \brief Simply remove extension from context
709  * 
710  * \param context context to remove extension from
711  * \param extension which extension to remove
712  * \param priority priority of extension to remove (0 to remove all)
713  * \param callerid NULL to remove all; non-NULL to match a single record per priority
714  * \param matchcid non-zero to match callerid element (if non-NULL); 0 to match default case
715  * \param registrar registrar of the extension
716  *
717  * This function removes an extension from a given context.
718  *
719  * \retval 0 on success 
720  * \retval -1 on failure
721  *
722  * @{
723  */
724 int ast_context_remove_extension(const char *context, const char *extension, int priority,
725         const char *registrar);
726
727 int ast_context_remove_extension2(struct ast_context *con, const char *extension,
728         int priority, const char *registrar, int already_locked);
729
730 int ast_context_remove_extension_callerid(const char *context, const char *extension,
731         int priority, const char *callerid, int matchcid, const char *registrar);
732
733 int ast_context_remove_extension_callerid2(struct ast_context *con, const char *extension,
734         int priority, const char *callerid, int matchcid, const char *registrar,
735         int already_locked);
736 /*! @} */
737
738 /*! 
739  * \brief Add an ignorepat
740  * 
741  * \param context which context to add the ignorpattern to
742  * \param ignorepat ignorepattern to set up for the extension
743  * \param registrar registrar of the ignore pattern
744  *
745  * Adds an ignore pattern to a particular context.
746  *
747  * \retval 0 on success 
748  * \retval -1 on failure
749  */
750 int ast_context_add_ignorepat(const char *context, const char *ignorepat, const char *registrar);
751
752 int ast_context_add_ignorepat2(struct ast_context *con, const char *ignorepat, const char *registrar);
753
754 /* 
755  * \brief Remove an ignorepat
756  * 
757  * \param context context from which to remove the pattern
758  * \param ignorepat the pattern to remove
759  * \param registrar the registrar of the ignore pattern
760  *
761  * This removes the given ignorepattern
762  *
763  * \retval 0 on success 
764  * \retval -1 on failure
765  */
766 int ast_context_remove_ignorepat(const char *context, const char *ignorepat, const char *registrar);
767
768 int ast_context_remove_ignorepat2(struct ast_context *con, const char *ignorepat, const char *registrar);
769
770 /*! 
771  * \brief Checks to see if a number should be ignored
772  * 
773  * \param context context to search within
774  * \param pattern to check whether it should be ignored or not
775  *
776  * Check if a number should be ignored with respect to dialtone cancellation.
777  *
778  * \retval 0 if the pattern should not be ignored 
779  * \retval non-zero if the pattern should be ignored 
780  */
781 int ast_ignore_pattern(const char *context, const char *pattern);
782
783 /* Locking functions for outer modules, especially for completion functions */
784
785 /*! 
786  * \brief Write locks the context list
787  *
788  * \retval 0 on success 
789  * \retval -1 on error
790  */
791 int ast_wrlock_contexts(void);
792
793 /*!
794  * \brief Read locks the context list
795  *
796  * \retval 0 on success
797  * \retval -1 on error
798  */
799 int ast_rdlock_contexts(void);
800
801 /*! 
802  * \brief Unlocks contexts
803  * 
804  * \retval 0 on success 
805  * \retval -1 on failure
806  */
807 int ast_unlock_contexts(void);
808
809 /*! 
810  * \brief Write locks a given context
811  * 
812  * \param con context to lock
813  *
814  * \retval 0 on success 
815  * \retval -1 on failure
816  */
817 int ast_wrlock_context(struct ast_context *con);
818
819 /*!
820  * \brief Read locks a given context
821  *
822  * \param con context to lock
823  *
824  * \retval 0 on success
825  * \retval -1 on failure
826  */
827 int ast_rdlock_context(struct ast_context *con);
828
829 /*! 
830  * \retval Unlocks the given context
831  * 
832  * \param con context to unlock
833  *
834  * \retval 0 on success 
835  * \retval -1 on failure
836  */
837 int ast_unlock_context(struct ast_context *con);
838
839 /*! 
840  * \brief locks the macrolock in the given given context
841  *
842  * \param macrocontext name of the macro-context to lock
843  *
844  * Locks the given macro-context to ensure only one thread (call) can execute it at a time
845  *
846  * \retval 0 on success
847  * \retval -1 on failure
848  */
849 int ast_context_lockmacro(const char *macrocontext);
850
851 /*!
852  * \brief Unlocks the macrolock in the given context
853  *
854  * \param macrocontext name of the macro-context to unlock
855  *
856  * Unlocks the given macro-context so that another thread (call) can execute it
857  *
858  * \retval 0 on success
859  * \retval -1 on failure
860  */
861 int ast_context_unlockmacro(const char *macrocontext);
862
863 /*!\brief Set the channel to next execute the specified dialplan location.
864  * \see ast_async_parseable_goto, ast_async_goto_if_exists
865  */
866 int ast_async_goto(struct ast_channel *chan, const char *context, const char *exten, int priority);
867
868 /*!\brief Set the channel to next execute the specified dialplan location.
869  */
870 int ast_async_goto_by_name(const char *chan, const char *context, const char *exten, int priority);
871
872 /*! Synchronously or asynchronously make an outbound call and send it to a
873    particular extension */
874 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, const char *account, struct ast_channel **locked_channel);
875
876 /*! Synchronously or asynchronously make an outbound call and send it to a
877    particular application with given extension */
878 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, const char *account, struct ast_channel **locked_channel);
879
880 /*!
881  * \brief Evaluate a condition
882  *
883  * \retval 0 if the condition is NULL or of zero length
884  * \retval int If the string is an integer, the integer representation of
885  *             the integer is returned
886  * \retval 1 Any other non-empty string
887  */
888 int pbx_checkcondition(const char *condition);
889
890 /*! @name 
891  * Functions for returning values from structures */
892 /*! @{ */
893 const char *ast_get_context_name(struct ast_context *con);
894 const char *ast_get_extension_name(struct ast_exten *exten);
895 struct ast_context *ast_get_extension_context(struct ast_exten *exten);
896 const char *ast_get_include_name(struct ast_include *include);
897 const char *ast_get_ignorepat_name(struct ast_ignorepat *ip);
898 const char *ast_get_switch_name(struct ast_sw *sw);
899 const char *ast_get_switch_data(struct ast_sw *sw);
900 int ast_get_switch_eval(struct ast_sw *sw);
901         
902 /*! @} */
903
904 /*! @name Other Extension stuff */
905 /*! @{ */
906 int ast_get_extension_priority(struct ast_exten *exten);
907 int ast_get_extension_matchcid(struct ast_exten *e);
908 const char *ast_get_extension_cidmatch(struct ast_exten *e);
909 const char *ast_get_extension_app(struct ast_exten *e);
910 const char *ast_get_extension_label(struct ast_exten *e);
911 void *ast_get_extension_app_data(struct ast_exten *e);
912 /*! @} */
913
914 /*! @name Registrar info functions ... */
915 /*! @{ */
916 const char *ast_get_context_registrar(struct ast_context *c);
917 const char *ast_get_extension_registrar(struct ast_exten *e);
918 const char *ast_get_include_registrar(struct ast_include *i);
919 const char *ast_get_ignorepat_registrar(struct ast_ignorepat *ip);
920 const char *ast_get_switch_registrar(struct ast_sw *sw);
921 /*! @} */
922
923 /*! @name Walking functions ... */
924 /*! @{ */
925 struct ast_context *ast_walk_contexts(struct ast_context *con);
926 struct ast_exten *ast_walk_context_extensions(struct ast_context *con,
927         struct ast_exten *priority);
928 struct ast_exten *ast_walk_extension_priorities(struct ast_exten *exten,
929         struct ast_exten *priority);
930 struct ast_include *ast_walk_context_includes(struct ast_context *con,
931         struct ast_include *inc);
932 struct ast_ignorepat *ast_walk_context_ignorepats(struct ast_context *con,
933         struct ast_ignorepat *ip);
934 struct ast_sw *ast_walk_context_switches(struct ast_context *con, struct ast_sw *sw);
935 /*! @} */
936
937 /*!\brief Create a human-readable string, specifying all variables and their corresponding values.
938  * \param chan Channel from which to read variables
939  * \param buf Dynamic string in which to place the result (should be allocated with \see ast_str_create).
940  * \note Will lock the channel.
941  */
942 int pbx_builtin_serialize_variables(struct ast_channel *chan, struct ast_str **buf);
943
944 /*!\brief Return a pointer to the value of the corresponding channel variable.
945  * \note Will lock the channel.
946  *
947  * \note This function will return a pointer to the buffer inside the channel
948  * variable.  This value should only be accessed with the channel locked.  If
949  * the value needs to be kept around, it should be done by using the following
950  * thread-safe code:
951  * \code
952  *              const char *var;
953  *
954  *              ast_channel_lock(chan);
955  *              if ((var = pbx_builtin_getvar_helper(chan, "MYVAR"))) {
956  *                      var = ast_strdupa(var);
957  *              }
958  *              ast_channel_unlock(chan);
959  * \endcode
960  */
961 const char *pbx_builtin_getvar_helper(struct ast_channel *chan, const char *name);
962
963 /*!\brief Add a variable to the channel variable stack, without removing any previously set value.
964  * \note Will lock the channel.
965  */
966 void pbx_builtin_pushvar_helper(struct ast_channel *chan, const char *name, const char *value);
967
968 /*!\brief Add a variable to the channel variable stack, removing the most recently set value for the same name.
969  * \note Will lock the channel.  May also be used to set a channel dialplan function to a particular value.
970  * \see ast_func_write
971  */
972 void pbx_builtin_setvar_helper(struct ast_channel *chan, const char *name, const char *value);
973
974 /*!\brief Retrieve the value of a builtin variable or variable from the channel variable stack.
975  * \note Will lock the channel.
976  */
977 void pbx_retrieve_variable(struct ast_channel *c, const char *var, char **ret, char *workspace, int workspacelen, struct varshead *headp);
978 void pbx_builtin_clear_globals(void);
979
980 /*!\brief Parse and set a single channel variable, where the name and value are separated with an '=' character.
981  * \note Will lock the channel.
982  */
983 int pbx_builtin_setvar(struct ast_channel *chan, const char *data);
984
985 /*!\brief Parse and set multiple channel variables, where the pairs are separated by the ',' character, and name and value are separated with an '=' character.
986  * \note Will lock the channel.
987  */
988 int pbx_builtin_setvar_multiple(struct ast_channel *chan, const char *data);
989
990 int pbx_builtin_raise_exception(struct ast_channel *chan, const char *data);
991
992 /*! @name Substitution routines, using static string buffers
993  * @{ */
994 void pbx_substitute_variables_helper(struct ast_channel *c, const char *cp1, char *cp2, int count);
995 void pbx_substitute_variables_varshead(struct varshead *headp, const char *cp1, char *cp2, int count);
996 void pbx_substitute_variables_helper_full(struct ast_channel *c, struct varshead *headp, const char *cp1, char *cp2, int cp2_size, size_t *used);
997 /*! @} */
998 /*! @} */
999
1000 /*! @name Substitution routines, using dynamic string buffers */
1001
1002 /*!
1003  * \param buf Result will be placed in this buffer.
1004  * \param maxlen -1 if the buffer should not grow, 0 if the buffer may grow to any size, and >0 if the buffer should grow only to that number of bytes.
1005  * \param chan Channel variables from which to extract values, and channel to pass to any dialplan functions.
1006  * \param headp If no channel is specified, a channel list from which to extract variable values
1007  * \param var Variable name to retrieve.
1008  */
1009 const char *ast_str_retrieve_variable(struct ast_str **buf, ssize_t maxlen, struct ast_channel *chan, struct varshead *headp, const char *var);
1010
1011 /*!
1012  * \param buf Result will be placed in this buffer.
1013  * \param maxlen -1 if the buffer should not grow, 0 if the buffer may grow to any size, and >0 if the buffer should grow only to that number of bytes.
1014  * \param chan Channel variables from which to extract values, and channel to pass to any dialplan functions.
1015  * \param templ Variable template to expand.
1016  */
1017 void ast_str_substitute_variables(struct ast_str **buf, ssize_t maxlen, struct ast_channel *chan, const char *templ);
1018
1019 /*!
1020  * \param buf Result will be placed in this buffer.
1021  * \param maxlen -1 if the buffer should not grow, 0 if the buffer may grow to any size, and >0 if the buffer should grow only to that number of bytes.
1022  * \param headp If no channel is specified, a channel list from which to extract variable values
1023  * \param templ Variable template to expand.
1024  */
1025 void ast_str_substitute_variables_varshead(struct ast_str **buf, ssize_t maxlen, struct varshead *headp, const char *templ);
1026
1027 /*!
1028  * \param buf Result will be placed in this buffer.
1029  * \param maxlen -1 if the buffer should not grow, 0 if the buffer may grow to any size, and >0 if the buffer should grow only to that number of bytes.
1030  * \param c Channel variables from which to extract values, and channel to pass to any dialplan functions.
1031  * \param headp If no channel is specified, a channel list from which to extract variable values
1032  * \param templ Variable template to expand.
1033  * \param used Number of bytes read from the template.
1034  */
1035 void ast_str_substitute_variables_full(struct ast_str **buf, ssize_t maxlen, struct ast_channel *c, struct varshead *headp, const char *templ, size_t *used);
1036 /*! @} */
1037
1038 int ast_extension_patmatch(const char *pattern, const char *data);
1039
1040 /*! Set "autofallthrough" flag, if newval is <0, does not actually set.  If
1041   set to 1, sets to auto fall through.  If newval set to 0, sets to no auto
1042   fall through (reads extension instead).  Returns previous value. */
1043 int pbx_set_autofallthrough(int newval);
1044
1045 /*! Set "extenpatternmatchnew" flag, if newval is <0, does not actually set.  If
1046   set to 1, sets to use the new Trie-based pattern matcher.  If newval set to 0, sets to use
1047   the old linear-search algorithm.  Returns previous value. */
1048 int pbx_set_extenpatternmatchnew(int newval);
1049
1050 /*! Set "overrideswitch" field.  If set and of nonzero length, all contexts
1051  * will be tried directly through the named switch prior to any other
1052  * matching within that context.
1053  * \since 1.6.1
1054  */ 
1055 void pbx_set_overrideswitch(const char *newval);
1056
1057 /*!
1058  * \note This function will handle locking the channel as needed.
1059  */
1060 int ast_goto_if_exists(struct ast_channel *chan, const char *context, const char *exten, int priority);
1061
1062 /*!
1063  * \note This function will handle locking the channel as needed.
1064  */
1065 int ast_parseable_goto(struct ast_channel *chan, const char *goto_string);
1066
1067 /*!
1068  * \note This function will handle locking the channel as needed.
1069  */
1070 int ast_async_parseable_goto(struct ast_channel *chan, const char *goto_string);
1071
1072 /*!
1073  * \note This function will handle locking the channel as needed.
1074  */
1075 int ast_explicit_goto(struct ast_channel *chan, const char *context, const char *exten, int priority);
1076
1077 /*!
1078  * \note This function will handle locking the channel as needed.
1079  */
1080 int ast_async_goto_if_exists(struct ast_channel *chan, const char *context, const char *exten, int priority);
1081
1082 struct ast_custom_function* ast_custom_function_find(const char *name);
1083
1084 /*!
1085  * \brief Unregister a custom function
1086  */
1087 int ast_custom_function_unregister(struct ast_custom_function *acf);
1088
1089 /*!
1090  * \brief Register a custom function
1091  */
1092 #define ast_custom_function_register(acf) __ast_custom_function_register(acf, ast_module_info->self)
1093
1094 /*!
1095  * \brief Register a custom function
1096  */
1097 int __ast_custom_function_register(struct ast_custom_function *acf, struct ast_module *mod);
1098
1099 /*! 
1100  * \brief Retrieve the number of active calls
1101  */
1102 int ast_active_calls(void);
1103
1104 /*! 
1105  * \brief Retrieve the total number of calls processed through the PBX since last restart
1106  */
1107 int ast_processed_calls(void);
1108         
1109 /*!
1110  * \brief executes a read operation on a function 
1111  *
1112  * \param chan Channel to execute on
1113  * \param function Data containing the function call string (will be modified)
1114  * \param workspace A pointer to safe memory to use for a return value 
1115  * \param len the number of bytes in workspace
1116  *
1117  * This application executes a function in read mode on a given channel.
1118  *
1119  * \retval 0 success
1120  * \retval non-zero failure
1121  */
1122 int ast_func_read(struct ast_channel *chan, const char *function, char *workspace, size_t len);
1123
1124 /*!
1125  * \brief executes a read operation on a function 
1126  *
1127  * \param chan Channel to execute on
1128  * \param function Data containing the function call string (will be modified)
1129  * \param str A dynamic string buffer into which to place the result.
1130  * \param maxlen <0 if the dynamic buffer should not grow; >0 if the dynamic buffer should be limited to that number of bytes; 0 if the dynamic buffer has no upper limit
1131  *
1132  * This application executes a function in read mode on a given channel.
1133  *
1134  * \retval 0 success
1135  * \retval non-zero failure
1136  */
1137 int ast_func_read2(struct ast_channel *chan, const char *function, struct ast_str **str, ssize_t maxlen);
1138
1139 /*!
1140  * \brief executes a write operation on a function
1141  *
1142  * \param chan Channel to execute on
1143  * \param function Data containing the function call string (will be modified)
1144  * \param value A value parameter to pass for writing
1145  *
1146  * This application executes a function in write mode on a given channel.
1147  *
1148  * \retval 0 success
1149  * \retval non-zero failure
1150  */
1151 int ast_func_write(struct ast_channel *chan, const char *function, const char *value);
1152
1153 /*!
1154  * When looking up extensions, we can have different requests
1155  * identified by the 'action' argument, as follows.
1156  * Note that the coding is such that the low 4 bits are the
1157  * third argument to extension_match_core.
1158  */
1159
1160 enum ext_match_t {
1161         E_MATCHMORE =   0x00,   /* extension can match but only with more 'digits' */
1162         E_CANMATCH =    0x01,   /* extension can match with or without more 'digits' */
1163         E_MATCH =       0x02,   /* extension is an exact match */
1164         E_MATCH_MASK =  0x03,   /* mask for the argument to extension_match_core() */
1165         E_SPAWN =       0x12,   /* want to spawn an extension. Requires exact match */
1166         E_FINDLABEL =   0x22    /* returns the priority for a given label. Requires exact match */
1167 };
1168
1169 #define STATUS_NO_CONTEXT       1
1170 #define STATUS_NO_EXTENSION     2
1171 #define STATUS_NO_PRIORITY      3
1172 #define STATUS_NO_LABEL         4
1173 #define STATUS_SUCCESS          5 
1174 #define AST_PBX_MAX_STACK  128
1175
1176 /* request and result for pbx_find_extension */
1177 struct pbx_find_info {
1178 #if 0
1179         const char *context;
1180         const char *exten;
1181         int priority;
1182 #endif
1183
1184         char *incstack[AST_PBX_MAX_STACK];      /* filled during the search */
1185         int stacklen;                   /* modified during the search */
1186         int status;                     /* set on return */
1187         struct ast_switch *swo;         /* set on return */
1188         const char *data;               /* set on return */
1189         const char *foundcontext;       /* set on return */
1190 };
1191  
1192 struct ast_exten *pbx_find_extension(struct ast_channel *chan,
1193                                                                          struct ast_context *bypass, struct pbx_find_info *q,
1194                                                                          const char *context, const char *exten, int priority,
1195                                                                          const char *label, const char *callerid, enum ext_match_t action);
1196
1197
1198 /* every time a write lock is obtained for contexts,
1199    a counter is incremented. You can check this via the
1200    following func */
1201
1202 int ast_wrlock_contexts_version(void);
1203         
1204
1205 /*!\brief hashtable functions for contexts */
1206 /*! @{ */
1207 int ast_hashtab_compare_contexts(const void *ah_a, const void *ah_b);
1208 unsigned int ast_hashtab_hash_contexts(const void *obj);
1209 /*! @} */
1210
1211 /*!
1212  * \brief Command completion for the list of installed applications.
1213  *
1214  * This can be called from a CLI command completion function that wants to
1215  * complete from the list of available applications.
1216  */
1217 char *ast_complete_applications(const char *line, const char *word, int state);
1218
1219 #if defined(__cplusplus) || defined(c_plusplus)
1220 }
1221 #endif
1222
1223 #endif /* _ASTERISK_PBX_H */