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