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