issue #5590
[asterisk/asterisk.git] / include / asterisk / channel.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 1999 - 2005, Digium, Inc.
5  *
6  * Mark Spencer <markster@digium.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18
19 /*! \file
20  * \brief General Asterisk PBX channel definitions.
21  * \par See also:
22  *  \arg \ref Def_Channel
23  *  \arg \ref channel_drivers
24  */
25
26 /*! \page Def_Channel Asterisk Channels
27         \par What is a Channel?
28         A phone call through Asterisk consists of an incoming
29         connection and an outbound connection. Each call comes
30         in through a channel driver that supports one technology,
31         like SIP, ZAP, IAX2 etc. 
32         \par
33         Each channel driver, technology, has it's own private
34         channel or dialog structure, that is technology-dependent.
35         Each private structure is "owned" by a generic Asterisk
36         channel structure, defined in channel.h and handled by
37         channel.c .
38         \par Call scenario
39         This happens when an incoming call arrives to Asterisk
40         -# Call arrives on a channel driver interface
41         -# Channel driver creates a PBX channel and starts a 
42            pbx thread on the channel
43         -# The dial plan is executed
44         -# At this point at least two things can happen:
45                 -# The call is answered by Asterisk and 
46                    Asterisk plays a media stream or reads media
47                 -# The dial plan forces Asterisk to create an outbound 
48                    call somewhere with the dial (see \ref app_dial.c)
49                    application
50
51         .
52         \par Bridging channels
53         If Asterisk dials out this happens:
54         -# Dial creates an outbound PBX channel and asks one of the
55            channel drivers to create a call
56         -# When the call is answered, Asterisk bridges the media streams
57            so the caller on the first channel can speak with the callee
58            on the second, outbound channel
59         -# In some cases where we have the same technology on both
60            channels and compatible codecs, a native bridge is used.
61            In a native bridge, the channel driver handles forwarding
62            of incoming audio to the outbound stream internally, without
63            sending audio frames through the PBX.
64         -# In SIP, theres an "external native bridge" where Asterisk
65            redirects the endpoint, so audio flows directly between the
66            caller's phone and the callee's phone. Signalling stays in
67            Asterisk in order to be able to provide a proper CDR record
68            for the call.
69
70         
71         \par Masquerading channels
72         In some cases, a channel can masquerade itself into another
73         channel. This happens frequently in call transfers, where 
74         a new channel takes over a channel that is already involved
75         in a call. The new channel sneaks in and takes over the bridge
76         and the old channel, now a zombie, is hung up.
77         
78         \par Reference
79         \arg channel.c - generic functions
80         \arg channel.h - declarations of functions, flags and structures
81         \arg \ref channel_drivers - Implemented channel drivers
82         \arg \ref Def_Frame Asterisk Multimedia Frames
83
84 */
85
86 #ifndef _ASTERISK_CHANNEL_H
87 #define _ASTERISK_CHANNEL_H
88
89 #include <unistd.h>
90 #include <setjmp.h>
91 #ifdef POLLCOMPAT 
92 #include "asterisk/poll-compat.h"
93 #else
94 #include <sys/poll.h>
95 #endif
96
97 #if defined(__cplusplus) || defined(c_plusplus)
98 extern "C" {
99 #endif
100
101 /*! Max length of an extension */
102 #define AST_MAX_EXTENSION       80
103
104 #define AST_MAX_CONTEXT         80
105
106 #define AST_CHANNEL_NAME        80
107
108 #include "asterisk/compat.h"
109 #include "asterisk/frame.h"
110 #include "asterisk/sched.h"
111 #include "asterisk/chanvars.h"
112 #include "asterisk/config.h"
113 #include "asterisk/lock.h"
114 #include "asterisk/cdr.h"
115 #include "asterisk/utils.h"
116 #include "asterisk/linkedlists.h"
117
118 #define MAX_LANGUAGE            20
119
120 #define MAX_MUSICCLASS          20
121
122 #define AST_MAX_FDS             8
123
124 enum ast_bridge_result {
125         AST_BRIDGE_COMPLETE = 0,
126         AST_BRIDGE_FAILED = -1,
127         AST_BRIDGE_FAILED_NOWARN = -2,
128         AST_BRIDGE_RETRY = -3,
129 };
130
131 typedef unsigned long long ast_group_t;
132
133 struct ast_generator {
134         void *(*alloc)(struct ast_channel *chan, void *params);
135         void (*release)(struct ast_channel *chan, void *data);
136         int (*generate)(struct ast_channel *chan, void *data, int len, int samples);
137 };
138
139 /*! Structure for all kinds of caller ID identifications */
140 struct ast_callerid {
141         /*! Malloc'd Dialed Number Identifier */
142         char *cid_dnid;                         
143         /*! Malloc'd Caller Number */
144         char *cid_num;
145         /*! Malloc'd Caller Name */
146         char *cid_name;
147         /*! Malloc'd ANI */
148         char *cid_ani;                  
149         /*! Malloc'd RDNIS */
150         char *cid_rdnis;
151         /*! Callerid presentation/screening */
152         int cid_pres;
153         /*! Callerid ANI 2 (Info digits) */
154         int cid_ani2;
155         /*! Callerid Type of Number */
156         int cid_ton;
157         /*! Callerid Transit Network Select */
158         int cid_tns;
159 };
160
161 /*! Structure to describe a channel "technology", ie a channel driver 
162         See
163         \arg chan_iax2.c - The Inter-Asterisk exchange protocol
164         \arg chan_sip.c - The SIP channel driver
165         \arg chan_zap.c - PSTN connectivity (TDM, PRI, T1/E1, FXO, FXS)
166
167         If you develop your own channel driver, this is where you
168         tell the PBX at registration of your driver what properties
169         this driver supports and where different callbacks are 
170         implemented.
171 */
172         
173
174 struct ast_channel_tech {
175         const char * const type;
176         const char * const description;
177
178         /*! Bitmap of formats this channel can handle */
179         int capabilities;
180
181         /*! Technology Properties */
182         int properties;
183
184         /*! Requester - to set up call data structures (pvt's) */
185         struct ast_channel *(* const requester)(const char *type, int format, void *data, int *cause);
186
187         /*! Devicestate call back */
188         int (* const devicestate)(void *data);
189
190         /*! Send a literal DTMF digit */
191         int (* const send_digit)(struct ast_channel *chan, char digit);
192
193         /*! Call a given phone number (address, etc), but don't
194            take longer than timeout seconds to do so.  */
195         int (* const call)(struct ast_channel *chan, char *addr, int timeout);
196
197         /*! Hangup (and possibly destroy) the channel */
198         int (* const hangup)(struct ast_channel *chan);
199
200         /*! Answer the channel */
201         int (* const answer)(struct ast_channel *chan);
202
203         /*! Read a frame, in standard format (see frame.h) */
204         struct ast_frame * (* const read)(struct ast_channel *chan);
205
206         /*! Write a frame, in standard format (see frame.h) */
207         int (* const write)(struct ast_channel *chan, struct ast_frame *frame);
208
209         /*! Display or transmit text */
210         int (* const send_text)(struct ast_channel *chan, const char *text);
211
212         /*! Display or send an image */
213         int (* const send_image)(struct ast_channel *chan, struct ast_frame *frame);
214
215         /*! Send HTML data */
216         int (* const send_html)(struct ast_channel *chan, int subclass, const char *data, int len);
217
218         /*! Handle an exception, reading a frame */
219         struct ast_frame * (* const exception)(struct ast_channel *chan);
220
221         /*! Bridge two channels of the same type together */
222         enum ast_bridge_result (* const bridge)(struct ast_channel *c0, struct ast_channel *c1, int flags,
223                                                 struct ast_frame **fo, struct ast_channel **rc, int timeoutms);
224
225         /*! Indicate a particular condition (e.g. AST_CONTROL_BUSY or AST_CONTROL_RINGING or AST_CONTROL_CONGESTION */
226         int (* const indicate)(struct ast_channel *c, int condition);
227
228         /*! Fix up a channel:  If a channel is consumed, this is called.  Basically update any ->owner links */
229         int (* const fixup)(struct ast_channel *oldchan, struct ast_channel *newchan);
230
231         /*! Set a given option */
232         int (* const setoption)(struct ast_channel *chan, int option, void *data, int datalen);
233
234         /*! Query a given option */
235         int (* const queryoption)(struct ast_channel *chan, int option, void *data, int *datalen);
236
237         /*! Blind transfer other side (see app_transfer.c and ast_transfer() */
238         int (* const transfer)(struct ast_channel *chan, const char *newdest);
239
240         /*! Write a frame, in standard format */
241         int (* const write_video)(struct ast_channel *chan, struct ast_frame *frame);
242
243         /*! Find bridged channel */
244         struct ast_channel *(* const bridged_channel)(struct ast_channel *chan, struct ast_channel *bridge);
245 };
246
247 struct ast_channel_spy_list;
248
249 /*! Main Channel structure associated with a channel. 
250  * This is the side of it mostly used by the pbx and call management.
251  */
252 struct ast_channel {
253         /*! ASCII unique channel name */
254         char name[AST_CHANNEL_NAME];
255         
256         /*! Technology (point to channel driver) */
257         const struct ast_channel_tech *tech;
258
259         /*! Private data used by the technology driver */
260         void *tech_pvt;
261
262         /*! Language requested for voice prompts */
263         char language[MAX_LANGUAGE];            
264         /*! Type of channel */
265         const char *type;                               
266         /*! File descriptor for channel -- Drivers will poll on these file descriptors, so at least one must be non -1.  */
267         int fds[AST_MAX_FDS];                   
268
269         /*! Default music class */
270         char musicclass[MAX_MUSICCLASS];
271         /*! Music State*/
272         void *music_state;
273         /*! Current generator data if there is any */
274         void *generatordata;
275         /*! Current active data generator */
276         struct ast_generator *generator;
277
278         /*! Who are we bridged to, if we're bridged  Do not access directly,
279             use ast_bridged_channel(chan) */
280         struct ast_channel *_bridge;
281         /*! Channel that will masquerade as us */
282         struct ast_channel *masq;               
283         /*! Who we are masquerading as */
284         struct ast_channel *masqr;              
285         /*! Call Detail Record Flags */
286         int cdrflags;                                                                              
287         /*! Whether or not we have been hung up...  Do not set this value
288             directly, use ast_softhangup */
289         int _softhangup;
290         /*! Non-zero, set to actual time when channel is to be hung up */
291         time_t  whentohangup;
292         /*! If anyone is blocking, this is them */
293         pthread_t blocker;                      
294         /*! Lock, can be used to lock a channel for some operations */
295         ast_mutex_t lock;                       
296         /*! Procedure causing blocking */
297         const char *blockproc;                  
298
299         /*! Current application */
300         char *appl;                             
301         /*! Data passed to current application */
302         char *data;                             
303         
304         /*! Which fd had an event detected on */
305         int fdno;                               
306         /*! Schedule context */
307         struct sched_context *sched;            
308         /*! For streaming playback, the schedule ID */
309         int streamid;                           
310         /*! Stream itself. */
311         struct ast_filestream *stream;          
312         /*! For streaming video playback, the schedule ID */
313         int vstreamid;                          
314         /*! Video Stream itself. */
315         struct ast_filestream *vstream;         
316         /*! Original writer format */
317         int oldwriteformat;                     
318         
319         /*! Timing fd */
320         int timingfd;
321         int (*timingfunc)(void *data);
322         void *timingdata;
323
324         /*! State of line -- Don't write directly, use ast_setstate */
325         int _state;                             
326         /*! Number of rings so far */
327         int rings;                              
328
329         /*! Kinds of data this channel can natively handle */
330         int nativeformats;                      
331         /*! Requested read format */
332         int readformat;                         
333         /*! Requested write format */
334         int writeformat;                        
335
336         struct ast_callerid cid;
337                 
338         /*! Current extension context */
339         char context[AST_MAX_CONTEXT];
340         /*! Current non-macro context */
341         char macrocontext[AST_MAX_CONTEXT];     
342         /*! Current non-macro extension */
343         char macroexten[AST_MAX_EXTENSION];
344         /*! Current non-macro priority */
345         int macropriority;
346         /*! Current extension number */
347         char exten[AST_MAX_EXTENSION];          
348         /* Current extension priority */
349         int priority;                                           
350         /*! Any/all queued DTMF characters */
351         char dtmfq[AST_MAX_EXTENSION];          
352         /*! DTMF frame */
353         struct ast_frame dtmff;                 
354
355         /*! PBX private structure */
356         struct ast_pbx *pbx;
357         /*! Set BEFORE PBX is started to determine AMA flags */
358         int amaflags;                   
359         /*! Account code for billing */
360         char accountcode[AST_MAX_ACCOUNT_CODE];         
361         /*! Call Detail Record */
362         struct ast_cdr *cdr;                    
363         /*! Whether or not ADSI is detected on CPE */
364         int adsicpe;
365         /*! Where to forward to if asked to dial on this interface */
366         char call_forward[AST_MAX_EXTENSION];
367
368         /*! Tone zone as set in indications.conf */
369         struct tone_zone *zone;
370
371         /* Channel monitoring */
372         struct ast_channel_monitor *monitor;
373
374         /*! Track the read/written samples for monitor use */
375         unsigned long insmpl;
376         unsigned long outsmpl;
377
378         /* Frames in/out counters */
379         unsigned int fin;
380         unsigned int fout;
381
382         /* Unique Channel Identifier */
383         char uniqueid[32];
384
385         /* Why is the channel hanged up */
386         int hangupcause;
387         
388         /* A linked list for variables */
389         struct varshead varshead;
390
391         unsigned int callgroup;
392         unsigned int pickupgroup;
393
394         /*! channel flags of AST_FLAG_ type */
395         unsigned int flags;
396         
397         /*! ISDN Transfer Capbility - AST_FLAG_DIGITAL is not enough */
398         unsigned short transfercapability;
399
400         struct ast_frame *readq;
401         int alertpipe[2];
402         /*! Write translation path */
403         struct ast_trans_pvt *writetrans;
404         /*! Read translation path */
405         struct ast_trans_pvt *readtrans;
406         /*! Raw read format */
407         int rawreadformat;
408         /*! Raw write format */
409         int rawwriteformat;
410
411         /*! Chan Spy stuff */
412         struct ast_channel_spy_list *spies;
413
414         /*! For easy linking */
415         struct ast_channel *next;
416 };
417
418 /* \defgroup chanprop Channel tech properties:
419         \brief Channels have this property if they can accept input with jitter; i.e. most VoIP channels */
420 /* @{ */
421 #define AST_CHAN_TP_WANTSJITTER (1 << 0)        
422
423 /* This flag has been deprecated by the transfercapbilty data member in struct ast_channel */
424 /* #define AST_FLAG_DIGITAL     (1 << 0) */     /* if the call is a digital ISDN call */
425 #define AST_FLAG_DEFER_DTMF     (1 << 1)        /*!< if dtmf should be deferred */
426 #define AST_FLAG_WRITE_INT      (1 << 2)        /*!< if write should be interrupt generator */
427 #define AST_FLAG_BLOCKING       (1 << 3)        /*!< if we are blocking */
428 #define AST_FLAG_ZOMBIE         (1 << 4)        /*!< if we are a zombie */
429 #define AST_FLAG_EXCEPTION      (1 << 5)        /*!< if there is a pending exception */
430 #define AST_FLAG_MOH            (1 << 6)        /*!< XXX anthm promises me this will disappear XXX listening to moh */
431 #define AST_FLAG_SPYING         (1 << 7)        /*!< XXX might also go away XXX is spying on someone */
432 #define AST_FLAG_NBRIDGE        (1 << 8)        /*!< is it in a native bridge */
433 #define AST_FLAG_IN_AUTOLOOP    (1 << 9)        /*!< the channel is in an auto-incrementing dialplan processor,
434                                                    so when ->priority is set, it will get incremented before
435                                                    finding the next priority to run
436                                                 */
437 /* @} */
438
439 #define AST_FEATURE_PLAY_WARNING        (1 << 0)
440 #define AST_FEATURE_REDIRECT            (1 << 1)
441 #define AST_FEATURE_DISCONNECT          (1 << 2)
442 #define AST_FEATURE_ATXFER              (1 << 3)
443 #define AST_FEATURE_AUTOMON             (1 << 4)
444
445 #define AST_FEATURE_FLAG_NEEDSDTMF      (1 << 0)
446 #define AST_FEATURE_FLAG_CALLEE         (1 << 1)
447 #define AST_FEATURE_FLAG_CALLER         (1 << 2)
448
449 struct ast_bridge_config {
450         struct ast_flags features_caller;
451         struct ast_flags features_callee;
452         struct timeval start_time;
453         long feature_timer;
454         long timelimit;
455         long play_warning;
456         long warning_freq;
457         char *warning_sound;
458         char *end_sound;
459         char *start_sound;
460         int firstpass;
461         unsigned int flags;
462 };
463
464 struct chanmon;
465
466 #define LOAD_OH(oh) {   \
467         oh.context = context; \
468         oh.exten = exten; \
469         oh.priority = priority; \
470         oh.cid_num = cid_num; \
471         oh.cid_name = cid_name; \
472         oh.vars = vars; \
473         oh.parent_channel = NULL; \
474
475
476 struct outgoing_helper {
477         const char *context;
478         const char *exten;
479         int priority;
480         const char *cid_num;
481         const char *cid_name;
482         struct ast_variable *vars;
483         struct ast_channel *parent_channel;
484 };
485
486 #define AST_CDR_TRANSFER        (1 << 0)
487 #define AST_CDR_FORWARD         (1 << 1)
488 #define AST_CDR_CALLWAIT        (1 << 2)
489 #define AST_CDR_CONFERENCE      (1 << 3)
490
491 #define AST_ADSI_UNKNOWN        (0)
492 #define AST_ADSI_AVAILABLE      (1)
493 #define AST_ADSI_UNAVAILABLE    (2)
494 #define AST_ADSI_OFFHOOKONLY    (3)
495
496 #define AST_SOFTHANGUP_DEV              (1 << 0)        /*!< Soft hangup by device */
497 #define AST_SOFTHANGUP_ASYNCGOTO        (1 << 1)        /*!< Soft hangup for async goto */
498 #define AST_SOFTHANGUP_SHUTDOWN         (1 << 2)
499 #define AST_SOFTHANGUP_TIMEOUT          (1 << 3)
500 #define AST_SOFTHANGUP_APPUNLOAD        (1 << 4)
501 #define AST_SOFTHANGUP_EXPLICIT         (1 << 5)
502 #define AST_SOFTHANGUP_UNBRIDGE     (1 << 6)
503
504
505 /*! \defgroup ChanState Channel states
506 \brief Bits 0-15 of state are reserved for the state (up/down) of the line */
507 /*! @{ */
508 /*! Channel is down and available */
509 #define AST_STATE_DOWN          0               
510 /*! Channel is down, but reserved */
511 #define AST_STATE_RESERVED      1               
512 /*! Channel is off hook */
513 #define AST_STATE_OFFHOOK       2               
514 /*! Digits (or equivalent) have been dialed */
515 #define AST_STATE_DIALING       3               
516 /*! Line is ringing */
517 #define AST_STATE_RING          4               
518 /*! Remote end is ringing */
519 #define AST_STATE_RINGING       5               
520 /*! Line is up */
521 #define AST_STATE_UP            6               
522 /*! Line is busy */
523 #define AST_STATE_BUSY          7               
524 /*! Digits (or equivalent) have been dialed while offhook */
525 #define AST_STATE_DIALING_OFFHOOK       8
526 /*! Channel has detected an incoming call and is waiting for ring */
527 #define AST_STATE_PRERING       9
528
529 /* Bits 16-32 of state are reserved for flags (See \ref ChanState ) */
530 /*! Do not transmit voice data */
531 #define AST_STATE_MUTE          (1 << 16)       
532 /*! @} */
533
534 /*! \brief Change the state of a channel */
535 int ast_setstate(struct ast_channel *chan, int state);
536
537 /*! \brief Create a channel structure 
538     \return Returns NULL on failure to allocate.
539         \note New channels are 
540         by default set to the "default" context and
541         extension "s"
542  */
543 struct ast_channel *ast_channel_alloc(int needalertpipe);
544
545 /*! \brief Queue an outgoing frame */
546 int ast_queue_frame(struct ast_channel *chan, struct ast_frame *f);
547
548 /*! \brief Queue a hangup frame */
549 int ast_queue_hangup(struct ast_channel *chan);
550
551 /*! \brief Queue a control frame */
552 int ast_queue_control(struct ast_channel *chan, int control);
553
554
555 /*! \brief Change channel name */
556 void ast_change_name(struct ast_channel *chan, char *newname);
557
558 /*! \brief Free a channel structure */
559 void  ast_channel_free(struct ast_channel *);
560
561 /*! \brief Requests a channel 
562  * \param type type of channel to request
563  * \param format requested channel format
564  * \param data data to pass to the channel requester
565  * \param status status
566  * Request a channel of a given type, with data as optional information used 
567  * by the low level module
568  * \return Returns an ast_channel on success, NULL on failure.
569  */
570 struct ast_channel *ast_request(const char *type, int format, void *data, int *status);
571
572 /*!
573  * \brief Request a channel of a given type, with data as optional information used 
574  * by the low level module and attempt to place a call on it
575  * \param type type of channel to request
576  * \param format requested channel format
577  * \param data data to pass to the channel requester
578  * \param timeout maximum amount of time to wait for an answer
579  * \param reason why unsuccessful (if unsuceessful)
580  * \param cidnum Caller-ID Number
581  * \param cidname Caller-ID Name
582  * \return Returns an ast_channel on success or no answer, NULL on failure.  Check the value of chan->_state
583  * to know if the call was answered or not.
584  */
585 struct ast_channel *ast_request_and_dial(const char *type, int format, void *data, int timeout, int *reason, const char *cidnum, const char *cidname);
586
587 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);
588
589 /*!\brief Register a channel technology (a new channel driver)
590  * Called by a channel module to register the kind of channels it supports.
591  * \param tech Structure defining channel technology or "type"
592  * \return Returns 0 on success, -1 on failure.
593  */
594 int ast_channel_register(const struct ast_channel_tech *tech);
595
596 /*! \brief Unregister a channel technology 
597  * \param tech Structure defining channel technology or "type" that was previously registered
598  * \return No return value.
599  */
600 void ast_channel_unregister(const struct ast_channel_tech *tech);
601
602 /*! \brief Get a channel technology structure by name
603  * \param name name of technology to find
604  * \return a pointer to the structure, or NULL if no matching technology found
605  */
606 const struct ast_channel_tech *ast_get_channel_tech(const char *name);
607
608 /*! \brief Hang up a channel  
609  * \note This function performs a hard hangup on a channel.  Unlike the soft-hangup, this function
610  * performs all stream stopping, etc, on the channel that needs to end.
611  * chan is no longer valid after this call.
612  * \param chan channel to hang up
613  * \return Returns 0 on success, -1 on failure.
614  */
615 int ast_hangup(struct ast_channel *chan);
616
617 /*! \brief Softly hangup up a channel 
618  * \param chan channel to be soft-hung-up
619  * Call the protocol layer, but don't destroy the channel structure (use this if you are trying to
620  * safely hangup a channel managed by another thread.
621  * \param cause Ast hangupcause for hangup
622  * \return Returns 0 regardless
623  */
624 int ast_softhangup(struct ast_channel *chan, int cause);
625
626 /*! \brief Softly hangup up a channel (no channel lock) 
627  * \param chan channel to be soft-hung-up
628  * \param cause Ast hangupcause for hangup (see cause.h) */
629 int ast_softhangup_nolock(struct ast_channel *chan, int cause);
630
631 /*! \brief Check to see if a channel is needing hang up 
632  * \param chan channel on which to check for hang up
633  * This function determines if the channel is being requested to be hung up.
634  * \return Returns 0 if not, or 1 if hang up is requested (including time-out).
635  */
636 int ast_check_hangup(struct ast_channel *chan);
637
638 /*! \brief Compare a offset with the settings of when to hang a channel up 
639  * \param chan channel on which to check for hang up
640  * \param offset offset in seconds from current time
641  * \return 1, 0, or -1
642  * This function compares a offset from current time with the absolute time 
643  * out on a channel (when to hang up). If the absolute time out on a channel
644  * is earlier than current time plus the offset, it returns 1, if the two
645  * time values are equal, it return 0, otherwise, it retturn -1.
646  */
647 int ast_channel_cmpwhentohangup(struct ast_channel *chan, time_t offset);
648
649 /*! \brief Set when to hang a channel up 
650  * \param chan channel on which to check for hang up
651  * \param offset offset in seconds from current time of when to hang up
652  * This function sets the absolute time out on a channel (when to hang up).
653  */
654 void ast_channel_setwhentohangup(struct ast_channel *chan, time_t offset);
655
656 /*! \brief Answer a ringing call 
657  * \param chan channel to answer
658  * This function answers a channel and handles all necessary call
659  * setup functions.
660  * \return Returns 0 on success, -1 on failure
661  */
662 int ast_answer(struct ast_channel *chan);
663
664 /*! \brief Make a call 
665  * \param chan which channel to make the call on
666  * \param addr destination of the call
667  * \param timeout time to wait on for connect
668  * Place a call, take no longer than timeout ms. 
669    \return Returns -1 on failure, 0 on not enough time 
670    (does not automatically stop ringing), and  
671    the number of seconds the connect took otherwise.
672    */
673 int ast_call(struct ast_channel *chan, char *addr, int timeout);
674
675 /*! \brief Indicates condition of channel 
676  * \note Indicate a condition such as AST_CONTROL_BUSY, AST_CONTROL_RINGING, or AST_CONTROL_CONGESTION on a channel
677  * \param chan channel to change the indication
678  * \param condition which condition to indicate on the channel
679  * \return Returns 0 on success, -1 on failure
680  */
681 int ast_indicate(struct ast_channel *chan, int condition);
682
683 /* Misc stuff ------------------------------------------------ */
684
685 /*! \brief Wait for input on a channel 
686  * \param chan channel to wait on
687  * \param ms length of time to wait on the channel
688  * Wait for input on a channel for a given # of milliseconds (<0 for indefinite). 
689   \return Returns < 0 on  failure, 0 if nothing ever arrived, and the # of ms remaining otherwise */
690 int ast_waitfor(struct ast_channel *chan, int ms);
691
692 /*! \brief Wait for a specied amount of time, looking for hangups 
693  * \param chan channel to wait for
694  * \param ms length of time in milliseconds to sleep
695  * Waits for a specified amount of time, servicing the channel as required.
696  * \return returns -1 on hangup, otherwise 0.
697  */
698 int ast_safe_sleep(struct ast_channel *chan, int ms);
699
700 /*! \brief Wait for a specied amount of time, looking for hangups and a condition argument 
701  * \param chan channel to wait for
702  * \param ms length of time in milliseconds to sleep
703  * \param cond a function pointer for testing continue condition
704  * \param data argument to be passed to the condition test function
705  * \return returns -1 on hangup, otherwise 0.
706  * Waits for a specified amount of time, servicing the channel as required. If cond
707  * returns 0, this function returns.
708  */
709 int ast_safe_sleep_conditional(struct ast_channel *chan, int ms, int (*cond)(void*), void *data );
710
711 /*! \brief Waits for activity on a group of channels 
712  * \param chan an array of pointers to channels
713  * \param n number of channels that are to be waited upon
714  * \param fds an array of fds to wait upon
715  * \param nfds the number of fds to wait upon
716  * \param exception exception flag
717  * \param outfd fd that had activity on it
718  * \param ms how long the wait was
719  * Big momma function here.  Wait for activity on any of the n channels, or any of the nfds
720    file descriptors.
721    \return Returns the channel with activity, or NULL on error or if an FD
722    came first.  If the FD came first, it will be returned in outfd, otherwise, outfd
723    will be -1 */
724 struct ast_channel *ast_waitfor_nandfds(struct ast_channel **chan, int n, int *fds, int nfds, int *exception, int *outfd, int *ms);
725
726 /*! Waits for input on a group of channels */
727 /*! Wait for input on an array of channels for a given # of milliseconds. Return channel
728    with activity, or NULL if none has activity.  time "ms" is modified in-place, if applicable */
729 struct ast_channel *ast_waitfor_n(struct ast_channel **chan, int n, int *ms);
730
731 /*! Waits for input on an fd */
732 /*! This version works on fd's only.  Be careful with it. */
733 int ast_waitfor_n_fd(int *fds, int n, int *ms, int *exception);
734
735
736 /*! Reads a frame */
737 /*!
738  * \param chan channel to read a frame from
739  * Read a frame.  Returns a frame, or NULL on error.  If it returns NULL, you
740    best just stop reading frames and assume the channel has been
741    disconnected. */
742 struct ast_frame *ast_read(struct ast_channel *chan);
743
744 /*! Write a frame to a channel */
745 /*!
746  * \param chan destination channel of the frame
747  * \param frame frame that will be written
748  * This function writes the given frame to the indicated channel.
749  * It returns 0 on success, -1 on failure.
750  */
751 int ast_write(struct ast_channel *chan, struct ast_frame *frame);
752
753 /*! Write video frame to a channel */
754 /*!
755  * \param chan destination channel of the frame
756  * \param frame frame that will be written
757  * This function writes the given frame to the indicated channel.
758  * It returns 1 on success, 0 if not implemented, and -1 on failure.
759  */
760 int ast_write_video(struct ast_channel *chan, struct ast_frame *frame);
761
762 /* Send empty audio to prime a channel driver */
763 int ast_prod(struct ast_channel *chan);
764
765 /*! Sets read format on channel chan */
766 /*! 
767  * \param chan channel to change
768  * \param format format to change to
769  * Set read format for channel to whichever component of "format" is best. 
770  * Returns 0 on success, -1 on failure
771  */
772 int ast_set_read_format(struct ast_channel *chan, int format);
773
774 /*! Sets write format on channel chan */
775 /*! 
776  * \param chan channel to change
777  * \param format new format for writing
778  * Set write format for channel to whichever compoent of "format" is best. 
779  * Returns 0 on success, -1 on failure
780  */
781 int ast_set_write_format(struct ast_channel *chan, int format);
782
783 /*! Sends text to a channel */
784 /*! 
785  * \param chan channel to act upon
786  * \param text string of text to send on the channel
787  * Write text to a display on a channel
788  * Returns 0 on success, -1 on failure
789  */
790 int ast_sendtext(struct ast_channel *chan, const char *text);
791
792 /*! Receives a text character from a channel */
793 /*! 
794  * \param chan channel to act upon
795  * \param timeout timeout in milliseconds (0 for infinite wait)
796  * Read a char of text from a channel
797  * Returns 0 on success, -1 on failure
798  */
799 int ast_recvchar(struct ast_channel *chan, int timeout);
800
801 /*! Send a DTMF digit to a channel */
802 /*! 
803  * \param chan channel to act upon
804  * \param digit the DTMF digit to send, encoded in ASCII
805  * Send a DTMF digit to a channel.
806  * Returns 0 on success, -1 on failure
807  */
808 int ast_senddigit(struct ast_channel *chan, char digit);
809
810 /*! Receives a text string from a channel */
811 /*! 
812  * \param chan channel to act upon
813  * \param timeout timeout in milliseconds (0 for infinite wait)
814  * \return the received text, or NULL to signify failure.
815  * Read a string of text from a channel
816  */
817 char *ast_recvtext(struct ast_channel *chan, int timeout);
818
819 /*! Browse channels in use */
820 /*! 
821  * \param prev where you want to start in the channel list
822  * Browse the channels currently in use 
823  * Returns the next channel in the list, NULL on end.
824  * If it returns a channel, that channel *has been locked*!
825  */
826 struct ast_channel *ast_channel_walk_locked(const struct ast_channel *prev);
827
828 /*! Get channel by name (locks channel) */
829 struct ast_channel *ast_get_channel_by_name_locked(const char *chan);
830
831 /*! Get channel by name prefix (locks channel) */
832 struct ast_channel *ast_get_channel_by_name_prefix_locked(const char *name, const int namelen);
833
834 /*! Get channel by name prefix (locks channel) */
835 struct ast_channel *ast_walk_channel_by_name_prefix_locked(struct ast_channel *chan, const char *name, const int namelen);
836
837 /*--- ast_get_channel_by_exten_locked: Get channel by exten (and optionally context) and lock it */
838 struct ast_channel *ast_get_channel_by_exten_locked(const char *exten, const char *context);
839
840 /*! Waits for a digit */
841 /*! 
842  * \param c channel to wait for a digit on
843  * \param ms how many milliseconds to wait
844  * Wait for a digit.  Returns <0 on error, 0 on no entry, and the digit on success. */
845 int ast_waitfordigit(struct ast_channel *c, int ms);
846
847 /* Same as above with audio fd for outputing read audio and ctrlfd to monitor for
848    reading. Returns 1 if ctrlfd becomes available */
849 int ast_waitfordigit_full(struct ast_channel *c, int ms, int audiofd, int ctrlfd);
850
851 /*! Reads multiple digits */
852 /*! 
853  * \param c channel to read from
854  * \param s string to read in to.  Must be at least the size of your length
855  * \param len how many digits to read (maximum)
856  * \param timeout how long to timeout between digits
857  * \param rtimeout timeout to wait on the first digit
858  * \param enders digits to end the string
859  * Read in a digit string "s", max length "len", maximum timeout between 
860    digits "timeout" (-1 for none), terminated by anything in "enders".  Give them rtimeout
861    for the first digit.  Returns 0 on normal return, or 1 on a timeout.  In the case of
862    a timeout, any digits that were read before the timeout will still be available in s.  
863    RETURNS 2 in full version when ctrlfd is available, NOT 1*/
864 int ast_readstring(struct ast_channel *c, char *s, int len, int timeout, int rtimeout, char *enders);
865 int ast_readstring_full(struct ast_channel *c, char *s, int len, int timeout, int rtimeout, char *enders, int audiofd, int ctrlfd);
866
867 /*! Report DTMF on channel 0 */
868 #define AST_BRIDGE_DTMF_CHANNEL_0               (1 << 0)                
869 /*! Report DTMF on channel 1 */
870 #define AST_BRIDGE_DTMF_CHANNEL_1               (1 << 1)                
871 /*! Return all voice frames on channel 0 */
872 #define AST_BRIDGE_REC_CHANNEL_0                (1 << 2)                
873 /*! Return all voice frames on channel 1 */
874 #define AST_BRIDGE_REC_CHANNEL_1                (1 << 3)                
875 /*! Ignore all signal frames except NULL */
876 #define AST_BRIDGE_IGNORE_SIGS                  (1 << 4)                
877
878
879 /*! Makes two channel formats compatible */
880 /*! 
881  * \param c0 first channel to make compatible
882  * \param c1 other channel to make compatible
883  * Set two channels to compatible formats -- call before ast_channel_bridge in general .  Returns 0 on success
884    and -1 if it could not be done */
885 int ast_channel_make_compatible(struct ast_channel *c0, struct ast_channel *c1);
886
887 /*! Bridge two channels together */
888 /*! 
889  * \param c0 first channel to bridge
890  * \param c1 second channel to bridge
891  * \param config config for the channels
892  * \param fo destination frame(?)
893  * \param rc destination channel(?)
894  * Bridge two channels (c0 and c1) together.  If an important frame occurs, we return that frame in
895    *rf (remember, it could be NULL) and which channel (0 or 1) in rc */
896 /* int ast_channel_bridge(struct ast_channel *c0, struct ast_channel *c1, int flags, struct ast_frame **fo, struct ast_channel **rc); */
897 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);
898
899 /*! Weird function made for call transfers */
900 /*! 
901  * \param original channel to make a copy of
902  * \param clone copy of the original channel
903  * This is a very strange and freaky function used primarily for transfer.  Suppose that
904    "original" and "clone" are two channels in random situations.  This function takes
905    the guts out of "clone" and puts them into the "original" channel, then alerts the
906    channel driver of the change, asking it to fixup any private information (like the
907    p->owner pointer) that is affected by the change.  The physical layer of the original
908    channel is hung up.  */
909 int ast_channel_masquerade(struct ast_channel *original, struct ast_channel *clone);
910
911 /*! Gives the string form of a given cause code */
912 /*! 
913  * \param state cause to get the description of
914  * Give a name to a cause code
915  * Returns the text form of the binary cause code given
916  */
917 const char *ast_cause2str(int state);
918
919 /*! Gives the string form of a given channel state */
920 /*! 
921  * \param state state to get the name of
922  * Give a name to a state 
923  * Returns the text form of the binary state given
924  */
925 char *ast_state2str(int state);
926
927 /*! Gives the string form of a given transfer capability */
928 /*!
929  * \param transfercapability transfercapabilty to get the name of
930  * Give a name to a transfercapbility
931  * See above
932  * Returns the text form of the binary transfer capbility
933  */
934 char *ast_transfercapability2str(int transfercapability);
935
936 /* Options: Some low-level drivers may implement "options" allowing fine tuning of the
937    low level channel.  See frame.h for options.  Note that many channel drivers may support
938    none or a subset of those features, and you should not count on this if you want your
939    asterisk application to be portable.  They're mainly useful for tweaking performance */
940
941 /*! Sets an option on a channel */
942 /*! 
943  * \param channel channel to set options on
944  * \param option option to change
945  * \param data data specific to option
946  * \param datalen length of the data
947  * \param block blocking or not
948  * Set an option on a channel (see frame.h), optionally blocking awaiting the reply 
949  * Returns 0 on success and -1 on failure
950  */
951 int ast_channel_setoption(struct ast_channel *channel, int option, void *data, int datalen, int block);
952
953 /*! Pick the best codec  */
954 /* Choose the best codec...  Uhhh...   Yah. */
955 extern int ast_best_codec(int fmts);
956
957
958 /*! Checks the value of an option */
959 /*! 
960  * Query the value of an option, optionally blocking until a reply is received
961  * Works similarly to setoption except only reads the options.
962  */
963 struct ast_frame *ast_channel_queryoption(struct ast_channel *channel, int option, void *data, int *datalen, int block);
964
965 /*! Checks for HTML support on a channel */
966 /*! Returns 0 if channel does not support HTML or non-zero if it does */
967 int ast_channel_supports_html(struct ast_channel *channel);
968
969 /*! Sends HTML on given channel */
970 /*! Send HTML or URL on link.  Returns 0 on success or -1 on failure */
971 int ast_channel_sendhtml(struct ast_channel *channel, int subclass, const char *data, int datalen);
972
973 /*! Sends a URL on a given link */
974 /*! Send URL on link.  Returns 0 on success or -1 on failure */
975 int ast_channel_sendurl(struct ast_channel *channel, const char *url);
976
977 /*! Defers DTMF */
978 /*! Defer DTMF so that you only read things like hangups and audio.  Returns
979    non-zero if channel was already DTMF-deferred or 0 if channel is just now
980    being DTMF-deferred */
981 int ast_channel_defer_dtmf(struct ast_channel *chan);
982
983 /*! Undeos a defer */
984 /*! Undo defer.  ast_read will return any dtmf characters that were queued */
985 void ast_channel_undefer_dtmf(struct ast_channel *chan);
986
987 /*! Initiate system shutdown -- prevents new channels from being allocated.
988     If "hangup" is non-zero, all existing channels will receive soft
989      hangups */
990 void ast_begin_shutdown(int hangup);
991
992 /*! Cancels an existing shutdown and returns to normal operation */
993 void ast_cancel_shutdown(void);
994
995 /*! Returns number of active/allocated channels */
996 int ast_active_channels(void);
997
998 /*! Returns non-zero if Asterisk is being shut down */
999 int ast_shutting_down(void);
1000
1001 /*! Activate a given generator */
1002 int ast_activate_generator(struct ast_channel *chan, struct ast_generator *gen, void *params);
1003
1004 /*! Deactive an active generator */
1005 void ast_deactivate_generator(struct ast_channel *chan);
1006
1007 void ast_set_callerid(struct ast_channel *chan, const char *cidnum, const char *cidname, const char *ani);
1008
1009 /*! Start a tone going */
1010 int ast_tonepair_start(struct ast_channel *chan, int freq1, int freq2, int duration, int vol);
1011 /*! Stop a tone from playing */
1012 void ast_tonepair_stop(struct ast_channel *chan);
1013 /*! Play a tone pair for a given amount of time */
1014 int ast_tonepair(struct ast_channel *chan, int freq1, int freq2, int duration, int vol);
1015
1016 /*! Automatically service a channel for us... */
1017 int ast_autoservice_start(struct ast_channel *chan);
1018
1019 /*! Stop servicing a channel for us...  Returns -1 on error or if channel has been hungup */
1020 int ast_autoservice_stop(struct ast_channel *chan);
1021
1022 /* If built with zaptel optimizations, force a scheduled expiration on the
1023    timer fd, at which point we call the callback function / data */
1024 int ast_settimeout(struct ast_channel *c, int samples, int (*func)(void *data), void *data);
1025
1026 /*!     \brief Transfer a channel (if supported).  Returns -1 on error, 0 if not supported
1027    and 1 if supported and requested 
1028         \param chan current channel
1029         \param dest destination extension for transfer
1030 */
1031 int ast_transfer(struct ast_channel *chan, char *dest);
1032
1033 /*!     \brief  Start masquerading a channel
1034         XXX This is a seriously wacked out operation.  We're essentially putting the guts of
1035            the clone channel into the original channel.  Start by killing off the original
1036            channel's backend.   I'm not sure we're going to keep this function, because
1037            while the features are nice, the cost is very high in terms of pure nastiness. XXX
1038         \param chan     Channel to masquerade
1039 */
1040 int ast_do_masquerade(struct ast_channel *chan);
1041
1042 /*!     \brief Find bridged channel 
1043         \param chan Current channel
1044 */
1045 struct ast_channel *ast_bridged_channel(struct ast_channel *chan);
1046
1047 /*!
1048   \brief Inherits channel variable from parent to child channel
1049   \param parent Parent channel
1050   \param child Child channel
1051
1052   Scans all channel variables in the parent channel, looking for those
1053   that should be copied into the child channel.
1054   Variables whose names begin with a single '_' are copied into the
1055   child channel with the prefix removed.
1056   Variables whose names begin with '__' are copied into the child
1057   channel with their names unchanged.
1058 */
1059 void ast_channel_inherit_variables(const struct ast_channel *parent, struct ast_channel *child);
1060
1061 /*!
1062   \brief adds a list of channel variables to a channel
1063   \param chan the channel
1064   \param vars a linked list of variables
1065
1066   Variable names can be for a regular channel variable or a dialplan function
1067   that has the ability to be written to.
1068 */
1069 void ast_set_variables(struct ast_channel *chan, struct ast_variable *vars);
1070
1071 /*!
1072   \brief An opaque 'object' structure use by silence generators on channels.
1073  */
1074 struct ast_silence_generator;
1075
1076 /*!
1077   \brief Starts a silence generator on the given channel.
1078   \param chan The channel to generate silence on
1079   \return An ast_silence_generator pointer, or NULL if an error occurs
1080
1081   This function will cause SLINEAR silence to be generated on the supplied
1082   channel until it is disabled; if the channel cannot be put into SLINEAR
1083   mode then the function will fail.
1084
1085   The pointer returned by this function must be preserved and passed to
1086   ast_channel_stop_silence_generator when you wish to stop the silence
1087   generation.
1088  */
1089 struct ast_silence_generator *ast_channel_start_silence_generator(struct ast_channel *chan);
1090
1091 /*!
1092   \brief Stops a previously-started silence generator on the given channel.
1093   \param chan The channel to operate on
1094   \param state The ast_silence_generator pointer return by a previous call to
1095   ast_channel_start_silence_generator.
1096   \return nothing
1097
1098   This function will stop the operating silence generator and return the channel
1099   to its previous write format.
1100  */
1101 void ast_channel_stop_silence_generator(struct ast_channel *chan, struct ast_silence_generator *state);
1102
1103 /* Misc. functions below */
1104
1105 /* Helper function for migrating select to poll */
1106 static inline int ast_fdisset(struct pollfd *pfds, int fd, int max, int *start)
1107 {
1108         int x;
1109         for (x=start ? *start : 0;x<max;x++)
1110                 if (pfds[x].fd == fd) {
1111                         if (start) {
1112                                 if (x==*start)
1113                                         (*start)++;
1114                         }
1115                         return pfds[x].revents;
1116                 }
1117         return 0;
1118 }
1119
1120 #ifdef SOLARIS
1121 static inline void timersub(struct timeval *tvend, struct timeval *tvstart, struct timeval *tvdiff)
1122 {
1123         tvdiff->tv_sec = tvend->tv_sec - tvstart->tv_sec;
1124         tvdiff->tv_usec = tvend->tv_usec - tvstart->tv_usec;
1125         if (tvdiff->tv_usec < 0) {
1126                 tvdiff->tv_sec --;
1127                 tvdiff->tv_usec += 1000000;
1128         }
1129
1130 }
1131 #endif
1132
1133 /*! \brief Waits for activity on a group of channels 
1134  * \param nfds the maximum number of file descriptors in the sets
1135  * \param rfds file descriptors to check for read availability
1136  * \param wfds file descriptors to check for write availability
1137  * \param efds file descriptors to check for exceptions (OOB data)
1138  * \param tvp timeout while waiting for events
1139  * This is the same as a standard select(), except it guarantees the
1140  * behaviour where the passed struct timeval is updated with how much
1141  * time was not slept while waiting for the specified events
1142  */
1143 static inline int ast_select(int nfds, fd_set *rfds, fd_set *wfds, fd_set *efds, struct timeval *tvp)
1144 {
1145 #ifdef __linux__
1146         return select(nfds, rfds, wfds, efds, tvp);
1147 #else
1148         if (tvp) {
1149                 struct timeval tv, tvstart, tvend, tvlen;
1150                 int res;
1151
1152                 tv = *tvp;
1153                 gettimeofday(&tvstart, NULL);
1154                 res = select(nfds, rfds, wfds, efds, tvp);
1155                 gettimeofday(&tvend, NULL);
1156                 timersub(&tvend, &tvstart, &tvlen);
1157                 timersub(&tv, &tvlen, tvp);
1158                 if (tvp->tv_sec < 0 || (tvp->tv_sec == 0 && tvp->tv_usec < 0)) {
1159                         tvp->tv_sec = 0;
1160                         tvp->tv_usec = 0;
1161                 }
1162                 return res;
1163         }
1164         else
1165                 return select(nfds, rfds, wfds, efds, NULL);
1166 #endif
1167 }
1168
1169 #if !defined(ast_strdupa) && defined(__GNUC__)
1170 # define ast_strdupa(s)                                                                 \
1171   (__extension__                                                                                \
1172     ({                                                                                                  \
1173       __const char *__old = (s);                                                \
1174       size_t __len = strlen (__old) + 1;                                \
1175       char *__new = (char *) __builtin_alloca (__len);  \
1176       (char *) memcpy (__new, __old, __len);                    \
1177     }))
1178 #endif
1179
1180 #ifdef DO_CRASH
1181 #define CRASH do { fprintf(stderr, "!! Forcing immediate crash a-la abort !!\n"); *((int *)0) = 0; } while(0)
1182 #else
1183 #define CRASH do { } while(0)
1184 #endif
1185
1186 #define CHECK_BLOCKING(c) {      \
1187                                                         if (ast_test_flag(c, AST_FLAG_BLOCKING)) {\
1188                                                                 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); \
1189                                                                 CRASH; \
1190                                                         } else { \
1191                                                                 (c)->blocker = pthread_self(); \
1192                                                                 (c)->blockproc = __PRETTY_FUNCTION__; \
1193                                                                         ast_set_flag(c, AST_FLAG_BLOCKING); \
1194                                                                         } }
1195
1196 extern ast_group_t ast_get_group(char *s);
1197 /* print call- and pickup groups into buffer */
1198 extern char *ast_print_group(char *buf, int buflen, ast_group_t group);
1199
1200
1201 #if defined(__cplusplus) || defined(c_plusplus)
1202 }
1203 #endif
1204
1205 #endif /* _ASTERISK_CHANNEL_H */