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