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