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