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