Merge enhanced status changes, add SIP subscribe from Andre
[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_state_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 fmt devicename like a dialstring with format parameters
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(const char *fmt, ...)
224         __attribute__ ((format (printf, 1, 2)));
225
226 //! Registers a state change callback
227 /*!
228  * \param context which context to look in
229  * \param exten which extension to get state
230  * \param callback callback to call if state changed
231  * \param data to pass to callback
232  * The callback is called if the state for extension is changed
233  * Return -1 on failure, ID on success
234  */ 
235 int ast_extension_state_add(char *context, char *exten, 
236                             ast_state_cb_type callback, void *data);
237
238 //! Deletes a registered state change callback by ID
239 /*!
240  * \param id of the callback to delete
241  * Removes the callback from list of callbacks
242  * Return 0 on success, -1 on failure
243  */
244 int ast_extension_state_del(int id, ast_state_cb_type callback);
245
246 //! If an extension exists, return non-zero
247 /*!
248  * \param hint buffer for hint
249  * \param maxlen size of hint buffer
250  * \param c this is not important
251  * \param context which context to look in
252  * \param exten which extension to search for
253  * If an extension within the given context with the priority PRIORITY_HINT
254  * is found a non zero value will be returned.
255  * Otherwise, 0 is returned.
256  */
257 int ast_get_hint(char *hint, int maxlen, struct ast_channel *c, char *context, char *exten);
258
259 //! If an extension exists, return non-zero
260 // work
261 /*!
262  * \param c this is not important
263  * \param context which context to look in
264  * \param exten which extension to search for
265  * \param priority priority of the action within the extension
266  * \param callerid callerid to search for
267  * If an extension within the given context(or callerid) with the given priority is found a non zero value will be returned.
268  * Otherwise, 0 is returned.
269  */
270 int ast_exists_extension(struct ast_channel *c, char *context, char *exten, int priority, char *callerid);
271
272 //! Looks for a valid matching extension
273 /*!
274   \param c not really important
275   \param context context to serach within
276   \param exten extension to check
277   \param priority priority of extension path
278   \param callerid callerid of extension being searched for
279    If "exten" *could be* a valid extension in this context with or without
280    some more digits, return non-zero.  Basically, when this returns 0, no matter
281    what you add to exten, it's not going to be a valid extension anymore
282 */
283 int ast_canmatch_extension(struct ast_channel *c, char *context, char *exten, int priority, char *callerid);
284
285 //! Looks to see if adding anything to this extension might match something. (exists ^ canmatch)
286 /*!
287   \param c not really important
288   \param context context to serach within
289   \param exten extension to check
290   \param priority priority of extension path
291   \param callerid callerid of extension being searched for
292    If "exten" *could match* a valid extension in this context with
293    some more digits, return non-zero.  Does NOT return non-zero if this is
294    an exact-match only.  Basically, when this returns 0, no matter
295    what you add to exten, it's not going to be a valid extension anymore
296 */
297 int ast_matchmore_extension(struct ast_channel *c, char *context, char *exten, int priority, char *callerid);
298
299 //! Determine if a given extension matches a given pattern (in NXX format)
300 /*!
301  * \param pattern pattern to match
302  * \param extension extension to check against the pattern.
303  * Checks whether or not the given extension matches the given pattern.
304  * Returns 1 on match, 0 on failure
305  */
306 int ast_extension_match(char *pattern, char *extension);
307
308 //! Launch a new extension (i.e. new stack)
309 /*!
310  * \param c not important
311  * \param context which context to generate the extension within
312  * \param exten new extension to add
313  * \param priority priority of new extension
314  * \param callerid callerid of extension
315  * This adds a new extension to the asterisk extension list.
316  * It returns 0 on success, -1 on failure.
317  */
318 int ast_spawn_extension(struct ast_channel *c, char *context, char *exten, int priority, char *callerid);
319
320 //! Execute an extension.
321 /*!
322   \param c channel to execute upon
323   \param context which context extension is in
324   \param exten extension to execute
325   \param priority priority to execute within the given extension
326    If it's not available, do whatever you should do for
327    default extensions and halt the thread if necessary.  This function does not
328    return, except on error.
329 */
330 int ast_exec_extension(struct ast_channel *c, char *context, char *exten, int priority, char *callerid);
331
332 //! Add an include
333 /*!
334   \param context context to add include to
335   \param include new include to add
336   \param registrar who's registering it
337    Adds an include taking a char * string as the context parameter
338    Returns 0 on success, -1 on error
339 */
340 int ast_context_add_include(char *context, char *include, char *registrar);
341
342 //! Add an include
343 /*!
344   \param con context to add the include to
345   \param include include to add
346   \param registrar who registered the context
347    Adds an include taking a struct ast_context as the first parameter
348    Returns 0 on success, -1 on failure
349 */
350 int ast_context_add_include2(struct ast_context *con, char *include, char *registrar);
351
352 //! Removes an include
353 /*!
354  * See add_include
355  */
356 int ast_context_remove_include(char *context, char *include, char *registrar);
357 //! Removes an include by an ast_context structure
358 /*!
359  * See add_include2
360  */
361 int ast_context_remove_include2(struct ast_context *con, char *include, char *registrar);
362
363 //! Add a switch
364 /*!
365  * \param context context to which to add the switch
366  * \param sw switch to add
367  * \param data data to pass to switch
368  * \param registrar whoever registered the switch
369  * This function registers a switch with the asterisk switch architecture
370  * It returns 0 on success, -1 on failure
371  */
372 int ast_context_add_switch(char *context, char *sw, char *data, char *registrar);
373 //! Adds a switch (first param is a ast_context)
374 /*!
375  * See ast_context_add_switch()
376  */
377 int ast_context_add_switch2(struct ast_context *con, char *sw, char *data, char *registrar);
378
379 //! Remove a switch
380 /*!
381  * Removes a switch with the given parameters
382  * Returns 0 on success, -1 on failure
383  */
384 int ast_context_remove_switch(char *context, char *sw, char *data, char *registrar);
385 int ast_context_remove_switch2(struct ast_context *con, char *sw, char *data, char *registrar);
386
387 //! Simply remove extension from context
388 /*!
389  * \param context context to remove extension from
390  * \param extension which extension to remove
391  * \param priority priority of extension to remove
392  * \param registrar registrar of the extension
393  * This function removes an extension from a given context.
394  * Returns 0 on success, -1 on failure
395  */
396 int ast_context_remove_extension(char *context, char *extension, int priority,
397         char *registrar);
398 int ast_context_remove_extension2(struct ast_context *con, char *extension,
399         int priority, char *registrar);
400
401 //! Add an ignorepat
402 /*!
403  * \param context which context to add the ignorpattern to
404  * \param ignorpat ignorepattern to set up for the extension
405  * \param registrar registrar of the ignore pattern
406  * Adds an ignore pattern to a particular context.
407  * Returns 0 on success, -1 on failure
408  */
409 int ast_context_add_ignorepat(char *context, char *ignorepat, char *registrar);
410 int ast_context_add_ignorepat2(struct ast_context *con, char *ignorepat, char *registrar);
411
412 /* Remove an ignorepat */
413 /*!
414  * \param context context from which to remove the pattern
415  * \param ignorepat the pattern to remove
416  * \param registrar the registrar of the ignore pattern
417  * This removes the given ignorepattern
418  * Returns 0 on success, -1 on failure
419  */
420 int ast_context_remove_ignorepat(char *context, char *ignorepat, char *registrar);
421 int ast_context_remove_ignorepat2(struct ast_context *con, char *ignorepat, char *registrar);
422
423 //! Checks to see if a number should be ignored
424 /*!
425  * \param context context to search within
426  * \param extension to check whether it should be ignored or not
427  * Check if a number should be ignored with respect to dialtone cancellation.  
428  * Returns 0 if the pattern should not be ignored, or non-zero if the pattern should be ignored 
429  */
430 int ast_ignore_pattern(char *context, char *pattern);
431
432 /* Locking functions for outer modules, especially for completion functions */
433 //! Locks the contexts
434 /*! Locks the context list
435  * Returns 0 on success, -1 on error
436  */
437 int ast_lock_contexts(void);
438
439 //! Unlocks contexts
440 /*!
441  * Returns 0 on success, -1 on failure
442  */
443 int ast_unlock_contexts(void);
444
445 //! Locks a given context
446 /*!
447  * \param con context to lock
448  * Locks the context.
449  * Returns 0 on success, -1 on failure
450  */
451 int ast_lock_context(struct ast_context *con);
452 //! Unlocks the given context
453 /*!
454  * \param con context to unlock
455  * Unlocks the given context
456  * Returns 0 on success, -1 on failure
457  */
458 int ast_unlock_context(struct ast_context *con);
459
460
461 int ast_async_goto(struct ast_channel *chan, char *context, char *exten, int priority, int needlock);
462
463 int ast_async_goto_by_name(char *chan, char *context, char *exten, int priority);
464
465 /* Synchronously or asynchronously make an outbound call and send it to a
466    particular extension */
467 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 );
468
469 /* Synchronously or asynchronously make an outbound call and send it to a
470    particular application with given extension */
471 int ast_pbx_outgoing_app(char *type, int format, void *data, int timeout, char *app, char *appdata, int *reason, int sync, char *callerid);
472
473 /* Functions for returning values from structures */
474 char *ast_get_context_name(struct ast_context *con);
475 char *ast_get_extension_name(struct ast_exten *exten);
476 char *ast_get_include_name(struct ast_include *include);
477 char *ast_get_ignorepat_name(struct ast_ignorepat *ip);
478 char *ast_get_switch_name(struct ast_sw *sw);
479 char *ast_get_switch_data(struct ast_sw *sw);
480
481 /* Other extension stuff */
482 int ast_get_extension_priority(struct ast_exten *exten);
483 char *ast_get_extension_app(struct ast_exten *e);
484 void *ast_get_extension_app_data(struct ast_exten *e);
485
486 /* Registrar info functions ... */
487 char *ast_get_context_registrar(struct ast_context *c);
488 char *ast_get_extension_registrar(struct ast_exten *e);
489 char *ast_get_include_registrar(struct ast_include *i);
490 char *ast_get_ignorepat_registrar(struct ast_ignorepat *ip);
491 char *ast_get_switch_registrar(struct ast_sw *sw);
492
493 /* Walking functions ... */
494 struct ast_context *ast_walk_contexts(struct ast_context *con);
495 struct ast_exten *ast_walk_context_extensions(struct ast_context *con,
496         struct ast_exten *priority);
497 struct ast_exten *ast_walk_extension_priorities(struct ast_exten *exten,
498         struct ast_exten *priority);
499 struct ast_include *ast_walk_context_includes(struct ast_context *con,
500         struct ast_include *inc);
501 struct ast_ignorepat *ast_walk_context_ignorepats(struct ast_context *con,
502         struct ast_ignorepat *ip);
503 struct ast_sw *ast_walk_context_switches(struct ast_context *con, struct ast_sw *sw);
504
505 extern char *pbx_builtin_getvar_helper(struct ast_channel *chan, char *name);
506 extern void pbx_builtin_setvar_helper(struct ast_channel *chan, char *name, char *value);
507 extern void pbx_builtin_clear_globals(void);
508
509 #if defined(__cplusplus) || defined(c_plusplus)
510 }
511 #endif
512
513
514 #endif