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