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