app_queue.c: Queue don't play "thank-you" when here is no hold time announcements
[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/channel.h"
27 #include "asterisk/sched.h"
28 #include "asterisk/devicestate.h"
29 #include "asterisk/presencestate.h"
30 #include "asterisk/chanvars.h"
31 #include "asterisk/hashtab.h"
32 #include "asterisk/stringfields.h"
33 #include "asterisk/xmldoc.h"
34 #include "asterisk/format.h"
35
36 #if defined(__cplusplus) || defined(c_plusplus)
37 extern "C" {
38 #endif
39
40 #define AST_MAX_APP     32      /*!< Max length of an application */
41
42 #define AST_PBX_GOTO_FAILED -3
43 #define AST_PBX_KEEP    0
44 #define AST_PBX_REPLACE 1
45
46 /*! \brief Special return values from applications to the PBX
47  * @{ */
48 #define AST_PBX_HANGUP                -1    /*!< Jump to the 'h' exten */
49 #define AST_PBX_OK                     0    /*!< No errors */
50 #define AST_PBX_ERROR                  1    /*!< Jump to the 'e' exten */
51 #define AST_PBX_INCOMPLETE             12   /*!< Return to PBX matching, allowing more digits for the extension */
52 /*! @} */
53
54 #define PRIORITY_HINT   -1      /*!< Special Priority for a hint */
55
56 /*!
57  * \brief Extension states
58  * \note States can be combined
59  * \ref AstExtState
60  */
61 enum ast_extension_states {
62         AST_EXTENSION_REMOVED = -2,     /*!< Extension removed */
63         AST_EXTENSION_DEACTIVATED = -1, /*!< Extension hint removed */
64         AST_EXTENSION_NOT_INUSE = 0,    /*!< No device INUSE or BUSY  */
65         AST_EXTENSION_INUSE = 1 << 0,   /*!< One or more devices INUSE */
66         AST_EXTENSION_BUSY = 1 << 1,    /*!< All devices BUSY */
67         AST_EXTENSION_UNAVAILABLE = 1 << 2, /*!< All devices UNAVAILABLE/UNREGISTERED */
68         AST_EXTENSION_RINGING = 1 << 3, /*!< All devices RINGING */
69         AST_EXTENSION_ONHOLD = 1 << 4,  /*!< All devices ONHOLD */
70 };
71
72 /*!
73  * \brief extension matchcid types
74  * \note matchcid in ast_exten retains 0/1, this adds 3rd state for functions to specify all
75  * \see ast_context_remove_extension_callerid
76  */
77 enum ast_ext_matchcid_types {
78         AST_EXT_MATCHCID_OFF = 0,       /*!< Match only extensions with matchcid=0 */
79         AST_EXT_MATCHCID_ON = 1,        /*!< Match only extensions with matchcid=1 AND cidmatch matches */
80         AST_EXT_MATCHCID_ANY = 2,       /*!< Match both - used only in functions manipulating ast_exten's */
81 };
82
83 struct ast_context;
84 struct ast_exten;
85 struct ast_include;
86 struct ast_ignorepat;
87 struct ast_sw;
88
89 enum ast_state_cb_update_reason {
90         /*! The extension state update is a result of a device state changing on the extension. */
91         AST_HINT_UPDATE_DEVICE = 1,
92         /*! The extension state update is a result of presence state changing on the extension. */
93         AST_HINT_UPDATE_PRESENCE = 2,
94 };
95
96 struct ast_device_state_info {
97         enum ast_device_state device_state;
98         struct ast_channel *causing_channel;
99         char device_name[1];
100 };
101
102 struct ast_state_cb_info {
103         enum ast_state_cb_update_reason reason;
104         enum ast_extension_states exten_state;
105         struct ao2_container *device_state_info; /* holds ast_device_state_info, must be referenced by callback if stored */
106         enum ast_presence_state presence_state;
107         const char *presence_subtype;
108         const char *presence_message;
109 };
110
111 /*! \brief Typedef for devicestate and hint callbacks */
112 typedef int (*ast_state_cb_type)(const char *context, const char *exten, struct ast_state_cb_info *info, void *data);
113
114 /*! \brief Typedef for devicestate and hint callback removal indication callback */
115 typedef void (*ast_state_cb_destroy_type)(int id, void *data);
116
117 /*! \brief Data structure associated with a custom dialplan function */
118 struct ast_custom_function {
119         const char *name;                       /*!< Name */
120         AST_DECLARE_STRING_FIELDS(
121                 AST_STRING_FIELD(synopsis);     /*!< Synopsis text for 'show functions' */
122                 AST_STRING_FIELD(desc);         /*!< Description (help text) for 'show functions &lt;name&gt;' */
123                 AST_STRING_FIELD(syntax);       /*!< Syntax text for 'core show functions' */
124                 AST_STRING_FIELD(arguments);    /*!< Arguments description */
125                 AST_STRING_FIELD(seealso);      /*!< See also */
126         );
127         enum ast_doc_src docsrc;                /*!< Where the documentation come from */
128         /*! Read function, if read is supported */
129         ast_acf_read_fn_t read;         /*!< Read function, if read is supported */
130         /*! Read function, if read is supported.  Note: only one of read or read2
131          * needs to be implemented.  In new code, read2 should be implemented as
132          * the way forward, but they should return identical results, within the
133          * constraints of buffer size, if both are implemented.  That is, if the
134          * read function is handed a 16-byte buffer, and the result is 17 bytes
135          * long, then the first 15 bytes (remember NULL terminator) should be
136          * the same for both the read and the read2 methods. */
137         ast_acf_read2_fn_t read2;
138         /*! If no read2 function is provided, what maximum size? */
139         size_t read_max;
140         /*! Write function, if write is supported */
141         ast_acf_write_fn_t write;       /*!< Write function, if write is supported */
142         struct ast_module *mod;         /*!< Module this custom function belongs to */
143         unsigned int read_escalates:1;  /*!< The read function is to be considered
144                                          * 'dangerous', and should not be run directly
145                                          * from external interfaces (AMI, ARI, etc.)
146                                          * \since 12 */
147         unsigned int write_escalates:1; /*!< The write function is to be considered
148                                          * 'dangerous', and should not be run directly
149                                          * from external interfaces (AMI, ARI, etc.)
150                                          * \since 12 */
151
152         AST_RWLIST_ENTRY(ast_custom_function) acflist;
153 };
154
155 /*! \brief All switch functions have the same interface, so define a type for them */
156 typedef int (ast_switch_f)(struct ast_channel *chan, const char *context,
157         const char *exten, int priority, const char *callerid, const char *data);
158
159 /*!< Data structure associated with an Asterisk switch */
160 struct ast_switch {
161         AST_LIST_ENTRY(ast_switch) list;
162         const char *name;                       /*!< Name of the switch */
163         const char *description;                /*!< Description of the switch */
164
165         ast_switch_f *exists;
166         ast_switch_f *canmatch;
167         ast_switch_f *exec;
168         ast_switch_f *matchmore;
169 };
170
171 struct ast_timing {
172         int hastime;                    /*!< If time construct exists */
173         unsigned int monthmask;         /*!< Mask for month */
174         unsigned int daymask;           /*!< Mask for date */
175         unsigned int dowmask;           /*!< Mask for day of week (sun-sat) */
176         unsigned int minmask[48];       /*!< Mask for minute */
177         char *timezone;                 /*!< NULL, or zoneinfo style timezone */
178 };
179
180 /*!
181  * \brief Construct a timing bitmap, for use in time-based conditionals.
182  * \param i Pointer to an ast_timing structure.
183  * \param info_in Standard string containing a timerange, weekday range, monthday range, and month range, as well as an optional timezone.
184  * \retval 1 on success.
185  * \retval 0 on failure.
186  */
187 int ast_build_timing(struct ast_timing *i, const char *info_in);
188
189 /*!
190  * \brief Evaluate a pre-constructed bitmap as to whether the current time falls within the range specified.
191  * \param i Pointer to an ast_timing structure.
192  * \retval 1 if the time matches.
193  * \retval 0 if the current time falls outside of the specified range.
194  */
195 int ast_check_timing(const struct ast_timing *i);
196
197 /*!
198  * \brief Evaluate a pre-constructed bitmap as to whether a particular time falls within the range specified.
199  * \param i Pointer to an ast_timing structure.
200  * \param tv Specified time
201  * \retval 1 if the time matches.
202  * \retval 0 if the time falls outside of the specified range.
203  */
204 int ast_check_timing2(const struct ast_timing *i, const struct timeval tv);
205
206 /*!
207  * \brief Deallocates memory structures associated with a timing bitmap.
208  * \param i Pointer to an ast_timing structure.
209  * \retval 0 success
210  * \retval non-zero failure (number suitable to pass to \see strerror)
211  */
212 int ast_destroy_timing(struct ast_timing *i);
213
214 struct ast_pbx {
215         int dtimeoutms;                         /*!< Timeout between digits (milliseconds) */
216         int rtimeoutms;                         /*!< Timeout for response (milliseconds) */
217 };
218
219
220 /*!
221  * \brief Register an alternative dialplan switch
222  *
223  * \param sw switch to register
224  *
225  * This function registers a populated ast_switch structure with the
226  * asterisk switching architecture.
227  *
228  * \retval 0 success
229  * \retval non-zero failure
230  */
231 int ast_register_switch(struct ast_switch *sw);
232
233 /*!
234  * \brief Unregister an alternative switch
235  *
236  * \param sw switch to unregister
237  *
238  * Unregisters a switch from asterisk.
239  */
240 void ast_unregister_switch(struct ast_switch *sw);
241
242 /*!
243  * \brief Look up an application
244  *
245  * \param app name of the app
246  *
247  * This function searches for the ast_app structure within
248  * the apps that are registered for the one with the name
249  * you passed in.
250  *
251  * \return the ast_app structure that matches on success, or NULL on failure
252  */
253 struct ast_app *pbx_findapp(const char *app);
254
255 /*!
256  * \brief Execute an application
257  *
258  * \param c channel to execute on
259  * \param app which app to execute
260  * \param data the data passed into the app
261  *
262  * This application executes an application on a given channel.  It
263  * saves the stack and executes the given application passing in
264  * the given data.
265  *
266  * \retval 0 success
267  * \retval -1 failure
268  */
269 int pbx_exec(struct ast_channel *c, struct ast_app *app, const char *data);
270
271 /*!
272  * \brief Register a new context or find an existing one
273  *
274  * \param extcontexts pointer to the ast_context structure pointer
275  * \param exttable pointer to the hashtable that contains all the elements in extcontexts
276  * \param name name of the new context
277  * \param registrar registrar of the context
278  *
279  * This function allows you to play in two environments: the global contexts (active dialplan)
280  * or an external context set of your choosing. To act on the external set, make sure extcontexts
281  * and exttable are set; for the globals, make sure both extcontexts and exttable are NULL.
282  *
283  * This will first search for a context with your name.  If it exists already, it will not
284  * create a new one.  If it does not exist, it will create a new one with the given name
285  * and registrar.
286  *
287  * \return NULL on failure, and an ast_context structure on success
288  */
289 struct ast_context *ast_context_find_or_create(struct ast_context **extcontexts, struct ast_hashtab *exttable, const char *name, const char *registrar);
290
291 /*!
292  * \brief Enable or disable autohints support on a context
293  *
294  * \param con pointer to the context
295  * \param enabled whether autohints are enabled
296  *
297  */
298 void ast_context_set_autohints(struct ast_context *con, int enabled);
299
300 /*!
301  * \brief Merge the temporary contexts into a global contexts list and delete from the
302  *        global list the ones that are being added
303  *
304  * \param extcontexts pointer to the ast_context structure
305  * \param exttable pointer to the ast_hashtab structure that contains all the elements in extcontexts
306  * \param registrar of the context; if it's set the routine will delete all contexts
307  *        that belong to that registrar; if NULL only the contexts that are specified
308  *        in extcontexts
309  */
310 void ast_merge_contexts_and_delete(struct ast_context **extcontexts, struct ast_hashtab *exttable, const char *registrar);
311
312 /*!
313  * \brief Destroy a context by name
314  *
315  * \param context Name of the context to destroy
316  * \param registrar who registered it
317  *
318  * You can optionally leave out the registrar parameter.  It will find it
319  * based on the context name.
320  *
321  * \retval -1 context not found
322  * \retval 0 Success
323  */
324 int ast_context_destroy_by_name(const char *context, const char *registrar);
325
326 /*!
327  * \brief Destroy a context (matches the specified context or ANY context if NULL)
328  *
329  * \param con context to destroy
330  * \param registrar who registered it
331  *
332  * You can optionally leave out either parameter.  It will find it
333  * based on either the ast_context or the registrar name.
334  */
335 void ast_context_destroy(struct ast_context *con, const char *registrar);
336
337 /*!
338  * \brief Find a context
339  *
340  * \param name name of the context to find
341  *
342  * Will search for the context with the given name.
343  *
344  * \return the ast_context on success, NULL on failure.
345  */
346 struct ast_context *ast_context_find(const char *name);
347
348 /*!
349  * \brief The result codes when starting the PBX on a channel with ast_pbx_start.
350  * \note AST_PBX_CALL_LIMIT refers to the maxcalls call limit in asterisk.conf
351  * \see ast_pbx_start
352  */
353 enum ast_pbx_result {
354         AST_PBX_SUCCESS = 0,
355         AST_PBX_FAILED = -1,
356         AST_PBX_CALL_LIMIT = -2,
357 };
358
359 /*!
360  * \brief Create a new thread and start the PBX
361  *
362  * \param c channel to start the pbx on
363  *
364  * \see ast_pbx_run for a synchronous function to run the PBX in the
365  * current thread, as opposed to starting a new one.
366  *
367  * \retval Zero on success
368  * \retval non-zero on failure
369  */
370 enum ast_pbx_result ast_pbx_start(struct ast_channel *c);
371
372 /*!
373  * \brief Execute the PBX in the current thread
374  *
375  * \param c channel to run the pbx on
376  *
377  * This executes the PBX on a given channel. It allocates a new
378  * PBX structure for the channel, and provides all PBX functionality.
379  * See ast_pbx_start for an asynchronous function to run the PBX in a
380  * new thread as opposed to the current one.
381  *
382  * \retval Zero on success
383  * \retval non-zero on failure
384  */
385 enum ast_pbx_result ast_pbx_run(struct ast_channel *c);
386
387 /*!
388  * \brief Options for ast_pbx_run()
389  */
390 struct ast_pbx_args {
391         union {
392                 /*! Pad this out so that we have plenty of room to add options
393                  *  but still maintain ABI compatibility over time. */
394                 uint64_t __padding;
395                 struct {
396                         /*! Do not hangup the channel when the PBX is complete. */
397                         unsigned int no_hangup_chan:1;
398                 };
399         };
400 };
401
402 /*!
403  * \brief Execute the PBX in the current thread
404  *
405  * \param c channel to run the pbx on
406  * \param args options for the pbx
407  *
408  * This executes the PBX on a given channel. It allocates a new
409  * PBX structure for the channel, and provides all PBX functionality.
410  * See ast_pbx_start for an asynchronous function to run the PBX in a
411  * new thread as opposed to the current one.
412  *
413  * \retval Zero on success
414  * \retval non-zero on failure
415  */
416 enum ast_pbx_result ast_pbx_run_args(struct ast_channel *c, struct ast_pbx_args *args);
417
418 /*!
419  * \brief Run the h exten from the given context.
420  * \since 11.0
421  *
422  * \param chan Channel to run the h exten on.
423  * \param context Context the h exten is in.
424  */
425 void ast_pbx_h_exten_run(struct ast_channel *chan, const char *context);
426
427 /*!
428  * \brief Run all hangup handlers on the channel.
429  * \since 11.0
430  *
431  * \param chan Channel to run the hangup handlers on.
432  *
433  * \note Absolutely _NO_ channel locks should be held before calling this function.
434  *
435  * \retval Zero if no hangup handlers run.
436  * \retval non-zero if hangup handlers were run.
437  */
438 int ast_pbx_hangup_handler_run(struct ast_channel *chan);
439
440 /*!
441  * \brief Init the hangup handler container on a channel.
442  * \since 11.0
443  *
444  * \param chan Channel to init the hangup handler container on.
445  */
446 void ast_pbx_hangup_handler_init(struct ast_channel *chan);
447
448 /*!
449  * \brief Destroy the hangup handler container on a channel.
450  * \since 11.0
451  *
452  * \param chan Channel to destroy the hangup handler container on.
453  */
454 void ast_pbx_hangup_handler_destroy(struct ast_channel *chan);
455
456 /*!
457  * \brief Pop the top of the channel hangup handler stack.
458  * \since 11.0
459  *
460  * \param chan Channel to push the hangup handler onto.
461  *
462  * \retval TRUE if a handler was popped off of the stack.
463  */
464 int ast_pbx_hangup_handler_pop(struct ast_channel *chan);
465
466 /*!
467  * \brief Push the given hangup handler onto the channel hangup handler stack.
468  * \since 11.0
469  *
470  * \param chan Channel to push the hangup handler onto.
471  * \param handler Gosub application parameter string.
472  */
473 void ast_pbx_hangup_handler_push(struct ast_channel *chan, const char *handler);
474
475 /*!
476  * \brief Add and extension to an extension context.
477  *
478  * \param context context to add the extension to
479  * \param replace
480  * \param extension extension to add
481  * \param priority priority level of extension addition
482  * \param label extension label
483  * \param callerid pattern to match CallerID, or NULL to match any CallerID
484  * \param application application to run on the extension with that priority level
485  * \param data data to pass to the application
486  * \param datad a pointer to a function that will deallocate \c data when needed
487  *              or NULL if \c data does not need to be freed.
488  * \param registrar who registered the extension
489  *
490  * \note On any failure, the function pointed to by \c datap will be called and passed the
491  *       \c data pointer.
492  *
493  * \retval 0 success
494  * \retval -1 failure
495  */
496 int ast_add_extension(const char *context, int replace, const char *extension,
497         int priority, const char *label, const char *callerid,
498         const char *application, void *data, void (*datad)(void *), const char *registrar);
499
500 /*!
501  * \brief Add an extension to an extension context, this time with an ast_context *.
502  *
503  * \param con context to add the extension to
504  * \param replace
505  * \param extension extension to add
506  * \param priority priority level of extension addition
507  * \param label extension label
508  * \param callerid pattern to match CallerID, or NULL to match any CallerID
509  * \param application application to run on the extension with that priority level
510  * \param data data to pass to the application
511  * \param datad a pointer to a function that will deallocate \c data when needed
512  *              or NULL if \c data does not need to be freed.
513  * \param registrar who registered the extension
514  * \param registrar_file optional configuration file that defines this extension
515  * \param registrar_line optional line number of configuration file that defines extension
516  *
517  * \note On any failure, the function pointed to by \c datap will be called and passed the
518  *       \c data pointer.
519  *
520  * \retval 0 success
521  * \retval -1 failure
522  */
523 int ast_add_extension2(struct ast_context *con, int replace, const char *extension,
524         int priority, const char *label, const char *callerid,
525         const char *application, void *data, void (*datad)(void *), const char *registrar,
526         const char *registrar_file, int registrar_line);
527
528 /*!
529  * \brief Same as ast_add_extension2, but assumes you have already locked context
530  * \since 12.0.0
531  *
532  * \note con must be write locked prior to calling. For details about the arguments,
533  *       check ast_add_extension()
534  */
535 int ast_add_extension2_nolock(struct ast_context *con, int replace, const char *extension,
536         int priority, const char *label, const char *callerid,
537         const char *application, void *data, void (*datad)(void *), const char *registrar,
538         const char *registrar_file, int registrar_line);
539
540 /*!
541  * \brief Map devstate to an extension state.
542  *
543  * \param[in] devstate device state
544  *
545  * \return the extension state mapping.
546  */
547 enum ast_extension_states ast_devstate_to_extenstate(enum ast_device_state devstate);
548
549 /*!
550  * \brief Uses hint and devicestate callback to get the state of an extension
551  *
552  * \param c this is not important
553  * \param context which context to look in
554  * \param exten which extension to get state
555  *
556  * \return extension state as defined in the ast_extension_states enum
557  */
558 int ast_extension_state(struct ast_channel *c, const char *context, const char *exten);
559
560 /*!
561  * \brief Uses hint and devicestate callback to get the extended state of an extension
562  * \since 11
563  *
564  * \param c this is not important
565  * \param context which context to look in
566  * \param exten which extension to get state
567  * \param[out] device_state_info ptr to an ao2_container with extended state info, must be unref'd after use.
568  *
569  * \return extension state as defined in the ast_extension_states enum
570  */
571 int ast_extension_state_extended(struct ast_channel *c, const char *context, const char *exten,
572         struct ao2_container **device_state_info);
573
574 /*!
575  * \brief Uses hint and presence state callback to get the presence state of an extension
576  *
577  * \param c this is not important
578  * \param context which context to look in
579  * \param exten which extension to get state
580  * \param[out] subtype Further information regarding the presence returned
581  * \param[out] message Custom message further describing current presence
582  *
583  * \note The subtype and message are dynamically allocated and must be freed by
584  * the caller of this function.
585  *
586  * \return returns the presence state value.
587  */
588 int ast_hint_presence_state(struct ast_channel *c, const char *context, const char *exten, char **subtype, char **message);
589
590 /*!
591  * \brief Return string representation of the state of an extension
592  *
593  * \param extension_state is the numerical state delivered by ast_extension_state
594  *
595  * \return the state of an extension as string
596  */
597 const char *ast_extension_state2str(int extension_state);
598
599 /*!
600  * \brief Add watcher for extension states with destructor.
601  * \since 1.8.9
602  * \since 10.1.0
603  *
604  * \param context which context to look in
605  * \param exten which extension to get state
606  * \param change_cb callback to call if state changed
607  * \param destroy_cb callback to call when the watcher is destroyed.
608  * \param data to pass to callbacks
609  *
610  * \note If context and exten are NULL then the added watcher is global.
611  * The change_cb is called for every extension's state change.
612  *
613  * \note The change_cb is called if the state of an extension is changed.
614  *
615  * \note The destroy_cb is called when the watcher is deleted so the
616  * watcher can release any associated resources.
617  *
618  * \retval -1 on failure
619  * \retval 0 Global watcher added successfully
620  * \retval ID on success
621  */
622 int ast_extension_state_add_destroy(const char *context, const char *exten,
623         ast_state_cb_type change_cb, ast_state_cb_destroy_type destroy_cb, void *data);
624
625 /*!
626  * \brief Add watcher for extended extension states with destructor.
627  * \since 11
628  *
629  * \param context which context to look in
630  * \param exten which extension to get state
631  * \param change_cb callback to call if state changed
632  * \param destroy_cb callback to call when the watcher is destroyed.
633  * \param data to pass to callbacks
634  *
635  * \note If context and exten are NULL then the added watcher is global.
636  * The change_cb is called for every extension's state change.
637  *
638  * \note The change_cb is called if the state of an extension is changed.
639  * The extended state is passed to the callback in the device_state_info
640  * member of ast_state_cb_info.
641  *
642  * \note The destroy_cb is called when the watcher is deleted so the
643  * watcher can release any associated resources.
644  *
645  * \retval -1 on failure
646  * \retval 0 Global watcher added successfully
647  * \retval ID on success
648  */
649 int ast_extension_state_add_destroy_extended(const char *context, const char *exten,
650         ast_state_cb_type change_cb, ast_state_cb_destroy_type destroy_cb, void *data);
651
652 /*!
653  * \brief Add watcher for extension states.
654  *
655  * \param context which context to look in
656  * \param exten which extension to get state
657  * \param change_cb callback to call if state changed
658  * \param data to pass to callback
659  *
660  * \note If context and exten are NULL then the added watcher is global.
661  * The change_cb is called for every extension's state change.
662  *
663  * \note The change_cb is called if the state of an extension is changed.
664  *
665  * \retval -1 on failure
666  * \retval 0 Global watcher added successfully
667  * \retval ID on success
668  */
669 int ast_extension_state_add(const char *context, const char *exten,
670         ast_state_cb_type change_cb, void *data);
671
672 /*!
673  * \brief Add watcher for extended extension states.
674  * \since 11
675  *
676  * \param context which context to look in
677  * \param exten which extension to get state
678  * \param change_cb callback to call if state changed
679  * \param data to pass to callback
680  *
681  * \note If context and exten are NULL then the added watcher is global.
682  * The change_cb is called for every extension's state change.
683  *
684  * \note The change_cb is called if the state of an extension is changed.
685  * The extended state is passed to the callback in the device_state_info
686  * member of ast_state_cb_info.
687  *
688  * \retval -1 on failure
689  * \retval 0 Global watcher added successfully
690  * \retval ID on success
691  */
692 int ast_extension_state_add_extended(const char *context, const char *exten,
693         ast_state_cb_type change_cb, void *data);
694
695 /*!
696  * \brief Deletes a state change watcher by ID
697  *
698  * \param id of the state watcher to delete (0 for global watcher)
699  * \param change_cb callback to call if state changed (Used if id == 0 (global))
700  *
701  * \retval 0 success
702  * \retval -1 failure
703  */
704 int ast_extension_state_del(int id, ast_state_cb_type change_cb);
705
706 /*!
707  * \brief If an extension hint exists, return non-zero
708  *
709  * \param hint buffer for hint
710  * \param hintsize size of hint buffer, in bytes
711  * \param name buffer for name portion of hint
712  * \param namesize size of name buffer
713  * \param c Channel from which to return the hint.  This is only important when the hint or name contains an expression to be expanded.
714  * \param context which context to look in
715  * \param exten which extension to search for
716  *
717  * \return If an extension within the given context with the priority PRIORITY_HINT
718  * is found, a non zero value will be returned.
719  * Otherwise, 0 is returned.
720  */
721 int ast_get_hint(char *hint, int hintsize, char *name, int namesize,
722         struct ast_channel *c, const char *context, const char *exten);
723
724 /*!
725  * \brief If an extension hint exists, return non-zero
726  *
727  * \param hint buffer for hint
728  * \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)
729  * \param name buffer for name portion of hint
730  * \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)
731  * \param c Channel from which to return the hint.  This is only important when the hint or name contains an expression to be expanded.
732  * \param context which context to look in
733  * \param exten which extension to search for
734  *
735  * \return If an extension within the given context with the priority PRIORITY_HINT
736  * is found, a non zero value will be returned.
737  * Otherwise, 0 is returned.
738  */
739 int ast_str_get_hint(struct ast_str **hint, ssize_t hintsize, struct ast_str **name, ssize_t namesize,
740         struct ast_channel *c, const char *context, const char *exten);
741
742 /*!
743  * \brief Determine whether an extension exists
744  *
745  * \param c this is not important
746  * \param context which context to look in
747  * \param exten which extension to search for
748  * \param priority priority of the action within the extension
749  * \param callerid callerid to search for
750  *
751  * \note It is possible for autoservice to be started and stopped on c during this
752  * function call, it is important that c is not locked prior to calling this. Otherwise
753  * a deadlock may occur
754  *
755  * \return If an extension within the given context(or callerid) with the given priority
756  *         is found a non zero value will be returned. Otherwise, 0 is returned.
757  */
758 int ast_exists_extension(struct ast_channel *c, const char *context, const char *exten,
759         int priority, const char *callerid);
760
761 /*!
762  * \brief Find the priority of an extension that has the specified label
763  *
764  * \param c this is not important
765  * \param context which context to look in
766  * \param exten which extension to search for
767  * \param label label of the action within the extension to match to priority
768  * \param callerid callerid to search for
769  *
770  * \note It is possible for autoservice to be started and stopped on c during this
771  * function call, it is important that c is not locked prior to calling this. Otherwise
772  * a deadlock may occur
773  *
774  * \retval the priority which matches the given label in the extension
775  * \retval -1 if not found.
776  */
777 int ast_findlabel_extension(struct ast_channel *c, const char *context,
778         const char *exten, const char *label, const char *callerid);
779
780 /*!
781  * \brief Find the priority of an extension that has the specified label
782  *
783  * \note It is possible for autoservice to be started and stopped on c during this
784  * function call, it is important that c is not locked prior to calling this. Otherwise
785  * a deadlock may occur
786  *
787  * \note This function is the same as ast_findlabel_extension, except that it accepts
788  * a pointer to an ast_context structure to specify the context instead of the
789  * name of the context. Otherwise, the functions behave the same.
790  */
791 int ast_findlabel_extension2(struct ast_channel *c, struct ast_context *con,
792         const char *exten, const char *label, const char *callerid);
793
794 /*!
795  * \brief Looks for a valid matching extension
796  *
797  * \param c not really important
798  * \param context context to search within
799  * \param exten extension to check
800  * \param priority priority of extension path
801  * \param callerid callerid of extension being searched for
802  *
803  * \note It is possible for autoservice to be started and stopped on c during this
804  * function call, it is important that c is not locked prior to calling this. Otherwise
805  * a deadlock may occur
806  *
807  * \return If "exten" *could be* a valid extension in this context with or without
808  * some more digits, return non-zero.  Basically, when this returns 0, no matter
809  * what you add to exten, it's not going to be a valid extension anymore
810  */
811 int ast_canmatch_extension(struct ast_channel *c, const char *context,
812         const char *exten, int priority, const char *callerid);
813
814 /*!
815  * \brief Looks to see if adding anything to this extension might match something. (exists ^ canmatch)
816  *
817  * \param c not really important XXX
818  * \param context context to search within
819  * \param exten extension to check
820  * \param priority priority of extension path
821  * \param callerid callerid of extension being searched for
822  *
823  * \note It is possible for autoservice to be started and stopped on c during this
824  * function call, it is important that c is not locked prior to calling this. Otherwise
825  * a deadlock may occur
826  *
827  * \return If "exten" *could match* a valid extension in this context with
828  * some more digits, return non-zero.  Does NOT return non-zero if this is
829  * an exact-match only.  Basically, when this returns 0, no matter
830  * what you add to exten, it's not going to be a valid extension anymore
831  */
832 int ast_matchmore_extension(struct ast_channel *c, const char *context,
833         const char *exten, int priority, const char *callerid);
834
835 /*!
836  * \brief Determine if a given extension matches a given pattern (in NXX format)
837  *
838  * \param pattern pattern to match
839  * \param extension extension to check against the pattern.
840  *
841  * Checks whether or not the given extension matches the given pattern.
842  *
843  * \retval 1 on match
844  * \retval 0 on failure
845  */
846 int ast_extension_match(const char *pattern, const char *extension);
847
848 int ast_extension_close(const char *pattern, const char *data, int needmore);
849
850 /*!
851  * \brief Determine if one extension should match before another
852  *
853  * \param a extension to compare with b
854  * \param b extension to compare with a
855  *
856  * Checks whether or extension a should match before extension b
857  *
858  * \retval 0 if the two extensions have equal matching priority
859  * \retval 1 on a > b
860  * \retval -1 on a < b
861  */
862 int ast_extension_cmp(const char *a, const char *b);
863
864 /*!
865  * \brief Launch a new extension (i.e. new stack)
866  *
867  * \param c not important
868  * \param context which context to generate the extension within
869  * \param exten new extension to add
870  * \param priority priority of new extension
871  * \param callerid callerid of extension
872  * \param found
873  * \param combined_find_spawn
874  *
875  * This adds a new extension to the asterisk extension list.
876  *
877  * \note It is possible for autoservice to be started and stopped on c during this
878  * function call, it is important that c is not locked prior to calling this. Otherwise
879  * a deadlock may occur
880  *
881  * \retval 0 on success
882  * \retval -1 on failure.
883  */
884 int ast_spawn_extension(struct ast_channel *c, const char *context,
885       const char *exten, int priority, const char *callerid, int *found, int combined_find_spawn);
886
887 /*!
888  * \brief Add a context include
889  *
890  * \param context context to add include to
891  * \param include new include to add
892  * \param registrar who's registering it
893  *
894  * Adds an include taking a char * string as the context parameter
895  *
896  * \retval 0 on success
897  * \retval -1 on error
898 */
899 int ast_context_add_include(const char *context, const char *include,
900         const char *registrar);
901
902 /*!
903  * \brief Add a context include
904  *
905  * Adds an include taking a struct ast_context as the first parameter
906  *
907  * \note See ast_context_add_include for information on arguments
908  */
909 int ast_context_add_include2(struct ast_context *con, const char *value,
910         const char *registrar);
911
912 /*!
913  * \brief Remove a context include
914  *
915  * \note See ast_context_add_include for information on arguments
916  */
917 int ast_context_remove_include(const char *context, const char *include,
918         const char *registrar);
919
920 /*!
921  * \brief Removes an include by an ast_context structure
922  *
923  * \note See ast_context_add_include for information on arguments
924  */
925 int ast_context_remove_include2(struct ast_context *con, const char *include,
926         const char *registrar);
927
928 /*!
929  * \brief Verifies includes in an ast_contect structure
930  *
931  * \param con context in which to verify the includes
932  *
933  * \retval 0 if no problems found
934  * \retval -1 if there were any missing context
935  */
936 int ast_context_verify_includes(struct ast_context *con);
937
938 /*!
939  * \brief Add a switch
940  *
941  * \param context context to which to add the switch
942  * \param sw switch to add
943  * \param data data to pass to switch
944  * \param eval whether to evaluate variables when running switch
945  * \param registrar whoever registered the switch
946  *
947  * This function registers a switch with the asterisk switch architecture
948  *
949  * \retval 0 on success
950  * \retval -1 on failure
951  */
952 int ast_context_add_switch(const char *context, const char *sw, const char *data,
953         int eval, const char *registrar);
954
955 /*!
956  * \brief Adds a switch (first param is a ast_context)
957  *
958  * \note See ast_context_add_switch() for argument information, with the exception of
959  *       the first argument. In this case, it's a pointer to an ast_context structure
960  *       as opposed to the name.
961  */
962 int ast_context_add_switch2(struct ast_context *con, const char *sw, const char *data,
963         int eval, const char *registrar);
964
965 /*!
966  * \brief Remove a switch
967  *
968  * Removes a switch with the given parameters
969  *
970  * \retval 0 on success
971  * \retval -1 on failure
972  */
973 int ast_context_remove_switch(const char *context, const char *sw,
974         const char *data, const char *registrar);
975
976 int ast_context_remove_switch2(struct ast_context *con, const char *sw,
977         const char *data, const char *registrar);
978
979 /*!
980  * \brief Simply remove extension from context
981  *
982  * \param context context to remove extension from
983  * \param extension which extension to remove
984  * \param priority priority of extension to remove (0 to remove all)
985  * \param registrar registrar of the extension
986  *
987  * This function removes an extension from a given context.
988  *
989  * \retval 0 on success
990  * \retval -1 on failure
991  *
992  * @{
993  */
994 int ast_context_remove_extension(const char *context, const char *extension, int priority,
995         const char *registrar);
996
997 int ast_context_remove_extension2(struct ast_context *con, const char *extension,
998         int priority, const char *registrar, int already_locked);
999
1000 int ast_context_remove_extension_callerid(const char *context, const char *extension,
1001         int priority, const char *callerid, int matchcid, const char *registrar);
1002
1003 int ast_context_remove_extension_callerid2(struct ast_context *con, const char *extension,
1004         int priority, const char *callerid, int matchcid, const char *registrar,
1005         int already_locked);
1006 /*! @} */
1007
1008 /*!
1009  * \brief Add an ignorepat
1010  *
1011  * \param context which context to add the ignorepattern to
1012  * \param ignorepat ignorepattern to set up for the extension
1013  * \param registrar registrar of the ignore pattern
1014  *
1015  * Adds an ignore pattern to a particular context.
1016  *
1017  * \retval 0 on success
1018  * \retval -1 on failure
1019  */
1020 int ast_context_add_ignorepat(const char *context, const char *ignorepat, const char *registrar);
1021
1022 int ast_context_add_ignorepat2(struct ast_context *con, const char *ignorepat, const char *registrar);
1023
1024 /*!
1025  * \brief Remove an ignorepat
1026  *
1027  * \param context context from which to remove the pattern
1028  * \param ignorepat the pattern to remove
1029  * \param registrar the registrar of the ignore pattern
1030  *
1031  * This removes the given ignorepattern
1032  *
1033  * \retval 0 on success
1034  * \retval -1 on failure
1035  */
1036 int ast_context_remove_ignorepat(const char *context, const char *ignorepat, const char *registrar);
1037
1038 int ast_context_remove_ignorepat2(struct ast_context *con, const char *ignorepat, const char *registrar);
1039
1040 /*!
1041  * \brief Checks to see if a number should be ignored
1042  *
1043  * \param context context to search within
1044  * \param pattern to check whether it should be ignored or not
1045  *
1046  * Check if a number should be ignored with respect to dialtone cancellation.
1047  *
1048  * \retval 0 if the pattern should not be ignored
1049  * \retval non-zero if the pattern should be ignored
1050  */
1051 int ast_ignore_pattern(const char *context, const char *pattern);
1052
1053 /* Locking functions for outer modules, especially for completion functions */
1054
1055 /*!
1056  * \brief Write locks the context list
1057  *
1058  * \retval 0 on success
1059  * \retval -1 on error
1060  */
1061 int ast_wrlock_contexts(void);
1062
1063 /*!
1064  * \brief Read locks the context list
1065  *
1066  * \retval 0 on success
1067  * \retval -1 on error
1068  */
1069 int ast_rdlock_contexts(void);
1070
1071 /*!
1072  * \brief Unlocks contexts
1073  *
1074  * \retval 0 on success
1075  * \retval -1 on failure
1076  */
1077 int ast_unlock_contexts(void);
1078
1079 /*!
1080  * \brief Write locks a given context
1081  *
1082  * \param con context to lock
1083  *
1084  * \retval 0 on success
1085  * \retval -1 on failure
1086  */
1087 int ast_wrlock_context(struct ast_context *con);
1088
1089 /*!
1090  * \brief Read locks a given context
1091  *
1092  * \param con context to lock
1093  *
1094  * \retval 0 on success
1095  * \retval -1 on failure
1096  */
1097 int ast_rdlock_context(struct ast_context *con);
1098
1099 /*!
1100  * \retval Unlocks the given context
1101  *
1102  * \param con context to unlock
1103  *
1104  * \retval 0 on success
1105  * \retval -1 on failure
1106  */
1107 int ast_unlock_context(struct ast_context *con);
1108
1109 /*!
1110  * \brief locks the macrolock in the given context
1111  *
1112  * \param macrocontext name of the macro-context to lock
1113  *
1114  * Locks the given macro-context to ensure only one thread (call) can execute it at a time
1115  *
1116  * \retval 0 on success
1117  * \retval -1 on failure
1118  */
1119 int ast_context_lockmacro(const char *macrocontext);
1120
1121 /*!
1122  * \brief Unlocks the macrolock in the given context
1123  *
1124  * \param macrocontext name of the macro-context to unlock
1125  *
1126  * Unlocks the given macro-context so that another thread (call) can execute it
1127  *
1128  * \retval 0 on success
1129  * \retval -1 on failure
1130  */
1131 int ast_context_unlockmacro(const char *macrocontext);
1132
1133 /*!
1134  * \brief Set the channel to next execute the specified dialplan location.
1135  * \see ast_async_parseable_goto, ast_async_goto_if_exists
1136  *
1137  * \note Do _NOT_ hold any channel locks when calling this function.
1138  */
1139 int ast_async_goto(struct ast_channel *chan, const char *context, const char *exten, int priority);
1140
1141 /*!
1142  * \brief Set the channel to next execute the specified dialplan location.
1143  */
1144 int ast_async_goto_by_name(const char *chan, const char *context, const char *exten, int priority);
1145
1146 enum ast_pbx_outgoing_sync {
1147         AST_OUTGOING_NO_WAIT = 0,       /*!< Don't wait for originated call to answer */
1148         AST_OUTGOING_WAIT = 1,          /*!< Wait for originated call to answer */
1149         AST_OUTGOING_WAIT_COMPLETE = 2, /*!< Wait for originated call to answer and hangup */
1150 };
1151
1152 /*!
1153  * \brief Synchronously or asynchronously make an outbound call and send it to a
1154  * particular extension
1155  *
1156  * \param type The channel technology to create
1157  * \param cap The format capabilities for the channel
1158  * \param addr Address data to pass to the channel technology driver
1159  * \param timeout How long we should attempt to dial the outbound channel
1160  * \param context The destination context for the outbound channel
1161  * \param exten The destination extension for the outbound channel
1162  * \param priority The destination priority for the outbound channel
1163  * \param reason Optional.  If provided, the dialed status of the outgoing channel.
1164  *        Codes are AST_CONTROL_xxx values.  Valid only if synchronous is non-zero.
1165  * \param synchronous defined by the ast_pbx_outgoing_sync enum.
1166  *        If \c AST_OUTGOING_NO_WAIT then don't wait for anything.
1167  *        If \c AST_OUTGOING_WAIT then block until the outbound channel answers or
1168  *        the call fails.
1169  *        If \c AST_OUTGOING_WAIT_COMPLETE then wait for the call to complete or
1170  *        fail.
1171  *        If \c AST_OUTGOING_WAIT or \c AST_OUTGOING_WAIT_COMPLETE is specified,
1172  *        the call doesn't answer, and \c failed\@context exists then run a channel
1173  *        named \c OutgoingSpoolFailed at \c failed\@context.
1174  * \param cid_num The caller ID number to set on the outbound channel
1175  * \param cid_name The caller ID name to set on the outbound channel
1176  * \param vars Variables to set on the outbound channel
1177  * \param account The accountcode for the outbound channel
1178  * \param locked_channel Optional.  The outbound channel that was created if success
1179  *        is returned.  Otherwise it is set to NULL.  This is returned both locked
1180  *        and reference bumped.
1181  * \param early_media If non-zero the channel "answers" when progress is indicated.
1182  * \param assignedids Optional. The uniqueid(s) to assign the channel(s) that are created.
1183  *
1184  * \retval 0 on success
1185  * \retval -1 on failure
1186  */
1187 int ast_pbx_outgoing_exten(const char *type, struct ast_format_cap *cap, const char *addr,
1188         int timeout, const char *context, const char *exten, int priority, int *reason,
1189         int synchronous, const char *cid_num, const char *cid_name, struct ast_variable *vars,
1190         const char *account, struct ast_channel **locked_channel, int early_media,
1191         const struct ast_assigned_ids *assignedids);
1192
1193 int ast_pbx_outgoing_exten_predial(const char *type, struct ast_format_cap *cap, const char *addr,
1194         int timeout, const char *context, const char *exten, int priority, int *reason,
1195         int synchronous, const char *cid_num, const char *cid_name, struct ast_variable *vars,
1196         const char *account, struct ast_channel **locked_channel, int early_media,
1197         const struct ast_assigned_ids *assignedids, const char *predial_callee);
1198
1199 /*!
1200  * \brief Synchronously or asynchronously make an outbound call and execute an
1201  *  application on the channel.
1202  *
1203  * Note that when the application stops executing, the channel is hungup.
1204  *
1205  * \param type The channel technology to create
1206  * \param cap The format capabilities for the channel
1207  * \param addr Address data to pass to the channel technology driver
1208  * \param timeout How long we should attempt to dial the outbound channel
1209  * \param app The name of the application to execute
1210  * \param appdata Data to pass to the application
1211  * \param reason Optional.  If provided, the dialed status of the outgoing channel.
1212  *        Codes are AST_CONTROL_xxx values.  Valid only if synchronous is non-zero.
1213  * \param synchronous defined by the ast_pbx_outgoing_sync enum.
1214  *        If \c AST_OUTGOING_NO_WAIT then don't wait for anything.
1215  *        If \c AST_OUTGOING_WAIT then block until the outbound channel answers or
1216  *        the call fails.
1217  *        If \c AST_OUTGOING_WAIT_COMPLETE then wait for the call to complete or
1218  *        fail.
1219  * \param cid_num The caller ID number to set on the outbound channel
1220  * \param cid_name The caller ID name to set on the outbound channel
1221  * \param vars Variables to set on the outbound channel
1222  * \param account The accountcode for the outbound channel
1223  * \param locked_channel Optional.  The outbound channel that was created if success
1224  *        is returned.  Otherwise it is set to NULL.  This is returned both locked
1225  *        and reference bumped.
1226  * \param assignedids Optional. The uniqueid(s) to assign the channel(s) that are created.
1227  *
1228  * \retval 0 on success
1229  * \retval -1 on failure
1230  */
1231 int ast_pbx_outgoing_app(const char *type, struct ast_format_cap *cap, const char *addr,
1232         int timeout, const char *app, const char *appdata, int *reason, int synchronous,
1233         const char *cid_num, const char *cid_name, struct ast_variable *vars,
1234         const char *account, struct ast_channel **locked_channel,
1235         const struct ast_assigned_ids *assignedids);
1236
1237 int ast_pbx_outgoing_app_predial(const char *type, struct ast_format_cap *cap, const char *addr,
1238         int timeout, const char *app, const char *appdata, int *reason, int synchronous,
1239         const char *cid_num, const char *cid_name, struct ast_variable *vars,
1240         const char *account, struct ast_channel **locked_channel,
1241         const struct ast_assigned_ids *assignedids, const char *predial_callee);
1242
1243 /*!
1244  * \brief Evaluate a condition
1245  *
1246  * \retval 0 if the condition is NULL or of zero length
1247  * \retval int If the string is an integer, the integer representation of
1248  *             the integer is returned
1249  * \retval 1 Any other non-empty string
1250  */
1251 int pbx_checkcondition(const char *condition);
1252
1253 /*! @name
1254  * Functions for returning values from structures */
1255 /*! @{ */
1256 const char *ast_get_context_name(struct ast_context *con);
1257 const char *ast_get_extension_name(struct ast_exten *exten);
1258 struct ast_context *ast_get_extension_context(struct ast_exten *exten);
1259 const char *ast_get_include_name(const struct ast_include *include);
1260 const char *ast_get_ignorepat_name(const struct ast_ignorepat *ip);
1261 const char *ast_get_switch_name(const struct ast_sw *sw);
1262 const char *ast_get_switch_data(const struct ast_sw *sw);
1263 int ast_get_switch_eval(const struct ast_sw *sw);
1264
1265 /*! @} */
1266
1267 /*! @name Other Extension stuff */
1268 /*! @{ */
1269 int ast_get_extension_priority(struct ast_exten *exten);
1270 int ast_get_extension_matchcid(struct ast_exten *e);
1271 const char *ast_get_extension_cidmatch(struct ast_exten *e);
1272 const char *ast_get_extension_app(struct ast_exten *e);
1273 const char *ast_get_extension_label(struct ast_exten *e);
1274 void *ast_get_extension_app_data(struct ast_exten *e);
1275
1276 /*!
1277  * \brief Fill a string buffer with the data at a dialplan extension
1278  *
1279  * \param buf String buffer
1280  * \param bufsize Size of buf
1281  * \param c Channel
1282  * \param context Dialplan context
1283  * \param exten Dialplan extension
1284  * \param priority Dialplan priority
1285  *
1286  * \retval -1 Failed to obtain extension data
1287  * \retval 0 Successfully obtained extension data
1288  */
1289 int ast_get_extension_data(char *buf, int bufsize, struct ast_channel *c,
1290         const char *context, const char *exten, int priority);
1291 /*! @} */
1292
1293 /*! @name Registrar info functions ... */
1294 /*! @{ */
1295 const char *ast_get_context_registrar(struct ast_context *c);
1296 const char *ast_get_extension_registrar(struct ast_exten *e);
1297 const char *ast_get_include_registrar(const struct ast_include *i);
1298 const char *ast_get_ignorepat_registrar(const struct ast_ignorepat *ip);
1299 const char *ast_get_switch_registrar(const struct ast_sw *sw);
1300 /*! @} */
1301
1302 /*!
1303  * \brief Get name of configuration file used by registrar to register this extension
1304  *
1305  * \retval NULL if registrar did not indicate config file when registering the extension
1306  * \retval name of the file used to register the extension
1307  */
1308 const char *ast_get_extension_registrar_file(struct ast_exten *e);
1309
1310 /*!
1311  * \brief Get line number of configuration file used by registrar to register this extension
1312  *
1313  * \retval 0 if the line wasn't indicated when the extension was registered
1314  * \retval positive integer indicating what line in the config file was responsible for
1315  *         registering the extension.
1316  */
1317 int ast_get_extension_registrar_line(struct ast_exten *e);
1318
1319 /*! @name Walking functions ... */
1320 /*! @{ */
1321 struct ast_context *ast_walk_contexts(struct ast_context *con);
1322 struct ast_exten *ast_walk_context_extensions(struct ast_context *con,
1323         struct ast_exten *priority);
1324 struct ast_exten *ast_walk_extension_priorities(struct ast_exten *exten,
1325         struct ast_exten *priority);
1326 const struct ast_include *ast_walk_context_includes(const struct ast_context *con,
1327         const struct ast_include *inc);
1328 const struct ast_ignorepat *ast_walk_context_ignorepats(const struct ast_context *con,
1329         const struct ast_ignorepat *ip);
1330 const struct ast_sw *ast_walk_context_switches(const struct ast_context *con,
1331         const struct ast_sw *sw);
1332 /*! @} */
1333
1334 /*! @name Iterator functions ... */
1335 /*! @{ */
1336 int ast_context_includes_count(const struct ast_context *con);
1337 const struct ast_include *ast_context_includes_get(const struct ast_context *con, int idx);
1338 int ast_context_ignorepats_count(const struct ast_context *con);
1339 const struct ast_ignorepat *ast_context_ignorepats_get(const struct ast_context *con, int idx);
1340 int ast_context_switches_count(const struct ast_context *con);
1341 const struct ast_sw *ast_context_switches_get(const struct ast_context *con, int idx);
1342 /*! @} */
1343
1344 /*!
1345  * \brief Create a human-readable string, specifying all variables and their corresponding values.
1346  * \param chan Channel from which to read variables
1347  * \param buf Dynamic string in which to place the result (should be allocated with ast_str_create).
1348  * \see ast_str_create
1349  * \note Will lock the channel.
1350  */
1351 int pbx_builtin_serialize_variables(struct ast_channel *chan, struct ast_str **buf);
1352
1353 /*!
1354  * \brief Return a pointer to the value of the corresponding channel variable.
1355  * \note Will lock the channel.
1356  *
1357  * \note This function will return a pointer to the buffer inside the channel
1358  * variable.  This value should only be accessed with the channel locked.  If
1359  * the value needs to be kept around, it should be done by using the following
1360  * thread-safe code:
1361  * \code
1362  *              const char *var;
1363  *
1364  *              ast_channel_lock(chan);
1365  *              if ((var = pbx_builtin_getvar_helper(chan, "MYVAR"))) {
1366  *                      var = ast_strdupa(var);
1367  *              }
1368  *              ast_channel_unlock(chan);
1369  * \endcode
1370  */
1371 const char *pbx_builtin_getvar_helper(struct ast_channel *chan, const char *name);
1372
1373 /*!
1374  * \brief Add a variable to the channel variable stack, without removing any previously set value.
1375  * \note Will lock the channel.
1376  */
1377 void pbx_builtin_pushvar_helper(struct ast_channel *chan, const char *name, const char *value);
1378
1379 /*!
1380  * \brief Add a variable to the channel variable stack, removing the most recently set value for the same name.
1381  * \note Will lock the channel.  May also be used to set a channel dialplan function to a particular value.
1382  * \see ast_func_write
1383  * \return -1 if the dialplan function fails to be set
1384  * \version 1.8 changed the function to return an error code
1385  */
1386 int pbx_builtin_setvar_helper(struct ast_channel *chan, const char *name, const char *value);
1387
1388 /*!
1389  * \brief Retrieve the value of a builtin variable or variable from the channel variable stack.
1390  * \note Will lock the channel.
1391  */
1392 void pbx_retrieve_variable(struct ast_channel *c, const char *var, char **ret, char *workspace, int workspacelen, struct varshead *headp);
1393 void pbx_builtin_clear_globals(void);
1394
1395 /*!
1396  * \brief Parse and set a single channel variable, where the name and value are separated with an '=' character.
1397  * \note Will lock the channel.
1398  */
1399 int pbx_builtin_setvar(struct ast_channel *chan, const char *data);
1400
1401 /*!
1402  * \brief Parse and set multiple channel variables, where the pairs are separated by the ',' character, and name and value are separated with an '=' character.
1403  * \note Will lock the channel.
1404  */
1405 int pbx_builtin_setvar_multiple(struct ast_channel *chan, const char *data);
1406
1407 int pbx_builtin_raise_exception(struct ast_channel *chan, const char *data);
1408
1409 /*! @name Substitution routines, using static string buffers
1410  * @{ */
1411 void pbx_substitute_variables_helper(struct ast_channel *c, const char *cp1, char *cp2, int count);
1412 void pbx_substitute_variables_varshead(struct varshead *headp, const char *cp1, char *cp2, int count);
1413 void pbx_substitute_variables_helper_full(struct ast_channel *c, struct varshead *headp, const char *cp1, char *cp2, int cp2_size, size_t *used);
1414
1415 /*!
1416  * \brief Substitutes variables, similar to pbx_substitute_variables_helper_full, but allows passing the context, extension, and priority in.
1417  */
1418 void pbx_substitute_variables_helper_full_location(struct ast_channel *c, struct varshead *headp, const char *cp1, char *cp2, int cp2_size, size_t *used, char *context, char *exten, int pri);
1419 /*! @} */
1420
1421 /*! @name Substitution routines, using dynamic string buffers
1422  * @{ */
1423
1424 /*!
1425  * \param buf Result will be placed in this buffer.
1426  * \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.
1427  * \param chan Channel variables from which to extract values, and channel to pass to any dialplan functions.
1428  * \param headp If no channel is specified, a channel list from which to extract variable values
1429  * \param var Variable name to retrieve.
1430  */
1431 const char *ast_str_retrieve_variable(struct ast_str **buf, ssize_t maxlen, struct ast_channel *chan, struct varshead *headp, const char *var);
1432
1433 /*!
1434  * \param buf Result will be placed in this buffer.
1435  * \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.
1436  * \param chan Channel variables from which to extract values, and channel to pass to any dialplan functions.
1437  * \param templ Variable template to expand.
1438  */
1439 void ast_str_substitute_variables(struct ast_str **buf, ssize_t maxlen, struct ast_channel *chan, const char *templ);
1440
1441 /*!
1442  * \param buf Result will be placed in this buffer.
1443  * \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.
1444  * \param headp If no channel is specified, a channel list from which to extract variable values
1445  * \param templ Variable template to expand.
1446  */
1447 void ast_str_substitute_variables_varshead(struct ast_str **buf, ssize_t maxlen, struct varshead *headp, const char *templ);
1448
1449 /*!
1450  * \param buf Result will be placed in this buffer.
1451  * \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.
1452  * \param c Channel variables from which to extract values, and channel to pass to any dialplan functions.
1453  * \param headp If no channel is specified, a channel list from which to extract variable values
1454  * \param templ Variable template to expand.
1455  * \param used Number of bytes read from the template.  (May be NULL)
1456  */
1457 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);
1458 /*! @} */
1459
1460 int ast_extension_patmatch(const char *pattern, const char *data);
1461
1462 /*! Set "autofallthrough" flag, if newval is <0, does not actually set.  If
1463   set to 1, sets to auto fall through.  If newval set to 0, sets to no auto
1464   fall through (reads extension instead).  Returns previous value. */
1465 int pbx_set_autofallthrough(int newval);
1466
1467 /*! Set "extenpatternmatchnew" flag, if newval is <0, does not actually set.  If
1468   set to 1, sets to use the new Trie-based pattern matcher.  If newval set to 0, sets to use
1469   the old linear-search algorithm.  Returns previous value. */
1470 int pbx_set_extenpatternmatchnew(int newval);
1471
1472 /*! Set "overrideswitch" field.  If set and of nonzero length, all contexts
1473  * will be tried directly through the named switch prior to any other
1474  * matching within that context.
1475  * \since 1.6.1
1476  */
1477 void pbx_set_overrideswitch(const char *newval);
1478
1479 /*!
1480  * \note This function will handle locking the channel as needed.
1481  */
1482 int ast_goto_if_exists(struct ast_channel *chan, const char *context, const char *exten, int priority);
1483
1484 /*!
1485  * \note This function will handle locking the channel as needed.
1486  */
1487 int ast_parseable_goto(struct ast_channel *chan, const char *goto_string);
1488
1489 /*!
1490  * \note This function will handle locking the channel as needed.
1491  */
1492 int ast_async_parseable_goto(struct ast_channel *chan, const char *goto_string);
1493
1494 /*!
1495  * \note This function will handle locking the channel as needed.
1496  */
1497 int ast_explicit_goto(struct ast_channel *chan, const char *context, const char *exten, int priority);
1498
1499 /*!
1500  * \note This function will handle locking the channel as needed.
1501  */
1502 int ast_async_goto_if_exists(struct ast_channel *chan, const char *context, const char *exten, int priority);
1503
1504 struct ast_custom_function* ast_custom_function_find(const char *name);
1505
1506 /*!
1507  * \brief Unregister a custom function
1508  */
1509 int ast_custom_function_unregister(struct ast_custom_function *acf);
1510
1511 /*!
1512  * \brief Description of the ways in which a function may escalate privileges.
1513  */
1514 enum ast_custom_function_escalation {
1515         AST_CFE_NONE,
1516         AST_CFE_READ,
1517         AST_CFE_WRITE,
1518         AST_CFE_BOTH,
1519 };
1520
1521 /*!
1522  * \brief Register a custom function
1523  */
1524 #define ast_custom_function_register(acf) __ast_custom_function_register(acf, AST_MODULE_SELF)
1525
1526 /*!
1527  * \brief Register a custom function which requires escalated privileges.
1528  *
1529  * Examples would be SHELL() (for which a read needs permission to execute
1530  * arbitrary code) or FILE() (for which write needs permission to change files
1531  * on the filesystem).
1532  */
1533 #define ast_custom_function_register_escalating(acf, escalation) __ast_custom_function_register_escalating(acf, escalation, AST_MODULE_SELF)
1534
1535 /*!
1536  * \brief Register a custom function
1537  */
1538 int __ast_custom_function_register(struct ast_custom_function *acf, struct ast_module *mod);
1539
1540 /*!
1541  * \brief Register a custom function which requires escalated privileges.
1542  *
1543  * Examples would be SHELL() (for which a read needs permission to execute
1544  * arbitrary code) or FILE() (for which write needs permission to change files
1545  * on the filesystem).
1546  */
1547 int __ast_custom_function_register_escalating(struct ast_custom_function *acf, enum ast_custom_function_escalation escalation, struct ast_module *mod);
1548
1549 /*!
1550  * \brief Retrieve the number of active calls
1551  */
1552 int ast_active_calls(void);
1553
1554 /*!
1555  * \brief Retrieve the total number of calls processed through the PBX since last restart
1556  */
1557 int ast_processed_calls(void);
1558
1559 /*!
1560  * \brief executes a read operation on a function
1561  *
1562  * \param chan Channel to execute on
1563  * \param function Data containing the function call string (will be modified)
1564  * \param workspace A pointer to safe memory to use for a return value
1565  * \param len the number of bytes in workspace
1566  *
1567  * This application executes a function in read mode on a given channel.
1568  *
1569  * \retval 0 success
1570  * \retval non-zero failure
1571  */
1572 int ast_func_read(struct ast_channel *chan, const char *function, char *workspace, size_t len);
1573
1574 /*!
1575  * \brief executes a read operation on a function
1576  *
1577  * \param chan Channel to execute on
1578  * \param function Data containing the function call string (will be modified)
1579  * \param str A dynamic string buffer into which to place the result.
1580  * \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
1581  *
1582  * This application executes a function in read mode on a given channel.
1583  *
1584  * \retval 0 success
1585  * \retval non-zero failure
1586  */
1587 int ast_func_read2(struct ast_channel *chan, const char *function, struct ast_str **str, ssize_t maxlen);
1588
1589 /*!
1590  * \brief executes a write operation on a function
1591  *
1592  * \param chan Channel to execute on
1593  * \param function Data containing the function call string (will be modified)
1594  * \param value A value parameter to pass for writing
1595  *
1596  * This application executes a function in write mode on a given channel.
1597  *
1598  * \retval 0 success
1599  * \retval non-zero failure
1600  */
1601 int ast_func_write(struct ast_channel *chan, const char *function, const char *value);
1602
1603 /*!
1604  * \details
1605  * When looking up extensions, we can have different requests
1606  * identified by the 'action' argument, as follows.
1607  *
1608  * \note that the coding is such that the low 4 bits are the
1609  * third argument to extension_match_core.
1610  */
1611 enum ext_match_t {
1612         E_MATCHMORE =   0x00,   /* extension can match but only with more 'digits' */
1613         E_CANMATCH =    0x01,   /* extension can match with or without more 'digits' */
1614         E_MATCH =       0x02,   /* extension is an exact match */
1615         E_MATCH_MASK =  0x03,   /* mask for the argument to extension_match_core() */
1616         E_SPAWN =       0x12,   /* want to spawn an extension. Requires exact match */
1617         E_FINDLABEL =   0x22    /* returns the priority for a given label. Requires exact match */
1618 };
1619
1620 #define STATUS_NO_CONTEXT       1
1621 #define STATUS_NO_EXTENSION     2
1622 #define STATUS_NO_PRIORITY      3
1623 #define STATUS_NO_LABEL         4
1624 #define STATUS_SUCCESS          5
1625
1626 #ifdef LOW_MEMORY
1627 #define AST_PBX_MAX_STACK  128
1628 #else
1629 #define AST_PBX_MAX_STACK  512
1630 #endif
1631
1632 /* request and result for pbx_find_extension */
1633 struct pbx_find_info {
1634 #if 0
1635         const char *context;
1636         const char *exten;
1637         int priority;
1638 #endif
1639
1640         char *incstack[AST_PBX_MAX_STACK];      /* filled during the search */
1641         int stacklen;                   /* modified during the search */
1642         int status;                     /* set on return */
1643         struct ast_switch *swo;         /* set on return */
1644         const char *data;               /* set on return */
1645         const char *foundcontext;       /* set on return */
1646 };
1647
1648 struct ast_exten *pbx_find_extension(struct ast_channel *chan,
1649                                                                          struct ast_context *bypass, struct pbx_find_info *q,
1650                                                                          const char *context, const char *exten, int priority,
1651                                                                          const char *label, const char *callerid, enum ext_match_t action);
1652
1653 /*! \brief hashtable functions for contexts */
1654 /*! @{ */
1655 int ast_hashtab_compare_contexts(const void *ah_a, const void *ah_b);
1656 unsigned int ast_hashtab_hash_contexts(const void *obj);
1657 /*! @} */
1658
1659 /*!
1660  * \brief Command completion for the list of installed applications.
1661  *
1662  * This can be called from a CLI command completion function that wants to
1663  * complete from the list of available applications.
1664  */
1665 char *ast_complete_applications(const char *line, const char *word, int state);
1666
1667 /*!
1668  * \brief Enable/disable the execution of 'dangerous' functions from external
1669  * protocols (AMI, etc.).
1670  *
1671  * These dialplan functions (such as \c SHELL) provide an opportunity for
1672  * privilege escalation. They are okay to invoke from the dialplan, but external
1673  * protocols with permission controls should not normally invoke them.
1674  *
1675  * This function can globally enable/disable the execution of dangerous
1676  * functions from external protocols.
1677  *
1678  * \param new_live_dangerously If true, enable the execution of escalating
1679  * functions from external protocols.
1680  */
1681 void pbx_live_dangerously(int new_live_dangerously);
1682
1683 /*!
1684  * \brief Inhibit (in the current thread) the execution of dialplan functions
1685  * which cause privilege escalations. If pbx_live_dangerously() has been
1686  * called, this function has no effect.
1687  *
1688  * \return 0 if successfuly marked current thread.
1689  * \return Non-zero if marking current thread failed.
1690  */
1691 int ast_thread_inhibit_escalations(void);
1692
1693 /*!
1694  * \brief Swap the current thread escalation inhibit setting.
1695  * \since 11.24.0
1696  *
1697  * \param inhibit New setting.  Non-zero to inhibit.
1698  *
1699  * \retval 1 if dangerous function execution was inhibited.
1700  * \retval 0 if dangerous function execution was allowed.
1701  * \retval -1 on error.
1702  */
1703 int ast_thread_inhibit_escalations_swap(int inhibit);
1704
1705 #if defined(__cplusplus) || defined(c_plusplus)
1706 }
1707 #endif
1708
1709 #endif /* _ASTERISK_PBX_H */