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