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