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