a616414e33f6d91935d96f9c450c7f1be64ef31d
[asterisk/asterisk.git] / include / asterisk / pbx.h
1 /*
2  * Asterisk -- A telephony toolkit for Linux.
3  *
4  * Core PBX routines and definitions.
5  * 
6  * Copyright (C) 1999, Mark Spencer
7  *
8  * Mark Spencer <markster@linux-support.net>
9  *
10  * This program is free software, distributed under the terms of
11  * the GNU General Public License
12  */
13 #ifndef _ASTERISK_PBX_H
14 #define _ASTERISK_PBX_H
15
16 #include <asterisk/sched.h>
17 #include <asterisk/channel.h>
18
19 #if defined(__cplusplus) || defined(c_plusplus)
20 extern "C" {
21 #endif
22
23 #define AST_PBX_KEEP    0
24 #define AST_PBX_REPLACE 1
25
26 //! Max length of an application
27 #define AST_MAX_APP     32
28
29 //! Special return values from applications to the PBX
30 #define AST_PBX_KEEPALIVE       10              /* Destroy the thread, but don't hang up the channel */
31
32 //! Special Priority for an hint
33 #define PRIORITY_HINT   -1
34
35 //! Extension states
36 //! No device INUSE or BUSY 
37 #define AST_EXTENSION_NOT_INUSE         0
38 //! One or more devices INUSE
39 #define AST_EXTENSION_INUSE             1
40 //! All devices BUSY
41 #define AST_EXTENSION_BUSY              2
42 //! All devices UNAVAILABLE/UNREGISTERED
43 #define AST_EXTENSION_UNAVAILABLE       3
44
45 struct ast_context;
46 struct ast_exten;     
47 struct ast_include;
48 struct ast_ignorepat;
49 struct ast_sw;
50
51 typedef int (*ast_notify_cb_type)(char *context, char* id, int state, void *data);
52
53 //! Data structure associated with an asterisk switch
54 struct ast_switch {
55         /*! NULL */
56         struct ast_switch *next;        
57         /*! Name of the switch */
58         char *name;                             
59         /*! Description of the switch */
60         char *description;              
61         
62         int (*exists)(struct ast_channel *chan, char *context, char *exten, int priority, char *callerid, char *data);
63         
64         int (*canmatch)(struct ast_channel *chan, char *context, char *exten, int priority, char *callerid, char *data);
65         
66         int (*exec)(struct ast_channel *chan, char *context, char *exten, int priority, char *callerid, int newstack, char *data);
67
68         int (*matchmore)(struct ast_channel *chan, char *context, char *exten, int priority, char *callerid, char *data);
69 };
70
71 //! Register an alternative switch
72 /*!
73  * \param sw switch to register
74  * This function registers a populated ast_switch structure with the
75  * asterisk switching architecture.
76  * It returns 0 on success, and other than 0 on failure
77  */
78 extern int ast_register_switch(struct ast_switch *sw);
79
80 //! Unregister an alternative switch
81 /*!
82  * \param sw switch to unregister
83  * Unregisters a switch from asterisk.
84  * Returns nothing
85  */
86 extern void ast_unregister_switch(struct ast_switch *sw);
87
88 //! Look up an application
89 /*!
90  * \param app name of the app
91  * This function searches for the ast_app structure within
92  * the apps that are registered for the one with the name
93  * you passed in.
94  * Returns the ast_app structure that matches on success, or NULL on failure
95  */
96 extern struct ast_app *pbx_findapp(char *app);
97
98 //! executes an application
99 /*!
100  * \param c channel to execute on
101  * \param app which app to execute
102  * \param data the data passed into the app
103  * \param newstack stack pointer
104  * This application executes an application on a given channel.  It
105  * saves the stack and executes the given appliation passing in
106  * the given data.
107  * It returns 0 on success, and -1 on failure
108  */
109 int pbx_exec(struct ast_channel *c, struct ast_app *app, void *data, int newstack);
110
111 //! Register a new context
112 /*!
113  * \param name name of the new context
114  * \param registrar registrar of the context
115  * This will first search for a context with your name.  If it exists already, it will not
116  * create a new one.  If it does not exist, it will create a new one with the given name
117  * and registrar.
118  * It returns NULL on failure, and an ast_context structure on success
119  */
120 struct ast_context *ast_context_create(char *name, char *registrar);
121
122 //! Destroy a context (matches the specified context (or ANY context if NULL)
123 /*!
124  * \param con context to destroy
125  * \param registrar who registered it
126  * You can optionally leave out either parameter.  It will find it
127  * based on either the ast_context or the registrar name.
128  * Returns nothing
129  */
130 void ast_context_destroy(struct ast_context *con, char *registrar);
131
132 //! Find a context
133 /*!
134  * \param name name of the context to find
135  * Will search for the context with the given name.
136  * Returns the ast_context on success, NULL on failure.
137  */
138 struct ast_context *ast_context_find(char *name);
139
140 //! Create a new thread and start the PBX (or whatever)
141 /*!
142  * \param c channel to start the pbx on
143  * Starts a pbx thread on a given channel
144  * It returns -1 on failure, and 0 on success
145  */
146 int ast_pbx_start(struct ast_channel *c);
147
148 //! Execute the PBX in the current thread
149 /*!
150  * \param c channel to run the pbx on
151  * This executes the PBX on a given channel.  It allocates a new
152  * PBX structure for the channel, and provides all PBX functionality.
153  */
154 int ast_pbx_run(struct ast_channel *c);
155
156 /*! 
157  * \param context context to add the extension to
158  * \param replace
159  * \param extension extension to add
160  * \param priority priority level of extension addition
161  * \param callerid callerid of extension
162  * \param application application to run on the extension with that priority level
163  * \param data data to pass to the application
164  * \param datad
165  * \param registrar who registered the extension
166  * Add and extension to an extension context.  
167  * Callerid is a pattern to match CallerID, or NULL to match any callerid
168  * Returns 0 on success, -1 on failure
169  */
170 int ast_add_extension(char *context, int replace, char *extension, int priority, char *callerid,
171         char *application, void *data, void (*datad)(void *), char *registrar);
172
173 //! Add an extension to an extension context, this time with an ast_context *.  CallerID is a pattern to match on callerid, or NULL to not care about callerid
174 /*! 
175  * For details about the arguements, check ast_add_extension()
176  */
177 int ast_add_extension2(struct ast_context *con,
178                                       int replace, char *extension, int priority, char *callerid, 
179                                           char *application, void *data, void (*datad)(void *),
180                                           char *registrar);
181
182 //! Add an application.  The function 'execute' should return non-zero if the line needs to be hung up. 
183 /*!
184   \param app Short name of the application
185   \param execute a function callback to execute the application
186   \param synopsis a short description of the application
187   \param description long description of the application
188    Include a one-line synopsis (e.g. 'hangs up a channel') and a more lengthy, multiline
189    description with more detail, including under what conditions the application
190    will return 0 or -1.
191    This registers an application with asterisks internal application list.  Please note:
192    The individual applications themselves are responsible for registering and unregistering
193    CLI commands.
194    It returns 0 on success, -1 on failure.
195 */
196 int ast_register_application(char *app, int (*execute)(struct ast_channel *, void *),
197                              char *synopsis, char *description);
198
199 //! Remove an application
200 /*!
201  * \param app name of the application (does not have to be the same string as the one that was registered)
202  * This unregisters an application from asterisk's internal registration mechanisms.
203  * It returns 0 on success, and -1 on failure.
204  */
205 int ast_unregister_application(char *app);
206
207 //! Uses hint and devicestate callback to get the state of an extension
208 /*!
209  * \param c this is not important
210  * \param context which context to look in
211  * \param exten which extension to get state
212  * Returns extension state !! = AST_EXTENSION_???
213  */
214 int ast_extension_state(struct ast_channel *c, char *context, char *exten);
215
216 //! Tells Asterisk the State for Device is changed
217 /*!
218  * \param device devicename like a dialstring
219  * Asterisk polls the new extensionstates and calls the registered
220  * callbacks for the changed extensions
221  * Returns 0 on success, -1 on failure
222  */
223 int ast_device_state_changed(char *device);
224
225 //! Registers a state change callback
226 /*!
227  * \param context which context to look in
228  * \param exten which extension to get state
229  * \param callback callback to call if state changed
230  * \param data to pass to callback
231  * The callback is called if the state for extension is changed
232  * Return -1 on failure, ID on success
233  */ 
234 int ast_extension_state_add(char *context, char *exten, 
235                             ast_notify_cb_type callback, void *data);
236
237 //! Deletes a registered state change callback by ID
238 /*!
239  * \param id of the callback to delete
240  * Removes the callback from list of callbacks
241  * Return 0 on success, -1 on failure
242  */
243 int ast_extension_state_del(int id);
244
245 //! If an extension exists, return non-zero
246 /*!
247  * \param hint buffer for hint
248  * \param maxlen size of hint buffer
249  * \param c this is not important
250  * \param context which context to look in
251  * \param exten which extension to search for
252  * If an extension within the given context with the priority PRIORITY_HINT
253  * is found a non zero value will be returned.
254  * Otherwise, 0 is returned.
255  */
256 int ast_get_hint(char *hint, int maxlen, struct ast_channel *c, char *context, char *exten);
257
258 //! If an extension exists, return non-zero
259 // work
260 /*!
261  * \param c this is not important
262  * \param context which context to look in
263  * \param exten which extension to search for
264  * \param priority priority of the action within the extension
265  * \param callerid callerid to search for
266  * If an extension within the given context(or callerid) with the given priority is found a non zero value will be returned.
267  * Otherwise, 0 is returned.
268  */
269 int ast_exists_extension(struct ast_channel *c, char *context, char *exten, int priority, char *callerid);
270
271 //! Looks for a valid matching extension
272 /*!
273   \param c not really important
274   \param context context to serach within
275   \param exten extension to check
276   \param priority priority of extension path
277   \param callerid callerid of extension being searched for
278    If "exten" *could be* a valid extension in this context with or without
279    some more digits, return non-zero.  Basically, when this returns 0, no matter
280    what you add to exten, it's not going to be a valid extension anymore
281 */
282 int ast_canmatch_extension(struct ast_channel *c, char *context, char *exten, int priority, char *callerid);
283
284 //! Looks to see if adding anything to this extension might match something. (exists ^ canmatch)
285 /*!
286   \param c not really important
287   \param context context to serach within
288   \param exten extension to check
289   \param priority priority of extension path
290   \param callerid callerid of extension being searched for
291    If "exten" *could match* a valid extension in this context with
292    some more digits, return non-zero.  Does NOT return non-zero if this is
293    an exact-match only.  Basically, when this returns 0, no matter
294    what you add to exten, it's not going to be a valid extension anymore
295 */
296 int ast_matchmore_extension(struct ast_channel *c, char *context, char *exten, int priority, char *callerid);
297
298 //! Determine if a given extension matches a given pattern (in NXX format)
299 /*!
300  * \param pattern pattern to match
301  * \param extension extension to check against the pattern.
302  * Checks whether or not the given extension matches the given pattern.
303  * Returns 1 on match, 0 on failure
304  */
305 int ast_extension_match(char *pattern, char *extension);
306
307 //! Launch a new extension (i.e. new stack)
308 /*!
309  * \param c not important
310  * \param context which context to generate the extension within
311  * \param exten new extension to add
312  * \param priority priority of new extension
313  * \param callerid callerid of extension
314  * This adds a new extension to the asterisk extension list.
315  * It returns 0 on success, -1 on failure.
316  */
317 int ast_spawn_extension(struct ast_channel *c, char *context, char *exten, int priority, char *callerid);
318
319 //! Execute an extension.
320 /*!
321   \param c channel to execute upon
322   \param context which context extension is in
323   \param exten extension to execute
324   \param priority priority to execute within the given extension
325    If it's not available, do whatever you should do for
326    default extensions and halt the thread if necessary.  This function does not
327    return, except on error.
328 */
329 int ast_exec_extension(struct ast_channel *c, char *context, char *exten, int priority, char *callerid);
330
331 //! Add an include
332 /*!
333   \param context context to add include to
334   \param include new include to add
335   \param registrar who's registering it
336    Adds an include taking a char * string as the context parameter
337    Returns 0 on success, -1 on error
338 */
339 int ast_context_add_include(char *context, char *include, char *registrar);
340
341 //! Add an include
342 /*!
343   \param con context to add the include to
344   \param include include to add
345   \param registrar who registered the context
346    Adds an include taking a struct ast_context as the first parameter
347    Returns 0 on success, -1 on failure
348 */
349 int ast_context_add_include2(struct ast_context *con, char *include, char *registrar);
350
351 //! Removes an include
352 /*!
353  * See add_include
354  */
355 int ast_context_remove_include(char *context, char *include, char *registrar);
356 //! Removes an include by an ast_context structure
357 /*!
358  * See add_include2
359  */
360 int ast_context_remove_include2(struct ast_context *con, char *include, char *registrar);
361
362 //! Add a switch
363 /*!
364  * \param context context to which to add the switch
365  * \param sw switch to add
366  * \param data data to pass to switch
367  * \param registrar whoever registered the switch
368  * This function registers a switch with the asterisk switch architecture
369  * It returns 0 on success, -1 on failure
370  */
371 int ast_context_add_switch(char *context, char *sw, char *data, char *registrar);
372 //! Adds a switch (first param is a ast_context)
373 /*!
374  * See ast_context_add_switch()
375  */
376 int ast_context_add_switch2(struct ast_context *con, char *sw, char *data, char *registrar);
377
378 //! Remove a switch
379 /*!
380  * Removes a switch with the given parameters
381  * Returns 0 on success, -1 on failure
382  */
383 int ast_context_remove_switch(char *context, char *sw, char *data, char *registrar);
384 int ast_context_remove_switch2(struct ast_context *con, char *sw, char *data, char *registrar);
385
386 //! Simply remove extension from context
387 /*!
388  * \param context context to remove extension from
389  * \param extension which extension to remove
390  * \param priority priority of extension to remove
391  * \param registrar registrar of the extension
392  * This function removes an extension from a given context.
393  * Returns 0 on success, -1 on failure
394  */
395 int ast_context_remove_extension(char *context, char *extension, int priority,
396         char *registrar);
397 int ast_context_remove_extension2(struct ast_context *con, char *extension,
398         int priority, char *registrar);
399
400 //! Add an ignorepat
401 /*!
402  * \param context which context to add the ignorpattern to
403  * \param ignorpat ignorepattern to set up for the extension
404  * \param registrar registrar of the ignore pattern
405  * Adds an ignore pattern to a particular context.
406  * Returns 0 on success, -1 on failure
407  */
408 int ast_context_add_ignorepat(char *context, char *ignorepat, char *registrar);
409 int ast_context_add_ignorepat2(struct ast_context *con, char *ignorepat, char *registrar);
410
411 /* Remove an ignorepat */
412 /*!
413  * \param context context from which to remove the pattern
414  * \param ignorepat the pattern to remove
415  * \param registrar the registrar of the ignore pattern
416  * This removes the given ignorepattern
417  * Returns 0 on success, -1 on failure
418  */
419 int ast_context_remove_ignorepat(char *context, char *ignorepat, char *registrar);
420 int ast_context_remove_ignorepat2(struct ast_context *con, char *ignorepat, char *registrar);
421
422 //! Checks to see if a number should be ignored
423 /*!
424  * \param context context to search within
425  * \param extension to check whether it should be ignored or not
426  * Check if a number should be ignored with respect to dialtone cancellation.  
427  * Returns 0 if the pattern should not be ignored, or non-zero if the pattern should be ignored 
428  */
429 int ast_ignore_pattern(char *context, char *pattern);
430
431 /* Locking functions for outer modules, especially for completion functions */
432 //! Locks the contexts
433 /*! Locks the context list
434  * Returns 0 on success, -1 on error
435  */
436 int ast_lock_contexts(void);
437
438 //! Unlocks contexts
439 /*!
440  * Returns 0 on success, -1 on failure
441  */
442 int ast_unlock_contexts(void);
443
444 //! Locks a given context
445 /*!
446  * \param con context to lock
447  * Locks the context.
448  * Returns 0 on success, -1 on failure
449  */
450 int ast_lock_context(struct ast_context *con);
451 //! Unlocks the given context
452 /*!
453  * \param con context to unlock
454  * Unlocks the given context
455  * Returns 0 on success, -1 on failure
456  */
457 int ast_unlock_context(struct ast_context *con);
458
459
460 int ast_async_goto(struct ast_channel *chan, char *context, char *exten, int priority, int needlock);
461
462 int ast_async_goto_by_name(char *chan, char *context, char *exten, int priority);
463
464 /* Synchronously or asynchronously make an outbound call and send it to a
465    particular extension */
466 int ast_pbx_outgoing_exten(char *type, int format, void *data, int timeout, char *context, char *exten, int priority, int *reason, int sync, char *callerid, char *variable );
467
468 /* Synchronously or asynchronously make an outbound call and send it to a
469    particular application with given extension */
470 int ast_pbx_outgoing_app(char *type, int format, void *data, int timeout, char *app, char *appdata, int *reason, int sync, char *callerid);
471
472 /* Functions for returning values from structures */
473 char *ast_get_context_name(struct ast_context *con);
474 char *ast_get_extension_name(struct ast_exten *exten);
475 char *ast_get_include_name(struct ast_include *include);
476 char *ast_get_ignorepat_name(struct ast_ignorepat *ip);
477 char *ast_get_switch_name(struct ast_sw *sw);
478 char *ast_get_switch_data(struct ast_sw *sw);
479
480 /* Other extension stuff */
481 int ast_get_extension_priority(struct ast_exten *exten);
482 char *ast_get_extension_app(struct ast_exten *e);
483 void *ast_get_extension_app_data(struct ast_exten *e);
484
485 /* Registrar info functions ... */
486 char *ast_get_context_registrar(struct ast_context *c);
487 char *ast_get_extension_registrar(struct ast_exten *e);
488 char *ast_get_include_registrar(struct ast_include *i);
489 char *ast_get_ignorepat_registrar(struct ast_ignorepat *ip);
490 char *ast_get_switch_registrar(struct ast_sw *sw);
491
492 /* Walking functions ... */
493 struct ast_context *ast_walk_contexts(struct ast_context *con);
494 struct ast_exten *ast_walk_context_extensions(struct ast_context *con,
495         struct ast_exten *priority);
496 struct ast_exten *ast_walk_extension_priorities(struct ast_exten *exten,
497         struct ast_exten *priority);
498 struct ast_include *ast_walk_context_includes(struct ast_context *con,
499         struct ast_include *inc);
500 struct ast_ignorepat *ast_walk_context_ignorepats(struct ast_context *con,
501         struct ast_ignorepat *ip);
502 struct ast_sw *ast_walk_context_switches(struct ast_context *con, struct ast_sw *sw);
503
504 extern char *pbx_builtin_getvar_helper(struct ast_channel *chan, char *name);
505 extern void pbx_builtin_setvar_helper(struct ast_channel *chan, char *name, char *value);
506 extern void pbx_builtin_clear_globals(void);
507
508 #if defined(__cplusplus) || defined(c_plusplus)
509 }
510 #endif
511
512
513 #endif