Let's start with implementing the base architecture for UTF8 caller ID's
[asterisk/asterisk.git] / include / asterisk / channel.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 1999 - 2006, 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 translate.h - Transcoding support functions
82         \arg \ref channel_drivers - Implemented channel drivers
83         \arg \ref Def_Frame Asterisk Multimedia Frames
84         \arg \ref Def_Bridge
85
86 */
87 /*! \page Def_Bridge Asterisk Channel Bridges
88
89         In Asterisk, there's several media bridges. 
90
91         The Core bridge handles two channels (a "phone call") and bridge
92         them together.
93         
94         The conference bridge (meetme) handles several channels simultaneously
95         with the support of an external timer (zaptel timer). This is used
96         not only by the Conference application (meetme) but also by the
97         page application and the SLA system introduced in 1.4.
98         The conference bridge does not handle video.
99
100         When two channels of the same type connect, the channel driver
101         or the media subsystem used by the channel driver (i.e. RTP)
102         can create a native bridge without sending media through the
103         core.
104
105         Native briding can be disabled by a number of reasons,
106         like DTMF being needed by the core or codecs being incompatible
107         so a transcoding module is needed.
108
109 References:
110         \li \see ast_channel_early_bridge()
111         \li \see ast_channel_bridge()
112         \li \see app_meetme.c
113         \li \ref AstRTPbridge
114         \li \see ast_rtp_bridge() 
115         \li \ref Def_Channel
116 */
117
118 /*! \page AstFileDesc File descriptors 
119         Asterisk File descriptors are connected to each channel (see \ref Def_Channel)
120         in the \ref ast_channel structure.
121 */
122
123 #ifndef _ASTERISK_CHANNEL_H
124 #define _ASTERISK_CHANNEL_H
125
126 #include "asterisk/abstract_jb.h"
127
128 #ifdef HAVE_SYS_POLL_H
129 #include <sys/poll.h>
130 #else
131 #include "asterisk/poll-compat.h"
132 #endif
133
134 #if defined(__cplusplus) || defined(c_plusplus)
135 extern "C" {
136 #endif
137
138 #define AST_MAX_EXTENSION       80      /*!< Max length of an extension */
139 #define AST_MAX_CONTEXT         80      /*!< Max length of a context */
140 #define AST_CHANNEL_NAME        80      /*!< Max length of an ast_channel name */
141 #define MAX_LANGUAGE            20      /*!< Max length of the language setting */
142 #define MAX_MUSICCLASS          80      /*!< Max length of the music class setting */
143
144 #include "asterisk/frame.h"
145 #include "asterisk/sched.h"
146 #include "asterisk/chanvars.h"
147 #include "asterisk/config.h"
148 #include "asterisk/lock.h"
149 #include "asterisk/cdr.h"
150 #include "asterisk/utils.h"
151 #include "asterisk/linkedlists.h"
152 #include "asterisk/stringfields.h"
153
154 #define DATASTORE_INHERIT_FOREVER       INT_MAX
155
156 #define AST_MAX_FDS             10
157 /*
158  * We have AST_MAX_FDS file descriptors in a channel.
159  * Some of them have a fixed use:
160  */
161 #define AST_ALERT_FD    (AST_MAX_FDS-1)         /*!< used for alertpipe */
162 #define AST_TIMING_FD   (AST_MAX_FDS-2)         /*!< used for timingfd */
163 #define AST_AGENT_FD    (AST_MAX_FDS-3)         /*!< used by agents for pass through */
164 #define AST_GENERATOR_FD        (AST_MAX_FDS-4) /*!< used by generator */
165
166 enum ast_bridge_result {
167         AST_BRIDGE_COMPLETE = 0,
168         AST_BRIDGE_FAILED = -1,
169         AST_BRIDGE_FAILED_NOWARN = -2,
170         AST_BRIDGE_RETRY = -3,
171 };
172
173 typedef unsigned long long ast_group_t;
174
175 /*! \todo Add an explanation of an Asterisk generator 
176 */
177 struct ast_generator {
178         void *(*alloc)(struct ast_channel *chan, void *params);
179         void (*release)(struct ast_channel *chan, void *data);
180         /*! This function gets called with the channel locked */
181         int (*generate)(struct ast_channel *chan, void *data, int len, int samples);
182         /*! This gets called when DTMF_END frames are read from the channel */
183         void (*digit)(struct ast_channel *chan, char digit);
184 };
185
186 /*! \brief Structure for a data store type */
187 struct ast_datastore_info {
188         const char *type;               /*!< Type of data store */
189         void *(*duplicate)(void *data); /*!< Duplicate item data (used for inheritance) */
190         void (*destroy)(void *data);    /*!< Destroy function */
191 };
192
193 /*! \brief Structure for a channel data store */
194 struct ast_datastore {
195         const char *uid;                /*!< Unique data store identifier */
196         void *data;             /*!< Contained data */
197         const struct ast_datastore_info *info;  /*!< Data store type information */
198         unsigned int inheritance;       /*!< Number of levels this item will continue to be inherited */
199         AST_LIST_ENTRY(ast_datastore) entry; /*!< Used for easy linking */
200 };
201
202 /*! \brief Structure for all kinds of caller ID identifications.
203  * \note All string fields here are malloc'ed, so they need to be
204  * freed when the structure is deleted.
205  * Also, NULL and "" must be considered equivalent.
206  * 
207  * SIP and IAX2 has utf8 encoded Unicode caller ID names.
208  * In some cases, we also have an alternative (RPID) E.164 number that can be used
209  * as caller ID on numeric E.164 phone networks (zaptel or SIP/IAX2 to pstn gateway).
210
211  * SIP and IAX2 will prefer the cid_utf8 if it exists, otherwise use the cid_name.
212  * \todo Implement this in chan_sip.c and chan_iax2.c
213  *
214  * \todo Implement settings for transliteration between UTF8 caller ID names in
215  *       to Ascii Caller ID's (Zaptel). Östen Åsklund might be transliterated into
216  *       Osten Asklund or Oesten Aasklund depending upon language and person...
217  *       We need automatic routines for incoming calls and static settings for
218  *       our own accounts.
219  */
220 struct ast_callerid {
221         char *cid_dnid;         /*!< Malloc'd Dialed Number Identifier */
222         char *cid_num;          /*!< Malloc'd Caller Number */
223         char *cid_name;         /*!< Malloc'd Caller Name (ASCII) */
224         char *cid_ani;          /*!< Malloc'd ANI */
225         char *cid_rdnis;        /*!< Malloc'd RDNIS */
226         char *cid_utf8;         /*!< Malloc'd Caller ID name in utf8 */
227         char *cid_domain;       /*!< Malloc'd Caller ID domain (ascii. IDN supported) */
228         char *cid_e164;         /*!< Malloc'd Alternative Caller ID E.164 (alternative to SIP/IAX2 utf8 uri, RPID) */
229         int cid_pres;           /*!< Callerid presentation/screening */
230         int cid_ani2;           /*!< Callerid ANI 2 (Info digits) */
231         int cid_ton;            /*!< Callerid Type of Number */
232         int cid_tns;            /*!< Callerid Transit Network Select */
233 };
234
235 /*! \brief 
236         Structure to describe a channel "technology", ie a channel driver 
237         See for examples:
238         \arg chan_iax2.c - The Inter-Asterisk exchange protocol
239         \arg chan_sip.c - The SIP channel driver
240         \arg chan_zap.c - PSTN connectivity (TDM, PRI, T1/E1, FXO, FXS)
241
242         If you develop your own channel driver, this is where you
243         tell the PBX at registration of your driver what properties
244         this driver supports and where different callbacks are 
245         implemented.
246 */
247 struct ast_channel_tech {
248         const char * const type;
249         const char * const description;
250
251         int capabilities;               /*!< Bitmap of formats this channel can handle */
252
253         int properties;                 /*!< Technology Properties */
254
255         /*! \brief Requester - to set up call data structures (pvt's) */
256         struct ast_channel *(* const requester)(const char *type, int format, void *data, int *cause);
257
258         int (* const devicestate)(void *data);  /*!< Devicestate call back */
259
260         /*! \brief Start sending a literal DTMF digit */
261         int (* const send_digit_begin)(struct ast_channel *chan, char digit);
262
263         /*! \brief Stop sending a literal DTMF digit */
264         int (* const send_digit_end)(struct ast_channel *chan, char digit, unsigned int duration);
265
266         /*! \brief Call a given phone number (address, etc), but don't
267            take longer than timeout seconds to do so.  */
268         int (* const call)(struct ast_channel *chan, char *addr, int timeout);
269
270         /*! \brief Hangup (and possibly destroy) the channel */
271         int (* const hangup)(struct ast_channel *chan);
272
273         /*! \brief Answer the channel */
274         int (* const answer)(struct ast_channel *chan);
275
276         /*! \brief Read a frame, in standard format (see frame.h) */
277         struct ast_frame * (* const read)(struct ast_channel *chan);
278
279         /*! \brief Write a frame, in standard format (see frame.h) */
280         int (* const write)(struct ast_channel *chan, struct ast_frame *frame);
281
282         /*! \brief Display or transmit text */
283         int (* const send_text)(struct ast_channel *chan, const char *text);
284
285         /*! \brief Display or send an image */
286         int (* const send_image)(struct ast_channel *chan, struct ast_frame *frame);
287
288         /*! \brief Send HTML data */
289         int (* const send_html)(struct ast_channel *chan, int subclass, const char *data, int len);
290
291         /*! \brief Handle an exception, reading a frame */
292         struct ast_frame * (* const exception)(struct ast_channel *chan);
293
294         /*! \brief Bridge two channels of the same type together */
295         enum ast_bridge_result (* const bridge)(struct ast_channel *c0, struct ast_channel *c1, int flags,
296                                                 struct ast_frame **fo, struct ast_channel **rc, int timeoutms);
297
298         /*! \brief Bridge two channels of the same type together (early) */
299         enum ast_bridge_result (* const early_bridge)(struct ast_channel *c0, struct ast_channel *c1);
300
301         /*! \brief Indicate a particular condition (e.g. AST_CONTROL_BUSY or AST_CONTROL_RINGING or AST_CONTROL_CONGESTION */
302         int (* const indicate)(struct ast_channel *c, int condition, const void *data, size_t datalen);
303
304         /*! \brief Fix up a channel:  If a channel is consumed, this is called.  Basically update any ->owner links */
305         int (* const fixup)(struct ast_channel *oldchan, struct ast_channel *newchan);
306
307         /*! \brief Set a given option */
308         int (* const setoption)(struct ast_channel *chan, int option, void *data, int datalen);
309
310         /*! \brief Query a given option */
311         int (* const queryoption)(struct ast_channel *chan, int option, void *data, int *datalen);
312
313         /*! \brief Blind transfer other side (see app_transfer.c and ast_transfer() */
314         int (* const transfer)(struct ast_channel *chan, const char *newdest);
315
316         /*! \brief Write a frame, in standard format */
317         int (* const write_video)(struct ast_channel *chan, struct ast_frame *frame);
318
319         /*! \brief Write a text frame, in standard format */
320         int (* const write_text)(struct ast_channel *chan, struct ast_frame *frame);
321
322         /*! \brief Find bridged channel */
323         struct ast_channel *(* const bridged_channel)(struct ast_channel *chan, struct ast_channel *bridge);
324
325         /*! \brief Provide additional read items for CHANNEL() dialplan function */
326         int (* func_channel_read)(struct ast_channel *chan, const char *function, char *data, char *buf, size_t len);
327
328         /*! \brief Provide additional write items for CHANNEL() dialplan function */
329         int (* func_channel_write)(struct ast_channel *chan, const char *function, char *data, const char *value);
330
331         /*! \brief Retrieve base channel (agent and local) */
332         struct ast_channel* (* get_base_channel)(struct ast_channel *chan);
333         
334         /*! \brief Set base channel (agent and local) */
335         int (* set_base_channel)(struct ast_channel *chan, struct ast_channel *base);
336 };
337
338 struct ast_epoll_data;
339
340 /*!
341  * The high bit of the frame count is used as a debug marker, so
342  * increments of the counters must be done with care.
343  * Please use c->fin = FRAMECOUNT_INC(c->fin) and the same for c->fout.
344  */
345 #define DEBUGCHAN_FLAG  0x80000000
346
347 /* XXX not ideal to evaluate x twice... */
348 #define FRAMECOUNT_INC(x)       ( ((x) & DEBUGCHAN_FLAG) | (((x)+1) & ~DEBUGCHAN_FLAG) )
349
350 /*!
351  * The current value of the debug flags is stored in the two
352  * variables global_fin and global_fout (declared in main/channel.c)
353  */
354 extern unsigned long global_fin, global_fout;
355
356 enum ast_channel_adsicpe {
357         AST_ADSI_UNKNOWN,
358         AST_ADSI_AVAILABLE,
359         AST_ADSI_UNAVAILABLE,
360         AST_ADSI_OFFHOOKONLY,
361 };
362
363 /*! 
364  * \brief ast_channel states
365  *
366  * \note Bits 0-15 of state are reserved for the state (up/down) of the line
367  *       Bits 16-32 of state are reserved for flags
368  */
369 enum ast_channel_state {
370         AST_STATE_DOWN,                 /*!< Channel is down and available */
371         AST_STATE_RESERVED,             /*!< Channel is down, but reserved */
372         AST_STATE_OFFHOOK,              /*!< Channel is off hook */
373         AST_STATE_DIALING,              /*!< Digits (or equivalent) have been dialed */
374         AST_STATE_RING,                 /*!< Line is ringing */
375         AST_STATE_RINGING,              /*!< Remote end is ringing */
376         AST_STATE_UP,                   /*!< Line is up */
377         AST_STATE_BUSY,                 /*!< Line is busy */
378         AST_STATE_DIALING_OFFHOOK,      /*!< Digits (or equivalent) have been dialed while offhook */
379         AST_STATE_PRERING,              /*!< Channel has detected an incoming call and is waiting for ring */
380
381         AST_STATE_MUTE = (1 << 16),     /*!< Do not transmit voice data */
382 };
383
384 /*! \brief Main Channel structure associated with a channel. 
385  * This is the side of it mostly used by the pbx and call management.
386  *
387  * \note XXX It is important to remember to increment .cleancount each time
388  *       this structure is changed. XXX
389  */
390
391 struct ast_channel {
392         const struct ast_channel_tech *tech;            /*!< Technology (point to channel driver) */
393
394         void *tech_pvt;                                 /*!< Private data used by the technology driver */
395
396         AST_DECLARE_STRING_FIELDS(
397                 AST_STRING_FIELD(name);                 /*!< ASCII unique channel name */
398                 AST_STRING_FIELD(language);             /*!< Language requested for voice prompts */
399                 AST_STRING_FIELD(musicclass);           /*!< Default music class */
400                 AST_STRING_FIELD(accountcode);          /*!< Account code for billing */
401                 AST_STRING_FIELD(call_forward);         /*!< Where to forward to if asked to dial on this interface */
402                 AST_STRING_FIELD(uniqueid);             /*!< Unique Channel Identifier */
403         );
404         
405         int fds[AST_MAX_FDS];                           /*!< File descriptors for channel -- Drivers will poll on
406                                                                 these file descriptors, so at least one must be non -1.
407                                                                  See \arg \ref AstFileDesc */
408
409         void *music_state;                              /*!< Music State*/
410         void *generatordata;                            /*!< Current generator data if there is any */
411         struct ast_generator *generator;                /*!< Current active data generator */
412
413         struct ast_channel *_bridge;                    /*!< Who are we bridged to, if we're bridged.
414                                                                 Who is proxying for us, if we are proxied (i.e. chan_agent).
415                                                                 Do not access directly, use ast_bridged_channel(chan) */
416
417         struct ast_channel *masq;                       /*!< Channel that will masquerade as us */
418         struct ast_channel *masqr;                      /*!< Who we are masquerading as */
419         int cdrflags;                                   /*!< Call Detail Record Flags */
420
421         int _softhangup;                                /*!< Whether or not we have been hung up...  Do not set this value
422                                                                 directly, use ast_softhangup() */
423         time_t  whentohangup;                           /*!< Non-zero, set to actual time when channel is to be hung up */
424         pthread_t blocker;                              /*!< If anyone is blocking, this is them */
425         ast_mutex_t lock_dont_use;                      /*!< Lock a channel for some operations. See ast_channel_lock() */
426         const char *blockproc;                          /*!< Procedure causing blocking */
427
428         const char *appl;                               /*!< Current application */
429         const char *data;                               /*!< Data passed to current application */
430         int fdno;                                       /*!< Which fd had an event detected on */
431         struct sched_context *sched;                    /*!< Schedule context */
432         int streamid;                                   /*!< For streaming playback, the schedule ID */
433         struct ast_filestream *stream;                  /*!< Stream itself. */
434         int vstreamid;                                  /*!< For streaming video playback, the schedule ID */
435         struct ast_filestream *vstream;                 /*!< Video Stream itself. */
436         int oldwriteformat;                             /*!< Original writer format */
437         
438         int timingfd;                                   /*!< Timing fd */
439         int (*timingfunc)(const void *data);
440         void *timingdata;
441
442         enum ast_channel_state _state;                  /*!< State of line -- Don't write directly, use ast_setstate() */
443         int rings;                                      /*!< Number of rings so far */
444         struct ast_callerid cid;                        /*!< Caller ID, name, presentation etc */
445         char dtmfq[AST_MAX_EXTENSION];                  /*!< Any/all queued DTMF characters */
446         struct ast_frame dtmff;                         /*!< DTMF frame */
447
448         char context[AST_MAX_CONTEXT];                  /*!< Dialplan: Current extension context */
449         char exten[AST_MAX_EXTENSION];                  /*!< Dialplan: Current extension number */
450         int priority;                                   /*!< Dialplan: Current extension priority */
451         char macrocontext[AST_MAX_CONTEXT];             /*!< Macro: Current non-macro context. See app_macro.c */
452         char macroexten[AST_MAX_EXTENSION];             /*!< Macro: Current non-macro extension. See app_macro.c */
453         int macropriority;                              /*!< Macro: Current non-macro priority. See app_macro.c */
454         char dialcontext[AST_MAX_CONTEXT];              /*!< Dial: Extension context that we were called from */
455
456         struct ast_pbx *pbx;                            /*!< PBX private structure for this channel */
457         int amaflags;                                   /*!< Set BEFORE PBX is started to determine AMA flags */
458         struct ast_cdr *cdr;                            /*!< Call Detail Record */
459         enum ast_channel_adsicpe adsicpe;               /*!< Whether or not ADSI is detected on CPE */
460
461         struct ind_tone_zone *zone;                     /*!< Tone zone as set in indications.conf or
462                                                                 in the CHANNEL dialplan function */
463
464         struct ast_channel_monitor *monitor;            /*!< Channel monitoring */
465
466         unsigned long insmpl;                           /*!< Track the read/written samples for monitor use */
467         unsigned long outsmpl;                          /*!< Track the read/written samples for monitor use */
468
469         unsigned int fin;                               /*!< Frames in counters. The high bit is a debug mask, so
470                                                                 the counter is only in the remaining bits */
471         unsigned int fout;                              /*!< Frames out counters. The high bit is a debug mask, so
472                                                                 the counter is only in the remaining bits */
473         int hangupcause;                                /*!< Why is the channel hanged up. See causes.h */
474         struct varshead varshead;                       /*!< A linked list for channel variables. See \ref AstChanVar */
475         ast_group_t callgroup;                          /*!< Call group for call pickups */
476         ast_group_t pickupgroup;                        /*!< Pickup group - which calls groups can be picked up? */
477         unsigned int flags;                             /*!< channel flags of AST_FLAG_ type */
478         unsigned short transfercapability;              /*!< ISDN Transfer Capbility - AST_FLAG_DIGITAL is not enough */
479         AST_LIST_HEAD_NOLOCK(, ast_frame) readq;
480         int alertpipe[2];
481
482         int nativeformats;                              /*!< Kinds of data this channel can natively handle */
483         int readformat;                                 /*!< Requested read format */
484         int writeformat;                                /*!< Requested write format */
485         struct ast_trans_pvt *writetrans;               /*!< Write translation path */
486         struct ast_trans_pvt *readtrans;                /*!< Read translation path */
487         int rawreadformat;                              /*!< Raw read format */
488         int rawwriteformat;                             /*!< Raw write format */
489
490         struct ast_audiohook_list *audiohooks;
491
492         AST_LIST_ENTRY(ast_channel) chan_list;          /*!< For easy linking */
493         
494         struct ast_jb jb;                               /*!< The jitterbuffer state  */
495
496         char emulate_dtmf_digit;                        /*!< Digit being emulated */
497         unsigned int emulate_dtmf_duration;             /*!< Number of ms left to emulate DTMF for */
498         struct timeval dtmf_tv;                         /*!< The time that an in process digit began, or the last digit ended */
499
500         AST_LIST_HEAD_NOLOCK(datastores, ast_datastore) datastores; /*!< Data stores on the channel */
501
502 #ifdef HAVE_EPOLL
503         int epfd;
504         struct ast_epoll_data *epfd_data[AST_MAX_FDS];
505 #endif
506 };
507
508 /*! \brief ast_channel_tech Properties */
509 enum {
510         /*! \brief Channels have this property if they can accept input with jitter; 
511          *         i.e. most VoIP channels */
512         AST_CHAN_TP_WANTSJITTER = (1 << 0),
513         /*! \brief Channels have this property if they can create jitter; 
514          *         i.e. most VoIP channels */
515         AST_CHAN_TP_CREATESJITTER = (1 << 1),
516 };
517
518 /*! \brief ast_channel flags */
519 enum {
520         /*! Queue incoming dtmf, to be released when this flag is turned off */
521         AST_FLAG_DEFER_DTMF =    (1 << 1),
522         /*! write should be interrupt generator */
523         AST_FLAG_WRITE_INT =     (1 << 2),
524         /*! a thread is blocking on this channel */
525         AST_FLAG_BLOCKING =      (1 << 3),
526         /*! This is a zombie channel */
527         AST_FLAG_ZOMBIE =        (1 << 4),
528         /*! There is an exception pending */
529         AST_FLAG_EXCEPTION =     (1 << 5),
530         /*! Listening to moh XXX anthm promises me this will disappear XXX */
531         AST_FLAG_MOH =           (1 << 6),
532         /*! This channel is spying on another channel */
533         AST_FLAG_SPYING =        (1 << 7),
534         /*! This channel is in a native bridge */
535         AST_FLAG_NBRIDGE =       (1 << 8),
536         /*! the channel is in an auto-incrementing dialplan processor,
537          *  so when ->priority is set, it will get incremented before
538          *  finding the next priority to run */
539         AST_FLAG_IN_AUTOLOOP =   (1 << 9),
540         /*! This is an outgoing call */
541         AST_FLAG_OUTGOING =      (1 << 10),
542         /*! A DTMF_BEGIN frame has been read from this channel, but not yet an END */
543         AST_FLAG_IN_DTMF =       (1 << 12),
544         /*! A DTMF_END was received when not IN_DTMF, so the length of the digit is 
545          *  currently being emulated */
546         AST_FLAG_EMULATE_DTMF =  (1 << 13),
547         /*! This is set to tell the channel not to generate DTMF begin frames, and
548          *  to instead only generate END frames. */
549         AST_FLAG_END_DTMF_ONLY = (1 << 14),
550         /*! Flag to show channels that this call is hangup due to the fact that the call
551             was indeed anwered, but in another channel */
552         AST_FLAG_ANSWERED_ELSEWHERE = (1 << 15),
553         /*! This flag indicates that on a masquerade, an active stream should not
554          *  be carried over */
555         AST_FLAG_MASQ_NOSTREAM = (1 << 16),
556 };
557
558 /*! \brief ast_bridge_config flags */
559 enum {
560         AST_FEATURE_PLAY_WARNING = (1 << 0),
561         AST_FEATURE_REDIRECT =     (1 << 1),
562         AST_FEATURE_DISCONNECT =   (1 << 2),
563         AST_FEATURE_ATXFER =       (1 << 3),
564         AST_FEATURE_AUTOMON =      (1 << 4),
565         AST_FEATURE_PARKCALL =     (1 << 5),
566 };
567
568 /*! \brief bridge configuration */
569 struct ast_bridge_config {
570         struct ast_flags features_caller;
571         struct ast_flags features_callee;
572         struct timeval start_time;
573         long feature_timer;
574         long timelimit;
575         long play_warning;
576         long warning_freq;
577         const char *warning_sound;
578         const char *end_sound;
579         const char *start_sound;
580         int firstpass;
581         unsigned int flags;
582 };
583
584 struct chanmon;
585
586 struct outgoing_helper {
587         const char *context;
588         const char *exten;
589         int priority;
590         const char *cid_num;
591         const char *cid_name;
592         const char *account;
593         struct ast_variable *vars;
594         struct ast_channel *parent_channel;
595 };
596
597 enum {
598         AST_CDR_TRANSFER =   (1 << 0),
599         AST_CDR_FORWARD =    (1 << 1),
600         AST_CDR_CALLWAIT =   (1 << 2),
601         AST_CDR_CONFERENCE = (1 << 3),
602 };
603
604 enum {
605         /*! Soft hangup by device */
606         AST_SOFTHANGUP_DEV =       (1 << 0),
607         /*! Soft hangup for async goto */
608         AST_SOFTHANGUP_ASYNCGOTO = (1 << 1),
609         AST_SOFTHANGUP_SHUTDOWN =  (1 << 2),
610         AST_SOFTHANGUP_TIMEOUT =   (1 << 3),
611         AST_SOFTHANGUP_APPUNLOAD = (1 << 4),
612         AST_SOFTHANGUP_EXPLICIT =  (1 << 5),
613         AST_SOFTHANGUP_UNBRIDGE =  (1 << 6),
614 };
615
616
617 /*! \brief Channel reload reasons for manager events at load or reload of configuration */
618 enum channelreloadreason {
619         CHANNEL_MODULE_LOAD,
620         CHANNEL_MODULE_RELOAD,
621         CHANNEL_CLI_RELOAD,
622         CHANNEL_MANAGER_RELOAD,
623 };
624
625 /*! 
626  * \brief Create a channel datastore structure 
627  *
628  * \note None of the datastore API calls lock the ast_channel they are using.
629  *       So, the channel should be locked before calling the functions that
630  *       take a channel argument.
631  */
632 struct ast_datastore *ast_channel_datastore_alloc(const struct ast_datastore_info *info, const char *uid);
633
634 /*! \brief Free a channel datastore structure */
635 int ast_channel_datastore_free(struct ast_datastore *datastore);
636
637 /*! \brief Inherit datastores from a parent to a child. */
638 int ast_channel_datastore_inherit(struct ast_channel *from, struct ast_channel *to);
639
640 /*! \brief Add a datastore to a channel */
641 int ast_channel_datastore_add(struct ast_channel *chan, struct ast_datastore *datastore);
642
643 /*! \brief Remove a datastore from a channel */
644 int ast_channel_datastore_remove(struct ast_channel *chan, struct ast_datastore *datastore);
645
646 /*! \brief Find a datastore on a channel */
647 struct ast_datastore *ast_channel_datastore_find(struct ast_channel *chan, const struct ast_datastore_info *info, const char *uid);
648
649 /*! \brief Change the state of a channel */
650 int ast_setstate(struct ast_channel *chan, enum ast_channel_state);
651
652 /*! \brief Create a channel structure 
653     \return Returns NULL on failure to allocate.
654         \note New channels are 
655         by default set to the "default" context and
656         extension "s"
657  */
658 struct ast_channel *ast_channel_alloc(int needqueue, int state, const char *cid_num, const char *cid_name, const char *acctcode, const char *exten, const char *context, const int amaflag, const char *name_fmt, ...);
659
660 /*! \brief Queue an outgoing frame */
661 int ast_queue_frame(struct ast_channel *chan, struct ast_frame *f);
662
663 /*! \brief Queue a hangup frame */
664 int ast_queue_hangup(struct ast_channel *chan);
665
666 /*!
667   \brief Queue a control frame with payload
668   \param chan channel to queue frame onto
669   \param control type of control frame
670   \return zero on success, non-zero on failure
671 */
672 int ast_queue_control(struct ast_channel *chan, enum ast_control_frame_type control);
673
674 /*!
675   \brief Queue a control frame with payload
676   \param chan channel to queue frame onto
677   \param control type of control frame
678   \param data pointer to payload data to be included in frame
679   \param datalen number of bytes of payload data
680   \return zero on success, non-zero on failure
681
682   The supplied payload data is copied into the frame, so the caller's copy
683   is not modified nor freed, and the resulting frame will retain a copy of
684   the data even if the caller frees their local copy.
685
686   \note This method should be treated as a 'network transport'; in other
687   words, your frames may be transferred across an IAX2 channel to another
688   system, which may be a different endianness than yours. Because of this,
689   you should ensure that either your frames will never be expected to work
690   across systems, or that you always put your payload data into 'network byte
691   order' before calling this function.
692 */
693 int ast_queue_control_data(struct ast_channel *chan, enum ast_control_frame_type control,
694                            const void *data, size_t datalen);
695
696 /*! \brief Change channel name */
697 void ast_change_name(struct ast_channel *chan, char *newname);
698
699 /*! \brief Free a channel structure */
700 void  ast_channel_free(struct ast_channel *);
701
702 /*! \brief Requests a channel 
703  * \param type type of channel to request
704  * \param format requested channel format (codec)
705  * \param data data to pass to the channel requester
706  * \param status status
707  * Request a channel of a given type, with data as optional information used 
708  * by the low level module
709  * \return Returns an ast_channel on success, NULL on failure.
710  */
711 struct ast_channel *ast_request(const char *type, int format, void *data, int *status);
712
713 /*!
714  * \brief Request a channel of a given type, with data as optional information used 
715  * by the low level module and attempt to place a call on it
716  * \param type type of channel to request
717  * \param format requested channel format
718  * \param data data to pass to the channel requester
719  * \param timeout maximum amount of time to wait for an answer
720  * \param reason why unsuccessful (if unsuccessful)
721  * \param cidnum Caller-ID Number
722  * \param cidname Caller-ID Name
723  * \return Returns an ast_channel on success or no answer, NULL on failure.  Check the value of chan->_state
724  * to know if the call was answered or not.
725  */
726 struct ast_channel *ast_request_and_dial(const char *type, int format, void *data,
727         int timeout, int *reason, const char *cidnum, const char *cidname);
728
729 struct ast_channel *__ast_request_and_dial(const char *type, int format, void *data,
730         int timeout, int *reason, const char *cidnum, const char *cidname, struct outgoing_helper *oh);
731
732 /*!\brief Register a channel technology (a new channel driver)
733  * Called by a channel module to register the kind of channels it supports.
734  * \param tech Structure defining channel technology or "type"
735  * \return Returns 0 on success, -1 on failure.
736  */
737 int ast_channel_register(const struct ast_channel_tech *tech);
738
739 /*! \brief Unregister a channel technology 
740  * \param tech Structure defining channel technology or "type" that was previously registered
741  * \return No return value.
742  */
743 void ast_channel_unregister(const struct ast_channel_tech *tech);
744
745 /*! \brief Get a channel technology structure by name
746  * \param name name of technology to find
747  * \return a pointer to the structure, or NULL if no matching technology found
748  */
749 const struct ast_channel_tech *ast_get_channel_tech(const char *name);
750
751 /*! \brief Hang up a channel  
752  * \note This function performs a hard hangup on a channel.  Unlike the soft-hangup, this function
753  * performs all stream stopping, etc, on the channel that needs to end.
754  * chan is no longer valid after this call.
755  * \param chan channel to hang up
756  * \return Returns 0 on success, -1 on failure.
757  */
758 int ast_hangup(struct ast_channel *chan);
759
760 /*! \brief Softly hangup up a channel 
761  * \param chan channel to be soft-hung-up
762  * Call the protocol layer, but don't destroy the channel structure (use this if you are trying to
763  * safely hangup a channel managed by another thread.
764  * \param cause Ast hangupcause for hangup
765  * \return Returns 0 regardless
766  */
767 int ast_softhangup(struct ast_channel *chan, int cause);
768
769 /*! \brief Softly hangup up a channel (no channel lock) 
770  * \param chan channel to be soft-hung-up
771  * \param cause Ast hangupcause for hangup (see cause.h) */
772 int ast_softhangup_nolock(struct ast_channel *chan, int cause);
773
774 /*! \brief Check to see if a channel is needing hang up 
775  * \param chan channel on which to check for hang up
776  * This function determines if the channel is being requested to be hung up.
777  * \return Returns 0 if not, or 1 if hang up is requested (including time-out).
778  */
779 int ast_check_hangup(struct ast_channel *chan);
780
781 /*! \brief Compare a offset with the settings of when to hang a channel up 
782  * \param chan channel on which to check for hang up
783  * \param offset offset in seconds from current time
784  * \return 1, 0, or -1
785  * This function compares a offset from current time with the absolute time 
786  * out on a channel (when to hang up). If the absolute time out on a channel
787  * is earlier than current time plus the offset, it returns 1, if the two
788  * time values are equal, it return 0, otherwise, it return -1.
789  */
790 int ast_channel_cmpwhentohangup(struct ast_channel *chan, time_t offset);
791
792 /*! \brief Set when to hang a channel up 
793  * \param chan channel on which to check for hang up
794  * \param offset offset in seconds from current time of when to hang up
795  * This function sets the absolute time out on a channel (when to hang up).
796  */
797 void ast_channel_setwhentohangup(struct ast_channel *chan, time_t offset);
798
799 /*! \brief Answer a channel
800  * \param chan channel to answer
801  * This function answers a channel and handles all necessary call
802  * setup functions.
803  * \return Returns 0 on success, non-zero on failure
804  */
805 int ast_answer(struct ast_channel *chan);
806 int __ast_answer(struct ast_channel *chan, unsigned int delay);
807
808 /*! \brief Make a call 
809  * \param chan which channel to make the call on
810  * \param addr destination of the call
811  * \param timeout time to wait on for connect
812  * Place a call, take no longer than timeout ms. 
813    \return Returns -1 on failure, 0 on not enough time 
814    (does not automatically stop ringing), and  
815    the number of seconds the connect took otherwise.
816    */
817 int ast_call(struct ast_channel *chan, char *addr, int timeout);
818
819 /*! \brief Indicates condition of channel 
820  * \note Indicate a condition such as AST_CONTROL_BUSY, AST_CONTROL_RINGING, or AST_CONTROL_CONGESTION on a channel
821  * \param chan channel to change the indication
822  * \param condition which condition to indicate on the channel
823  * \return Returns 0 on success, -1 on failure
824  */
825 int ast_indicate(struct ast_channel *chan, int condition);
826
827 /*! \brief Indicates condition of channel, with payload
828  * \note Indicate a condition such as AST_CONTROL_HOLD with payload being music on hold class
829  * \param chan channel to change the indication
830  * \param condition which condition to indicate on the channel
831  * \param data pointer to payload data
832  * \param datalen size of payload data
833  * \return Returns 0 on success, -1 on failure
834  */
835 int ast_indicate_data(struct ast_channel *chan, int condition, const void *data, size_t datalen);
836
837 /* Misc stuff ------------------------------------------------ */
838
839 /*! \brief Wait for input on a channel 
840  * \param chan channel to wait on
841  * \param ms length of time to wait on the channel
842  * Wait for input on a channel for a given # of milliseconds (<0 for indefinite). 
843   \return Returns < 0 on  failure, 0 if nothing ever arrived, and the # of ms remaining otherwise */
844 int ast_waitfor(struct ast_channel *chan, int ms);
845
846 /*! \brief Wait for a specified amount of time, looking for hangups 
847  * \param chan channel to wait for
848  * \param ms length of time in milliseconds to sleep
849  * Waits for a specified amount of time, servicing the channel as required.
850  * \return returns -1 on hangup, otherwise 0.
851  */
852 int ast_safe_sleep(struct ast_channel *chan, int ms);
853
854 /*! \brief Wait for a specified amount of time, looking for hangups and a condition argument 
855  * \param chan channel to wait for
856  * \param ms length of time in milliseconds to sleep
857  * \param cond a function pointer for testing continue condition
858  * \param data argument to be passed to the condition test function
859  * \return returns -1 on hangup, otherwise 0.
860  * Waits for a specified amount of time, servicing the channel as required. If cond
861  * returns 0, this function returns.
862  */
863 int ast_safe_sleep_conditional(struct ast_channel *chan, int ms, int (*cond)(void*), void *data );
864
865 /*! \brief Waits for activity on a group of channels 
866  * \param chan an array of pointers to channels
867  * \param n number of channels that are to be waited upon
868  * \param fds an array of fds to wait upon
869  * \param nfds the number of fds to wait upon
870  * \param exception exception flag
871  * \param outfd fd that had activity on it
872  * \param ms how long the wait was
873  * Big momma function here.  Wait for activity on any of the n channels, or any of the nfds
874    file descriptors.
875    \return Returns the channel with activity, or NULL on error or if an FD
876    came first.  If the FD came first, it will be returned in outfd, otherwise, outfd
877    will be -1 */
878 struct ast_channel *ast_waitfor_nandfds(struct ast_channel **chan, int n,
879         int *fds, int nfds, int *exception, int *outfd, int *ms);
880
881 /*! \brief Waits for input on a group of channels
882    Wait for input on an array of channels for a given # of milliseconds. 
883         \return Return channel with activity, or NULL if none has activity.  
884         \param chan an array of pointers to channels
885         \param n number of channels that are to be waited upon
886         \param ms time "ms" is modified in-place, if applicable */
887 struct ast_channel *ast_waitfor_n(struct ast_channel **chan, int n, int *ms);
888
889 /*! \brief Waits for input on an fd
890         This version works on fd's only.  Be careful with it. */
891 int ast_waitfor_n_fd(int *fds, int n, int *ms, int *exception);
892
893
894 /*! \brief Reads a frame
895  * \param chan channel to read a frame from
896  * \return Returns a frame, or NULL on error.  If it returns NULL, you
897         best just stop reading frames and assume the channel has been
898         disconnected. */
899 struct ast_frame *ast_read(struct ast_channel *chan);
900
901 /*! \brief Reads a frame, returning AST_FRAME_NULL frame if audio. 
902         \param chan channel to read a frame from
903         \return  Returns a frame, or NULL on error.  If it returns NULL, you
904                 best just stop reading frames and assume the channel has been
905                 disconnected.  
906         \note Audio is replaced with AST_FRAME_NULL to avoid 
907         transcode when the resulting audio is not necessary. */
908 struct ast_frame *ast_read_noaudio(struct ast_channel *chan);
909
910 /*! \brief Write a frame to a channel 
911  * This function writes the given frame to the indicated channel.
912  * \param chan destination channel of the frame
913  * \param frame frame that will be written
914  * \return It returns 0 on success, -1 on failure.
915  */
916 int ast_write(struct ast_channel *chan, struct ast_frame *frame);
917
918 /*! \brief Write video frame to a channel 
919  * This function writes the given frame to the indicated channel.
920  * \param chan destination channel of the frame
921  * \param frame frame that will be written
922  * \return It returns 1 on success, 0 if not implemented, and -1 on failure.
923  */
924 int ast_write_video(struct ast_channel *chan, struct ast_frame *frame);
925
926 /*! \brief Write text frame to a channel 
927  * This function writes the given frame to the indicated channel.
928  * \param chan destination channel of the frame
929  * \param frame frame that will be written
930  * \return It returns 1 on success, 0 if not implemented, and -1 on failure.
931  */
932 int ast_write_text(struct ast_channel *chan, struct ast_frame *frame);
933
934 /*! \brief Send empty audio to prime a channel driver */
935 int ast_prod(struct ast_channel *chan);
936
937 /*! \brief Sets read format on channel chan
938  * Set read format for channel to whichever component of "format" is best. 
939  * \param chan channel to change
940  * \param format format to change to
941  * \return Returns 0 on success, -1 on failure
942  */
943 int ast_set_read_format(struct ast_channel *chan, int format);
944
945 /*! \brief Sets write format on channel chan
946  * Set write format for channel to whichever component of "format" is best. 
947  * \param chan channel to change
948  * \param format new format for writing
949  * \return Returns 0 on success, -1 on failure
950  */
951 int ast_set_write_format(struct ast_channel *chan, int format);
952
953 /*! \brief Sends text to a channel 
954  * Write text to a display on a channel
955  * \param chan channel to act upon
956  * \param text string of text to send on the channel
957  * \return Returns 0 on success, -1 on failure
958  */
959 int ast_sendtext(struct ast_channel *chan, const char *text);
960
961 /*! \brief Receives a text character from a channel
962  * \param chan channel to act upon
963  * \param timeout timeout in milliseconds (0 for infinite wait)
964  * Read a char of text from a channel
965  * Returns 0 on success, -1 on failure
966  */
967 int ast_recvchar(struct ast_channel *chan, int timeout);
968
969 /*! \brief Send a DTMF digit to a channel
970  * Send a DTMF digit to a channel.
971  * \param chan channel to act upon
972  * \param digit the DTMF digit to send, encoded in ASCII
973  * \param duration the duration of the digit ending in ms
974  * \return Returns 0 on success, -1 on failure
975  */
976 int ast_senddigit(struct ast_channel *chan, char digit, unsigned int duration);
977
978 /*! \brief Send a DTMF digit to a channel
979  * Send a DTMF digit to a channel.
980  * \param chan channel to act upon
981  * \param digit the DTMF digit to send, encoded in ASCII
982  * \return Returns 0 on success, -1 on failure
983  */
984 int ast_senddigit_begin(struct ast_channel *chan, char digit);
985
986 /*! \brief Send a DTMF digit to a channel
987
988  * Send a DTMF digit to a channel.
989  * \param chan channel to act upon
990  * \param digit the DTMF digit to send, encoded in ASCII
991  * \param duration the duration of the digit ending in ms
992  * \return Returns 0 on success, -1 on failure
993  */
994 int ast_senddigit_end(struct ast_channel *chan, char digit, unsigned int duration);
995
996 /*! \brief Receives a text string from a channel
997  * Read a string of text from a channel
998  * \param chan channel to act upon
999  * \param timeout timeout in milliseconds (0 for infinite wait)
1000  * \return the received text, or NULL to signify failure.
1001  */
1002 char *ast_recvtext(struct ast_channel *chan, int timeout);
1003
1004 /*! \brief Browse channels in use
1005  * Browse the channels currently in use 
1006  * \param prev where you want to start in the channel list
1007  * \return Returns the next channel in the list, NULL on end.
1008  *      If it returns a channel, that channel *has been locked*!
1009  */
1010 struct ast_channel *ast_channel_walk_locked(const struct ast_channel *prev);
1011
1012 /*! \brief Get channel by name (locks channel) */
1013 struct ast_channel *ast_get_channel_by_name_locked(const char *chan);
1014
1015 /*! \brief Get channel by name prefix (locks channel) */
1016 struct ast_channel *ast_get_channel_by_name_prefix_locked(const char *name, const int namelen);
1017
1018 /*! \brief Get channel by name prefix (locks channel) */
1019 struct ast_channel *ast_walk_channel_by_name_prefix_locked(const struct ast_channel *chan, const char *name, const int namelen);
1020
1021 /*! \brief Get channel by exten (and optionally context) and lock it */
1022 struct ast_channel *ast_get_channel_by_exten_locked(const char *exten, const char *context);
1023
1024 /*! \brief Get next channel by exten (and optionally context) and lock it */
1025 struct ast_channel *ast_walk_channel_by_exten_locked(const struct ast_channel *chan, const char *exten,
1026                                                      const char *context);
1027
1028 /*! ! \brief Waits for a digit
1029  * \param c channel to wait for a digit on
1030  * \param ms how many milliseconds to wait
1031  * \return Returns <0 on error, 0 on no entry, and the digit on success. */
1032 int ast_waitfordigit(struct ast_channel *c, int ms);
1033
1034 /*! \brief Wait for a digit
1035  Same as ast_waitfordigit() with audio fd for outputting read audio and ctrlfd to monitor for reading. 
1036  * \param c channel to wait for a digit on
1037  * \param ms how many milliseconds to wait
1038  * \param audiofd audio file descriptor to write to if audio frames are received
1039  * \param ctrlfd control file descriptor to monitor for reading
1040  * \return Returns 1 if ctrlfd becomes available */
1041 int ast_waitfordigit_full(struct ast_channel *c, int ms, int audiofd, int ctrlfd);
1042
1043 /*! Reads multiple digits 
1044  * \param c channel to read from
1045  * \param s string to read in to.  Must be at least the size of your length
1046  * \param len how many digits to read (maximum)
1047  * \param timeout how long to timeout between digits
1048  * \param rtimeout timeout to wait on the first digit
1049  * \param enders digits to end the string
1050  * Read in a digit string "s", max length "len", maximum timeout between 
1051    digits "timeout" (-1 for none), terminated by anything in "enders".  Give them rtimeout
1052    for the first digit.  Returns 0 on normal return, or 1 on a timeout.  In the case of
1053    a timeout, any digits that were read before the timeout will still be available in s.  
1054    RETURNS 2 in full version when ctrlfd is available, NOT 1*/
1055 int ast_readstring(struct ast_channel *c, char *s, int len, int timeout, int rtimeout, char *enders);
1056 int ast_readstring_full(struct ast_channel *c, char *s, int len, int timeout, int rtimeout, char *enders, int audiofd, int ctrlfd);
1057
1058 /*! \brief Report DTMF on channel 0 */
1059 #define AST_BRIDGE_DTMF_CHANNEL_0               (1 << 0)                
1060 /*! \brief Report DTMF on channel 1 */
1061 #define AST_BRIDGE_DTMF_CHANNEL_1               (1 << 1)                
1062 /*! \brief Return all voice frames on channel 0 */
1063 #define AST_BRIDGE_REC_CHANNEL_0                (1 << 2)                
1064 /*! \brief Return all voice frames on channel 1 */
1065 #define AST_BRIDGE_REC_CHANNEL_1                (1 << 3)                
1066 /*! \brief Ignore all signal frames except NULL */
1067 #define AST_BRIDGE_IGNORE_SIGS                  (1 << 4)                
1068
1069
1070 /*! \brief Makes two channel formats compatible 
1071  * \param c0 first channel to make compatible
1072  * \param c1 other channel to make compatible
1073  * Set two channels to compatible formats -- call before ast_channel_bridge in general .  
1074  * \return Returns 0 on success and -1 if it could not be done */
1075 int ast_channel_make_compatible(struct ast_channel *c0, struct ast_channel *c1);
1076
1077 /*! Bridge two channels together (early)
1078  * \param c0 first channel to bridge
1079  * \param c1 second channel to bridge
1080  * Bridge two channels (c0 and c1) together early. This implies either side may not be answered yet.
1081  * \return Returns 0 on success and -1 if it could not be done */
1082 int ast_channel_early_bridge(struct ast_channel *c0, struct ast_channel *c1);
1083
1084 /*! Bridge two channels together 
1085  * \param c0 first channel to bridge
1086  * \param c1 second channel to bridge
1087  * \param config config for the channels
1088  * \param fo destination frame(?)
1089  * \param rc destination channel(?)
1090  * Bridge two channels (c0 and c1) together.  If an important frame occurs, we return that frame in
1091    *rf (remember, it could be NULL) and which channel (0 or 1) in rc */
1092 /* int ast_channel_bridge(struct ast_channel *c0, struct ast_channel *c1, int flags, struct ast_frame **fo, struct ast_channel **rc); */
1093 int ast_channel_bridge(struct ast_channel *c0,struct ast_channel *c1,
1094         struct ast_bridge_config *config, struct ast_frame **fo, struct ast_channel **rc);
1095
1096 /*! \brief Weird function made for call transfers
1097  * \param original channel to make a copy of
1098  * \param clone copy of the original channel
1099  * This is a very strange and freaky function used primarily for transfer.  Suppose that
1100    "original" and "clone" are two channels in random situations.  This function takes
1101    the guts out of "clone" and puts them into the "original" channel, then alerts the
1102    channel driver of the change, asking it to fixup any private information (like the
1103    p->owner pointer) that is affected by the change.  The physical layer of the original
1104    channel is hung up.  */
1105 int ast_channel_masquerade(struct ast_channel *original, struct ast_channel *clone);
1106
1107 /*! Gives the string form of a given cause code */
1108 /*! 
1109  * \param state cause to get the description of
1110  * Give a name to a cause code
1111  * Returns the text form of the binary cause code given
1112  */
1113 const char *ast_cause2str(int state) attribute_pure;
1114
1115 /*! Convert the string form of a cause code to a number */
1116 /*! 
1117  * \param name string form of the cause
1118  * Returns the cause code
1119  */
1120 int ast_str2cause(const char *name) attribute_pure;
1121
1122 /*! Gives the string form of a given channel state */
1123 /*! 
1124  * \param ast_channel_state state to get the name of
1125  * Give a name to a state 
1126  * Returns the text form of the binary state given
1127  */
1128 const char *ast_state2str(enum ast_channel_state);
1129
1130 /*! Gives the string form of a given transfer capability */
1131 /*!
1132  * \param transfercapability transfercapabilty to get the name of
1133  * Give a name to a transfercapbility
1134  * See above
1135  * Returns the text form of the binary transfer capbaility
1136  */
1137 char *ast_transfercapability2str(int transfercapability) attribute_const;
1138
1139 /* Options: Some low-level drivers may implement "options" allowing fine tuning of the
1140    low level channel.  See frame.h for options.  Note that many channel drivers may support
1141    none or a subset of those features, and you should not count on this if you want your
1142    asterisk application to be portable.  They're mainly useful for tweaking performance */
1143
1144 /*! Sets an option on a channel */
1145 /*! 
1146  * \param channel channel to set options on
1147  * \param option option to change
1148  * \param data data specific to option
1149  * \param datalen length of the data
1150  * \param block blocking or not
1151  * Set an option on a channel (see frame.h), optionally blocking awaiting the reply 
1152  * Returns 0 on success and -1 on failure
1153  */
1154 int ast_channel_setoption(struct ast_channel *channel, int option, void *data, int datalen, int block);
1155
1156 /*! Pick the best codec  */
1157 /* Choose the best codec...  Uhhh...   Yah. */
1158 int ast_best_codec(int fmts);
1159
1160
1161 /*! Checks the value of an option */
1162 /*! 
1163  * Query the value of an option, optionally blocking until a reply is received
1164  * Works similarly to setoption except only reads the options.
1165  */
1166 struct ast_frame *ast_channel_queryoption(struct ast_channel *channel, int option, void *data, int *datalen, int block);
1167
1168 /*! Checks for HTML support on a channel */
1169 /*! Returns 0 if channel does not support HTML or non-zero if it does */
1170 int ast_channel_supports_html(struct ast_channel *channel);
1171
1172 /*! Sends HTML on given channel */
1173 /*! Send HTML or URL on link.  Returns 0 on success or -1 on failure */
1174 int ast_channel_sendhtml(struct ast_channel *channel, int subclass, const char *data, int datalen);
1175
1176 /*! Sends a URL on a given link */
1177 /*! Send URL on link.  Returns 0 on success or -1 on failure */
1178 int ast_channel_sendurl(struct ast_channel *channel, const char *url);
1179
1180 /*! Defers DTMF */
1181 /*! Defer DTMF so that you only read things like hangups and audio.  Returns
1182    non-zero if channel was already DTMF-deferred or 0 if channel is just now
1183    being DTMF-deferred */
1184 int ast_channel_defer_dtmf(struct ast_channel *chan);
1185
1186 /*! Undo defer.  ast_read will return any dtmf characters that were queued */
1187 void ast_channel_undefer_dtmf(struct ast_channel *chan);
1188
1189 /*! Initiate system shutdown -- prevents new channels from being allocated.
1190     If "hangup" is non-zero, all existing channels will receive soft
1191      hangups */
1192 void ast_begin_shutdown(int hangup);
1193
1194 /*! Cancels an existing shutdown and returns to normal operation */
1195 void ast_cancel_shutdown(void);
1196
1197 /*! Returns number of active/allocated channels */
1198 int ast_active_channels(void);
1199
1200 /*! Returns non-zero if Asterisk is being shut down */
1201 int ast_shutting_down(void);
1202
1203 /*! Activate a given generator */
1204 int ast_activate_generator(struct ast_channel *chan, struct ast_generator *gen, void *params);
1205
1206 /*! Deactivate an active generator */
1207 void ast_deactivate_generator(struct ast_channel *chan);
1208
1209 void ast_set_callerid(struct ast_channel *chan, const char *cidnum, const char *cidname, const char *ani);
1210
1211 /*! Set the file descriptor on the channel */
1212 void ast_channel_set_fd(struct ast_channel *chan, int which, int fd);
1213
1214 /*! Add a channel to an optimized waitfor */
1215 void ast_poll_channel_add(struct ast_channel *chan0, struct ast_channel *chan1);
1216
1217 /*! Delete a channel from an optimized waitfor */
1218 void ast_poll_channel_del(struct ast_channel *chan0, struct ast_channel *chan1);
1219
1220 /*! Start a tone going */
1221 int ast_tonepair_start(struct ast_channel *chan, int freq1, int freq2, int duration, int vol);
1222 /*! Stop a tone from playing */
1223 void ast_tonepair_stop(struct ast_channel *chan);
1224 /*! Play a tone pair for a given amount of time */
1225 int ast_tonepair(struct ast_channel *chan, int freq1, int freq2, int duration, int vol);
1226
1227 /*!
1228  * \brief Automatically service a channel for us... 
1229  *
1230  * \retval 0 success
1231  * \retval -1 failure, or the channel is already being autoserviced
1232  */
1233 int ast_autoservice_start(struct ast_channel *chan);
1234
1235 /*! 
1236  * \brief Stop servicing a channel for us...  
1237  *
1238  * \retval 0 success
1239  * \retval -1 error, or the channel has been hungup 
1240  */
1241 int ast_autoservice_stop(struct ast_channel *chan);
1242
1243 /* If built with zaptel optimizations, force a scheduled expiration on the
1244    timer fd, at which point we call the callback function / data */
1245 int ast_settimeout(struct ast_channel *c, int samples, int (*func)(const void *data), void *data);
1246
1247 /*!     \brief Transfer a channel (if supported).  Returns -1 on error, 0 if not supported
1248    and 1 if supported and requested 
1249         \param chan current channel
1250         \param dest destination extension for transfer
1251 */
1252 int ast_transfer(struct ast_channel *chan, char *dest);
1253
1254 /*!     \brief  Start masquerading a channel
1255         XXX This is a seriously whacked out operation.  We're essentially putting the guts of
1256            the clone channel into the original channel.  Start by killing off the original
1257            channel's backend.   I'm not sure we're going to keep this function, because
1258            while the features are nice, the cost is very high in terms of pure nastiness. XXX
1259         \param chan     Channel to masquerade
1260 */
1261 int ast_do_masquerade(struct ast_channel *chan);
1262
1263 /*!     \brief Find bridged channel 
1264         \param chan Current channel
1265 */
1266 struct ast_channel *ast_bridged_channel(struct ast_channel *chan);
1267
1268 /*!
1269   \brief Inherits channel variable from parent to child channel
1270   \param parent Parent channel
1271   \param child Child channel
1272
1273   Scans all channel variables in the parent channel, looking for those
1274   that should be copied into the child channel.
1275   Variables whose names begin with a single '_' are copied into the
1276   child channel with the prefix removed.
1277   Variables whose names begin with '__' are copied into the child
1278   channel with their names unchanged.
1279 */
1280 void ast_channel_inherit_variables(const struct ast_channel *parent, struct ast_channel *child);
1281
1282 /*!
1283   \brief adds a list of channel variables to a channel
1284   \param chan the channel
1285   \param vars a linked list of variables
1286
1287   Variable names can be for a regular channel variable or a dialplan function
1288   that has the ability to be written to.
1289 */
1290 void ast_set_variables(struct ast_channel *chan, struct ast_variable *vars);
1291
1292 /*!
1293   \brief An opaque 'object' structure use by silence generators on channels.
1294  */
1295 struct ast_silence_generator;
1296
1297 /*!
1298   \brief Starts a silence generator on the given channel.
1299   \param chan The channel to generate silence on
1300   \return An ast_silence_generator pointer, or NULL if an error occurs
1301
1302   This function will cause SLINEAR silence to be generated on the supplied
1303   channel until it is disabled; if the channel cannot be put into SLINEAR
1304   mode then the function will fail.
1305
1306   The pointer returned by this function must be preserved and passed to
1307   ast_channel_stop_silence_generator when you wish to stop the silence
1308   generation.
1309  */
1310 struct ast_silence_generator *ast_channel_start_silence_generator(struct ast_channel *chan);
1311
1312 /*!
1313   \brief Stops a previously-started silence generator on the given channel.
1314   \param chan The channel to operate on
1315   \param state The ast_silence_generator pointer return by a previous call to
1316   ast_channel_start_silence_generator.
1317   \return nothing
1318
1319   This function will stop the operating silence generator and return the channel
1320   to its previous write format.
1321  */
1322 void ast_channel_stop_silence_generator(struct ast_channel *chan, struct ast_silence_generator *state);
1323
1324 /*!
1325   \brief Check if the channel can run in internal timing mode.
1326   \param chan The channel to check
1327   \return boolean
1328
1329   This function will return 1 if internal timing is enabled and the timing
1330   device is available.
1331  */
1332 int ast_internal_timing_enabled(struct ast_channel *chan);
1333
1334 /* Misc. functions below */
1335
1336 /*! \brief if fd is a valid descriptor, set *pfd with the descriptor
1337  * \return Return 1 (not -1!) if added, 0 otherwise (so we can add the
1338  * return value to the index into the array)
1339  */
1340 static inline int ast_add_fd(struct pollfd *pfd, int fd)
1341 {
1342         pfd->fd = fd;
1343         pfd->events = POLLIN | POLLPRI;
1344         return fd >= 0;
1345 }
1346
1347 /*! \brief Helper function for migrating select to poll */
1348 static inline int ast_fdisset(struct pollfd *pfds, int fd, int max, int *start)
1349 {
1350         int x;
1351         int dummy=0;
1352
1353         if (fd < 0)
1354                 return 0;
1355         if (!start)
1356                 start = &dummy;
1357         for (x = *start; x<max; x++)
1358                 if (pfds[x].fd == fd) {
1359                         if (x == *start)
1360                                 (*start)++;
1361                         return pfds[x].revents;
1362                 }
1363         return 0;
1364 }
1365
1366 #ifndef HAVE_TIMERSUB
1367 static inline void timersub(struct timeval *tvend, struct timeval *tvstart, struct timeval *tvdiff)
1368 {
1369         tvdiff->tv_sec = tvend->tv_sec - tvstart->tv_sec;
1370         tvdiff->tv_usec = tvend->tv_usec - tvstart->tv_usec;
1371         if (tvdiff->tv_usec < 0) {
1372                 tvdiff->tv_sec --;
1373                 tvdiff->tv_usec += 1000000;
1374         }
1375
1376 }
1377 #endif
1378
1379 /*! \brief Waits for activity on a group of channels 
1380  * \param nfds the maximum number of file descriptors in the sets
1381  * \param rfds file descriptors to check for read availability
1382  * \param wfds file descriptors to check for write availability
1383  * \param efds file descriptors to check for exceptions (OOB data)
1384  * \param tvp timeout while waiting for events
1385  * This is the same as a standard select(), except it guarantees the
1386  * behaviour where the passed struct timeval is updated with how much
1387  * time was not slept while waiting for the specified events
1388  */
1389 static inline int ast_select(int nfds, fd_set *rfds, fd_set *wfds, fd_set *efds, struct timeval *tvp)
1390 {
1391 #ifdef __linux__
1392         return select(nfds, rfds, wfds, efds, tvp);
1393 #else
1394         if (tvp) {
1395                 struct timeval tv, tvstart, tvend, tvlen;
1396                 int res;
1397
1398                 tv = *tvp;
1399                 gettimeofday(&tvstart, NULL);
1400                 res = select(nfds, rfds, wfds, efds, tvp);
1401                 gettimeofday(&tvend, NULL);
1402                 timersub(&tvend, &tvstart, &tvlen);
1403                 timersub(&tv, &tvlen, tvp);
1404                 if (tvp->tv_sec < 0 || (tvp->tv_sec == 0 && tvp->tv_usec < 0)) {
1405                         tvp->tv_sec = 0;
1406                         tvp->tv_usec = 0;
1407                 }
1408                 return res;
1409         }
1410         else
1411                 return select(nfds, rfds, wfds, efds, NULL);
1412 #endif
1413 }
1414
1415 #ifdef DO_CRASH
1416 #define CRASH do { fprintf(stderr, "!! Forcing immediate crash a-la abort !!\n"); *((int *)0) = 0; } while(0)
1417 #else
1418 #define CRASH do { } while(0)
1419 #endif
1420
1421 #define CHECK_BLOCKING(c) do {   \
1422         if (ast_test_flag(c, AST_FLAG_BLOCKING)) {\
1423                 if (option_debug) \
1424                         ast_log(LOG_DEBUG, "Thread %ld Blocking '%s', already blocked by thread %ld in procedure %s\n", (long) pthread_self(), (c)->name, (long) (c)->blocker, (c)->blockproc); \
1425                 CRASH; \
1426         } else { \
1427                 (c)->blocker = pthread_self(); \
1428                 (c)->blockproc = __PRETTY_FUNCTION__; \
1429                 ast_set_flag(c, AST_FLAG_BLOCKING); \
1430         } } while (0)
1431
1432 ast_group_t ast_get_group(const char *s);
1433
1434 /*! \brief print call- and pickup groups into buffer */
1435 char *ast_print_group(char *buf, int buflen, ast_group_t group);
1436
1437 /*! \brief Convert enum channelreloadreason to text string for manager event
1438         \param reason   Enum channelreloadreason - reason for reload (manager, cli, start etc)
1439 */
1440 const char *channelreloadreason2txt(enum channelreloadreason reason);
1441
1442 /*! \brief return an ast_variable list of channeltypes */
1443 struct ast_variable *ast_channeltype_list(void);
1444
1445 /*!
1446   \brief return an english explanation of the code returned thru __ast_request_and_dial's 'outstate' argument
1447   \param reason  The integer argument, usually taken from AST_CONTROL_ macros
1448   \return char pointer explaining the code
1449  */
1450 const char *ast_channel_reason2str(int reason);
1451
1452 /*! \brief channel group info
1453  */
1454 struct ast_group_info {
1455         struct ast_channel *chan;
1456         char *category;
1457         char *group;
1458         AST_LIST_ENTRY(ast_group_info) list;   
1459 };
1460
1461
1462 #if defined(__cplusplus) || defined(c_plusplus)
1463 }
1464 #endif
1465
1466 #endif /* _ASTERISK_CHANNEL_H */