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