Clean up doxygen warnings
[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 Map devstate to an extension state.
474  *
475  * \param[in] devstate device state
476  *
477  * \return the extension state mapping.
478  */
479 enum ast_extension_states ast_devstate_to_extenstate(enum ast_device_state devstate);
480
481 /*!
482  * \brief Uses hint and devicestate callback to get the state of an extension
483  *
484  * \param c this is not important
485  * \param context which context to look in
486  * \param exten which extension to get state
487  *
488  * \return extension state as defined in the ast_extension_states enum
489  */
490 int ast_extension_state(struct ast_channel *c, const char *context, const char *exten);
491
492 /*!
493  * \brief Uses hint and devicestate callback to get the extended state of an extension
494  * \since 11
495  *
496  * \param c this is not important
497  * \param context which context to look in
498  * \param exten which extension to get state
499  * \param[out] device_state_info ptr to an ao2_container with extended state info, must be unref'd after use.
500  *
501  * \return extension state as defined in the ast_extension_states enum
502  */
503 int ast_extension_state_extended(struct ast_channel *c, const char *context, const char *exten,
504         struct ao2_container **device_state_info);
505
506 /*!
507  * \brief Uses hint and presence state callback to get the presence state of an extension
508  *
509  * \param c this is not important
510  * \param context which context to look in
511  * \param exten which extension to get state
512  * \param[out] subtype Further information regarding the presence returned
513  * \param[out] message Custom message further describing current presence
514  *
515  * \note The subtype and message are dynamically allocated and must be freed by
516  * the caller of this function.
517  *
518  * \return returns the presence state value.
519  */
520 int ast_hint_presence_state(struct ast_channel *c, const char *context, const char *exten, char **subtype, char **message);
521
522 /*!
523  * \brief Return string representation of the state of an extension
524  *
525  * \param extension_state is the numerical state delivered by ast_extension_state
526  *
527  * \return the state of an extension as string
528  */
529 const char *ast_extension_state2str(int extension_state);
530
531 /*!
532  * \brief Registers a state change callback with destructor.
533  * \since 1.8.9
534  * \since 10.1.0
535  *
536  * \param context which context to look in
537  * \param exten which extension to get state
538  * \param change_cb callback to call if state changed
539  * \param destroy_cb callback to call when registration destroyed.
540  * \param data to pass to callback
541  *
542  * \note The change_cb is called if the state of an extension is changed.
543  *
544  * \note The destroy_cb is called when the registration is
545  * deleted so the registerer can release any associated
546  * resources.
547  *
548  * \retval -1 on failure
549  * \retval ID on success
550  */
551 int ast_extension_state_add_destroy(const char *context, const char *exten,
552         ast_state_cb_type change_cb, ast_state_cb_destroy_type destroy_cb, void *data);
553
554 /*!
555  * \brief Registers an extended state change callback with destructor.
556  * \since 11
557  *
558  * \param context which context to look in
559  * \param exten which extension to get state
560  * \param change_cb callback to call if state changed
561  * \param destroy_cb callback to call when registration destroyed.
562  * \param data to pass to callback
563  *
564  * \note The change_cb is called if the state of an extension is changed.
565  * The extended state is passed to the callback in the device_state_info
566  * member of ast_state_cb_info.
567  *
568  * \note The destroy_cb is called when the registration is
569  * deleted so the registerer can release any associated
570  * resources.
571  *
572  * \retval -1 on failure
573  * \retval ID on success
574  */
575 int ast_extension_state_add_destroy_extended(const char *context, const char *exten,
576         ast_state_cb_type change_cb, ast_state_cb_destroy_type destroy_cb, void *data);
577
578 /*!
579  * \brief Registers a state change callback
580  *
581  * \param context which context to look in
582  * \param exten which extension to get state
583  * \param change_cb callback to call if state changed
584  * \param data to pass to callback
585  *
586  * \note The change_cb is called if the state of an extension is changed.
587  *
588  * \retval -1 on failure
589  * \retval ID on success
590  */
591 int ast_extension_state_add(const char *context, const char *exten,
592         ast_state_cb_type change_cb, void *data);
593
594 /*!
595  * \brief Registers an extended state change callback
596  * \since 11
597  *
598  * \param context which context to look in
599  * \param exten which extension to get state
600  * \param change_cb callback to call if state changed
601  * \param data to pass to callback
602  *
603  * \note The change_cb is called if the state of an extension is changed.
604  * The extended state is passed to the callback in the device_state_info
605  * member of ast_state_cb_info.
606  *
607  * \retval -1 on failure
608  * \retval ID on success
609  */
610 int ast_extension_state_add_extended(const char *context, const char *exten,
611         ast_state_cb_type change_cb, void *data);
612
613 /*!
614  * \brief Deletes a registered state change callback by ID
615  *
616  * \param id of the registered state callback to delete
617  * \param change_cb callback to call if state changed (Used if id == 0 (global))
618  *
619  * \retval 0 success
620  * \retval -1 failure
621  */
622 int ast_extension_state_del(int id, ast_state_cb_type change_cb);
623
624 /*!
625  * \brief If an extension hint exists, return non-zero
626  *
627  * \param hint buffer for hint
628  * \param hintsize size of hint buffer, in bytes
629  * \param name buffer for name portion of hint
630  * \param namesize size of name buffer
631  * \param c Channel from which to return the hint.  This is only important when the hint or name contains an expression to be expanded.
632  * \param context which context to look in
633  * \param exten which extension to search for
634  *
635  * \return If an extension within the given context with the priority PRIORITY_HINT
636  * is found, a non zero value will be returned.
637  * Otherwise, 0 is returned.
638  */
639 int ast_get_hint(char *hint, int hintsize, char *name, int namesize,
640         struct ast_channel *c, const char *context, const char *exten);
641
642 /*!
643  * \brief If an extension hint exists, return non-zero
644  *
645  * \param hint buffer for hint
646  * \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)
647  * \param name buffer for name portion of hint
648  * \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)
649  * \param c Channel from which to return the hint.  This is only important when the hint or name contains an expression to be expanded.
650  * \param context which context to look in
651  * \param exten which extension to search for
652  *
653  * \return If an extension within the given context with the priority PRIORITY_HINT
654  * is found, a non zero value will be returned.
655  * Otherwise, 0 is returned.
656  */
657 int ast_str_get_hint(struct ast_str **hint, ssize_t hintsize, struct ast_str **name, ssize_t namesize,
658         struct ast_channel *c, const char *context, const char *exten);
659
660 /*!
661  * \brief Determine whether an extension exists
662  *
663  * \param c this is not important
664  * \param context which context to look in
665  * \param exten which extension to search for
666  * \param priority priority of the action within the extension
667  * \param callerid callerid to search for
668  *
669  * \note It is possible for autoservice to be started and stopped on c during this
670  * function call, it is important that c is not locked prior to calling this. Otherwise
671  * a deadlock may occur
672  *
673  * \return If an extension within the given context(or callerid) with the given priority
674  *         is found a non zero value will be returned. Otherwise, 0 is returned.
675  */
676 int ast_exists_extension(struct ast_channel *c, const char *context, const char *exten,
677         int priority, const char *callerid);
678
679 /*!
680  * \brief Find the priority of an extension that has the specified label
681  *
682  * \param c this is not important
683  * \param context which context to look in
684  * \param exten which extension to search for
685  * \param label label of the action within the extension to match to priority
686  * \param callerid callerid to search for
687  *
688  * \note It is possible for autoservice to be started and stopped on c during this
689  * function call, it is important that c is not locked prior to calling this. Otherwise
690  * a deadlock may occur
691  *
692  * \retval the priority which matches the given label in the extension
693  * \retval -1 if not found.
694  */
695 int ast_findlabel_extension(struct ast_channel *c, const char *context,
696         const char *exten, const char *label, const char *callerid);
697
698 /*!
699  * \brief Find the priority of an extension that has the specified label
700  *
701  * \note It is possible for autoservice to be started and stopped on c during this
702  * function call, it is important that c is not locked prior to calling this. Otherwise
703  * a deadlock may occur
704  *
705  * \note This function is the same as ast_findlabel_extension, except that it accepts
706  * a pointer to an ast_context structure to specify the context instead of the
707  * name of the context. Otherwise, the functions behave the same.
708  */
709 int ast_findlabel_extension2(struct ast_channel *c, struct ast_context *con,
710         const char *exten, const char *label, const char *callerid);
711
712 /*!
713  * \brief Looks for a valid matching extension
714  *
715  * \param c not really important
716  * \param context context to serach within
717  * \param exten extension to check
718  * \param priority priority of extension path
719  * \param callerid callerid of extension being searched for
720  *
721  * \note It is possible for autoservice to be started and stopped on c during this
722  * function call, it is important that c is not locked prior to calling this. Otherwise
723  * a deadlock may occur
724  *
725  * \return If "exten" *could be* a valid extension in this context with or without
726  * some more digits, return non-zero.  Basically, when this returns 0, no matter
727  * what you add to exten, it's not going to be a valid extension anymore
728  */
729 int ast_canmatch_extension(struct ast_channel *c, const char *context,
730         const char *exten, int priority, const char *callerid);
731
732 /*!
733  * \brief Looks to see if adding anything to this extension might match something. (exists ^ canmatch)
734  *
735  * \param c not really important XXX
736  * \param context context to serach within
737  * \param exten extension to check
738  * \param priority priority of extension path
739  * \param callerid callerid of extension being searched for
740  *
741  * \note It is possible for autoservice to be started and stopped on c during this
742  * function call, it is important that c is not locked prior to calling this. Otherwise
743  * a deadlock may occur
744  *
745  * \return If "exten" *could match* a valid extension in this context with
746  * some more digits, return non-zero.  Does NOT return non-zero if this is
747  * an exact-match only.  Basically, when this returns 0, no matter
748  * what you add to exten, it's not going to be a valid extension anymore
749  */
750 int ast_matchmore_extension(struct ast_channel *c, const char *context,
751         const char *exten, int priority, const char *callerid);
752
753 /*!
754  * \brief Determine if a given extension matches a given pattern (in NXX format)
755  *
756  * \param pattern pattern to match
757  * \param extension extension to check against the pattern.
758  *
759  * Checks whether or not the given extension matches the given pattern.
760  *
761  * \retval 1 on match
762  * \retval 0 on failure
763  */
764 int ast_extension_match(const char *pattern, const char *extension);
765
766 int ast_extension_close(const char *pattern, const char *data, int needmore);
767
768 /*!
769  * \brief Determine if one extension should match before another
770  *
771  * \param a extension to compare with b
772  * \param b extension to compare with a
773  *
774  * Checks whether or extension a should match before extension b
775  *
776  * \retval 0 if the two extensions have equal matching priority
777  * \retval 1 on a > b
778  * \retval -1 on a < b
779  */
780 int ast_extension_cmp(const char *a, const char *b);
781
782 /*!
783  * \brief Launch a new extension (i.e. new stack)
784  *
785  * \param c not important
786  * \param context which context to generate the extension within
787  * \param exten new extension to add
788  * \param priority priority of new extension
789  * \param callerid callerid of extension
790  * \param found
791  * \param combined_find_spawn
792  *
793  * This adds a new extension to the asterisk extension list.
794  *
795  * \note It is possible for autoservice to be started and stopped on c during this
796  * function call, it is important that c is not locked prior to calling this. Otherwise
797  * a deadlock may occur
798  *
799  * \retval 0 on success
800  * \retval -1 on failure.
801  */
802 int ast_spawn_extension(struct ast_channel *c, const char *context,
803       const char *exten, int priority, const char *callerid, int *found, int combined_find_spawn);
804
805 /*!
806  * \brief Add a context include
807  *
808  * \param context context to add include to
809  * \param include new include to add
810  * \param registrar who's registering it
811  *
812  * Adds an include taking a char * string as the context parameter
813  *
814  * \retval 0 on success
815  * \retval -1 on error
816 */
817 int ast_context_add_include(const char *context, const char *include,
818         const char *registrar);
819
820 /*!
821  * \brief Add a context include
822  *
823  * \param con context to add the include to
824  * \param value include include to add
825  * \param registrar who registered the context
826  *
827  * Adds an include taking a struct ast_context as the first parameter
828  *
829  * \retval 0 on success
830  * \retval -1 on failure
831  */
832 int ast_context_add_include2(struct ast_context *con, const char *include,
833         const char *registrar);
834
835 /*!
836  * \brief Remove a context include
837  *
838  * \note See ast_context_add_include for information on arguments
839  *
840  * \retval 0 on success
841  * \retval -1 on failure
842  */
843 int ast_context_remove_include(const char *context, const char *include,
844         const char *registrar);
845
846 /*!
847  * \brief Removes an include by an ast_context structure
848  *
849  * \note See ast_context_add_include2 for information on arguments
850  *
851  * \retval 0 on success
852  * \retval -1 on success
853  */
854 int ast_context_remove_include2(struct ast_context *con, const char *include,
855         const char *registrar);
856
857 /*!
858  * \brief Verifies includes in an ast_contect structure
859  *
860  * \param con context in which to verify the includes
861  *
862  * \retval 0 if no problems found
863  * \retval -1 if there were any missing context
864  */
865 int ast_context_verify_includes(struct ast_context *con);
866
867 /*!
868  * \brief Add a switch
869  *
870  * \param context context to which to add the switch
871  * \param sw switch to add
872  * \param data data to pass to switch
873  * \param eval whether to evaluate variables when running switch
874  * \param registrar whoever registered the switch
875  *
876  * This function registers a switch with the asterisk switch architecture
877  *
878  * \retval 0 on success
879  * \retval -1 on failure
880  */
881 int ast_context_add_switch(const char *context, const char *sw, const char *data,
882         int eval, const char *registrar);
883
884 /*!
885  * \brief Adds a switch (first param is a ast_context)
886  *
887  * \note See ast_context_add_switch() for argument information, with the exception of
888  *       the first argument. In this case, it's a pointer to an ast_context structure
889  *       as opposed to the name.
890  */
891 int ast_context_add_switch2(struct ast_context *con, const char *sw, const char *data,
892         int eval, const char *registrar);
893
894 /*!
895  * \brief Remove a switch
896  *
897  * Removes a switch with the given parameters
898  *
899  * \retval 0 on success
900  * \retval -1 on failure
901  */
902 int ast_context_remove_switch(const char *context, const char *sw,
903         const char *data, const char *registrar);
904
905 int ast_context_remove_switch2(struct ast_context *con, const char *sw,
906         const char *data, const char *registrar);
907
908 /*!
909  * \brief Simply remove extension from context
910  *
911  * \param context context to remove extension from
912  * \param extension which extension to remove
913  * \param priority priority of extension to remove (0 to remove all)
914  * \param registrar registrar of the extension
915  *
916  * This function removes an extension from a given context.
917  *
918  * \retval 0 on success
919  * \retval -1 on failure
920  *
921  * @{
922  */
923 int ast_context_remove_extension(const char *context, const char *extension, int priority,
924         const char *registrar);
925
926 int ast_context_remove_extension2(struct ast_context *con, const char *extension,
927         int priority, const char *registrar, int already_locked);
928
929 int ast_context_remove_extension_callerid(const char *context, const char *extension,
930         int priority, const char *callerid, int matchcid, const char *registrar);
931
932 int ast_context_remove_extension_callerid2(struct ast_context *con, const char *extension,
933         int priority, const char *callerid, int matchcid, const char *registrar,
934         int already_locked);
935 /*! @} */
936
937 /*!
938  * \brief Add an ignorepat
939  *
940  * \param context which context to add the ignorpattern to
941  * \param ignorepat ignorepattern to set up for the extension
942  * \param registrar registrar of the ignore pattern
943  *
944  * Adds an ignore pattern to a particular context.
945  *
946  * \retval 0 on success
947  * \retval -1 on failure
948  */
949 int ast_context_add_ignorepat(const char *context, const char *ignorepat, const char *registrar);
950
951 int ast_context_add_ignorepat2(struct ast_context *con, const char *ignorepat, const char *registrar);
952
953 /*
954  * \brief Remove an ignorepat
955  *
956  * \param context context from which to remove the pattern
957  * \param ignorepat the pattern to remove
958  * \param registrar the registrar of the ignore pattern
959  *
960  * This removes the given ignorepattern
961  *
962  * \retval 0 on success
963  * \retval -1 on failure
964  */
965 int ast_context_remove_ignorepat(const char *context, const char *ignorepat, const char *registrar);
966
967 int ast_context_remove_ignorepat2(struct ast_context *con, const char *ignorepat, const char *registrar);
968
969 /*!
970  * \brief Checks to see if a number should be ignored
971  *
972  * \param context context to search within
973  * \param pattern to check whether it should be ignored or not
974  *
975  * Check if a number should be ignored with respect to dialtone cancellation.
976  *
977  * \retval 0 if the pattern should not be ignored
978  * \retval non-zero if the pattern should be ignored
979  */
980 int ast_ignore_pattern(const char *context, const char *pattern);
981
982 /* Locking functions for outer modules, especially for completion functions */
983
984 /*!
985  * \brief Write locks the context list
986  *
987  * \retval 0 on success
988  * \retval -1 on error
989  */
990 int ast_wrlock_contexts(void);
991
992 /*!
993  * \brief Read locks the context list
994  *
995  * \retval 0 on success
996  * \retval -1 on error
997  */
998 int ast_rdlock_contexts(void);
999
1000 /*!
1001  * \brief Unlocks contexts
1002  *
1003  * \retval 0 on success
1004  * \retval -1 on failure
1005  */
1006 int ast_unlock_contexts(void);
1007
1008 /*!
1009  * \brief Write locks a given context
1010  *
1011  * \param con context to lock
1012  *
1013  * \retval 0 on success
1014  * \retval -1 on failure
1015  */
1016 int ast_wrlock_context(struct ast_context *con);
1017
1018 /*!
1019  * \brief Read locks a given context
1020  *
1021  * \param con context to lock
1022  *
1023  * \retval 0 on success
1024  * \retval -1 on failure
1025  */
1026 int ast_rdlock_context(struct ast_context *con);
1027
1028 /*!
1029  * \retval Unlocks the given context
1030  *
1031  * \param con context to unlock
1032  *
1033  * \retval 0 on success
1034  * \retval -1 on failure
1035  */
1036 int ast_unlock_context(struct ast_context *con);
1037
1038 /*!
1039  * \brief locks the macrolock in the given given context
1040  *
1041  * \param macrocontext name of the macro-context to lock
1042  *
1043  * Locks the given macro-context to ensure only one thread (call) can execute it at a time
1044  *
1045  * \retval 0 on success
1046  * \retval -1 on failure
1047  */
1048 int ast_context_lockmacro(const char *macrocontext);
1049
1050 /*!
1051  * \brief Unlocks the macrolock in the given context
1052  *
1053  * \param macrocontext name of the macro-context to unlock
1054  *
1055  * Unlocks the given macro-context so that another thread (call) can execute it
1056  *
1057  * \retval 0 on success
1058  * \retval -1 on failure
1059  */
1060 int ast_context_unlockmacro(const char *macrocontext);
1061
1062 /*!
1063  * \brief Set the channel to next execute the specified dialplan location.
1064  * \see ast_async_parseable_goto, ast_async_goto_if_exists
1065  *
1066  * \note Do _NOT_ hold any channel locks when calling this function.
1067  */
1068 int ast_async_goto(struct ast_channel *chan, const char *context, const char *exten, int priority);
1069
1070 /*!
1071  * \brief Set the channel to next execute the specified dialplan location.
1072  */
1073 int ast_async_goto_by_name(const char *chan, const char *context, const char *exten, int priority);
1074
1075 /*! Synchronously or asynchronously make an outbound call and send it to a
1076    particular extension */
1077 int ast_pbx_outgoing_exten(const char *type, struct ast_format_cap *cap, const char *addr, int timeout, const char *context, const char *exten, int priority, int *reason, int sync, const char *cid_num, const char *cid_name, struct ast_variable *vars, const char *account, struct ast_channel **locked_channel, int early_media);
1078
1079 /*! Synchronously or asynchronously make an outbound call and send it to a
1080    particular application with given extension */
1081 int ast_pbx_outgoing_app(const char *type, struct ast_format_cap *cap, const char *addr, int timeout, const char *app, const char *appdata, int *reason, int sync, const char *cid_num, const char *cid_name, struct ast_variable *vars, const char *account, struct ast_channel **locked_channel);
1082
1083 /*!
1084  * \brief Evaluate a condition
1085  *
1086  * \retval 0 if the condition is NULL or of zero length
1087  * \retval int If the string is an integer, the integer representation of
1088  *             the integer is returned
1089  * \retval 1 Any other non-empty string
1090  */
1091 int pbx_checkcondition(const char *condition);
1092
1093 /*! @name
1094  * Functions for returning values from structures */
1095 /*! @{ */
1096 const char *ast_get_context_name(struct ast_context *con);
1097 const char *ast_get_extension_name(struct ast_exten *exten);
1098 struct ast_context *ast_get_extension_context(struct ast_exten *exten);
1099 const char *ast_get_include_name(struct ast_include *include);
1100 const char *ast_get_ignorepat_name(struct ast_ignorepat *ip);
1101 const char *ast_get_switch_name(struct ast_sw *sw);
1102 const char *ast_get_switch_data(struct ast_sw *sw);
1103 int ast_get_switch_eval(struct ast_sw *sw);
1104
1105 /*! @} */
1106
1107 /*! @name Other Extension stuff */
1108 /*! @{ */
1109 int ast_get_extension_priority(struct ast_exten *exten);
1110 int ast_get_extension_matchcid(struct ast_exten *e);
1111 const char *ast_get_extension_cidmatch(struct ast_exten *e);
1112 const char *ast_get_extension_app(struct ast_exten *e);
1113 const char *ast_get_extension_label(struct ast_exten *e);
1114 void *ast_get_extension_app_data(struct ast_exten *e);
1115 /*! @} */
1116
1117 /*! @name Registrar info functions ... */
1118 /*! @{ */
1119 const char *ast_get_context_registrar(struct ast_context *c);
1120 const char *ast_get_extension_registrar(struct ast_exten *e);
1121 const char *ast_get_include_registrar(struct ast_include *i);
1122 const char *ast_get_ignorepat_registrar(struct ast_ignorepat *ip);
1123 const char *ast_get_switch_registrar(struct ast_sw *sw);
1124 /*! @} */
1125
1126 /*! @name Walking functions ... */
1127 /*! @{ */
1128 struct ast_context *ast_walk_contexts(struct ast_context *con);
1129 struct ast_exten *ast_walk_context_extensions(struct ast_context *con,
1130         struct ast_exten *priority);
1131 struct ast_exten *ast_walk_extension_priorities(struct ast_exten *exten,
1132         struct ast_exten *priority);
1133 struct ast_include *ast_walk_context_includes(struct ast_context *con,
1134         struct ast_include *inc);
1135 struct ast_ignorepat *ast_walk_context_ignorepats(struct ast_context *con,
1136         struct ast_ignorepat *ip);
1137 struct ast_sw *ast_walk_context_switches(struct ast_context *con, struct ast_sw *sw);
1138 /*! @} */
1139
1140 /*!
1141  * \brief Create a human-readable string, specifying all variables and their corresponding values.
1142  * \param chan Channel from which to read variables
1143  * \param buf Dynamic string in which to place the result (should be allocated with ast_str_create).
1144  * \see ast_str_create
1145  * \note Will lock the channel.
1146  */
1147 int pbx_builtin_serialize_variables(struct ast_channel *chan, struct ast_str **buf);
1148
1149 /*!
1150  * \brief Return a pointer to the value of the corresponding channel variable.
1151  * \note Will lock the channel.
1152  *
1153  * \note This function will return a pointer to the buffer inside the channel
1154  * variable.  This value should only be accessed with the channel locked.  If
1155  * the value needs to be kept around, it should be done by using the following
1156  * thread-safe code:
1157  * \code
1158  *              const char *var;
1159  *
1160  *              ast_channel_lock(chan);
1161  *              if ((var = pbx_builtin_getvar_helper(chan, "MYVAR"))) {
1162  *                      var = ast_strdupa(var);
1163  *              }
1164  *              ast_channel_unlock(chan);
1165  * \endcode
1166  */
1167 const char *pbx_builtin_getvar_helper(struct ast_channel *chan, const char *name);
1168
1169 /*!
1170  * \brief Add a variable to the channel variable stack, without removing any previously set value.
1171  * \note Will lock the channel.
1172  */
1173 void pbx_builtin_pushvar_helper(struct ast_channel *chan, const char *name, const char *value);
1174
1175 /*!
1176  * \brief Add a variable to the channel variable stack, removing the most recently set value for the same name.
1177  * \note Will lock the channel.  May also be used to set a channel dialplan function to a particular value.
1178  * \see ast_func_write
1179  * \return -1 if the dialplan function fails to be set
1180  * \version 1.8 changed the function to return an error code
1181  */
1182 int pbx_builtin_setvar_helper(struct ast_channel *chan, const char *name, const char *value);
1183
1184 /*!
1185  * \brief Retrieve the value of a builtin variable or variable from the channel variable stack.
1186  * \note Will lock the channel.
1187  */
1188 void pbx_retrieve_variable(struct ast_channel *c, const char *var, char **ret, char *workspace, int workspacelen, struct varshead *headp);
1189 void pbx_builtin_clear_globals(void);
1190
1191 /*!
1192  * \brief Parse and set a single channel variable, where the name and value are separated with an '=' character.
1193  * \note Will lock the channel.
1194  */
1195 int pbx_builtin_setvar(struct ast_channel *chan, const char *data);
1196
1197 /*!
1198  * \brief Parse and set multiple channel variables, where the pairs are separated by the ',' character, and name and value are separated with an '=' character.
1199  * \note Will lock the channel.
1200  */
1201 int pbx_builtin_setvar_multiple(struct ast_channel *chan, const char *data);
1202
1203 int pbx_builtin_raise_exception(struct ast_channel *chan, const char *data);
1204
1205 /*! @name Substitution routines, using static string buffers
1206  * @{ */
1207 void pbx_substitute_variables_helper(struct ast_channel *c, const char *cp1, char *cp2, int count);
1208 void pbx_substitute_variables_varshead(struct varshead *headp, const char *cp1, char *cp2, int count);
1209 void pbx_substitute_variables_helper_full(struct ast_channel *c, struct varshead *headp, const char *cp1, char *cp2, int cp2_size, size_t *used);
1210 /*! @} */
1211 /*! @} */
1212
1213 /*! @name Substitution routines, using dynamic string buffers */
1214
1215 /*!
1216  * \param buf Result will be placed in this buffer.
1217  * \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.
1218  * \param chan Channel variables from which to extract values, and channel to pass to any dialplan functions.
1219  * \param headp If no channel is specified, a channel list from which to extract variable values
1220  * \param var Variable name to retrieve.
1221  */
1222 const char *ast_str_retrieve_variable(struct ast_str **buf, ssize_t maxlen, struct ast_channel *chan, struct varshead *headp, const char *var);
1223
1224 /*!
1225  * \param buf Result will be placed in this buffer.
1226  * \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.
1227  * \param chan Channel variables from which to extract values, and channel to pass to any dialplan functions.
1228  * \param templ Variable template to expand.
1229  */
1230 void ast_str_substitute_variables(struct ast_str **buf, ssize_t maxlen, struct ast_channel *chan, const char *templ);
1231
1232 /*!
1233  * \param buf Result will be placed in this buffer.
1234  * \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.
1235  * \param headp If no channel is specified, a channel list from which to extract variable values
1236  * \param templ Variable template to expand.
1237  */
1238 void ast_str_substitute_variables_varshead(struct ast_str **buf, ssize_t maxlen, struct varshead *headp, const char *templ);
1239
1240 /*!
1241  * \param buf Result will be placed in this buffer.
1242  * \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.
1243  * \param c Channel variables from which to extract values, and channel to pass to any dialplan functions.
1244  * \param headp If no channel is specified, a channel list from which to extract variable values
1245  * \param templ Variable template to expand.
1246  * \param used Number of bytes read from the template.
1247  */
1248 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);
1249 /*! @} */
1250
1251 int ast_extension_patmatch(const char *pattern, const char *data);
1252
1253 /*! Set "autofallthrough" flag, if newval is <0, does not actually set.  If
1254   set to 1, sets to auto fall through.  If newval set to 0, sets to no auto
1255   fall through (reads extension instead).  Returns previous value. */
1256 int pbx_set_autofallthrough(int newval);
1257
1258 /*! Set "extenpatternmatchnew" flag, if newval is <0, does not actually set.  If
1259   set to 1, sets to use the new Trie-based pattern matcher.  If newval set to 0, sets to use
1260   the old linear-search algorithm.  Returns previous value. */
1261 int pbx_set_extenpatternmatchnew(int newval);
1262
1263 /*! Set "overrideswitch" field.  If set and of nonzero length, all contexts
1264  * will be tried directly through the named switch prior to any other
1265  * matching within that context.
1266  * \since 1.6.1
1267  */
1268 void pbx_set_overrideswitch(const char *newval);
1269
1270 /*!
1271  * \note This function will handle locking the channel as needed.
1272  */
1273 int ast_goto_if_exists(struct ast_channel *chan, const char *context, const char *exten, int priority);
1274
1275 /*!
1276  * \note This function will handle locking the channel as needed.
1277  */
1278 int ast_parseable_goto(struct ast_channel *chan, const char *goto_string);
1279
1280 /*!
1281  * \note This function will handle locking the channel as needed.
1282  */
1283 int ast_async_parseable_goto(struct ast_channel *chan, const char *goto_string);
1284
1285 /*!
1286  * \note This function will handle locking the channel as needed.
1287  */
1288 int ast_explicit_goto(struct ast_channel *chan, const char *context, const char *exten, int priority);
1289
1290 /*!
1291  * \note This function will handle locking the channel as needed.
1292  */
1293 int ast_async_goto_if_exists(struct ast_channel *chan, const char *context, const char *exten, int priority);
1294
1295 struct ast_custom_function* ast_custom_function_find(const char *name);
1296
1297 /*!
1298  * \brief Unregister a custom function
1299  */
1300 int ast_custom_function_unregister(struct ast_custom_function *acf);
1301
1302 /*!
1303  * \brief Register a custom function
1304  */
1305 #define ast_custom_function_register(acf) __ast_custom_function_register(acf, ast_module_info->self)
1306
1307 /*!
1308  * \brief Register a custom function
1309  */
1310 int __ast_custom_function_register(struct ast_custom_function *acf, struct ast_module *mod);
1311
1312 /*!
1313  * \brief Retrieve the number of active calls
1314  */
1315 int ast_active_calls(void);
1316
1317 /*!
1318  * \brief Retrieve the total number of calls processed through the PBX since last restart
1319  */
1320 int ast_processed_calls(void);
1321
1322 /*!
1323  * \brief executes a read operation on a function
1324  *
1325  * \param chan Channel to execute on
1326  * \param function Data containing the function call string (will be modified)
1327  * \param workspace A pointer to safe memory to use for a return value
1328  * \param len the number of bytes in workspace
1329  *
1330  * This application executes a function in read mode on a given channel.
1331  *
1332  * \retval 0 success
1333  * \retval non-zero failure
1334  */
1335 int ast_func_read(struct ast_channel *chan, const char *function, char *workspace, size_t len);
1336
1337 /*!
1338  * \brief executes a read operation on a function
1339  *
1340  * \param chan Channel to execute on
1341  * \param function Data containing the function call string (will be modified)
1342  * \param str A dynamic string buffer into which to place the result.
1343  * \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
1344  *
1345  * This application executes a function in read mode on a given channel.
1346  *
1347  * \retval 0 success
1348  * \retval non-zero failure
1349  */
1350 int ast_func_read2(struct ast_channel *chan, const char *function, struct ast_str **str, ssize_t maxlen);
1351
1352 /*!
1353  * \brief executes a write operation on a function
1354  *
1355  * \param chan Channel to execute on
1356  * \param function Data containing the function call string (will be modified)
1357  * \param value A value parameter to pass for writing
1358  *
1359  * This application executes a function in write mode on a given channel.
1360  *
1361  * \retval 0 success
1362  * \retval non-zero failure
1363  */
1364 int ast_func_write(struct ast_channel *chan, const char *function, const char *value);
1365
1366 /*!
1367  * \details
1368  * When looking up extensions, we can have different requests
1369  * identified by the 'action' argument, as follows.
1370  *
1371  * \note that the coding is such that the low 4 bits are the
1372  * third argument to extension_match_core.
1373  */
1374 enum ext_match_t {
1375         E_MATCHMORE =   0x00,   /* extension can match but only with more 'digits' */
1376         E_CANMATCH =    0x01,   /* extension can match with or without more 'digits' */
1377         E_MATCH =       0x02,   /* extension is an exact match */
1378         E_MATCH_MASK =  0x03,   /* mask for the argument to extension_match_core() */
1379         E_SPAWN =       0x12,   /* want to spawn an extension. Requires exact match */
1380         E_FINDLABEL =   0x22    /* returns the priority for a given label. Requires exact match */
1381 };
1382
1383 #define STATUS_NO_CONTEXT       1
1384 #define STATUS_NO_EXTENSION     2
1385 #define STATUS_NO_PRIORITY      3
1386 #define STATUS_NO_LABEL         4
1387 #define STATUS_SUCCESS          5
1388 #define AST_PBX_MAX_STACK  128
1389
1390 /* request and result for pbx_find_extension */
1391 struct pbx_find_info {
1392 #if 0
1393         const char *context;
1394         const char *exten;
1395         int priority;
1396 #endif
1397
1398         char *incstack[AST_PBX_MAX_STACK];      /* filled during the search */
1399         int stacklen;                   /* modified during the search */
1400         int status;                     /* set on return */
1401         struct ast_switch *swo;         /* set on return */
1402         const char *data;               /* set on return */
1403         const char *foundcontext;       /* set on return */
1404 };
1405
1406 struct ast_exten *pbx_find_extension(struct ast_channel *chan,
1407                                                                          struct ast_context *bypass, struct pbx_find_info *q,
1408                                                                          const char *context, const char *exten, int priority,
1409                                                                          const char *label, const char *callerid, enum ext_match_t action);
1410
1411 /*! \brief hashtable functions for contexts */
1412 /*! @{ */
1413 int ast_hashtab_compare_contexts(const void *ah_a, const void *ah_b);
1414 unsigned int ast_hashtab_hash_contexts(const void *obj);
1415 /*! @} */
1416
1417 /*!
1418  * \brief Command completion for the list of installed applications.
1419  *
1420  * This can be called from a CLI command completion function that wants to
1421  * complete from the list of available applications.
1422  */
1423 char *ast_complete_applications(const char *line, const char *word, int state);
1424
1425 #if defined(__cplusplus) || defined(c_plusplus)
1426 }
1427 #endif
1428
1429 #endif /* _ASTERISK_PBX_H */