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