Version 0.1.12 from FTP
[asterisk/asterisk.git] / include / asterisk / channel.h
1 /*
2  * Asterisk -- A telephony toolkit for Linux.
3  *
4  * General Asterisk channel 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
14 #ifndef _ASTERISK_CHANNEL_H
15 #define _ASTERISK_CHANNEL_H
16
17 #include <asterisk/frame.h>
18 #include <asterisk/sched.h>
19 #include <setjmp.h>
20 #include <pthread.h>
21
22 #if defined(__cplusplus) || defined(c_plusplus)
23 extern "C" {
24 #endif
25
26 #include <asterisk/lock.h>
27
28 //! Max length of an extension
29 #define AST_MAX_EXTENSION 80
30
31 #include <asterisk/cdr.h>
32
33
34 #define AST_CHANNEL_NAME 80
35 #define AST_CHANNEL_MAX_STACK 32
36
37 #define MAX_LANGUAGE 20
38
39
40 #define AST_MAX_FDS 4
41
42 struct ast_generator {
43         void *(*alloc)(struct ast_channel *chan, void *params);
44         void (*release)(struct ast_channel *chan, void *data);
45         int (*generate)(struct ast_channel *chan, void *data, int len);
46 };
47
48 //! Main Channel structure associated with a channel.
49 /*! 
50  * This is the side of it mostly used by the pbx and call management.
51  */
52 struct ast_channel {
53         /*! ASCII Description of channel name */
54         char name[AST_CHANNEL_NAME];            
55         /*! Language requested */
56         char language[MAX_LANGUAGE];            
57         /*! Type of channel */
58         char *type;                             
59         /*! File descriptor for channel -- Drivers will poll on these file descriptors, so at least one must be non -1.  */
60         int fds[AST_MAX_FDS];                   
61
62         /*! Default music class */
63         char musicclass[MAX_LANGUAGE];
64
65         /*! Current generator data if there is any */
66         void *generatordata;
67         /*! Current active data generator */
68         struct ast_generator *generator;
69         /*! Whether or not the generator should be interrupted by write */
70         int writeinterrupt;
71
72         /*! Who are we bridged to, if we're bridged */
73         struct ast_channel *bridge;             
74         /*! Channel that will masquerade as us */
75         struct ast_channel *masq;               
76         /*! Who we are masquerading as */
77         struct ast_channel *masqr;              
78         /*! Call Detail Record Flags */
79         int cdrflags;                                                                              
80         /*! Whether or not we're blocking */
81         int blocking;                           
82         /*! Whether or not we have been hung up */
83         int softhangup;                         
84         /*! Non-zero if this is a zombie channel */
85         int zombie;                                     
86         /*! Non-zero, set to actual time when channel is to be hung up */
87         time_t  whentohangup;
88         /*! If anyone is blocking, this is them */
89         pthread_t blocker;                      
90         /*! Lock, can be used to lock a channel for some operations */
91         pthread_mutex_t lock;                   
92         /*! Procedure causing blocking */
93         char *blockproc;                        
94
95         /*! Current application */
96         char *appl;                             
97         /*! Data passed to current application */
98         char *data;                             
99         
100         /*! Has an exception been detected */
101         int exception;                          
102         /*! Which fd had an event detected on */
103         int fdno;                               
104         /*! Schedule context */
105         struct sched_context *sched;            
106         /*! For streaming playback, the schedule ID */
107         int streamid;                           
108         /*! Stream itself. */
109         struct ast_filestream *stream;          
110         /*! Original writer format */
111         int oldwriteformat;                     
112
113
114         /*! State of line */
115         int state;                              
116         /*! Number of rings so far */
117         int rings;                              
118         /*! Current level of application */
119         int stack;                              
120
121
122         /*! Kinds of data this channel can natively handle */
123         int nativeformats;                      
124         /*! Requested read format */
125         int readformat;                         
126         /*! Requested write format */
127         int writeformat;                        
128
129         
130         /*! Malloc'd Dialed Number Identifier */
131         char *dnid;                             
132         /*! Malloc'd Caller ID */
133         char *callerid;                         
134         /*! Malloc'd ANI */
135         char *ani;                      
136
137         
138         /*! Current extension context */
139         char context[AST_MAX_EXTENSION];        
140         /*! Current extension number */
141         char exten[AST_MAX_EXTENSION];          
142         /* Current extension priority */
143         int priority;                                           
144         /*! Application information -- see assigned numbers */
145         void *app[AST_CHANNEL_MAX_STACK];       
146         /*! Any/all queued DTMF characters */
147         char dtmfq[AST_MAX_EXTENSION];          
148         /*! Are DTMF digits being deferred */
149         int deferdtmf;                          
150         /*! DTMF frame */
151         struct ast_frame dtmff;                 
152         /*! Private channel implementation details */
153         struct ast_channel_pvt *pvt;
154
155                                                 
156         /*! Jump buffer used for returning from applications */
157         jmp_buf jmp[AST_CHANNEL_MAX_STACK];     
158
159         struct ast_pbx *pbx;
160         /*! Set BEFORE PBX is started to determine AMA flags */
161         int     amaflags;                       
162         /*! Account code for billing */
163         char    accountcode[20];                
164         /*! Call Detail Record */
165         struct ast_cdr *cdr;                    
166         /*! Whether or not ADSI is detected on CPE */
167         int     adsicpe;
168         /*! Where to forward to if asked to dial on this interface */
169         char call_forward[AST_MAX_EXTENSION];
170         /*! For easy linking */
171         struct ast_channel *next;               
172
173 };
174
175 #define AST_CDR_TRANSFER        (1 << 0)
176 #define AST_CDR_FORWARD         (1 << 1)
177 #define AST_CDR_CALLWAIT        (1 << 2)
178 #define AST_CDR_CONFERENCE      (1 << 3)
179
180 #define AST_ADSI_UNKNOWN        (0)
181 #define AST_ADSI_AVAILABLE      (1)
182 #define AST_ADSI_UNAVAILABLE    (2)
183 #define AST_ADSI_OFFHOOKONLY    (3)
184
185 /* Bits 0-15 of state are reserved for the state (up/down) of the line */
186 /*! Channel is down and available */
187 #define AST_STATE_DOWN          0               
188 /*! Channel is down, but reserved */
189 #define AST_STATE_RESERVED      1               
190 /*! Channel is off hook */
191 #define AST_STATE_OFFHOOK       2               
192 /*! Digits (or equivalent) have been dialed */
193 #define AST_STATE_DIALING       3               
194 /*! Line is ringing */
195 #define AST_STATE_RING          4               
196 /*! Remote end is ringing */
197 #define AST_STATE_RINGING       5               
198 /*! Line is up */
199 #define AST_STATE_UP            6               
200 /*! Line is busy */
201 #define AST_STATE_BUSY          7               
202
203 /* Bits 16-32 of state are reserved for flags */
204 /*! Do not transmit voice data */
205 #define AST_STATE_MUTE          (1 << 16)       
206
207 //! Requests a channel
208 /*! 
209  * \param type type of channel to request
210  * \param format requested channel format
211  * \param data data to pass to the channel requester
212  * Request a channel of a given type, with data as optional information used 
213  * by the low level module
214  * Returns an ast_channel on success, NULL on failure.
215  */
216 struct ast_channel *ast_request(char *type, int format, void *data);
217
218 //! Registers a channel
219 /*! 
220  * \param type type of channel you are registering
221  * \param description short description of the channel
222  * \param capabilities a bit mask of the capabilities of the channel
223  * \param requester a function pointer that properly responds to a call.  See one of the channel drivers for details.
224  * Called by a channel module to register the kind of channels it supports.
225  * It supplies a brief type, a longer, but still short description, and a
226  * routine that creates a channel
227  * Returns 0 on success, -1 on failure.
228  */
229 int ast_channel_register(char *type, char *description, int capabilities, 
230                         struct ast_channel* (*requester)(char *type, int format, void *data));
231
232 //! Unregister a channel class
233 /*
234  * \param type the character string that corresponds to the channel you wish to unregister
235  * Basically just unregisters the channel with the asterisk channel system
236  * No return value.
237  */
238 void ast_channel_unregister(char *type);
239
240 //! Hang up a channel 
241 /*! 
242  * \param chan channel to hang up
243  * This function performs a hard hangup on a channel.  Unlike the soft-hangup, this function
244  * performs all stream stopping, etc, on the channel that needs to end.
245  * chan is no longer valid after this call.
246  * Returns 0 on success, -1 on failure.
247  */
248 int ast_hangup(struct ast_channel *chan);
249
250 //! Softly hangup up a channel
251 /*! 
252  * \param chan channel to be soft-hung-up
253  * Call the protocol layer, but don't destroy the channel structure (use this if you are trying to
254  * safely hangup a channel managed by another thread.
255  * Returns 0 regardless
256  */
257 int ast_softhangup(struct ast_channel *chan);
258
259 //! Check to see if a channel is needing hang up
260 /*! 
261  * \param chan channel on which to check for hang up
262  * This function determines if the channel is being requested to be hung up.
263  * Returns 0 if not, or 1 if hang up is requested (including time-out).
264  */
265 int ast_check_hangup(struct ast_channel *chan);
266
267 //! Set when to hang a channel up
268 /*! 
269  * \param chan channel on which to check for hang up
270  * \param offset offset in seconds from current time of when to hang up
271  * This function sets the absolute time out on a channel (when to hang up).
272  */
273 void ast_channel_setwhentohangup(struct ast_channel *chan, time_t offset);
274
275 //! Answer a ringing call
276 /*!
277  * \param chan channel to answer
278  * This function answers a channel and handles all necessary call
279  * setup functions.
280  * Returns 0 on success, -1 on failure
281  */
282 int ast_answer(struct ast_channel *chan);
283
284 //! Make a call
285 /*! 
286  * \param chan which channel to make the call on
287  * \param addr destination of the call
288  * \param timeout time to wait on for connect
289  * Place a call, take no longer than timeout ms.  Returns -1 on failure, 
290    0 on not enough time (does not auto matically stop ringing), and  
291    the number of seconds the connect took otherwise.
292    Returns 0 on success, -1 on failure
293    */
294 int ast_call(struct ast_channel *chan, char *addr, int timeout);
295
296 //! Indicates condition of channel
297 /*! 
298  * \param chan channel to change the indication
299  * \param condition which condition to indicate on the channel
300  * Indicate a condition such as AST_CONTROL_BUSY, AST_CONTROL_RINGING, or AST_CONTROL_CONGESTION on a channel
301  * Returns 0 on success, -1 on failure
302  */
303 int ast_indicate(struct ast_channel *chan, int condition);
304
305 /* Misc stuff */
306
307 //! Wait for input on a channel
308 /*! 
309  * \param chan channel to wait on
310  * \param ms length of time to wait on the channel
311  * Wait for input on a channel for a given # of milliseconds (<0 for indefinite). 
312   Returns < 0 on  failure, 0 if nothing ever arrived, and the # of ms remaining otherwise */
313 int ast_waitfor(struct ast_channel *chan, int ms);
314
315 //! Wait for a specied amount of time, looking for hangups
316 /*!
317  * \param chan channel to wait for
318  * \param ms length of time in milliseconds to sleep
319  * Waits for a specified amount of time, servicing the channel as required.
320  * returns -1 on hangup, otherwise 0.
321  */
322 int ast_safe_sleep(struct ast_channel *chan, int ms);
323
324 //! Waits for activity on a group of channels
325 /*! 
326  * \param chan an array of pointers to channels
327  * \param n number of channels that are to be waited upon
328  * \param fds an array of fds to wait upon
329  * \param nfds the number of fds to wait upon
330  * \param exception exception flag
331  * \param outfd fd that had activity on it
332  * \param ms how long the wait was
333  * Big momma function here.  Wait for activity on any of the n channels, or any of the nfds
334    file descriptors.  Returns the channel with activity, or NULL on error or if an FD
335    came first.  If the FD came first, it will be returned in outfd, otherwise, outfd
336    will be -1 */
337 struct ast_channel *ast_waitfor_nandfds(struct ast_channel **chan, int n, int *fds, int nfds, int *exception, int *outfd, int *ms);
338
339 //! Waits for input on a group of channels
340 /*! Wait for input on an array of channels for a given # of milliseconds. Return channel
341    with activity, or NULL if none has activity.  time "ms" is modified in-place, if applicable */
342 struct ast_channel *ast_waitfor_n(struct ast_channel **chan, int n, int *ms);
343
344 //! Waits for input on an fd
345 /*! This version works on fd's only.  Be careful with it. */
346 int ast_waitfor_n_fd(int *fds, int n, int *ms, int *exception);
347
348
349 //! Reads a frame
350 /*! 
351  * \param chan channel to read a frame from
352  * Read a frame.  Returns a frame, or NULL on error.  If it returns NULL, you
353    best just stop reading frames and assume the channel has been
354    disconnected. */
355 struct ast_frame *ast_read(struct ast_channel *chan);
356
357 //! Write a frame to a channel
358 /*!
359  * \param chan destination channel of the frame
360  * \param frame frame that will be written
361  * This function writes the given frame to the indicated channel.
362  * It returns 0 on success, -1 on failure.
363  */
364 int ast_write(struct ast_channel *chan, struct ast_frame *frame);
365
366 //! Sets read format on channel chan
367 /*! 
368  * \param chan channel to change
369  * \param format format to change to
370  * Set read format for channel to whichever component of "format" is best. 
371  * Returns 0 on success, -1 on failure
372  */
373 int ast_set_read_format(struct ast_channel *chan, int format);
374
375 //! Sets write format on channel chan
376 /*! 
377  * \param chan channel to change
378  * \param format new format for writing
379  * Set write format for channel to whichever compoent of "format" is best. 
380  * Returns 0 on success, -1 on failure
381  */
382 int ast_set_write_format(struct ast_channel *chan, int format);
383
384 //! Sends text to a channel
385 /*! 
386  * \param chan channel to act upon
387  * \param text string of text to send on the channel
388  * Write text to a display on a channel
389  * Returns 0 on success, -1 on failure
390  */
391 int ast_sendtext(struct ast_channel *chan, char *text);
392
393 //! Receives a text character from a channel
394 /*! 
395  * \param chan channel to act upon
396  * \param timeout timeout in milliseconds (0 for infinite wait)
397  * Read a char of text from a channel
398  * Returns 0 on success, -1 on failure
399  */
400 int ast_recvchar(struct ast_channel *chan, int timeout);
401
402 //! Browse channels in use
403 /*! 
404  * \param prev where you want to start in the channel list
405  * Browse the channels currently in use 
406  * Returns the next channel in the list, NULL on end.
407  */
408 struct ast_channel *ast_channel_walk(struct ast_channel *prev);
409
410 //! Waits for a digit
411 /*! 
412  * \param c channel to wait for a digit on
413  * \param ms how many milliseconds to wait
414  * Wait for a digit.  Returns <0 on error, 0 on no entry, and the digit on success. */
415 char ast_waitfordigit(struct ast_channel *c, int ms);
416
417 //! Reads multiple digits
418 /*! 
419  * \param c channel to read from
420  * \param s string to read in to.  Must be at least the size of your length
421  * \param len how many digits to read (maximum)
422  * \param timeout how long to timeout between digits
423  * \param rtimeout timeout to wait on the first digit
424  * \param enders digits to end the string
425  * Read in a digit string "s", max length "len", maximum timeout between 
426    digits "timeout" (-1 for none), terminated by anything in "enders".  Give them rtimeout
427    for the first digit.  Returns 0 on normal return, or 1 on a timeout.  In the case of
428    a timeout, any digits that were read before the timeout will still be available in s.  */
429 int ast_readstring(struct ast_channel *c, char *s, int len, int timeout, int rtimeout, char *enders);
430
431 /*! Report DTMF on channel 0 */
432 #define AST_BRIDGE_DTMF_CHANNEL_0               (1 << 0)                
433 /*! Report DTMF on channel 1 */
434 #define AST_BRIDGE_DTMF_CHANNEL_1               (1 << 1)                
435 /*! Return all voice frames on channel 0 */
436 #define AST_BRIDGE_REC_CHANNEL_0                (1 << 2)                
437 /*! Return all voice frames on channel 1 */
438 #define AST_BRIDGE_REC_CHANNEL_1                (1 << 3)                
439 /*! Ignore all signal frames except NULL */
440 #define AST_BRIDGE_IGNORE_SIGS                  (1 << 4)                
441
442
443 //! Makes two channel formats compatible
444 /*! 
445  * \param c0 first channel to make compatible
446  * \param c1 other channel to make compatible
447  * Set two channels to compatible formats -- call before ast_channel_bridge in general .  Returns 0 on success
448    and -1 if it could not be done */
449 int ast_channel_make_compatible(struct ast_channel *c0, struct ast_channel *c1);
450
451 //! Bridge two channels together
452 /*! 
453  * \param c0 first channel to bridge
454  * \param c1 second channel to bridge
455  * \param flags for the channels
456  * \param fo destination frame(?)
457  * \param rc destination channel(?)
458  * Bridge two channels (c0 and c1) together.  If an important frame occurs, we return that frame in
459    *rf (remember, it could be NULL) and which channel (0 or 1) in rc */
460 int ast_channel_bridge(struct ast_channel *c0, struct ast_channel *c1, int flags, struct ast_frame **fo, struct ast_channel **rc);
461
462 //! Weird function made for call transfers
463 /*! 
464  * \param original channel to make a copy of
465  * \param clone copy of the original channel
466  * This is a very strange and freaky function used primarily for transfer.  Suppose that
467    "original" and "clone" are two channels in random situations.  This function takes
468    the guts out of "clone" and puts them into the "original" channel, then alerts the
469    channel driver of the change, asking it to fixup any private information (like the
470    p->owner pointer) that is affected by the change.  The physical layer of the original
471    channel is hung up.  */
472 int ast_channel_masquerade(struct ast_channel *original, struct ast_channel *clone);
473
474 //! Gives the string form of a given state
475 /*! 
476  * \param state state to get the name of
477  * Give a name to a state 
478  * Pretty self explanatory.
479  * Returns the text form of the binary state given
480  */
481 char *ast_state2str(int state);
482
483 /* Options: Some low-level drivers may implement "options" allowing fine tuning of the
484    low level channel.  See frame.h for options.  Note that many channel drivers may support
485    none or a subset of those features, and you should not count on this if you want your
486    asterisk application to be portable.  They're mainly useful for tweaking performance */
487
488 //! Sets an option on a channel
489 /*! 
490  * \param channel channel to set options on
491  * \param option option to change
492  * \param data data specific to option
493  * \param datalen length of the data
494  * \param block blocking or not
495  * Set an option on a channel (see frame.h), optionally blocking awaiting the reply 
496  * Returns 0 on success and -1 on failure
497  */
498 int ast_channel_setoption(struct ast_channel *channel, int option, void *data, int datalen, int block);
499
500 //! Checks the value of an option
501 /*! 
502  * Query the value of an option, optionally blocking until a reply is received
503  * Works similarly to setoption except only reads the options.
504  */
505 struct ast_frame *ast_channel_queryoption(struct ast_channel *channel, int option, void *data, int *datalen, int block);
506
507 //! Checks for HTML support on a channel
508 /*! Returns 0 if channel does not support HTML or non-zero if it does */
509 int ast_channel_supports_html(struct ast_channel *channel);
510
511 //! Sends HTML on given channel
512 /*! Send HTML or URL on link.  Returns 0 on success or -1 on failure */
513 int ast_channel_sendhtml(struct ast_channel *channel, int subclass, char *data, int datalen);
514
515 //! Sends a URL on a given link
516 /*! Send URL on link.  Returns 0 on success or -1 on failure */
517 int ast_channel_sendurl(struct ast_channel *channel, char *url);
518
519 //! Defers DTMF
520 /*! Defer DTMF so that you only read things like hangups and audio.  Returns
521    non-zero if channel was already DTMF-deferred or 0 if channel is just now
522    being DTMF-deferred */
523 int ast_channel_defer_dtmf(struct ast_channel *chan);
524
525 //! Undeos a defer
526 /*! Undo defer.  ast_read will return any dtmf characters that were queued */
527 void ast_channel_undefer_dtmf(struct ast_channel *chan);
528
529 /*! Initiate system shutdown -- prevents new channels from being allocated.
530     If "hangup" is non-zero, all existing channels will receive soft
531      hangups */
532 void ast_begin_shutdown(int hangup);
533
534 /*! Cancels an existing shutdown and returns to normal operation */
535 void ast_cancel_shutdown(void);
536
537 /*! Returns number of active/allocated channels */
538 int ast_active_channels(void);
539
540 /*! Returns non-zero if Asterisk is being shut down */
541 int ast_shutting_down(void);
542
543 /*! Activate a given generator */
544 int ast_activate_generator(struct ast_channel *chan, struct ast_generator *gen, void *params);
545
546 /*! Deactive an active generator */
547 void ast_deactivate_generator(struct ast_channel *chan);
548
549 /*! Start a tone going */
550 int ast_tonepair_start(struct ast_channel *chan, int freq1, int freq2, int duration, int vol);
551 /*! Stop a tone from playing */
552 void ast_tonepair_stop(struct ast_channel *chan);
553 /*! Play a tone pair for a given amount of time */
554 int ast_tonepair(struct ast_channel *chan, int freq1, int freq2, int duration, int vol);
555
556 #ifdef DO_CRASH
557 #define CRASH do { *((int *)0) = 0; } while(0)
558 #else
559 #define CRASH do { } while(0)
560 #endif
561
562 #define CHECK_BLOCKING(c) {      \
563                                                         if ((c)->blocking) {\
564                                                                 ast_log(LOG_WARNING, "Thread %ld Blocking '%s', already blocked by thread %ld in procedure %s\n", pthread_self(), (c)->name, (c)->blocker, (c)->blockproc); \
565                                                                 CRASH; \
566                                                         } else { \
567                                                                 (c)->blocker = pthread_self(); \
568                                                                 (c)->blockproc = __PRETTY_FUNCTION__; \
569                                                                         c->blocking = -1; \
570                                                                         } }
571
572 #if defined(__cplusplus) || defined(c_plusplus)
573 }
574 #endif
575
576
577 #endif