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