70373999ebe88ab197b7edc1fcd7f8fd0ca84ed2
[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/sched.h"
27 #include "asterisk/channel.h"
28 #include "asterisk/linkedlists.h"
29
30 #if defined(__cplusplus) || defined(c_plusplus)
31 extern "C" {
32 #endif
33
34 #define AST_MAX_APP     32      /*!< Max length of an application */
35
36 #define AST_PBX_KEEP    0
37 #define AST_PBX_REPLACE 1
38
39 /*! \brief Special return values from applications to the PBX { */
40 #define AST_PBX_KEEPALIVE       10      /*!< Destroy the thread, but don't hang up the channel */
41 #define AST_PBX_NO_HANGUP_PEER  11
42 /*! } */
43
44 #define PRIORITY_HINT   -1      /*!< Special Priority for a hint */
45
46 /*! \brief Extension states 
47         \note States can be combined 
48         - \ref AstExtState
49 */
50 enum ast_extension_states {
51         AST_EXTENSION_REMOVED = -2,     /*!< Extension removed */
52         AST_EXTENSION_DEACTIVATED = -1, /*!< Extension hint removed */
53         AST_EXTENSION_NOT_INUSE = 0,    /*!< No device INUSE or BUSY  */
54         AST_EXTENSION_INUSE = 1 << 0,   /*!< One or more devices INUSE */
55         AST_EXTENSION_BUSY = 1 << 1,    /*!< All devices BUSY */
56         AST_EXTENSION_UNAVAILABLE = 1 << 2, /*!< All devices UNAVAILABLE/UNREGISTERED */
57         AST_EXTENSION_RINGING = 1 << 3, /*!< All devices RINGING */
58         AST_EXTENSION_ONHOLD = 1 << 4,  /*!< All devices ONHOLD */
59 };
60
61
62 struct ast_context;
63 struct ast_exten;     
64 struct ast_include;
65 struct ast_ignorepat;
66 struct ast_sw;
67
68 /*! \brief Typedef for devicestate and hint callbacks */
69 typedef int (*ast_state_cb_type)(char *context, char* id, enum ast_extension_states state, void *data);
70
71 /*! \brief Data structure associated with a custom dialplan function */
72 struct ast_custom_function {
73         const char *name;               /*!< Name */
74         const char *synopsis;           /*!< Short description for "show functions" */
75         const char *desc;               /*!< Help text that explains it all */
76         const char *syntax;             /*!< Syntax description */
77         int (*read)(struct ast_channel *, const char *, char *, char *, size_t);        /*!< Read function, if read is supported */
78         int (*write)(struct ast_channel *, const char *, char *, const char *);         /*!< Write function, if write is supported */
79         AST_RWLIST_ENTRY(ast_custom_function) acflist;
80 };
81
82 /*! \brief All switch functions have the same interface, so define a type for them */
83 typedef int (ast_switch_f)(struct ast_channel *chan, const char *context,
84         const char *exten, int priority, const char *callerid, const char *data);
85
86 /*!< Data structure associated with an Asterisk switch */
87 struct ast_switch {
88         AST_LIST_ENTRY(ast_switch) list;
89         const char *name;                       /*!< Name of the switch */
90         const char *description;                /*!< Description of the switch */
91         
92         ast_switch_f *exists;
93         ast_switch_f *canmatch;
94         ast_switch_f *exec;
95         ast_switch_f *matchmore;
96 };
97
98 struct ast_timing {
99         int hastime;                            /*!< If time construct exists */
100         unsigned int monthmask;                 /*!< Mask for month */
101         unsigned int daymask;                   /*!< Mask for date */
102         unsigned int dowmask;                   /*!< Mask for day of week (mon-sun) */
103         unsigned int minmask[24];               /*!< Mask for minute */
104 };
105
106 int ast_build_timing(struct ast_timing *i, const char *info);
107 int ast_check_timing(const struct ast_timing *i);
108
109 struct ast_pbx {
110         int dtimeout;                           /*!< Timeout between digits (seconds) */
111         int rtimeout;                           /*!< Timeout for response (seconds) */
112 };
113
114
115 /*!
116  * \brief Register an alternative dialplan switch
117  *
118  * \param sw switch to register
119  *
120  * This function registers a populated ast_switch structure with the
121  * asterisk switching architecture.
122  *
123  * \return 0 on success, and other than 0 on failure
124  */
125 int ast_register_switch(struct ast_switch *sw);
126
127 /*!
128  * \brief Unregister an alternative switch
129  *
130  * \param sw switch to unregister
131  * 
132  * Unregisters a switch from asterisk.
133  *
134  * \return nothing
135  */
136 void ast_unregister_switch(struct ast_switch *sw);
137
138 /*!
139  * \brief Look up an application
140  *
141  * \param app name of the app
142  *
143  * This function searches for the ast_app structure within
144  * the apps that are registered for the one with the name
145  * you passed in.
146  *
147  * \return the ast_app structure that matches on success, or NULL on failure
148  */
149 struct ast_app *pbx_findapp(const char *app);
150
151 /*!
152  * \brief Execute an application
153  *
154  * \param c channel to execute on
155  * \param app which app to execute
156  * \param data the data passed into the app
157  *
158  * This application executes an application on a given channel.  It
159  * saves the stack and executes the given application passing in
160  * the given data.
161  *
162  * \return 0 on success, and -1 on failure
163  */
164 int pbx_exec(struct ast_channel *c, struct ast_app *app, void *data);
165
166 /*!
167  * \brief Register a new context
168  *
169  * \param extcontexts pointer to the ast_context structure pointer
170  * \param name name of the new context
171  * \param registrar registrar of the context
172  *
173  * This will first search for a context with your name.  If it exists already, it will not
174  * create a new one.  If it does not exist, it will create a new one with the given name
175  * and registrar.
176  *
177  * \return NULL on failure, and an ast_context structure on success
178  */
179 struct ast_context *ast_context_create(struct ast_context **extcontexts, const char *name, const char *registrar);
180
181 /*!
182  * \brief Register a new context or find an existing one
183  *
184  * \param extcontexts pointer to the ast_context structure pointer
185  * \param name name of the new context
186  * \param registrar registrar of the context
187  *
188  * This will first search for a context with your name.  If it exists already, it will not
189  * create a new one.  If it does not exist, it will create a new one with the given name
190  * and registrar.
191  *
192  * \return NULL on failure, and an ast_context structure on success
193  */
194 struct ast_context *ast_context_find_or_create(struct ast_context **extcontexts, const char *name, const char *registrar);
195
196 /*!
197  * \brief Merge the temporary contexts into a global contexts list and delete from the 
198  *        global list the ones that are being added
199  *
200  * \param extcontexts pointer to the ast_context structure pointer
201  * \param registrar of the context; if it's set the routine will delete all contexts 
202  *        that belong to that registrar; if NULL only the contexts that are specified 
203  *        in extcontexts
204  */
205 void ast_merge_contexts_and_delete(struct ast_context **extcontexts, const char *registrar);
206
207 /*!
208  * \brief Destroy a context (matches the specified context (or ANY context if NULL)
209  *
210  * \param con context to destroy
211  * \param registrar who registered it
212  *
213  * You can optionally leave out either parameter.  It will find it
214  * based on either the ast_context or the registrar name.
215  *
216  * \return nothing
217  */
218 void ast_context_destroy(struct ast_context *con, const char *registrar);
219
220 /*!
221  * \brief Find a context
222  *
223  * \param name name of the context to find
224  *
225  * Will search for the context with the given name.
226  *
227  * \return the ast_context on success, NULL on failure.
228  */
229 struct ast_context *ast_context_find(const char *name);
230
231 /*! \brief The result codes when starting the PBX on a channelwith \see ast_pbx_start.
232         AST_PBX_CALL_LIMIT refers to the maxcalls call limit in asterisk.conf
233  */
234 enum ast_pbx_result {
235         AST_PBX_SUCCESS = 0,
236         AST_PBX_FAILED = -1,
237         AST_PBX_CALL_LIMIT = -2,
238 };
239
240 /*!
241  * \brief Create a new thread and start the PBX
242  *
243  * \param c channel to start the pbx on
244  *
245  * \see ast_pbx_run for a synchronous function to run the PBX in the
246  * current thread, as opposed to starting a new one.
247  *
248  * \retval Zero on success
249  * \retval non-zero on failure
250  */
251 enum ast_pbx_result ast_pbx_start(struct ast_channel *c);
252
253 /*!
254  * \brief Execute the PBX in the current thread
255  *
256  * \param c channel to run the pbx on
257  *
258  * This executes the PBX on a given channel. It allocates a new
259  * PBX structure for the channel, and provides all PBX functionality.
260  * See ast_pbx_start for an asynchronous function to run the PBX in a
261  * new thread as opposed to the current one.
262  * 
263  * \retval Zero on success
264  * \retval non-zero on failure
265  */
266 enum ast_pbx_result ast_pbx_run(struct ast_channel *c);
267
268 /*! 
269  * \brief Add and extension to an extension context.  
270  * 
271  * \param context context to add the extension to
272  * \param replace
273  * \param extension extension to add
274  * \param priority priority level of extension addition
275  * \param label extension label
276  * \param callerid pattern to match CallerID, or NULL to match any CallerID
277  * \param application application to run on the extension with that priority level
278  * \param data data to pass to the application
279  * \param datad
280  * \param registrar who registered the extension
281  *
282  * \retval 0 success 
283  * \retval -1 failure
284  */
285 int ast_add_extension(const char *context, int replace, const char *extension, 
286         int priority, const char *label, const char *callerid,
287         const char *application, void *data, void (*datad)(void *), const char *registrar);
288
289 /*! 
290  * \brief Add an extension to an extension context, this time with an ast_context *.
291  *
292  * \note For details about the arguments, check ast_add_extension()
293  */
294 int ast_add_extension2(struct ast_context *con, int replace, const char *extension,
295         int priority, const char *label, const char *callerid, 
296         const char *application, void *data, void (*datad)(void *), const char *registrar);
297
298
299 /*! 
300  * \brief Register an application.
301  *
302  * \param app Short name of the application
303  * \param execute a function callback to execute the application. It should return
304  *                non-zero if the channel needs to be hung up.
305  * \param synopsis a short description (one line synopsis) of the application
306  * \param description long description with all of the details about the use of 
307  *                    the application
308  * 
309  * This registers an application with Asterisk's internal application list. 
310  * \note The individual applications themselves are responsible for registering and unregistering
311  *       and unregistering their own CLI commands.
312  * 
313  * \retval 0 success 
314  * \retval -1 failure.
315  */
316 #define ast_register_application(app, execute, synopsis, description) ast_register_application2(app, execute, synopsis, description, ast_module_info->self)
317
318 /*!
319  * \brief Register an application.
320  *
321  * \param app Short name of the application
322  * \param execute a function callback to execute the application. It should return
323  *                non-zero if the channel needs to be hung up.
324  * \param synopsis a short description (one line synopsis) of the application
325  * \param description long description with all of the details about the use of
326  *                    the application
327  * \param mod module this application belongs to
328  *
329  * This registers an application with Asterisk's internal application list.
330  * \note The individual applications themselves are responsible for registering and unregistering
331  *       and unregistering their own CLI commands.
332  *
333  * \retval 0 success
334  * \retval -1 failure.
335  */
336 int ast_register_application2(const char *app, int (*execute)(struct ast_channel *, void *),
337                                      const char *synopsis, const char *description, void *mod);
338
339 /*! 
340  * \brief Unregister an application
341  * 
342  * \param app name of the application (does not have to be the same string as the one that was registered)
343  * 
344  * This unregisters an application from Asterisk's internal application list.
345  * 
346  * \retval 0 success 
347  * \retval -1 failure
348  */
349 int ast_unregister_application(const char *app);
350
351 /*! 
352  * \brief Uses hint and devicestate callback to get the state of an extension
353  *
354  * \param c this is not important
355  * \param context which context to look in
356  * \param exten which extension to get state
357  *
358  * \return extension state as defined in the ast_extension_states enum
359  */
360 int ast_extension_state(struct ast_channel *c, const char *context, const char *exten);
361
362 /*! 
363  * \brief Return string representation of the state of an extension
364  * 
365  * \param extension_state is the numerical state delivered by ast_extension_state
366  *
367  * \return the state of an extension as string
368  */
369 const char *ast_extension_state2str(int extension_state);
370
371 /*!
372  * \brief Registers a state change callback
373  * 
374  * \param context which context to look in
375  * \param exten which extension to get state
376  * \param callback callback to call if state changed
377  * \param data to pass to callback
378  *
379  * The callback is called if the state of an extension is changed.
380  *
381  * \retval -1 on failure
382  * \retval ID on success
383  */ 
384 int ast_extension_state_add(const char *context, const char *exten, 
385                             ast_state_cb_type callback, void *data);
386
387 /*! 
388  * \brief Deletes a registered state change callback by ID
389  * 
390  * \param id of the callback to delete
391  * \param callback callback
392  *
393  * Removes the callback from list of callbacks
394  *
395  * \retval 0 success 
396  * \retval -1 failure
397  */
398 int ast_extension_state_del(int id, ast_state_cb_type callback);
399
400 /*! 
401  * \brief If an extension hint exists, return non-zero
402  * 
403  * \param hint buffer for hint
404  * \param maxlen size of hint buffer
405  * \param name buffer for name portion of hint
406  * \param maxnamelen size of name buffer
407  * \param c this is not important
408  * \param context which context to look in
409  * \param exten which extension to search for
410  *
411  * \return If an extension within the given context with the priority PRIORITY_HINT
412  * is found a non zero value will be returned.
413  * Otherwise, 0 is returned.
414  */
415 int ast_get_hint(char *hint, int maxlen, char *name, int maxnamelen, 
416         struct ast_channel *c, const char *context, const char *exten);
417
418 /*!
419  * \brief Determine whether an extension exists
420  *
421  * \param c this is not important
422  * \param context which context to look in
423  * \param exten which extension to search for
424  * \param priority priority of the action within the extension
425  * \param callerid callerid to search for
426  *
427  * \return If an extension within the given context(or callerid) with the given priority 
428  *         is found a non zero value will be returned. Otherwise, 0 is returned.
429  */
430 int ast_exists_extension(struct ast_channel *c, const char *context, const char *exten, 
431         int priority, const char *callerid);
432
433 /*! 
434  * \brief Find the priority of an extension that has the specified label
435  * 
436  * \param c this is not important
437  * \param context which context to look in
438  * \param exten which extension to search for
439  * \param label label of the action within the extension to match to priority
440  * \param callerid callerid to search for
441  *
442  * \retval the priority which matches the given label in the extension
443  * \retval -1 if not found.
444  */
445 int ast_findlabel_extension(struct ast_channel *c, const char *context, 
446         const char *exten, const char *label, const char *callerid);
447
448 /*!
449  * \brief Find the priority of an extension that has the specified label
450  *
451  * \note This function is the same as ast_findlabel_extension, except that it accepts
452  * a pointer to an ast_context structure to specify the context instead of the
453  * name of the context. Otherwise, the functions behave the same.
454  */
455 int ast_findlabel_extension2(struct ast_channel *c, struct ast_context *con, 
456         const char *exten, const char *label, const char *callerid);
457
458 /*! 
459  * \brief Looks for a valid matching extension
460  * 
461  * \param c not really important
462  * \param context context to serach within
463  * \param exten extension to check
464  * \param priority priority of extension path
465  * \param callerid callerid of extension being searched for
466  *
467  * \return If "exten" *could be* a valid extension in this context with or without
468  * some more digits, return non-zero.  Basically, when this returns 0, no matter
469  * what you add to exten, it's not going to be a valid extension anymore
470  */
471 int ast_canmatch_extension(struct ast_channel *c, const char *context, 
472         const char *exten, int priority, const char *callerid);
473
474 /*! 
475  * \brief Looks to see if adding anything to this extension might match something. (exists ^ canmatch)
476  *
477  * \param c not really important XXX
478  * \param context context to serach within
479  * \param exten extension to check
480  * \param priority priority of extension path
481  * \param callerid callerid of extension being searched for
482  *
483  * \return If "exten" *could match* a valid extension in this context with
484  * some more digits, return non-zero.  Does NOT return non-zero if this is
485  * an exact-match only.  Basically, when this returns 0, no matter
486  * what you add to exten, it's not going to be a valid extension anymore
487  */
488 int ast_matchmore_extension(struct ast_channel *c, const char *context, 
489         const char *exten, int priority, const char *callerid);
490
491 /*! 
492  * \brief Determine if a given extension matches a given pattern (in NXX format)
493  * 
494  * \param pattern pattern to match
495  * \param extension extension to check against the pattern.
496  *
497  * Checks whether or not the given extension matches the given pattern.
498  *
499  * \retval 1 on match
500  * \retval 0 on failure
501  */
502 int ast_extension_match(const char *pattern, const char *extension);
503
504 int ast_extension_close(const char *pattern, const char *data, int needmore);
505
506 /*! 
507  * \brief Launch a new extension (i.e. new stack)
508  * 
509  * \param c not important
510  * \param context which context to generate the extension within
511  * \param exten new extension to add
512  * \param priority priority of new extension
513  * \param callerid callerid of extension
514  *
515  * This adds a new extension to the asterisk extension list.
516  *
517  * \retval 0 on success 
518  * \retval -1 on failure.
519  */
520 int ast_spawn_extension(struct ast_channel *c, const char *context, 
521         const char *exten, int priority, const char *callerid);
522
523 /*! 
524  * \brief Add a context include
525  *
526  * \param context context to add include to
527  * \param include new include to add
528  * \param registrar who's registering it
529  *
530  * Adds an include taking a char * string as the context parameter
531  *
532  * \retval 0 on success 
533  * \retval -1 on error
534 */
535 int ast_context_add_include(const char *context, const char *include, 
536         const char *registrar);
537
538 /*! 
539  * \brief Add a context include
540  * 
541  * \param con context to add the include to
542  * \param include include to add
543  * \param registrar who registered the context
544  *
545  * Adds an include taking a struct ast_context as the first parameter
546  *
547  * \retval 0 on success 
548  * \retval -1 on failure
549  */
550 int ast_context_add_include2(struct ast_context *con, const char *include, 
551         const char *registrar);
552
553 /*! 
554  * \brief Remove a context include
555  * 
556  * \note See ast_context_add_include for information on arguments
557  *
558  * \retval 0 on success
559  * \retval -1 on failure
560  */
561 int ast_context_remove_include(const char *context, const char *include, 
562         const char *registrar);
563
564 /*! 
565  * \brief Removes an include by an ast_context structure 
566  * 
567  * \note See ast_context_add_include2 for information on arguments
568  *
569  * \retval 0 on success
570  * \retval -1 on success
571  */
572 int ast_context_remove_include2(struct ast_context *con, const char *include, 
573         const char *registrar);
574
575 /*! 
576  * \brief Verifies includes in an ast_contect structure
577  * 
578  * \param con context in which to verify the includes
579  *
580  * \retval 0 if no problems found 
581  * \retval -1 if there were any missing context
582  */
583 int ast_context_verify_includes(struct ast_context *con);
584           
585 /*! 
586  * \brief Add a switch
587  * 
588  * \param context context to which to add the switch
589  * \param sw switch to add
590  * \param data data to pass to switch
591  * \param eval whether to evaluate variables when running switch
592  * \param registrar whoever registered the switch
593  *
594  * This function registers a switch with the asterisk switch architecture
595  *
596  * \retval 0 on success 
597  * \retval -1 on failure
598  */
599 int ast_context_add_switch(const char *context, const char *sw, const char *data, 
600         int eval, const char *registrar);
601
602 /*! 
603  * \brief Adds a switch (first param is a ast_context)
604  * 
605  * \note See ast_context_add_switch() for argument information, with the exception of
606  *       the first argument. In this case, it's a pointer to an ast_context structure
607  *       as opposed to the name.
608  */
609 int ast_context_add_switch2(struct ast_context *con, const char *sw, const char *data, 
610         int eval, const char *registrar);
611
612 /*! 
613  * \brief Remove a switch
614  * 
615  * Removes a switch with the given parameters
616  *
617  * \retval 0 on success 
618  * \retval -1 on failure
619  */
620 int ast_context_remove_switch(const char *context, const char *sw, 
621         const char *data, const char *registrar);
622
623 int ast_context_remove_switch2(struct ast_context *con, const char *sw, 
624         const char *data, const char *registrar);
625
626 /*! 
627  * \brief Simply remove extension from context
628  * 
629  * \param context context to remove extension from
630  * \param extension which extension to remove
631  * \param priority priority of extension to remove
632  * \param registrar registrar of the extension
633  *
634  * This function removes an extension from a given context.
635  *
636  * \retval 0 on success 
637  * \retval -1 on failure
638  */
639 int ast_context_remove_extension(const char *context, const char *extension, int priority,
640         const char *registrar);
641
642 int ast_context_remove_extension2(struct ast_context *con, const char *extension,
643         int priority, const char *registrar);
644
645 /*! 
646  * \brief Add an ignorepat
647  * 
648  * \param context which context to add the ignorpattern to
649  * \param ignorepat ignorepattern to set up for the extension
650  * \param registrar registrar of the ignore pattern
651  *
652  * Adds an ignore pattern to a particular context.
653  *
654  * \retval 0 on success 
655  * \retval -1 on failure
656  */
657 int ast_context_add_ignorepat(const char *context, const char *ignorepat, const char *registrar);
658
659 int ast_context_add_ignorepat2(struct ast_context *con, const char *ignorepat, const char *registrar);
660
661 /* 
662  * \brief Remove an ignorepat
663  * 
664  * \param context context from which to remove the pattern
665  * \param ignorepat the pattern to remove
666  * \param registrar the registrar of the ignore pattern
667  *
668  * This removes the given ignorepattern
669  *
670  * \retval 0 on success 
671  * \retval -1 on failure
672  */
673 int ast_context_remove_ignorepat(const char *context, const char *ignorepat, const char *registrar);
674
675 int ast_context_remove_ignorepat2(struct ast_context *con, const char *ignorepat, const char *registrar);
676
677 /*! 
678  * \brief Checks to see if a number should be ignored
679  * 
680  * \param context context to search within
681  * \param pattern to check whether it should be ignored or not
682  *
683  * Check if a number should be ignored with respect to dialtone cancellation.
684  *
685  * \retval 0 if the pattern should not be ignored 
686  * \retval non-zero if the pattern should be ignored 
687  */
688 int ast_ignore_pattern(const char *context, const char *pattern);
689
690 /* Locking functions for outer modules, especially for completion functions */
691
692 /*! 
693  * \brief Write locks the context list
694  *
695  * \retval 0 on success 
696  * \retval -1 on error
697  */
698 int ast_wrlock_contexts(void);
699
700 /*!
701  * \brief Read locks the context list
702  *
703  * \retval 0 on success
704  * \retval -1 on error
705  */
706 int ast_rdlock_contexts(void);
707
708 /*! 
709  * \brief Unlocks contexts
710  * 
711  * \retval 0 on success 
712  * \retval -1 on failure
713  */
714 int ast_unlock_contexts(void);
715
716 /*! 
717  * \brief Write locks a given context
718  * 
719  * \param con context to lock
720  *
721  * \retval 0 on success 
722  * \retval -1 on failure
723  */
724 int ast_wrlock_context(struct ast_context *con);
725
726 /*!
727  * \brief Read locks a given context
728  *
729  * \param con context to lock
730  *
731  * \retval 0 on success
732  * \retval -1 on failure
733  */
734 int ast_rdlock_context(struct ast_context *con);
735
736 /*! 
737  * \retval Unlocks the given context
738  * 
739  * \param con context to unlock
740  *
741  * \retval 0 on success 
742  * \retval -1 on failure
743  */
744 int ast_unlock_context(struct ast_context *con);
745
746 /*! 
747  * \brief locks the macrolock in the given given context
748  *
749  * \param macrocontext name of the macro-context to lock
750  *
751  * Locks the given macro-context to ensure only one thread (call) can execute it at a time
752  *
753  * \retval 0 on success
754  * \retval -1 on failure
755  */
756 int ast_context_lockmacro(const char *macrocontext);
757
758 /*!
759  * \brief Unlocks the macrolock in the given context
760  *
761  * \param macrocontext name of the macro-context to unlock
762  *
763  * Unlocks the given macro-context so that another thread (call) can execute it
764  *
765  * \retval 0 on success
766  * \retval -1 on failure
767  */
768 int ast_context_unlockmacro(const char *macrocontext);
769
770 int ast_async_goto(struct ast_channel *chan, const char *context, const char *exten, int priority);
771
772 int ast_async_goto_by_name(const char *chan, const char *context, const char *exten, int priority);
773
774 /*! Synchronously or asynchronously make an outbound call and send it to a
775    particular extension */
776 int ast_pbx_outgoing_exten(const char *type, int format, void *data, 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);
777
778 /*! Synchronously or asynchronously make an outbound call and send it to a
779    particular application with given extension */
780 int ast_pbx_outgoing_app(const char *type, int format, void *data, 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);
781
782 /*!
783  * \brief Evaluate a condition
784  *
785  * \retval 0 if the condition is NULL or of zero length
786  * \retval int If the string is an integer, the integer representation of
787  *             the integer is returned
788  * \retval 1 Any other non-empty string
789  */
790 int pbx_checkcondition(const char *condition);
791
792 /*! @name 
793  * Functions for returning values from structures */
794 /*! @{ */
795 const char *ast_get_context_name(struct ast_context *con);
796 const char *ast_get_extension_name(struct ast_exten *exten);
797 struct ast_context *ast_get_extension_context(struct ast_exten *exten);
798 const char *ast_get_include_name(struct ast_include *include);
799 const char *ast_get_ignorepat_name(struct ast_ignorepat *ip);
800 const char *ast_get_switch_name(struct ast_sw *sw);
801 const char *ast_get_switch_data(struct ast_sw *sw);
802 /*! @} */
803
804 /*! @name Other Extension stuff */
805 /*! @{ */
806 int ast_get_extension_priority(struct ast_exten *exten);
807 int ast_get_extension_matchcid(struct ast_exten *e);
808 const char *ast_get_extension_cidmatch(struct ast_exten *e);
809 const char *ast_get_extension_app(struct ast_exten *e);
810 const char *ast_get_extension_label(struct ast_exten *e);
811 void *ast_get_extension_app_data(struct ast_exten *e);
812 /*! @} */
813
814 /*! @name Registrar info functions ... */
815 /*! @{ */
816 const char *ast_get_context_registrar(struct ast_context *c);
817 const char *ast_get_extension_registrar(struct ast_exten *e);
818 const char *ast_get_include_registrar(struct ast_include *i);
819 const char *ast_get_ignorepat_registrar(struct ast_ignorepat *ip);
820 const char *ast_get_switch_registrar(struct ast_sw *sw);
821 /*! @} */
822
823 /* Walking functions ... */
824 struct ast_context *ast_walk_contexts(struct ast_context *con);
825 struct ast_exten *ast_walk_context_extensions(struct ast_context *con,
826         struct ast_exten *priority);
827 struct ast_exten *ast_walk_extension_priorities(struct ast_exten *exten,
828         struct ast_exten *priority);
829 struct ast_include *ast_walk_context_includes(struct ast_context *con,
830         struct ast_include *inc);
831 struct ast_ignorepat *ast_walk_context_ignorepats(struct ast_context *con,
832         struct ast_ignorepat *ip);
833 struct ast_sw *ast_walk_context_switches(struct ast_context *con, struct ast_sw *sw);
834
835 int pbx_builtin_serialize_variables(struct ast_channel *chan, struct ast_str **buf);
836 const char *pbx_builtin_getvar_helper(struct ast_channel *chan, const char *name);
837 void pbx_builtin_pushvar_helper(struct ast_channel *chan, const char *name, const char *value);
838 void pbx_builtin_setvar_helper(struct ast_channel *chan, const char *name, const char *value);
839 void pbx_retrieve_variable(struct ast_channel *c, const char *var, char **ret, char *workspace, int workspacelen, struct varshead *headp);
840 void pbx_builtin_clear_globals(void);
841 int pbx_builtin_setvar(struct ast_channel *chan, void *data);
842 void pbx_substitute_variables_helper(struct ast_channel *c,const char *cp1,char *cp2,int count);
843 void pbx_substitute_variables_varshead(struct varshead *headp, const char *cp1, char *cp2, int count);
844
845 int ast_extension_patmatch(const char *pattern, const char *data);
846
847 /*! Set "autofallthrough" flag, if newval is <0, does not acutally set.  If
848   set to 1, sets to auto fall through.  If newval set to 0, sets to no auto
849   fall through (reads extension instead).  Returns previous value. */
850 int pbx_set_autofallthrough(int newval);
851 int ast_goto_if_exists(struct ast_channel *chan, const char *context, const char *exten, int priority);
852 /* I can find neither parsable nor parseable at dictionary.com, but google gives me 169000 hits for parseable and only 49,800 for parsable */
853 int ast_parseable_goto(struct ast_channel *chan, const char *goto_string);
854 int ast_explicit_goto(struct ast_channel *chan, const char *context, const char *exten, int priority);
855 int ast_async_goto_if_exists(struct ast_channel *chan, const char *context, const char *exten, int priority);
856
857 struct ast_custom_function* ast_custom_function_find(const char *name);
858
859 /*!
860  * \brief Unregister a custom function
861  */
862 int ast_custom_function_unregister(struct ast_custom_function *acf);
863
864 /*!
865  * \brief Reigster a custom function
866  */
867 int ast_custom_function_register(struct ast_custom_function *acf);
868
869 /*! 
870  * \brief Retrieve the number of active calls
871  */
872 int ast_active_calls(void);
873         
874 /*!
875  * \brief executes a read operation on a function 
876  *
877  * \param chan Channel to execute on
878  * \param function Data containing the function call string (will be modified)
879  * \param workspace A pointer to safe memory to use for a return value 
880  * \param len the number of bytes in workspace
881  *
882  * This application executes a function in read mode on a given channel.
883  *
884  * \return zero on success, non-zero on failure
885  */
886 int ast_func_read(struct ast_channel *chan, const char *function, char *workspace, size_t len);
887
888 /*!
889  * \brief executes a write operation on a function
890  *
891  * \param chan Channel to execute on
892  * \param function Data containing the function call string (will be modified)
893  * \param value A value parameter to pass for writing
894  *
895  * This application executes a function in write mode on a given channel.
896  *
897  * \return zero on success, non-zero on failure
898  */
899 int ast_func_write(struct ast_channel *chan, const char *function, const char *value);
900
901 #if defined(__cplusplus) || defined(c_plusplus)
902 }
903 #endif
904
905 #endif /* _ASTERISK_PBX_H */