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