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