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