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