More BSD enhancements
[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 <asterisk/chanvars.h>
20 #include <setjmp.h>
21 #include <pthread.h>
22
23 #if defined(__cplusplus) || defined(c_plusplus)
24 extern "C" {
25 #endif
26
27 #include <asterisk/lock.h>
28
29 //! Max length of an extension
30 #define AST_MAX_EXTENSION 80
31
32 #include <asterisk/cdr.h>
33 #include <asterisk/monitor.h>
34
35
36 #define AST_CHANNEL_NAME 80
37 #define AST_CHANNEL_MAX_STACK 32
38
39 #define MAX_LANGUAGE 20
40
41
42 #define AST_MAX_FDS 4
43
44 struct ast_generator {
45         void *(*alloc)(struct ast_channel *chan, void *params);
46         void (*release)(struct ast_channel *chan, void *data);
47         int (*generate)(struct ast_channel *chan, void *data, int len, int samples);
48 };
49
50 //! Main Channel structure associated with a channel.
51 /*! 
52  * This is the side of it mostly used by the pbx and call management.
53  */
54 struct ast_channel {
55         /*! ASCII Description of channel name */
56         char name[AST_CHANNEL_NAME];            
57         /*! Language requested */
58         char language[MAX_LANGUAGE];            
59         /*! Type of channel */
60         char *type;                             
61         /*! File descriptor for channel -- Drivers will poll on these file descriptors, so at least one must be non -1.  */
62         int fds[AST_MAX_FDS];                   
63
64         /*! Default music class */
65         char musicclass[MAX_LANGUAGE];
66
67         /*! Current generator data if there is any */
68         void *generatordata;
69         /*! Current active data generator */
70         struct ast_generator *generator;
71         /*! Whether or not the generator should be interrupted by write */
72         int writeinterrupt;
73
74         /*! Who are we bridged to, if we're bridged */
75         struct ast_channel *bridge;             
76         /*! Channel that will masquerade as us */
77         struct ast_channel *masq;               
78         /*! Who we are masquerading as */
79         struct ast_channel *masqr;              
80         /*! Call Detail Record Flags */
81         int cdrflags;                                                                              
82         /*! Whether or not we're blocking */
83         int blocking;                           
84         /*! Whether or not we have been hung up...  Do not set this value
85             directly, use ast_softhangup */
86         int _softhangup;                                
87         /*! Non-zero if this is a zombie channel */
88         int zombie;                                     
89         /*! Non-zero, set to actual time when channel is to be hung up */
90         time_t  whentohangup;
91         /*! If anyone is blocking, this is them */
92         pthread_t blocker;                      
93         /*! Lock, can be used to lock a channel for some operations */
94         pthread_mutex_t lock;                   
95         /*! Procedure causing blocking */
96         char *blockproc;                        
97
98         /*! Current application */
99         char *appl;                             
100         /*! Data passed to current application */
101         char *data;                             
102         
103         /*! Has an exception been detected */
104         int exception;                          
105         /*! Which fd had an event detected on */
106         int fdno;                               
107         /*! Schedule context */
108         struct sched_context *sched;            
109         /*! For streaming playback, the schedule ID */
110         int streamid;                           
111         /*! Stream itself. */
112         struct ast_filestream *stream;          
113         /*! Original writer format */
114         int oldwriteformat;                     
115
116
117         /*! State of line -- Don't write directly, use ast_setstate */
118         int _state;                             
119         /*! Number of rings so far */
120         int rings;                              
121         /*! Current level of application */
122         int stack;                              
123
124
125         /*! Kinds of data this channel can natively handle */
126         int nativeformats;                      
127         /*! Requested read format */
128         int readformat;                         
129         /*! Requested write format */
130         int writeformat;                        
131
132         
133         /*! Malloc'd Dialed Number Identifier */
134         char *dnid;                             
135         /*! Malloc'd Caller ID */
136         char *callerid;                         
137         /*! Malloc'd ANI */
138         char *ani;                      
139         /*! Malloc'd RDNIS */
140         char *rdnis;
141
142         
143         /*! Current extension context */
144         char context[AST_MAX_EXTENSION];        
145         /*! Current non-macro context */
146         char macrocontext[AST_MAX_EXTENSION];   
147         /*! Current extension number */
148         char exten[AST_MAX_EXTENSION];          
149         /* Current extension priority */
150         int priority;                                           
151         /*! Application information -- see assigned numbers */
152         void *app[AST_CHANNEL_MAX_STACK];       
153         /*! Any/all queued DTMF characters */
154         char dtmfq[AST_MAX_EXTENSION];          
155         /*! Are DTMF digits being deferred */
156         int deferdtmf;                          
157         /*! DTMF frame */
158         struct ast_frame dtmff;                 
159         /*! Private channel implementation details */
160         struct ast_channel_pvt *pvt;
161
162                                                 
163         /*! Jump buffer used for returning from applications */
164         jmp_buf jmp[AST_CHANNEL_MAX_STACK];     
165
166         struct ast_pbx *pbx;
167         /*! Set BEFORE PBX is started to determine AMA flags */
168         int     amaflags;                       
169         /*! Account code for billing */
170         char    accountcode[20];                
171         /*! Call Detail Record */
172         struct ast_cdr *cdr;                    
173         /*! Whether or not ADSI is detected on CPE */
174         int     adsicpe;
175         /*! Where to forward to if asked to dial on this interface */
176         char call_forward[AST_MAX_EXTENSION];
177
178         /*! Tone zone */
179         struct tone_zone *zone;
180
181         /* Channel monitoring */
182         struct ast_channel_monitor *monitor;
183
184         /* Frames in/out counters */
185         unsigned int fin;
186         unsigned int fout;
187
188         /* A linked list for variables */
189         struct ast_var_t *vars; 
190         AST_LIST_HEAD(varshead,ast_var_t) varshead;
191
192         unsigned int callgroup;
193         unsigned int pickupgroup;
194         
195         /*! For easy linking */
196         struct ast_channel *next;               
197
198 };
199
200 struct chanmon;
201
202 #define AST_CDR_TRANSFER        (1 << 0)
203 #define AST_CDR_FORWARD         (1 << 1)
204 #define AST_CDR_CALLWAIT        (1 << 2)
205 #define AST_CDR_CONFERENCE      (1 << 3)
206
207 #define AST_ADSI_UNKNOWN        (0)
208 #define AST_ADSI_AVAILABLE      (1)
209 #define AST_ADSI_UNAVAILABLE    (2)
210 #define AST_ADSI_OFFHOOKONLY    (3)
211
212 #define AST_SOFTHANGUP_DEV                      (1 << 0)        /* Soft hangup by device */
213 #define AST_SOFTHANGUP_ASYNCGOTO        (1 << 1)        /* Soft hangup for async goto */
214 #define AST_SOFTHANGUP_SHUTDOWN         (1 << 2)
215 #define AST_SOFTHANGUP_TIMEOUT          (1 << 3)
216 #define AST_SOFTHANGUP_APPUNLOAD        (1 << 4)
217 #define AST_SOFTHANGUP_EXPLICIT         (1 << 5)
218
219 /* Bits 0-15 of state are reserved for the state (up/down) of the line */
220 /*! Channel is down and available */
221 #define AST_STATE_DOWN          0               
222 /*! Channel is down, but reserved */
223 #define AST_STATE_RESERVED      1               
224 /*! Channel is off hook */
225 #define AST_STATE_OFFHOOK       2               
226 /*! Digits (or equivalent) have been dialed */
227 #define AST_STATE_DIALING       3               
228 /*! Line is ringing */
229 #define AST_STATE_RING          4               
230 /*! Remote end is ringing */
231 #define AST_STATE_RINGING       5               
232 /*! Line is up */
233 #define AST_STATE_UP            6               
234 /*! Line is busy */
235 #define AST_STATE_BUSY          7               
236
237 /* Bits 16-32 of state are reserved for flags */
238 /*! Do not transmit voice data */
239 #define AST_STATE_MUTE          (1 << 16)       
240
241 /*! Device is valid but channel didn't know state */
242 #define AST_DEVICE_UNKNOWN      0
243 /*! Device is not used */
244 #define AST_DEVICE_NOT_INUSE    1
245 /*! Device is in use */
246 #define AST_DEVICE_INUSE        2
247 /*! Device is busy */
248 #define AST_DEVICE_BUSY         3
249 /*! Device is invalid */
250 #define AST_DEVICE_INVALID      4
251 /*! Device is unavailable */
252 #define AST_DEVICE_UNAVAILABLE  5
253
254 //! Requests a channel
255 /*! 
256  * \param type type of channel to request
257  * \param format requested channel format
258  * \param data data to pass to the channel requester
259  * Request a channel of a given type, with data as optional information used 
260  * by the low level module
261  * Returns an ast_channel on success, NULL on failure.
262  */
263 struct ast_channel *ast_request(char *type, int format, void *data);
264
265 //! Search the Channels by Name
266 /*!
267  * \param device like a dialstring
268  * Search the Device in active channels by compare the channelname against 
269  * the devicename. Compared are only the first chars to the first '-' char.
270  * Returns an AST_DEVICE_UNKNOWN if no channel found or
271  * AST_DEVICE_INUSE if a channel is found
272  */
273 int ast_parse_device_state(char *device);
274
275 //! Asks a channel for device state
276 /*!
277  * \param device like a dialstring
278  * Asks a channel for device state, data is  normaly a number from dialstring
279  * used by the low level module
280  * Trys the channel devicestate callback if not supported search in the
281  * active channels list for the device.
282  * Returns an AST_DEVICE_??? state -1 on failure
283  */
284 int ast_device_state(char *device);
285
286 /*!
287  * \param type type of channel to request
288  * \param format requested channel format
289  * \param data data to pass to the channel requester
290  * \param timeout maximum amount of time to wait for an answer
291  * \param why unsuccessful (if unsuceessful)
292  * Request a channel of a given type, with data as optional information used 
293  * by the low level module and attempt to place a call on it
294  * Returns an ast_channel on success or no answer, NULL on failure.  Check the value of chan->_state
295  * to know if the call was answered or not.
296  */
297 struct ast_channel *ast_request_and_dial(char *type, int format, void *data, int timeout, int *reason, char *callerid);
298
299 //! Registers a channel
300 /*! 
301  * \param type type of channel you are registering
302  * \param description short description of the channel
303  * \param capabilities a bit mask of the capabilities of the channel
304  * \param requester a function pointer that properly responds to a call.  See one of the channel drivers for details.
305  * Called by a channel module to register the kind of channels it supports.
306  * It supplies a brief type, a longer, but still short description, and a
307  * routine that creates a channel
308  * Returns 0 on success, -1 on failure.
309  */
310 int ast_channel_register(char *type, char *description, int capabilities, 
311                         struct ast_channel* (*requester)(char *type, int format, void *data));
312
313 /* Same like the upper function but with support for devicestate */
314 int ast_channel_register_ex(char *type, char *description, int capabilities,
315                 struct ast_channel *(*requester)(char *type, int format, void *data),
316                 int (*devicestate)(void *data));
317
318 //! Unregister a channel class
319 /*
320  * \param type the character string that corresponds to the channel you wish to unregister
321  * Basically just unregisters the channel with the asterisk channel system
322  * No return value.
323  */
324 void ast_channel_unregister(char *type);
325
326 //! Hang up a channel 
327 /*! 
328  * \param chan channel to hang up
329  * This function performs a hard hangup on a channel.  Unlike the soft-hangup, this function
330  * performs all stream stopping, etc, on the channel that needs to end.
331  * chan is no longer valid after this call.
332  * Returns 0 on success, -1 on failure.
333  */
334 int ast_hangup(struct ast_channel *chan);
335
336 //! Softly hangup up a channel
337 /*! 
338  * \param chan channel to be soft-hung-up
339  * Call the protocol layer, but don't destroy the channel structure (use this if you are trying to
340  * safely hangup a channel managed by another thread.
341  * Returns 0 regardless
342  */
343 int ast_softhangup(struct ast_channel *chan, int cause);
344 int ast_softhangup_nolock(struct ast_channel *chan, int cause);
345
346 //! Check to see if a channel is needing hang up
347 /*! 
348  * \param chan channel on which to check for hang up
349  * This function determines if the channel is being requested to be hung up.
350  * Returns 0 if not, or 1 if hang up is requested (including time-out).
351  */
352 int ast_check_hangup(struct ast_channel *chan);
353
354 //! Set when to hang a channel up
355 /*! 
356  * \param chan channel on which to check for hang up
357  * \param offset offset in seconds from current time of when to hang up
358  * This function sets the absolute time out on a channel (when to hang up).
359  */
360 void ast_channel_setwhentohangup(struct ast_channel *chan, time_t offset);
361
362 //! Answer a ringing call
363 /*!
364  * \param chan channel to answer
365  * This function answers a channel and handles all necessary call
366  * setup functions.
367  * Returns 0 on success, -1 on failure
368  */
369 int ast_answer(struct ast_channel *chan);
370
371 //! Make a call
372 /*! 
373  * \param chan which channel to make the call on
374  * \param addr destination of the call
375  * \param timeout time to wait on for connect
376  * Place a call, take no longer than timeout ms.  Returns -1 on failure, 
377    0 on not enough time (does not auto matically stop ringing), and  
378    the number of seconds the connect took otherwise.
379    Returns 0 on success, -1 on failure
380    */
381 int ast_call(struct ast_channel *chan, char *addr, int timeout);
382
383 //! Indicates condition of channel
384 /*! 
385  * \param chan channel to change the indication
386  * \param condition which condition to indicate on the channel
387  * Indicate a condition such as AST_CONTROL_BUSY, AST_CONTROL_RINGING, or AST_CONTROL_CONGESTION on a channel
388  * Returns 0 on success, -1 on failure
389  */
390 int ast_indicate(struct ast_channel *chan, int condition);
391
392 /* Misc stuff */
393
394 //! Wait for input on a channel
395 /*! 
396  * \param chan channel to wait on
397  * \param ms length of time to wait on the channel
398  * Wait for input on a channel for a given # of milliseconds (<0 for indefinite). 
399   Returns < 0 on  failure, 0 if nothing ever arrived, and the # of ms remaining otherwise */
400 int ast_waitfor(struct ast_channel *chan, int ms);
401
402 //! Wait for a specied amount of time, looking for hangups
403 /*!
404  * \param chan channel to wait for
405  * \param ms length of time in milliseconds to sleep
406  * Waits for a specified amount of time, servicing the channel as required.
407  * returns -1 on hangup, otherwise 0.
408  */
409 int ast_safe_sleep(struct ast_channel *chan, int ms);
410
411 //! Wait for a specied amount of time, looking for hangups and a condition argument
412 /*!
413  * \param chan channel to wait for
414  * \param ms length of time in milliseconds to sleep
415  * \param cond a function pointer for testing continue condition
416  * \param data argument to be passed to the condition test function
417  * Waits for a specified amount of time, servicing the channel as required. If cond
418  * returns 0, this function returns.
419  * returns -1 on hangup, otherwise 0.
420  */
421 int ast_safe_sleep_conditional(struct ast_channel *chan, int ms, int (*cond)(void*), void *data );
422
423 //! Waits for activity on a group of channels
424 /*! 
425  * \param chan an array of pointers to channels
426  * \param n number of channels that are to be waited upon
427  * \param fds an array of fds to wait upon
428  * \param nfds the number of fds to wait upon
429  * \param exception exception flag
430  * \param outfd fd that had activity on it
431  * \param ms how long the wait was
432  * Big momma function here.  Wait for activity on any of the n channels, or any of the nfds
433    file descriptors.  Returns the channel with activity, or NULL on error or if an FD
434    came first.  If the FD came first, it will be returned in outfd, otherwise, outfd
435    will be -1 */
436 struct ast_channel *ast_waitfor_nandfds(struct ast_channel **chan, int n, int *fds, int nfds, int *exception, int *outfd, int *ms);
437
438 //! Waits for input on a group of channels
439 /*! Wait for input on an array of channels for a given # of milliseconds. Return channel
440    with activity, or NULL if none has activity.  time "ms" is modified in-place, if applicable */
441 struct ast_channel *ast_waitfor_n(struct ast_channel **chan, int n, int *ms);
442
443 //! Waits for input on an fd
444 /*! This version works on fd's only.  Be careful with it. */
445 int ast_waitfor_n_fd(int *fds, int n, int *ms, int *exception);
446
447
448 //! Reads a frame
449 /*! 
450  * \param chan channel to read a frame from
451  * Read a frame.  Returns a frame, or NULL on error.  If it returns NULL, you
452    best just stop reading frames and assume the channel has been
453    disconnected. */
454 struct ast_frame *ast_read(struct ast_channel *chan);
455
456 //! Write a frame to a channel
457 /*!
458  * \param chan destination channel of the frame
459  * \param frame frame that will be written
460  * This function writes the given frame to the indicated channel.
461  * It returns 0 on success, -1 on failure.
462  */
463 int ast_write(struct ast_channel *chan, struct ast_frame *frame);
464
465 /* Send empty audio to prime a channel driver */
466 int ast_prod(struct ast_channel *chan);
467
468 //! Sets read format on channel chan
469 /*! 
470  * \param chan channel to change
471  * \param format format to change to
472  * Set read format for channel to whichever component of "format" is best. 
473  * Returns 0 on success, -1 on failure
474  */
475 int ast_set_read_format(struct ast_channel *chan, int format);
476
477 //! Sets write format on channel chan
478 /*! 
479  * \param chan channel to change
480  * \param format new format for writing
481  * Set write format for channel to whichever compoent of "format" is best. 
482  * Returns 0 on success, -1 on failure
483  */
484 int ast_set_write_format(struct ast_channel *chan, int format);
485
486 //! Sends text to a channel
487 /*! 
488  * \param chan channel to act upon
489  * \param text string of text to send on the channel
490  * Write text to a display on a channel
491  * Returns 0 on success, -1 on failure
492  */
493 int ast_sendtext(struct ast_channel *chan, char *text);
494
495 //! Receives a text character from a channel
496 /*! 
497  * \param chan channel to act upon
498  * \param timeout timeout in milliseconds (0 for infinite wait)
499  * Read a char of text from a channel
500  * Returns 0 on success, -1 on failure
501  */
502 int ast_recvchar(struct ast_channel *chan, int timeout);
503
504 //! Browse channels in use
505 /*! 
506  * \param prev where you want to start in the channel list
507  * Browse the channels currently in use 
508  * Returns the next channel in the list, NULL on end.
509  */
510 struct ast_channel *ast_channel_walk(struct ast_channel *prev);
511
512 //! Waits for a digit
513 /*! 
514  * \param c channel to wait for a digit on
515  * \param ms how many milliseconds to wait
516  * Wait for a digit.  Returns <0 on error, 0 on no entry, and the digit on success. */
517 char ast_waitfordigit(struct ast_channel *c, int ms);
518
519 /* Same as above with audio fd for outputing read audio and ctrlfd to monitor for
520    reading. Returns 1 if ctrlfd becomes available */
521 char ast_waitfordigit_full(struct ast_channel *c, int ms, int audiofd, int ctrlfd);
522
523 //! Reads multiple digits
524 /*! 
525  * \param c channel to read from
526  * \param s string to read in to.  Must be at least the size of your length
527  * \param len how many digits to read (maximum)
528  * \param timeout how long to timeout between digits
529  * \param rtimeout timeout to wait on the first digit
530  * \param enders digits to end the string
531  * Read in a digit string "s", max length "len", maximum timeout between 
532    digits "timeout" (-1 for none), terminated by anything in "enders".  Give them rtimeout
533    for the first digit.  Returns 0 on normal return, or 1 on a timeout.  In the case of
534    a timeout, any digits that were read before the timeout will still be available in s.  
535    RETURNS 2 in full version when ctrlfd is available, NOT 1*/
536 int ast_readstring(struct ast_channel *c, char *s, int len, int timeout, int rtimeout, char *enders);
537 int ast_readstring_full(struct ast_channel *c, char *s, int len, int timeout, int rtimeout, char *enders, int audiofd, int ctrlfd);
538
539 /*! Report DTMF on channel 0 */
540 #define AST_BRIDGE_DTMF_CHANNEL_0               (1 << 0)                
541 /*! Report DTMF on channel 1 */
542 #define AST_BRIDGE_DTMF_CHANNEL_1               (1 << 1)                
543 /*! Return all voice frames on channel 0 */
544 #define AST_BRIDGE_REC_CHANNEL_0                (1 << 2)                
545 /*! Return all voice frames on channel 1 */
546 #define AST_BRIDGE_REC_CHANNEL_1                (1 << 3)                
547 /*! Ignore all signal frames except NULL */
548 #define AST_BRIDGE_IGNORE_SIGS                  (1 << 4)                
549
550
551 //! Makes two channel formats compatible
552 /*! 
553  * \param c0 first channel to make compatible
554  * \param c1 other channel to make compatible
555  * Set two channels to compatible formats -- call before ast_channel_bridge in general .  Returns 0 on success
556    and -1 if it could not be done */
557 int ast_channel_make_compatible(struct ast_channel *c0, struct ast_channel *c1);
558
559 //! Bridge two channels together
560 /*! 
561  * \param c0 first channel to bridge
562  * \param c1 second channel to bridge
563  * \param flags for the channels
564  * \param fo destination frame(?)
565  * \param rc destination channel(?)
566  * Bridge two channels (c0 and c1) together.  If an important frame occurs, we return that frame in
567    *rf (remember, it could be NULL) and which channel (0 or 1) in rc */
568 int ast_channel_bridge(struct ast_channel *c0, struct ast_channel *c1, int flags, struct ast_frame **fo, struct ast_channel **rc);
569
570 //! Weird function made for call transfers
571 /*! 
572  * \param original channel to make a copy of
573  * \param clone copy of the original channel
574  * This is a very strange and freaky function used primarily for transfer.  Suppose that
575    "original" and "clone" are two channels in random situations.  This function takes
576    the guts out of "clone" and puts them into the "original" channel, then alerts the
577    channel driver of the change, asking it to fixup any private information (like the
578    p->owner pointer) that is affected by the change.  The physical layer of the original
579    channel is hung up.  */
580 int ast_channel_masquerade(struct ast_channel *original, struct ast_channel *clone);
581
582 //! Gives the string form of a given state
583 /*! 
584  * \param state state to get the name of
585  * Give a name to a state 
586  * Pretty self explanatory.
587  * Returns the text form of the binary state given
588  */
589 char *ast_state2str(int state);
590
591 /* Options: Some low-level drivers may implement "options" allowing fine tuning of the
592    low level channel.  See frame.h for options.  Note that many channel drivers may support
593    none or a subset of those features, and you should not count on this if you want your
594    asterisk application to be portable.  They're mainly useful for tweaking performance */
595
596 //! Sets an option on a channel
597 /*! 
598  * \param channel channel to set options on
599  * \param option option to change
600  * \param data data specific to option
601  * \param datalen length of the data
602  * \param block blocking or not
603  * Set an option on a channel (see frame.h), optionally blocking awaiting the reply 
604  * Returns 0 on success and -1 on failure
605  */
606 int ast_channel_setoption(struct ast_channel *channel, int option, void *data, int datalen, int block);
607
608 //! Checks the value of an option
609 /*! 
610  * Query the value of an option, optionally blocking until a reply is received
611  * Works similarly to setoption except only reads the options.
612  */
613 struct ast_frame *ast_channel_queryoption(struct ast_channel *channel, int option, void *data, int *datalen, int block);
614
615 //! Checks for HTML support on a channel
616 /*! Returns 0 if channel does not support HTML or non-zero if it does */
617 int ast_channel_supports_html(struct ast_channel *channel);
618
619 //! Sends HTML on given channel
620 /*! Send HTML or URL on link.  Returns 0 on success or -1 on failure */
621 int ast_channel_sendhtml(struct ast_channel *channel, int subclass, char *data, int datalen);
622
623 //! Sends a URL on a given link
624 /*! Send URL on link.  Returns 0 on success or -1 on failure */
625 int ast_channel_sendurl(struct ast_channel *channel, char *url);
626
627 //! Defers DTMF
628 /*! Defer DTMF so that you only read things like hangups and audio.  Returns
629    non-zero if channel was already DTMF-deferred or 0 if channel is just now
630    being DTMF-deferred */
631 int ast_channel_defer_dtmf(struct ast_channel *chan);
632
633 //! Undeos a defer
634 /*! Undo defer.  ast_read will return any dtmf characters that were queued */
635 void ast_channel_undefer_dtmf(struct ast_channel *chan);
636
637 /*! Initiate system shutdown -- prevents new channels from being allocated.
638     If "hangup" is non-zero, all existing channels will receive soft
639      hangups */
640 void ast_begin_shutdown(int hangup);
641
642 /*! Cancels an existing shutdown and returns to normal operation */
643 void ast_cancel_shutdown(void);
644
645 /*! Returns number of active/allocated channels */
646 int ast_active_channels(void);
647
648 /*! Returns non-zero if Asterisk is being shut down */
649 int ast_shutting_down(void);
650
651 /*! Activate a given generator */
652 int ast_activate_generator(struct ast_channel *chan, struct ast_generator *gen, void *params);
653
654 /*! Deactive an active generator */
655 void ast_deactivate_generator(struct ast_channel *chan);
656
657 void ast_set_callerid(struct ast_channel *chan, char *callerid, int  anitoo);
658
659 /*! Start a tone going */
660 int ast_tonepair_start(struct ast_channel *chan, int freq1, int freq2, int duration, int vol);
661 /*! Stop a tone from playing */
662 void ast_tonepair_stop(struct ast_channel *chan);
663 /*! Play a tone pair for a given amount of time */
664 int ast_tonepair(struct ast_channel *chan, int freq1, int freq2, int duration, int vol);
665
666 /*! Automatically service a channel for us... */
667 int ast_autoservice_start(struct ast_channel *chan);
668
669 /*! Stop servicing a channel for us...  Returns -1 on error or if channel has been hungup */
670 int ast_autoservice_stop(struct ast_channel *chan);
671
672 /* Misc. functions below */
673
674 //! Waits for activity on a group of channels
675 /*! 
676  * \param nfds the maximum number of file descriptors in the sets
677  * \param rfds file descriptors to check for read availability
678  * \param wfds file descriptors to check for write availability
679  * \param efds file descriptors to check for exceptions (OOB data)
680  * \param tvp timeout while waiting for events
681  * This is the same as a standard select(), except it guarantees the
682  * behaviour where the passed struct timeval is updated with how much
683  * time was not slept while waiting for the specified events
684  */
685 static inline int ast_select(int nfds, fd_set *rfds, fd_set *wfds, fd_set *efds, struct timeval *tvp)
686 {
687 #ifdef __linux__
688         return select(nfds, rfds, wfds, efds, tvp);
689 #else
690         if (tvp) {
691                 struct timeval tv, tvstart, tvend, tvlen;
692                 int res;
693
694                 tv = *tvp;
695                 gettimeofday(&tvstart, NULL);
696                 res = select(nfds, rfds, wfds, efds, tvp);
697                 gettimeofday(&tvend, NULL);
698                 timersub(&tvend, &tvstart, &tvlen);
699                 timersub(&tv, &tvlen, tvp);
700                 if (tvp->tv_sec < 0 || (tvp->tv_sec == 0 && tvp->tv_usec < 0)) {
701                         tvp->tv_sec = 0;
702                         tvp->tv_usec = 0;
703                 }
704                 return res;
705         }
706         else
707                 return(nfds, rfds, wfds, efds, NULL);
708 #endif
709 }
710
711 #ifdef DO_CRASH
712 #define CRASH do { fprintf(stderr, "!! Forcing immediate crash a-la abort !!\n"); *((int *)0) = 0; } while(0)
713 #else
714 #define CRASH do { } while(0)
715 #endif
716
717 #define CHECK_BLOCKING(c) {      \
718                                                         if ((c)->blocking) {\
719                                                                 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); \
720                                                                 CRASH; \
721                                                         } else { \
722                                                                 (c)->blocker = pthread_self(); \
723                                                                 (c)->blockproc = __PRETTY_FUNCTION__; \
724                                                                         c->blocking = -1; \
725                                                                         } }
726
727 #if defined(__cplusplus) || defined(c_plusplus)
728 }
729 #endif
730
731
732 #endif