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