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