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