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