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