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