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