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