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