Generic call forward api, ast_call_forward()
[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, DAHDI, 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 (DAHDI 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 bridging 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 #include "asterisk/astobj2.h"
128
129 #include "asterisk/poll-compat.h"
130
131 #if defined(__cplusplus) || defined(c_plusplus)
132 extern "C" {
133 #endif
134
135 #define AST_MAX_EXTENSION       80      /*!< Max length of an extension */
136 #define AST_MAX_CONTEXT         80      /*!< Max length of a context */
137 #define AST_CHANNEL_NAME        80      /*!< Max length of an ast_channel name */
138 #define MAX_LANGUAGE            20      /*!< Max length of the language setting */
139 #define MAX_MUSICCLASS          80      /*!< Max length of the music class setting */
140
141 #include "asterisk/frame.h"
142 #include "asterisk/sched.h"
143 #include "asterisk/chanvars.h"
144 #include "asterisk/config.h"
145 #include "asterisk/lock.h"
146 #include "asterisk/cdr.h"
147 #include "asterisk/utils.h"
148 #include "asterisk/linkedlists.h"
149 #include "asterisk/stringfields.h"
150 #include "asterisk/datastore.h"
151
152 #define DATASTORE_INHERIT_FOREVER       INT_MAX
153
154 #define AST_MAX_FDS             10
155 /*
156  * We have AST_MAX_FDS file descriptors in a channel.
157  * Some of them have a fixed use:
158  */
159 #define AST_ALERT_FD    (AST_MAX_FDS-1)         /*!< used for alertpipe */
160 #define AST_TIMING_FD   (AST_MAX_FDS-2)         /*!< used for timingfd */
161 #define AST_AGENT_FD    (AST_MAX_FDS-3)         /*!< used by agents for pass through */
162 #define AST_GENERATOR_FD        (AST_MAX_FDS-4) /*!< used by generator */
163
164 enum ast_bridge_result {
165         AST_BRIDGE_COMPLETE = 0,
166         AST_BRIDGE_FAILED = -1,
167         AST_BRIDGE_FAILED_NOWARN = -2,
168         AST_BRIDGE_RETRY = -3,
169 };
170
171 typedef unsigned long long ast_group_t;
172
173 /*! \todo Add an explanation of an Asterisk generator
174 */
175 struct ast_generator {
176         void *(*alloc)(struct ast_channel *chan, void *params);
177         void (*release)(struct ast_channel *chan, void *data);
178         /*! This function gets called with the channel unlocked, but is called in
179          *  the context of the channel thread so we know the channel is not going
180          *  to disappear.  This callback is responsible for locking the channel as
181          *  necessary. */
182         int (*generate)(struct ast_channel *chan, void *data, int len, int samples);
183         /*! This gets called when DTMF_END frames are read from the channel */
184         void (*digit)(struct ast_channel *chan, char digit);
185 };
186
187 /*!
188  * \brief Structure for all kinds of caller ID identifications.
189  * \note All string fields here are malloc'ed, so they need to be
190  * freed when the structure is deleted.
191  * Also, NULL and "" must be considered equivalent.
192  *
193  * \note SIP and IAX2 has utf8 encoded Unicode caller ID names.
194  * In some cases, we also have an alternative (RPID) E.164 number that can be used
195  * as caller ID on numeric E.164 phone networks (DAHDI or SIP/IAX2 to PSTN gateway).
196  *
197  * \todo Implement settings for transliteration between UTF8 caller ID names in
198  *       to Ascii Caller ID's (DAHDI). Östen Åsklund might be transliterated into
199  *       Osten Asklund or Oesten Aasklund depending upon language and person...
200  *       We need automatic routines for incoming calls and static settings for
201  *       our own accounts.
202  */
203 struct ast_callerid {
204         /*!
205          * \brief Malloc'd Dialed Number Identifier
206          * (Field will eventually move to struct ast_channel.dialed.number)
207          */
208         char *cid_dnid;
209
210         /*!
211          * \brief Malloc'd Caller Number
212          * (Field will eventually move to struct ast_channel.caller.id.number)
213          */
214         char *cid_num;
215
216         /*!
217          * \brief Malloc'd Caller Name (ASCII)
218          * (Field will eventually move to struct ast_channel.caller.id.name)
219          */
220         char *cid_name;
221
222         /*!
223          * \brief Malloc'd Automatic Number Identification (ANI)
224          * (Field will eventually move to struct ast_channel.caller.ani)
225          */
226         char *cid_ani;
227
228         /*!
229          * \brief Malloc'd Redirecting Directory Number Information Service (RDNIS)
230          * (Field will eventually move to struct ast_channel.redirecting.from.number)
231          */
232         char *cid_rdnis;
233
234         /*!
235          * \brief Callerid Q.931 encoded number presentation/screening fields
236          * (Field will eventually move to struct ast_channel.caller.id.number_presentation)
237          */
238         int cid_pres;
239
240         /*!
241          * \brief Callerid ANI 2 (Info digits)
242          * (Field will eventually move to struct ast_channel.caller.ani2)
243          */
244         int cid_ani2;
245
246         /*!
247          * \brief Callerid Q.931 encoded type-of-number/numbering-plan fields
248          * \note Currently this value is mostly just passed around the system.
249          * The H.323 interfaces set the value from received messages and uses the value for sent messages.
250          * The DAHDI PRI interfaces set the value from received messages but does not use it for sent messages.
251          * You can read it and set it but only H.323 uses it.
252          * (Field will eventually move to struct ast_channel.caller.id.number_type)
253          */
254         int cid_ton;
255
256         /*!
257          * \brief Callerid Transit Network Select
258          * \note Currently this value is just passed around the system.
259          * You can read it and set it but it is never used for anything.
260          * (Field will eventually move to struct ast_channel.dialed.transit_network_select)
261          */
262         int cid_tns;
263 };
264
265 /*!
266  * \since 1.6.3
267  * \brief Information needed to identify an endpoint in a call.
268  * \note All string fields here are malloc'ed, so they need to be
269  * freed when the structure is deleted.
270  * \note NULL and "" must be considered equivalent.
271  */
272 struct ast_party_id {
273         /*! \brief Subscriber phone number (Malloced) */
274         char *number;
275
276         /*! \brief Subscriber name (Malloced) */
277         char *name;
278
279         /*! \brief Q.931 encoded type-of-number/numbering-plan fields */
280         int number_type;
281
282         /*! \brief Q.931 encoded number presentation/screening fields */
283         int number_presentation;
284 };
285
286 /*!
287  * \since 1.6.3
288  * \brief Connected Line/Party information.
289  * \note All string fields here are malloc'ed, so they need to be
290  * freed when the structure is deleted.
291  * \note NULL and "" must be considered equivalent.
292  */
293 struct ast_party_connected_line {
294         struct ast_party_id id;         /*! \brief Connected party ID */
295
296         /*!
297          * \brief Automatic Number Identification (ANI) (Malloced)
298          * \note Not really part of connected line data but needed to
299          * save the corresponding caller id value.
300          */
301         char *ani;
302
303         /*!
304          * \brief Automatic Number Identification 2 (Info Digits)
305          * \note Not really part of connected line data but needed to
306          * save the corresponding caller id value.
307          */
308         int ani2;
309
310         /*!
311          * \brief Information about the source of an update.
312          * \note enum AST_CONNECTED_LINE_UPDATE_SOURCE values
313          * for Normal-Answer and Call-transfer.
314          */
315         int source;
316 };
317
318 /*!
319  * \since 1.6.3
320  * \brief Redirecting Line information.
321  * RDNIS (Redirecting Directory Number Information Service)
322  * Where a call diversion or transfer was invoked.
323  * \note All string fields here are malloc'ed, so they need to be
324  * freed when the structure is deleted.
325  * \note NULL and "" must be considered equivalent.
326  */
327 struct ast_party_redirecting {
328         /*! \brief Who is redirecting the call (Sent to the party the call is redirected toward) */
329         struct ast_party_id from;
330
331         /*! \brief Call is redirecting to a new party (Sent to the caller) */
332         struct ast_party_id to;
333
334         /*! \brief Number of times the call was redirected */
335         int count;
336
337         /*! \brief enum AST_REDIRECTING_REASON value for redirection */
338         int reason;
339 };
340
341 /*!
342  * \brief
343  * Structure to describe a channel "technology", ie a channel driver
344  * See for examples:
345  * \arg chan_iax2.c - The Inter-Asterisk exchange protocol
346  * \arg chan_sip.c - The SIP channel driver
347  * \arg chan_dahdi.c - PSTN connectivity (TDM, PRI, T1/E1, FXO, FXS)
348  *
349  * \details
350  * If you develop your own channel driver, this is where you
351  * tell the PBX at registration of your driver what properties
352  * this driver supports and where different callbacks are
353  * implemented.
354  */
355 struct ast_channel_tech {
356         const char * const type;
357         const char * const description;
358
359         int capabilities;               /*!< Bitmap of formats this channel can handle */
360
361         int properties;                 /*!< Technology Properties */
362
363         /*! \brief Requester - to set up call data structures (pvt's) */
364         struct ast_channel *(* const requester)(const char *type, int format, void *data, int *cause);
365
366         int (* const devicestate)(void *data);  /*!< Devicestate call back */
367
368         /*!
369          * \brief Start sending a literal DTMF digit
370          *
371          * \note The channel is not locked when this function gets called.
372          */
373         int (* const send_digit_begin)(struct ast_channel *chan, char digit);
374
375         /*!
376          * \brief Stop sending a literal DTMF digit
377          *
378          * \note The channel is not locked when this function gets called.
379          */
380         int (* const send_digit_end)(struct ast_channel *chan, char digit, unsigned int duration);
381
382         /*! \brief Call a given phone number (address, etc), but don't
383          *  take longer than timeout seconds to do so.  */
384         int (* const call)(struct ast_channel *chan, char *addr, int timeout);
385
386         /*! \brief Hangup (and possibly destroy) the channel */
387         int (* const hangup)(struct ast_channel *chan);
388
389         /*! \brief Answer the channel */
390         int (* const answer)(struct ast_channel *chan);
391
392         /*! \brief Read a frame, in standard format (see frame.h) */
393         struct ast_frame * (* const read)(struct ast_channel *chan);
394
395         /*! \brief Write a frame, in standard format (see frame.h) */
396         int (* const write)(struct ast_channel *chan, struct ast_frame *frame);
397
398         /*! \brief Display or transmit text */
399         int (* const send_text)(struct ast_channel *chan, const char *text);
400
401         /*! \brief Display or send an image */
402         int (* const send_image)(struct ast_channel *chan, struct ast_frame *frame);
403
404         /*! \brief Send HTML data */
405         int (* const send_html)(struct ast_channel *chan, int subclass, const char *data, int len);
406
407         /*! \brief Handle an exception, reading a frame */
408         struct ast_frame * (* const exception)(struct ast_channel *chan);
409
410         /*! \brief Bridge two channels of the same type together */
411         enum ast_bridge_result (* const bridge)(struct ast_channel *c0, struct ast_channel *c1, int flags,
412                                                 struct ast_frame **fo, struct ast_channel **rc, int timeoutms);
413
414         /*! \brief Bridge two channels of the same type together (early) */
415         enum ast_bridge_result (* const early_bridge)(struct ast_channel *c0, struct ast_channel *c1);
416
417         /*! \brief Indicate a particular condition (e.g. AST_CONTROL_BUSY or AST_CONTROL_RINGING or AST_CONTROL_CONGESTION */
418         int (* const indicate)(struct ast_channel *c, int condition, const void *data, size_t datalen);
419
420         /*! \brief Fix up a channel:  If a channel is consumed, this is called.  Basically update any ->owner links */
421         int (* const fixup)(struct ast_channel *oldchan, struct ast_channel *newchan);
422
423         /*! \brief Set a given option */
424         int (* const setoption)(struct ast_channel *chan, int option, void *data, int datalen);
425
426         /*! \brief Query a given option */
427         int (* const queryoption)(struct ast_channel *chan, int option, void *data, int *datalen);
428
429         /*! \brief Blind transfer other side (see app_transfer.c and ast_transfer() */
430         int (* const transfer)(struct ast_channel *chan, const char *newdest);
431
432         /*! \brief Write a frame, in standard format */
433         int (* const write_video)(struct ast_channel *chan, struct ast_frame *frame);
434
435         /*! \brief Write a text frame, in standard format */
436         int (* const write_text)(struct ast_channel *chan, struct ast_frame *frame);
437
438         /*! \brief Find bridged channel */
439         struct ast_channel *(* const bridged_channel)(struct ast_channel *chan, struct ast_channel *bridge);
440
441         /*! \brief Provide additional read items for CHANNEL() dialplan function */
442         int (* func_channel_read)(struct ast_channel *chan, const char *function, char *data, char *buf, size_t len);
443
444         /*! \brief Provide additional write items for CHANNEL() dialplan function */
445         int (* func_channel_write)(struct ast_channel *chan, const char *function, char *data, const char *value);
446
447         /*! \brief Retrieve base channel (agent and local) */
448         struct ast_channel* (* get_base_channel)(struct ast_channel *chan);
449
450         /*! \brief Set base channel (agent and local) */
451         int (* set_base_channel)(struct ast_channel *chan, struct ast_channel *base);
452
453         /*! \brief Get the unique identifier for the PVT, i.e. SIP call-ID for SIP */
454         const char * (* get_pvt_uniqueid)(struct ast_channel *chan);
455 };
456
457 struct ast_epoll_data;
458
459 /*!
460  * The high bit of the frame count is used as a debug marker, so
461  * increments of the counters must be done with care.
462  * Please use c->fin = FRAMECOUNT_INC(c->fin) and the same for c->fout.
463  */
464 #define DEBUGCHAN_FLAG  0x80000000
465
466 /* XXX not ideal to evaluate x twice... */
467 #define FRAMECOUNT_INC(x)       ( ((x) & DEBUGCHAN_FLAG) | (((x)+1) & ~DEBUGCHAN_FLAG) )
468
469 /*!
470  * The current value of the debug flags is stored in the two
471  * variables global_fin and global_fout (declared in main/channel.c)
472  */
473 extern unsigned long global_fin, global_fout;
474
475 enum ast_channel_adsicpe {
476         AST_ADSI_UNKNOWN,
477         AST_ADSI_AVAILABLE,
478         AST_ADSI_UNAVAILABLE,
479         AST_ADSI_OFFHOOKONLY,
480 };
481
482 /*!
483  * \brief ast_channel states
484  *
485  * \note Bits 0-15 of state are reserved for the state (up/down) of the line
486  *       Bits 16-32 of state are reserved for flags
487  */
488 enum ast_channel_state {
489         AST_STATE_DOWN,                 /*!< Channel is down and available */
490         AST_STATE_RESERVED,             /*!< Channel is down, but reserved */
491         AST_STATE_OFFHOOK,              /*!< Channel is off hook */
492         AST_STATE_DIALING,              /*!< Digits (or equivalent) have been dialed */
493         AST_STATE_RING,                 /*!< Line is ringing */
494         AST_STATE_RINGING,              /*!< Remote end is ringing */
495         AST_STATE_UP,                   /*!< Line is up */
496         AST_STATE_BUSY,                 /*!< Line is busy */
497         AST_STATE_DIALING_OFFHOOK,      /*!< Digits (or equivalent) have been dialed while offhook */
498         AST_STATE_PRERING,              /*!< Channel has detected an incoming call and is waiting for ring */
499
500         AST_STATE_MUTE = (1 << 16),     /*!< Do not transmit voice data */
501 };
502
503 /*!
504  * \brief Possible T38 states on channels
505  */
506 enum ast_t38_state {
507         T38_STATE_UNAVAILABLE,  /*!< T38 is unavailable on this channel or disabled by configuration */
508         T38_STATE_UNKNOWN,      /*!< The channel supports T38 but the current status is unknown */
509         T38_STATE_NEGOTIATING,  /*!< T38 is being negotiated */
510         T38_STATE_REJECTED,     /*!< Remote side has rejected our offer */
511         T38_STATE_NEGOTIATED,   /*!< T38 established */
512 };
513
514 /*!
515  * \page AstChannel ast_channel locking and reference tracking
516  *
517  * \par Creating Channels
518  * A channel is allocated using the ast_channel_alloc() function.  When created, it is
519  * automatically inserted into the main channels hash table that keeps track of all
520  * active channels in the system.  The hash key is based on the channel name.  Because
521  * of this, if you want to change the name, you _must_ use ast_change_name(), not change
522  * the name field directly.  When ast_channel_alloc() returns a channel pointer, you now
523  * hold a reference to that channel.  In most cases this reference is given to ast_pbx_run().
524  *
525  * \par Channel Locking
526  * There is a lock associated with every ast_channel.  It is allocated internally via astobj2.
527  * To lock or unlock a channel, you must use the ast_channel_lock() wrappers.
528  *
529  * Previously, before ast_channel was converted to astobj2, the channel lock was used in some
530  * additional ways that are no longer necessary.  Before, the only way to ensure that a channel
531  * did not disappear out from under you if you were working with a channel outside of the channel
532  * thread that owns it, was to hold the channel lock.  Now, that is no longer necessary.
533  * You simply must hold a reference to the channel to ensure it does not go away.
534  *
535  * The channel must be locked if you need to ensure that data that you reading from the channel
536  * does not change while you access it.  Further, you must hold the channel lock if you are
537  * making a non-atomic change to channel data.
538  *
539  * \par Channel References
540  * There are multiple ways to get a reference to a channel.  The first is that you hold a reference
541  * to a channel after creating it.  The other ways involve using the channel search or the channel
542  * traversal APIs.  These functions are the ast_channel_get_*() functions or ast_channel_iterator_*()
543  * functions.  Once a reference is retrieved by one of these methods, you know that the channel will
544  * not go away.  So, the channel should only get locked as needed for data access or modification.
545  * But, make sure that the reference gets released when you are done with it!
546  *
547  * There are different things you can do when you are done with a reference to a channel.  The first
548  * is to simply release the reference using ast_channel_unref().  The other option is to call
549  * ast_channel_release().  This function is generally used where ast_channel_free() was used in
550  * the past.  The release function releases a reference as well as ensures that the channel is no
551  * longer in the global channels container.  That way, the channel will get destroyed as soon as any
552  * other pending references get released.
553  *
554  * \par Exceptions to the rules
555  * Even though ast_channel is reference counted, there are some places where pointers to an ast_channel
556  * get stored, but the reference count does not reflect it.  The reason is mostly historical.
557  * The only places where this happens should be places where because of how the code works, we
558  * _know_ that the pointer to the channel will get removed before the channel goes away.  The main
559  * example of this is in channel drivers.  Channel drivers generally store a pointer to their owner
560  * ast_channel in their technology specific pvt struct.  In this case, the channel drivers _know_
561  * that this pointer to the channel will be removed in time, because the channel's hangup callback
562  * gets called before the channel goes away.
563  */
564
565 /*!
566  * \brief Main Channel structure associated with a channel.
567  *
568  * \note XXX It is important to remember to increment .cleancount each time
569  *       this structure is changed. XXX
570  *
571  * \note When adding fields to this structure, it is important to add the field
572  *       'in position' with like-aligned fields, so as to keep the compiler from
573  *       having to add padding to align fields. The structure's fields are sorted
574  *       in this order: pointers, structures, long, int/enum, short, char. This
575  *       is especially important on 64-bit architectures, where mixing 4-byte
576  *       and 8-byte fields causes 4 bytes of padding to be added before many
577  *       8-byte fields.
578  */
579 struct ast_channel {
580         const struct ast_channel_tech *tech;            /*!< Technology (point to channel driver) */
581         void *tech_pvt;                                 /*!< Private data used by the technology driver */
582         void *music_state;                              /*!< Music State*/
583         void *generatordata;                            /*!< Current generator data if there is any */
584         struct ast_generator *generator;                /*!< Current active data generator */
585         struct ast_channel *_bridge;                    /*!< Who are we bridged to, if we're bridged.
586                                                          *   Who is proxying for us, if we are proxied (i.e. chan_agent).
587                                                          *   Do not access directly, use ast_bridged_channel(chan) */
588         struct ast_channel *masq;                       /*!< Channel that will masquerade as us */
589         struct ast_channel *masqr;                      /*!< Who we are masquerading as */
590         const char *blockproc;                          /*!< Procedure causing blocking */
591         const char *appl;                               /*!< Current application */
592         const char *data;                               /*!< Data passed to current application */
593         struct sched_context *sched;                    /*!< Schedule context */
594         struct ast_filestream *stream;                  /*!< Stream itself. */
595         struct ast_filestream *vstream;                 /*!< Video Stream itself. */
596         int (*timingfunc)(const void *data);
597         void *timingdata;
598         struct ast_pbx *pbx;                            /*!< PBX private structure for this channel */
599         struct ast_trans_pvt *writetrans;               /*!< Write translation path */
600         struct ast_trans_pvt *readtrans;                /*!< Read translation path */
601         struct ast_audiohook_list *audiohooks;
602         struct ast_cdr *cdr;                            /*!< Call Detail Record */
603         struct ast_tone_zone *zone;                     /*!< Tone zone as set in indications.conf or
604                                                          *   in the CHANNEL dialplan function */
605         struct ast_channel_monitor *monitor;            /*!< Channel monitoring */
606 #ifdef HAVE_EPOLL
607         struct ast_epoll_data *epfd_data[AST_MAX_FDS];
608 #endif
609
610         AST_DECLARE_STRING_FIELDS(
611                 AST_STRING_FIELD(name);                 /*!< ASCII unique channel name */
612                 AST_STRING_FIELD(language);             /*!< Language requested for voice prompts */
613                 AST_STRING_FIELD(musicclass);           /*!< Default music class */
614                 AST_STRING_FIELD(accountcode);          /*!< Account code for billing */
615                 AST_STRING_FIELD(call_forward);         /*!< Where to forward to if asked to dial on this interface */
616                 AST_STRING_FIELD(uniqueid);             /*!< Unique Channel Identifier */
617                 AST_STRING_FIELD(parkinglot);           /*! Default parking lot, if empty, default parking lot  */
618                 AST_STRING_FIELD(dialcontext);          /*!< Dial: Extension context that we were called from */
619         );
620
621         struct timeval whentohangup;                    /*!< Non-zero, set to actual time when channel is to be hung up */
622         pthread_t blocker;                              /*!< If anyone is blocking, this is them */
623
624         /*!
625          * \brief Channel Caller ID information.
626          * \note The caller id information is the caller id of this
627          * channel when it is used to initiate a call.
628          */
629         struct ast_callerid cid;
630
631         /*!
632          * \brief Channel Connected Line ID information.
633          * \note The connected line information identifies the channel
634          * connected/bridged to this channel.
635          */
636         struct ast_party_connected_line connected;
637
638         /*!
639          * \brief Redirecting/Diversion information
640          * \note Until struct ast_channel.cid.cid_rdnis is replaced
641          * with ast_channel.redirecting.from.number, the
642          * ast_channel.redirecting.from.number field is not used.
643          */
644         struct ast_party_redirecting redirecting;
645
646         struct ast_frame dtmff;                         /*!< DTMF frame */
647         struct varshead varshead;                       /*!< A linked list for channel variables. See \ref AstChanVar */
648         ast_group_t callgroup;                          /*!< Call group for call pickups */
649         ast_group_t pickupgroup;                        /*!< Pickup group - which calls groups can be picked up? */
650         AST_LIST_HEAD_NOLOCK(, ast_frame) readq;
651         AST_LIST_ENTRY(ast_channel) chan_list;          /*!< For easy linking */
652         struct ast_jb jb;                               /*!< The jitterbuffer state */
653         struct timeval dtmf_tv;                         /*!< The time that an in process digit began, or the last digit ended */
654         AST_LIST_HEAD_NOLOCK(datastores, ast_datastore) datastores; /*!< Data stores on the channel */
655         AST_LIST_HEAD_NOLOCK(autochans, ast_autochan) autochans; /*!< Autochans on the channel */
656
657         unsigned long insmpl;                           /*!< Track the read/written samples for monitor use */
658         unsigned long outsmpl;                          /*!< Track the read/written samples for monitor use */
659
660         int fds[AST_MAX_FDS];                           /*!< File descriptors for channel -- Drivers will poll on
661                                                          *   these file descriptors, so at least one must be non -1.
662                                                          *   See \arg \ref AstFileDesc */
663         int cdrflags;                                   /*!< Call Detail Record Flags */
664         int _softhangup;                                /*!< Whether or not we have been hung up...  Do not set this value
665                                                          *   directly, use ast_softhangup() */
666         int fdno;                                       /*!< Which fd had an event detected on */
667         int streamid;                                   /*!< For streaming playback, the schedule ID */
668         int vstreamid;                                  /*!< For streaming video playback, the schedule ID */
669         int oldwriteformat;                             /*!< Original writer format */
670         int timingfd;                                   /*!< Timing fd */
671         enum ast_channel_state _state;                  /*!< State of line -- Don't write directly, use ast_setstate() */
672         int rings;                                      /*!< Number of rings so far */
673         int priority;                                   /*!< Dialplan: Current extension priority */
674         int macropriority;                              /*!< Macro: Current non-macro priority. See app_macro.c */
675         int amaflags;                                   /*!< Set BEFORE PBX is started to determine AMA flags */
676         enum ast_channel_adsicpe adsicpe;               /*!< Whether or not ADSI is detected on CPE */
677         unsigned int fin;                               /*!< Frames in counters. The high bit is a debug mask, so
678                                                          *   the counter is only in the remaining bits */
679         unsigned int fout;                              /*!< Frames out counters. The high bit is a debug mask, so
680                                                          *   the counter is only in the remaining bits */
681         int hangupcause;                                /*!< Why is the channel hanged up. See causes.h */
682         unsigned int flags;                             /*!< channel flags of AST_FLAG_ type */
683         int alertpipe[2];
684         int nativeformats;                              /*!< Kinds of data this channel can natively handle */
685         int readformat;                                 /*!< Requested read format */
686         int writeformat;                                /*!< Requested write format */
687         int rawreadformat;                              /*!< Raw read format */
688         int rawwriteformat;                             /*!< Raw write format */
689         unsigned int emulate_dtmf_duration;             /*!< Number of ms left to emulate DTMF for */
690 #ifdef HAVE_EPOLL
691         int epfd;
692 #endif
693         int visible_indication;                         /*!< Indication currently playing on the channel */
694
695         unsigned short transfercapability;              /*!< ISDN Transfer Capability - AST_FLAG_DIGITAL is not enough */
696
697         struct ast_bridge *bridge;                      /*!< Bridge this channel is participating in */
698         struct ast_timer *timer;                        /*!< timer object that provided timingfd */
699
700         char context[AST_MAX_CONTEXT];                  /*!< Dialplan: Current extension context */
701         char exten[AST_MAX_EXTENSION];                  /*!< Dialplan: Current extension number */
702         char macrocontext[AST_MAX_CONTEXT];             /*!< Macro: Current non-macro context. See app_macro.c */
703         char macroexten[AST_MAX_EXTENSION];             /*!< Macro: Current non-macro extension. See app_macro.c */
704         char emulate_dtmf_digit;                        /*!< Digit being emulated */
705 };
706
707 /*! \brief ast_channel_tech Properties */
708 enum {
709         /*!
710      * \brief Channels have this property if they can accept input with jitter;
711          * i.e. most VoIP channels
712          */
713         AST_CHAN_TP_WANTSJITTER = (1 << 0),
714         /*!
715      * \brief Channels have this property if they can create jitter;
716          * i.e. most VoIP channels
717          */
718         AST_CHAN_TP_CREATESJITTER = (1 << 1),
719 };
720
721 /*! \brief ast_channel flags */
722 enum {
723         /*! Queue incoming DTMF, to be released when this flag is turned off */
724         AST_FLAG_DEFER_DTMF =    (1 << 1),
725         /*! write should be interrupt generator */
726         AST_FLAG_WRITE_INT =     (1 << 2),
727         /*! a thread is blocking on this channel */
728         AST_FLAG_BLOCKING =      (1 << 3),
729         /*! This is a zombie channel */
730         AST_FLAG_ZOMBIE =        (1 << 4),
731         /*! There is an exception pending */
732         AST_FLAG_EXCEPTION =     (1 << 5),
733         /*! Listening to moh XXX anthm promises me this will disappear XXX */
734         AST_FLAG_MOH =           (1 << 6),
735         /*! This channel is spying on another channel */
736         AST_FLAG_SPYING =        (1 << 7),
737         /*! This channel is in a native bridge */
738         AST_FLAG_NBRIDGE =       (1 << 8),
739         /*! the channel is in an auto-incrementing dialplan processor,
740          *  so when ->priority is set, it will get incremented before
741          *  finding the next priority to run */
742         AST_FLAG_IN_AUTOLOOP =   (1 << 9),
743         /*! This is an outgoing call */
744         AST_FLAG_OUTGOING =      (1 << 10),
745         /*! A DTMF_BEGIN frame has been read from this channel, but not yet an END */
746         AST_FLAG_IN_DTMF =       (1 << 12),
747         /*! A DTMF_END was received when not IN_DTMF, so the length of the digit is
748          *  currently being emulated */
749         AST_FLAG_EMULATE_DTMF =  (1 << 13),
750         /*! This is set to tell the channel not to generate DTMF begin frames, and
751          *  to instead only generate END frames. */
752         AST_FLAG_END_DTMF_ONLY = (1 << 14),
753         /*! Flag to show channels that this call is hangup due to the fact that the call
754             was indeed answered, but in another channel */
755         AST_FLAG_ANSWERED_ELSEWHERE = (1 << 15),
756         /*! This flag indicates that on a masquerade, an active stream should not
757          *  be carried over */
758         AST_FLAG_MASQ_NOSTREAM = (1 << 16),
759         /*! This flag indicates that the hangup exten was run when the bridge terminated,
760          *  a message aimed at preventing a subsequent hangup exten being run at the pbx_run
761          *  level */
762         AST_FLAG_BRIDGE_HANGUP_RUN = (1 << 17),
763         /*! This flag indicates that the hangup exten should NOT be run when the
764          *  bridge terminates, this will allow the hangup in the pbx loop to be run instead.
765          *  */
766         AST_FLAG_BRIDGE_HANGUP_DONT = (1 << 18),
767 };
768
769 /*! \brief ast_bridge_config flags */
770 enum {
771         AST_FEATURE_PLAY_WARNING = (1 << 0),
772         AST_FEATURE_REDIRECT =     (1 << 1),
773         AST_FEATURE_DISCONNECT =   (1 << 2),
774         AST_FEATURE_ATXFER =       (1 << 3),
775         AST_FEATURE_AUTOMON =      (1 << 4),
776         AST_FEATURE_PARKCALL =     (1 << 5),
777         AST_FEATURE_AUTOMIXMON =   (1 << 6),
778         AST_FEATURE_NO_H_EXTEN =   (1 << 7),
779         AST_FEATURE_WARNING_ACTIVE = (1 << 8),
780 };
781
782 /*! \brief bridge configuration */
783 struct ast_bridge_config {
784         struct ast_flags features_caller;
785         struct ast_flags features_callee;
786         struct timeval start_time;
787         struct timeval nexteventts;
788         struct timeval feature_start_time;
789         long feature_timer;
790         long timelimit;
791         long play_warning;
792         long warning_freq;
793         const char *warning_sound;
794         const char *end_sound;
795         const char *start_sound;
796         unsigned int flags;
797         void (* end_bridge_callback)(void *);   /*!< A callback that is called after a bridge attempt */
798         void *end_bridge_callback_data;         /*!< Data passed to the callback */
799         /*! If the end_bridge_callback_data refers to a channel which no longer is going to
800          * exist when the end_bridge_callback is called, then it needs to be fixed up properly
801          */
802         void (*end_bridge_callback_data_fixup)(struct ast_bridge_config *bconfig, struct ast_channel *originator, struct ast_channel *terminator);
803 };
804
805 struct chanmon;
806
807 struct outgoing_helper {
808         const char *context;
809         const char *exten;
810         int priority;
811         const char *cid_num;
812         const char *cid_name;
813         const char *account;
814         struct ast_variable *vars;
815         struct ast_channel *parent_channel;
816 };
817
818 enum {
819         AST_CDR_TRANSFER =   (1 << 0),
820         AST_CDR_FORWARD =    (1 << 1),
821         AST_CDR_CALLWAIT =   (1 << 2),
822         AST_CDR_CONFERENCE = (1 << 3),
823 };
824
825 enum {
826         /*! Soft hangup by device */
827         AST_SOFTHANGUP_DEV =       (1 << 0),
828         /*! Soft hangup for async goto */
829         AST_SOFTHANGUP_ASYNCGOTO = (1 << 1),
830         AST_SOFTHANGUP_SHUTDOWN =  (1 << 2),
831         AST_SOFTHANGUP_TIMEOUT =   (1 << 3),
832         AST_SOFTHANGUP_APPUNLOAD = (1 << 4),
833         AST_SOFTHANGUP_EXPLICIT =  (1 << 5),
834         AST_SOFTHANGUP_UNBRIDGE =  (1 << 6),
835 };
836
837
838 /*! \brief Channel reload reasons for manager events at load or reload of configuration */
839 enum channelreloadreason {
840         CHANNEL_MODULE_LOAD,
841         CHANNEL_MODULE_RELOAD,
842         CHANNEL_CLI_RELOAD,
843         CHANNEL_MANAGER_RELOAD,
844 };
845
846 /*!
847  * \note None of the datastore API calls lock the ast_channel they are using.
848  *       So, the channel should be locked before calling the functions that
849  *       take a channel argument.
850  */
851
852 /*!
853  * \brief Create a channel data store object
854  * \deprecated You should use the ast_datastore_alloc() generic function instead.
855  * \version 1.6.1 deprecated
856  */
857 struct ast_datastore * attribute_malloc ast_channel_datastore_alloc(const struct ast_datastore_info *info, const char *uid)
858         __attribute__((deprecated));
859
860 /*!
861  * \brief Free a channel data store object
862  * \deprecated You should use the ast_datastore_free() generic function instead.
863  * \version 1.6.1 deprecated
864  */
865 int ast_channel_datastore_free(struct ast_datastore *datastore)
866         __attribute__((deprecated));
867
868 /*! \brief Inherit datastores from a parent to a child. */
869 int ast_channel_datastore_inherit(struct ast_channel *from, struct ast_channel *to);
870
871 /*!
872  * \brief Add a datastore to a channel
873  *
874  * \note The channel should be locked before calling this function.
875  *
876  * \retval 0 success
877  * \retval non-zero failure
878  */
879 int ast_channel_datastore_add(struct ast_channel *chan, struct ast_datastore *datastore);
880
881 /*!
882  * \brief Remove a datastore from a channel
883  *
884  * \note The channel should be locked before calling this function.
885  *
886  * \retval 0 success
887  * \retval non-zero failure
888  */
889 int ast_channel_datastore_remove(struct ast_channel *chan, struct ast_datastore *datastore);
890
891 /*!
892  * \brief Find a datastore on a channel
893  *
894  * \note The channel should be locked before calling this function.
895  *
896  * \note The datastore returned from this function must not be used if the
897  *       reference to the channel is released.
898  *
899  * \retval pointer to the datastore if found
900  * \retval NULL if not found
901  */
902 struct ast_datastore *ast_channel_datastore_find(struct ast_channel *chan, const struct ast_datastore_info *info, const char *uid);
903
904 /*! \brief Change the state of a channel */
905 int ast_setstate(struct ast_channel *chan, enum ast_channel_state);
906
907 /*!
908  * \brief Create a channel structure
909  *
910  * \retval NULL failure
911  * \retval non-NULL successfully allocated channel
912  *
913  * \note By default, new channels are set to the "s" extension
914  *       and "default" context.
915  */
916 struct ast_channel * attribute_malloc __attribute__((format(printf, 12, 13)))
917         __ast_channel_alloc(int needqueue, int state, const char *cid_num,
918                             const char *cid_name, const char *acctcode,
919                             const char *exten, const char *context,
920                             const int amaflag, const char *file, int line,
921                             const char *function, const char *name_fmt, ...);
922
923 #define ast_channel_alloc(needqueue, state, cid_num, cid_name, acctcode, exten, context, amaflag, ...) \
924         __ast_channel_alloc(needqueue, state, cid_num, cid_name, acctcode, exten, context, amaflag, \
925                             __FILE__, __LINE__, __FUNCTION__, __VA_ARGS__)
926
927 /*!
928  * \brief Queue an outgoing frame
929  *
930  * \note The channel does not need to be locked before calling this function.
931  */
932 int ast_queue_frame(struct ast_channel *chan, const struct ast_frame *f);
933
934 /*!
935  * \brief Queue an outgoing frame to the head of the frame queue
936  *
937  * \param chan the channel to queue the frame on
938  * \param f the frame to queue.  Note that this frame will be duplicated by
939  *        this function.  It is the responsibility of the caller to handle
940  *        freeing the memory associated with the frame being passed if
941  *        necessary.
942  *
943  * \retval 0 success
944  * \retval non-zero failure
945  */
946 int ast_queue_frame_head(struct ast_channel *chan, const struct ast_frame *f);
947
948 /*!
949  * \brief Queue a hangup frame
950  *
951  * \note The channel does not need to be locked before calling this function.
952  */
953 int ast_queue_hangup(struct ast_channel *chan);
954
955 /*!
956  * \brief Queue a hangup frame with hangupcause set
957  *
958  * \note The channel does not need to be locked before calling this function.
959  * \param[in] chan channel to queue frame onto
960  * \param[in] cause the hangup cause
961  * \return 0 on success, -1 on error
962  * \since 1.6.1
963  */
964 int ast_queue_hangup_with_cause(struct ast_channel *chan, int cause);
965
966 /*!
967  * \brief Queue a control frame with payload
968  *
969  * \param chan channel to queue frame onto
970  * \param control type of control frame
971  *
972  * \note The channel does not need to be locked before calling this function.
973  *
974  * \retval zero on success
975  * \retval non-zero on failure
976  */
977 int ast_queue_control(struct ast_channel *chan, enum ast_control_frame_type control);
978
979 /*!
980  * \brief Queue a control frame with payload
981  *
982  * \param chan channel to queue frame onto
983  * \param control type of control frame
984  * \param data pointer to payload data to be included in frame
985  * \param datalen number of bytes of payload data
986  *
987  * \retval 0 success
988  * \retval non-zero failure
989  *
990  * \details
991  * The supplied payload data is copied into the frame, so the caller's copy
992  * is not modified nor freed, and the resulting frame will retain a copy of
993  * the data even if the caller frees their local copy.
994  *
995  * \note This method should be treated as a 'network transport'; in other
996  * words, your frames may be transferred across an IAX2 channel to another
997  * system, which may be a different endianness than yours. Because of this,
998  * you should ensure that either your frames will never be expected to work
999  * across systems, or that you always put your payload data into 'network byte
1000  * order' before calling this function.
1001  *
1002  * \note The channel does not need to be locked before calling this function.
1003  */
1004 int ast_queue_control_data(struct ast_channel *chan, enum ast_control_frame_type control,
1005                            const void *data, size_t datalen);
1006
1007 /*!
1008  * \brief Change channel name
1009  *
1010  * \pre The channel must be locked before calling this function.
1011  *
1012  * \param chan the channel to change the name of
1013  * \param newname the name to change to
1014  *
1015  * \return nothing
1016  */
1017 void ast_change_name(struct ast_channel *chan, const char *newname);
1018
1019 /*!
1020  * \brief Unlink and release reference to a channel
1021  *
1022  * This function will unlink the channel from the global channels container
1023  * if it is still there and also release the current reference to the channel.
1024  *
1025  * \return NULL, convenient for clearing invalid pointers
1026  *
1027  * \since 1.6.3
1028  */
1029 struct ast_channel *ast_channel_release(struct ast_channel *chan);
1030
1031 /*!
1032  * \brief Requests a channel
1033  *
1034  * \param type type of channel to request
1035  * \param format requested channel format (codec)
1036  * \param data data to pass to the channel requester
1037  * \param status status
1038  *
1039  * \details
1040  * Request a channel of a given type, with data as optional information used
1041  * by the low level module
1042  *
1043  * \retval NULL failure
1044  * \retval non-NULL channel on success
1045  */
1046 struct ast_channel *ast_request(const char *type, int format, void *data, int *status);
1047
1048 /*!
1049  * \brief Request a channel of a given type, with data as optional information used
1050  *        by the low level module and attempt to place a call on it
1051  *
1052  * \param type type of channel to request
1053  * \param format requested channel format
1054  * \param data data to pass to the channel requester
1055  * \param timeout maximum amount of time to wait for an answer
1056  * \param reason why unsuccessful (if unsuccessful)
1057  * \param cid_num Caller-ID Number
1058  * \param cid_name Caller-ID Name (ascii)
1059  *
1060  * \return Returns an ast_channel on success or no answer, NULL on failure.  Check the value of chan->_state
1061  * to know if the call was answered or not.
1062  */
1063 struct ast_channel *ast_request_and_dial(const char *type, int format, void *data,
1064         int timeout, int *reason, const char *cid_num, const char *cid_name);
1065
1066 /*!
1067  * \brief Request a channel of a given type, with data as optional information used
1068  * by the low level module and attempt to place a call on it
1069  * \param type type of channel to request
1070  * \param format requested channel format
1071  * \param data data to pass to the channel requester
1072  * \param timeout maximum amount of time to wait for an answer
1073  * \param reason why unsuccessful (if unsuccessful)
1074  * \param cid_num Caller-ID Number
1075  * \param cid_name Caller-ID Name (ascii)
1076  * \param oh Outgoing helper
1077  * \return Returns an ast_channel on success or no answer, NULL on failure.  Check the value of chan->_state
1078  * to know if the call was answered or not.
1079  */
1080 struct ast_channel *__ast_request_and_dial(const char *type, int format, void *data,
1081         int timeout, int *reason, const char *cid_num, const char *cid_name, struct outgoing_helper *oh);
1082
1083 /*!
1084  * \brief Forwards a call to a new channel specified by the original channel's call_forward str.  If possible, the new forwarded channel is created and returned while the original one is terminated.
1085  * \param caller in channel that requested orig
1086  * \param orig channel being replaced by the call forward channel
1087  * \param timeout maximum amount of time to wait for setup of new forward channel
1088  * \param format requested channel format
1089  * \param oh outgoing helper used with original channel
1090  * \param outstate reason why unsuccessful (if uncuccessful)
1091  * \return Returns the forwarded call's ast_channel on success or NULL on failure
1092  */
1093 struct ast_channel *ast_call_forward(struct ast_channel *caller, struct ast_channel *orig, int *timeout, int format, struct outgoing_helper *oh, int *outstate);
1094
1095 /*!
1096  * \brief Register a channel technology (a new channel driver)
1097  * Called by a channel module to register the kind of channels it supports.
1098  * \param tech Structure defining channel technology or "type"
1099  * \return Returns 0 on success, -1 on failure.
1100  */
1101 int ast_channel_register(const struct ast_channel_tech *tech);
1102
1103 /*!
1104  * \brief Unregister a channel technology
1105  * \param tech Structure defining channel technology or "type" that was previously registered
1106  * \return No return value.
1107  */
1108 void ast_channel_unregister(const struct ast_channel_tech *tech);
1109
1110 /*!
1111  * \brief Get a channel technology structure by name
1112  * \param name name of technology to find
1113  * \return a pointer to the structure, or NULL if no matching technology found
1114  */
1115 const struct ast_channel_tech *ast_get_channel_tech(const char *name);
1116
1117 #ifdef CHANNEL_TRACE
1118 /*!
1119  * \brief Update the context backtrace if tracing is enabled
1120  * \return Returns 0 on success, -1 on failure
1121  */
1122 int ast_channel_trace_update(struct ast_channel *chan);
1123
1124 /*!
1125  * \brief Enable context tracing in the channel
1126  * \return Returns 0 on success, -1 on failure
1127  */
1128 int ast_channel_trace_enable(struct ast_channel *chan);
1129
1130 /*!
1131  * \brief Disable context tracing in the channel.
1132  * \note Does not remove current trace entries
1133  * \return Returns 0 on success, -1 on failure
1134  */
1135 int ast_channel_trace_disable(struct ast_channel *chan);
1136
1137 /*!
1138  * \brief Whether or not context tracing is enabled
1139  * \return Returns -1 when the trace is enabled. 0 if not.
1140  */
1141 int ast_channel_trace_is_enabled(struct ast_channel *chan);
1142
1143 /*!
1144  * \brief Put the channel backtrace in a string
1145  * \return Returns the amount of lines in the backtrace. -1 on error.
1146  */
1147 int ast_channel_trace_serialize(struct ast_channel *chan, struct ast_str **out);
1148 #endif
1149
1150 /*!
1151  * \brief Hang up a channel
1152  * \note This function performs a hard hangup on a channel.  Unlike the soft-hangup, this function
1153  * performs all stream stopping, etc, on the channel that needs to end.
1154  * chan is no longer valid after this call.
1155  * \param chan channel to hang up
1156  * \return Returns 0 on success, -1 on failure.
1157  */
1158 int ast_hangup(struct ast_channel *chan);
1159
1160 /*!
1161  * \brief Softly hangup up a channel
1162  *
1163  * \param chan channel to be soft-hung-up
1164  * \param cause Ast hangupcause for hangup
1165  *
1166  * \details
1167  * Call the protocol layer, but don't destroy the channel structure
1168  * (use this if you are trying to
1169  * safely hangup a channel managed by another thread.
1170  *
1171  * \note The channel passed to this function does not need to be locked.
1172  *
1173  * \return Returns 0 regardless
1174  */
1175 int ast_softhangup(struct ast_channel *chan, int cause);
1176
1177 /*!
1178  * \brief Softly hangup up a channel (no channel lock)
1179  * \param chan channel to be soft-hung-up
1180  * \param cause Ast hangupcause for hangup (see cause.h)
1181  */
1182 int ast_softhangup_nolock(struct ast_channel *chan, int cause);
1183
1184 /*! \brief Check to see if a channel is needing hang up
1185  * \param chan channel on which to check for hang up
1186  * This function determines if the channel is being requested to be hung up.
1187  * \return Returns 0 if not, or 1 if hang up is requested (including time-out).
1188  */
1189 int ast_check_hangup(struct ast_channel *chan);
1190
1191 int ast_check_hangup_locked(struct ast_channel *chan);
1192
1193 /*!
1194  * \brief Compare a offset with the settings of when to hang a channel up
1195  * \param chan channel on which to check for hang up
1196  * \param offset offset in seconds from current time
1197  * \return 1, 0, or -1
1198  * \details
1199  * This function compares a offset from current time with the absolute time
1200  * out on a channel (when to hang up). If the absolute time out on a channel
1201  * is earlier than current time plus the offset, it returns 1, if the two
1202  * time values are equal, it return 0, otherwise, it return -1.
1203  * \sa ast_channel_cmpwhentohangup_tv()
1204  * \version 1.6.1 deprecated function (only had seconds precision)
1205  */
1206 int ast_channel_cmpwhentohangup(struct ast_channel *chan, time_t offset) __attribute__((deprecated));
1207
1208 /*!
1209  * \brief Compare a offset with the settings of when to hang a channel up
1210  * \param chan channel on which to check for hangup
1211  * \param offset offset in seconds and microseconds from current time
1212  * \return 1, 0, or -1
1213  * This function compares a offset from current time with the absolute time
1214  * out on a channel (when to hang up). If the absolute time out on a channel
1215  * is earlier than current time plus the offset, it returns 1, if the two
1216  * time values are equal, it return 0, otherwise, it return -1.
1217  * \since 1.6.1
1218  */
1219 int ast_channel_cmpwhentohangup_tv(struct ast_channel *chan, struct timeval offset);
1220
1221 /*!
1222  * \brief Set when to hang a channel up
1223  *
1224  * \param chan channel on which to check for hang up
1225  * \param offset offset in seconds relative to the current time of when to hang up
1226  *
1227  * \details
1228  * This function sets the absolute time out on a channel (when to hang up).
1229  *
1230  * \note This function does not require that the channel is locked before
1231  *       calling it.
1232  *
1233  * \return Nothing
1234  * \sa ast_channel_setwhentohangup_tv()
1235  * \version 1.6.1 deprecated function (only had seconds precision)
1236  */
1237 void ast_channel_setwhentohangup(struct ast_channel *chan, time_t offset) __attribute__((deprecated));
1238
1239 /*!
1240  * \brief Set when to hang a channel up
1241  *
1242  * \param chan channel on which to check for hang up
1243  * \param offset offset in seconds and useconds relative to the current time of when to hang up
1244  *
1245  * This function sets the absolute time out on a channel (when to hang up).
1246  *
1247  * \note This function does not require that the channel is locked before
1248  * calling it.
1249  *
1250  * \return Nothing
1251  * \since 1.6.1
1252  */
1253 void ast_channel_setwhentohangup_tv(struct ast_channel *chan, struct timeval offset);
1254
1255 /*!
1256  * \brief Answer a channel
1257  *
1258  * \param chan channel to answer
1259  *
1260  * \details
1261  * This function answers a channel and handles all necessary call
1262  * setup functions.
1263  *
1264  * \note The channel passed does not need to be locked, but is locked
1265  * by the function when needed.
1266  *
1267  * \note This function will wait up to 500 milliseconds for media to
1268  * arrive on the channel before returning to the caller, so that the
1269  * caller can properly assume the channel is 'ready' for media flow.
1270  *
1271  * \retval 0 on success
1272  * \retval non-zero on failure
1273  */
1274 int ast_answer(struct ast_channel *chan);
1275
1276 /*!
1277  * \brief Answer a channel
1278  *
1279  * \param chan channel to answer
1280  * \param cdr_answer flag to control whether any associated CDR should be marked as 'answered'
1281  *
1282  * This function answers a channel and handles all necessary call
1283  * setup functions.
1284  *
1285  * \note The channel passed does not need to be locked, but is locked
1286  * by the function when needed.
1287  *
1288  * \note Unlike ast_answer(), this function will not wait for media
1289  * flow to begin. The caller should be careful before sending media
1290  * to the channel before incoming media arrives, as the outgoing
1291  * media may be lost.
1292  *
1293  * \retval 0 on success
1294  * \retval non-zero on failure
1295  */
1296 int ast_raw_answer(struct ast_channel *chan, int cdr_answer);
1297
1298 /*!
1299  * \brief Answer a channel, with a selectable delay before returning
1300  *
1301  * \param chan channel to answer
1302  * \param delay maximum amount of time to wait for incoming media
1303  * \param cdr_answer flag to control whether any associated CDR should be marked as 'answered'
1304  *
1305  * This function answers a channel and handles all necessary call
1306  * setup functions.
1307  *
1308  * \note The channel passed does not need to be locked, but is locked
1309  * by the function when needed.
1310  *
1311  * \note This function will wait up to 'delay' milliseconds for media to
1312  * arrive on the channel before returning to the caller, so that the
1313  * caller can properly assume the channel is 'ready' for media flow. If
1314  * 'delay' is less than 500, the function will wait up to 500 milliseconds.
1315  *
1316  * \retval 0 on success
1317  * \retval non-zero on failure
1318  */
1319 int __ast_answer(struct ast_channel *chan, unsigned int delay, int cdr_answer);
1320
1321 /*!
1322  * \brief Make a call
1323  * \param chan which channel to make the call on
1324  * \param addr destination of the call
1325  * \param timeout time to wait on for connect
1326  * \details
1327  * Place a call, take no longer than timeout ms.
1328  * \return -1 on failure, 0 on not enough time
1329  * (does not automatically stop ringing), and
1330  * the number of seconds the connect took otherwise.
1331  */
1332 int ast_call(struct ast_channel *chan, char *addr, int timeout);
1333
1334 /*!
1335  * \brief Indicates condition of channel
1336  * \note Indicate a condition such as AST_CONTROL_BUSY, AST_CONTROL_RINGING, or AST_CONTROL_CONGESTION on a channel
1337  * \param chan channel to change the indication
1338  * \param condition which condition to indicate on the channel
1339  * \return Returns 0 on success, -1 on failure
1340  */
1341 int ast_indicate(struct ast_channel *chan, int condition);
1342
1343 /*!
1344  * \brief Indicates condition of channel, with payload
1345  * \note Indicate a condition such as AST_CONTROL_HOLD with payload being music on hold class
1346  * \param chan channel to change the indication
1347  * \param condition which condition to indicate on the channel
1348  * \param data pointer to payload data
1349  * \param datalen size of payload data
1350  * \return Returns 0 on success, -1 on failure
1351  */
1352 int ast_indicate_data(struct ast_channel *chan, int condition, const void *data, size_t datalen);
1353
1354 /* Misc stuff ------------------------------------------------ */
1355
1356 /*!
1357  * \brief Wait for input on a channel
1358  * \param chan channel to wait on
1359  * \param ms length of time to wait on the channel
1360  * \details
1361  * Wait for input on a channel for a given # of milliseconds (<0 for indefinite).
1362  * \retval < 0 on failure
1363  * \retval 0 if nothing ever arrived
1364  * \retval the # of ms remaining otherwise
1365  */
1366 int ast_waitfor(struct ast_channel *chan, int ms);
1367
1368 /*!
1369  * \brief Wait for a specified amount of time, looking for hangups
1370  * \param chan channel to wait for
1371  * \param ms length of time in milliseconds to sleep
1372  * \details
1373  * Waits for a specified amount of time, servicing the channel as required.
1374  * \return returns -1 on hangup, otherwise 0.
1375  */
1376 int ast_safe_sleep(struct ast_channel *chan, int ms);
1377
1378 /*!
1379  * \brief Wait for a specified amount of time, looking for hangups and a condition argument
1380  * \param chan channel to wait for
1381  * \param ms length of time in milliseconds to sleep
1382  * \param cond a function pointer for testing continue condition
1383  * \param data argument to be passed to the condition test function
1384  * \return returns -1 on hangup, otherwise 0.
1385  * \details
1386  * Waits for a specified amount of time, servicing the channel as required. If cond
1387  * returns 0, this function returns.
1388  */
1389 int ast_safe_sleep_conditional(struct ast_channel *chan, int ms, int (*cond)(void*), void *data );
1390
1391 /*!
1392  * \brief Waits for activity on a group of channels
1393  * \param chan an array of pointers to channels
1394  * \param n number of channels that are to be waited upon
1395  * \param fds an array of fds to wait upon
1396  * \param nfds the number of fds to wait upon
1397  * \param exception exception flag
1398  * \param outfd fd that had activity on it
1399  * \param ms how long the wait was
1400  * \details
1401  * Big momma function here.  Wait for activity on any of the n channels, or any of the nfds
1402  * file descriptors.
1403  * \return Returns the channel with activity, or NULL on error or if an FD
1404  * came first.  If the FD came first, it will be returned in outfd, otherwise, outfd
1405  * will be -1
1406  */
1407 struct ast_channel *ast_waitfor_nandfds(struct ast_channel **chan, int n,
1408         int *fds, int nfds, int *exception, int *outfd, int *ms);
1409
1410 /*!
1411  * \brief Waits for input on a group of channels
1412  * Wait for input on an array of channels for a given # of milliseconds.
1413  * \return Return channel with activity, or NULL if none has activity.
1414  * \param chan an array of pointers to channels
1415  * \param n number of channels that are to be waited upon
1416  * \param ms time "ms" is modified in-place, if applicable
1417  */
1418 struct ast_channel *ast_waitfor_n(struct ast_channel **chan, int n, int *ms);
1419
1420 /*!
1421  * \brief Waits for input on an fd
1422  * \note This version works on fd's only.  Be careful with it.
1423  */
1424 int ast_waitfor_n_fd(int *fds, int n, int *ms, int *exception);
1425
1426
1427 /*!
1428  * \brief Reads a frame
1429  * \param chan channel to read a frame from
1430  * \return Returns a frame, or NULL on error.  If it returns NULL, you
1431  * best just stop reading frames and assume the channel has been
1432  * disconnected.
1433  */
1434 struct ast_frame *ast_read(struct ast_channel *chan);
1435
1436 /*!
1437  * \brief Reads a frame, returning AST_FRAME_NULL frame if audio.
1438  * \param chan channel to read a frame from
1439  * \return  Returns a frame, or NULL on error.  If it returns NULL, you
1440  * best just stop reading frames and assume the channel has been
1441  * disconnected.
1442  * \note Audio is replaced with AST_FRAME_NULL to avoid
1443  * transcode when the resulting audio is not necessary.
1444  */
1445 struct ast_frame *ast_read_noaudio(struct ast_channel *chan);
1446
1447 /*!
1448  * \brief Write a frame to a channel
1449  * This function writes the given frame to the indicated channel.
1450  * \param chan destination channel of the frame
1451  * \param frame frame that will be written
1452  * \return It returns 0 on success, -1 on failure.
1453  */
1454 int ast_write(struct ast_channel *chan, struct ast_frame *frame);
1455
1456 /*!
1457  * \brief Write video frame to a channel
1458  * This function writes the given frame to the indicated channel.
1459  * \param chan destination channel of the frame
1460  * \param frame frame that will be written
1461  * \return It returns 1 on success, 0 if not implemented, and -1 on failure.
1462  */
1463 int ast_write_video(struct ast_channel *chan, struct ast_frame *frame);
1464
1465 /*!
1466  * \brief Write text frame to a channel
1467  * This function writes the given frame to the indicated channel.
1468  * \param chan destination channel of the frame
1469  * \param frame frame that will be written
1470  * \return It returns 1 on success, 0 if not implemented, and -1 on failure.
1471  */
1472 int ast_write_text(struct ast_channel *chan, struct ast_frame *frame);
1473
1474 /*! \brief Send empty audio to prime a channel driver */
1475 int ast_prod(struct ast_channel *chan);
1476
1477 /*!
1478  * \brief Sets read format on channel chan
1479  * Set read format for channel to whichever component of "format" is best.
1480  * \param chan channel to change
1481  * \param format format to change to
1482  * \return Returns 0 on success, -1 on failure
1483  */
1484 int ast_set_read_format(struct ast_channel *chan, int format);
1485
1486 /*!
1487  * \brief Sets write format on channel chan
1488  * Set write format for channel to whichever component of "format" is best.
1489  * \param chan channel to change
1490  * \param format new format for writing
1491  * \return Returns 0 on success, -1 on failure
1492  */
1493 int ast_set_write_format(struct ast_channel *chan, int format);
1494
1495 /*!
1496  * \brief Sends text to a channel
1497  *
1498  * \param chan channel to act upon
1499  * \param text string of text to send on the channel
1500  *
1501  * \details
1502  * Write text to a display on a channel
1503  *
1504  * \note The channel does not need to be locked before calling this function.
1505  *
1506  * \retval 0 on success
1507  * \retval -1 on failure
1508  */
1509 int ast_sendtext(struct ast_channel *chan, const char *text);
1510
1511 /*!
1512  * \brief Receives a text character from a channel
1513  * \param chan channel to act upon
1514  * \param timeout timeout in milliseconds (0 for infinite wait)
1515  * \details
1516  * Read a char of text from a channel
1517  * \return 0 on success, -1 on failure
1518  */
1519 int ast_recvchar(struct ast_channel *chan, int timeout);
1520
1521 /*!
1522  * \brief Send a DTMF digit to a channel.
1523  * \param chan channel to act upon
1524  * \param digit the DTMF digit to send, encoded in ASCII
1525  * \param duration the duration of the digit ending in ms
1526  * \return 0 on success, -1 on failure
1527  */
1528 int ast_senddigit(struct ast_channel *chan, char digit, unsigned int duration);
1529
1530 /*!
1531  * \brief Send a DTMF digit to a channel.
1532  * \param chan channel to act upon
1533  * \param digit the DTMF digit to send, encoded in ASCII
1534  * \return 0 on success, -1 on failure
1535  */
1536 int ast_senddigit_begin(struct ast_channel *chan, char digit);
1537
1538 /*!
1539  * \brief Send a DTMF digit to a channel.
1540  * \param chan channel to act upon
1541  * \param digit the DTMF digit to send, encoded in ASCII
1542  * \param duration the duration of the digit ending in ms
1543  * \return Returns 0 on success, -1 on failure
1544  */
1545 int ast_senddigit_end(struct ast_channel *chan, char digit, unsigned int duration);
1546
1547 /*!
1548  * \brief Receives a text string from a channel
1549  * Read a string of text from a channel
1550  * \param chan channel to act upon
1551  * \param timeout timeout in milliseconds (0 for infinite wait)
1552  * \return the received text, or NULL to signify failure.
1553  */
1554 char *ast_recvtext(struct ast_channel *chan, int timeout);
1555
1556 /*!
1557  * \brief Waits for a digit
1558  * \param c channel to wait for a digit on
1559  * \param ms how many milliseconds to wait
1560  * \return Returns <0 on error, 0 on no entry, and the digit on success.
1561  */
1562 int ast_waitfordigit(struct ast_channel *c, int ms);
1563
1564 /*!
1565  * \brief Wait for a digit
1566  * Same as ast_waitfordigit() with audio fd for outputting read audio and ctrlfd to monitor for reading.
1567  * \param c channel to wait for a digit on
1568  * \param ms how many milliseconds to wait
1569  * \param audiofd audio file descriptor to write to if audio frames are received
1570  * \param ctrlfd control file descriptor to monitor for reading
1571  * \return Returns 1 if ctrlfd becomes available
1572  */
1573 int ast_waitfordigit_full(struct ast_channel *c, int ms, int audiofd, int ctrlfd);
1574
1575 /*!
1576  * \brief Reads multiple digits
1577  * \param c channel to read from
1578  * \param s string to read in to.  Must be at least the size of your length
1579  * \param len how many digits to read (maximum)
1580  * \param timeout how long to timeout between digits
1581  * \param rtimeout timeout to wait on the first digit
1582  * \param enders digits to end the string
1583  * \details
1584  * Read in a digit string "s", max length "len", maximum timeout between
1585  * digits "timeout" (-1 for none), terminated by anything in "enders".  Give them rtimeout
1586  * for the first digit.
1587  * \return Returns 0 on normal return, or 1 on a timeout.  In the case of
1588  * a timeout, any digits that were read before the timeout will still be available in s.
1589  * RETURNS 2 in full version when ctrlfd is available, NOT 1
1590  */
1591 int ast_readstring(struct ast_channel *c, char *s, int len, int timeout, int rtimeout, char *enders);
1592 int ast_readstring_full(struct ast_channel *c, char *s, int len, int timeout, int rtimeout, char *enders, int audiofd, int ctrlfd);
1593
1594 /*! \brief Report DTMF on channel 0 */
1595 #define AST_BRIDGE_DTMF_CHANNEL_0               (1 << 0)
1596 /*! \brief Report DTMF on channel 1 */
1597 #define AST_BRIDGE_DTMF_CHANNEL_1               (1 << 1)
1598 /*! \brief Return all voice frames on channel 0 */
1599 #define AST_BRIDGE_REC_CHANNEL_0                (1 << 2)
1600 /*! \brief Return all voice frames on channel 1 */
1601 #define AST_BRIDGE_REC_CHANNEL_1                (1 << 3)
1602 /*! \brief Ignore all signal frames except NULL */
1603 #define AST_BRIDGE_IGNORE_SIGS                  (1 << 4)
1604
1605
1606 /*!
1607  * \brief Makes two channel formats compatible
1608  * \param c0 first channel to make compatible
1609  * \param c1 other channel to make compatible
1610  * \details
1611  * Set two channels to compatible formats -- call before ast_channel_bridge in general.
1612  * \return Returns 0 on success and -1 if it could not be done
1613  */
1614 int ast_channel_make_compatible(struct ast_channel *c0, struct ast_channel *c1);
1615
1616 /*!
1617  * \brief Bridge two channels together (early)
1618  * \param c0 first channel to bridge
1619  * \param c1 second channel to bridge
1620  * \details
1621  * Bridge two channels (c0 and c1) together early. This implies either side may not be answered yet.
1622  * \return Returns 0 on success and -1 if it could not be done
1623  */
1624 int ast_channel_early_bridge(struct ast_channel *c0, struct ast_channel *c1);
1625
1626 /*!
1627  * \brief Bridge two channels together
1628  * \param c0 first channel to bridge
1629  * \param c1 second channel to bridge
1630  * \param config config for the channels
1631  * \param fo destination frame(?)
1632  * \param rc destination channel(?)
1633  * \details
1634  * Bridge two channels (c0 and c1) together.  If an important frame occurs, we return that frame in
1635  * *rf (remember, it could be NULL) and which channel (0 or 1) in rc
1636  */
1637 /* int ast_channel_bridge(struct ast_channel *c0, struct ast_channel *c1, int flags, struct ast_frame **fo, struct ast_channel **rc); */
1638 int ast_channel_bridge(struct ast_channel *c0,struct ast_channel *c1,
1639         struct ast_bridge_config *config, struct ast_frame **fo, struct ast_channel **rc);
1640
1641 /*!
1642  * \brief Weird function made for call transfers
1643  *
1644  * \param original channel to make a copy of
1645  * \param clone copy of the original channel
1646  *
1647  * \details
1648  * This is a very strange and freaky function used primarily for transfer.  Suppose that
1649  * "original" and "clone" are two channels in random situations.  This function takes
1650  * the guts out of "clone" and puts them into the "original" channel, then alerts the
1651  * channel driver of the change, asking it to fixup any private information (like the
1652  * p->owner pointer) that is affected by the change.  The physical layer of the original
1653  * channel is hung up.
1654  *
1655  * \note Neither channel passed here needs to be locked before calling this function.
1656  */
1657 int ast_channel_masquerade(struct ast_channel *original, struct ast_channel *clone);
1658
1659 /*!
1660  * \brief Gives the string form of a given cause code.
1661  *
1662  * \param state cause to get the description of
1663  * \return the text form of the binary cause code given
1664  */
1665 const char *ast_cause2str(int state) attribute_pure;
1666
1667 /*!
1668  * \brief Convert the string form of a cause code to a number
1669  *
1670  * \param name string form of the cause
1671  * \return the cause code
1672  */
1673 int ast_str2cause(const char *name) attribute_pure;
1674
1675 /*!
1676  * \brief Gives the string form of a given channel state
1677  *
1678  * \param ast_channel_state state to get the name of
1679  * \return the text form of the binary state given
1680  */
1681 const char *ast_state2str(enum ast_channel_state);
1682
1683 /*!
1684  * \brief Gives the string form of a given transfer capability
1685  *
1686  * \param transfercapability transfer capability to get the name of
1687  * \return the text form of the binary transfer capability
1688  */
1689 char *ast_transfercapability2str(int transfercapability) attribute_const;
1690
1691 /*
1692  * Options: Some low-level drivers may implement "options" allowing fine tuning of the
1693  * low level channel.  See frame.h for options.  Note that many channel drivers may support
1694  * none or a subset of those features, and you should not count on this if you want your
1695  * asterisk application to be portable.  They're mainly useful for tweaking performance
1696  */
1697
1698 /*!
1699  * \brief Sets an option on a channel
1700  *
1701  * \param channel channel to set options on
1702  * \param option option to change
1703  * \param data data specific to option
1704  * \param datalen length of the data
1705  * \param block blocking or not
1706  * \details
1707  * Set an option on a channel (see frame.h), optionally blocking awaiting the reply
1708  * \return 0 on success and -1 on failure
1709  */
1710 int ast_channel_setoption(struct ast_channel *channel, int option, void *data, int datalen, int block);
1711
1712 /*! Pick the best codec
1713  * Choose the best codec...  Uhhh...   Yah. */
1714 int ast_best_codec(int fmts);
1715
1716
1717 /*!
1718  * \brief Checks the value of an option
1719  *
1720  * Query the value of an option
1721  * Works similarly to setoption except only reads the options.
1722  */
1723 int ast_channel_queryoption(struct ast_channel *channel, int option, void *data, int *datalen, int block);
1724
1725 /*!
1726  * \brief Checks for HTML support on a channel
1727  * \return 0 if channel does not support HTML or non-zero if it does
1728  */
1729 int ast_channel_supports_html(struct ast_channel *channel);
1730
1731 /*!
1732  * \brief Sends HTML on given channel
1733  * Send HTML or URL on link.
1734  * \return 0 on success or -1 on failure
1735  */
1736 int ast_channel_sendhtml(struct ast_channel *channel, int subclass, const char *data, int datalen);
1737
1738 /*!
1739  * \brief Sends a URL on a given link
1740  * Send URL on link.
1741  * \return 0 on success or -1 on failure
1742  */
1743 int ast_channel_sendurl(struct ast_channel *channel, const char *url);
1744
1745 /*!
1746  * \brief Defers DTMF so that you only read things like hangups and audio.
1747  * \return non-zero if channel was already DTMF-deferred or
1748  * 0 if channel is just now being DTMF-deferred
1749  */
1750 int ast_channel_defer_dtmf(struct ast_channel *chan);
1751
1752 /*! Undo defer.  ast_read will return any DTMF characters that were queued */
1753 void ast_channel_undefer_dtmf(struct ast_channel *chan);
1754
1755 /*! Initiate system shutdown -- prevents new channels from being allocated.
1756  * \param hangup  If "hangup" is non-zero, all existing channels will receive soft
1757  *  hangups */
1758 void ast_begin_shutdown(int hangup);
1759
1760 /*! Cancels an existing shutdown and returns to normal operation */
1761 void ast_cancel_shutdown(void);
1762
1763 /*! \return number of active/allocated channels */
1764 int ast_active_channels(void);
1765
1766 /*! \return non-zero if Asterisk is being shut down */
1767 int ast_shutting_down(void);
1768
1769 /*! Activate a given generator */
1770 int ast_activate_generator(struct ast_channel *chan, struct ast_generator *gen, void *params);
1771
1772 /*! Deactivate an active generator */
1773 void ast_deactivate_generator(struct ast_channel *chan);
1774
1775 /*!
1776  * \brief Set caller ID number, name and ANI
1777  *
1778  * \note The channel does not need to be locked before calling this function.
1779  */
1780 void ast_set_callerid(struct ast_channel *chan, const char *cid_num, const char *cid_name, const char *cid_ani);
1781
1782 /*! Set the file descriptor on the channel */
1783 void ast_channel_set_fd(struct ast_channel *chan, int which, int fd);
1784
1785 /*! Add a channel to an optimized waitfor */
1786 void ast_poll_channel_add(struct ast_channel *chan0, struct ast_channel *chan1);
1787
1788 /*! Delete a channel from an optimized waitfor */
1789 void ast_poll_channel_del(struct ast_channel *chan0, struct ast_channel *chan1);
1790
1791 /*! Start a tone going */
1792 int ast_tonepair_start(struct ast_channel *chan, int freq1, int freq2, int duration, int vol);
1793 /*! Stop a tone from playing */
1794 void ast_tonepair_stop(struct ast_channel *chan);
1795 /*! Play a tone pair for a given amount of time */
1796 int ast_tonepair(struct ast_channel *chan, int freq1, int freq2, int duration, int vol);
1797
1798 /*!
1799  * \brief Automatically service a channel for us...
1800  *
1801  * \retval 0 success
1802  * \retval -1 failure, or the channel is already being autoserviced
1803  */
1804 int ast_autoservice_start(struct ast_channel *chan);
1805
1806 /*!
1807  * \brief Stop servicing a channel for us...
1808  *
1809  * \note if chan is locked prior to calling ast_autoservice_stop, it
1810  * is likely that there will be a deadlock between the thread that calls
1811  * ast_autoservice_stop and the autoservice thread. It is important
1812  * that chan is not locked prior to this call
1813  *
1814  * \retval 0 success
1815  * \retval -1 error, or the channel has been hungup
1816  */
1817 int ast_autoservice_stop(struct ast_channel *chan);
1818
1819 /*!
1820  * \brief Enable or disable timer ticks for a channel
1821  *
1822  * \param rate number of timer ticks per second
1823  *
1824  * \details
1825  * If timers are supported, force a scheduled expiration on the
1826  * timer fd, at which point we call the callback function / data
1827  *
1828  * \note Call this function with a rate of 0 to turn off the timer ticks
1829  *
1830  * \version 1.6.1 changed samples parameter to rate, accomodates new timing methods
1831  */
1832 int ast_settimeout(struct ast_channel *c, unsigned int rate, int (*func)(const void *data), void *data);
1833
1834 /*!
1835  * \brief Transfer a channel (if supported).
1836  * \retval -1 on error
1837  * \retval 0 if not supported
1838  * \retval 1 if supported and requested
1839  * \param chan current channel
1840  * \param dest destination extension for transfer
1841  */
1842 int ast_transfer(struct ast_channel *chan, char *dest);
1843
1844 /*!
1845  * \brief Start masquerading a channel
1846  * \details
1847  * XXX This is a seriously whacked out operation.  We're essentially putting the guts of
1848  *     the clone channel into the original channel.  Start by killing off the original
1849  *     channel's backend.   I'm not sure we're going to keep this function, because
1850  *     while the features are nice, the cost is very high in terms of pure nastiness. XXX
1851  * \param chan Channel to masquerade
1852  */
1853 int ast_do_masquerade(struct ast_channel *chan);
1854
1855 /*!
1856  * \brief Find bridged channel
1857  *
1858  * \note This function does _not_ return a reference to the bridged channel.
1859  * The reason for this is mostly historical.  It _should_ return a reference,
1860  * but it will take a lot of work to make the code base account for that.
1861  * So, for now, the old rules still apply for how to handle this function.
1862  * If this function is being used from the channel thread that owns the channel,
1863  * then a reference is already held, and channel locking is not required to
1864  * guarantee that the channel will stay around.  If this function is used
1865  * outside of the associated channel thread, the channel parameter 'chan'
1866  * MUST be locked before calling this function.  Also, 'chan' must remain locked
1867  * for the entire time that the result of this function is being used.
1868  *
1869  * \param chan Current channel
1870  *
1871  * \return A pointer to the bridged channel
1872 */
1873 struct ast_channel *ast_bridged_channel(struct ast_channel *chan);
1874
1875 /*!
1876  * \brief Inherits channel variable from parent to child channel
1877  * \param parent Parent channel
1878  * \param child Child channel
1879  *
1880  * \details
1881  * Scans all channel variables in the parent channel, looking for those
1882  * that should be copied into the child channel.
1883  * Variables whose names begin with a single '_' are copied into the
1884  * child channel with the prefix removed.
1885  * Variables whose names begin with '__' are copied into the child
1886  * channel with their names unchanged.
1887  */
1888 void ast_channel_inherit_variables(const struct ast_channel *parent, struct ast_channel *child);
1889
1890 /*!
1891  * \brief adds a list of channel variables to a channel
1892  * \param chan the channel
1893  * \param vars a linked list of variables
1894  *
1895  * \details
1896  * Variable names can be for a regular channel variable or a dialplan function
1897  * that has the ability to be written to.
1898  */
1899 void ast_set_variables(struct ast_channel *chan, struct ast_variable *vars);
1900
1901 /*!
1902  * \brief An opaque 'object' structure use by silence generators on channels.
1903  */
1904 struct ast_silence_generator;
1905
1906 /*!
1907  * \brief Starts a silence generator on the given channel.
1908  * \param chan The channel to generate silence on
1909  * \return An ast_silence_generator pointer, or NULL if an error occurs
1910  *
1911  * \details
1912  * This function will cause SLINEAR silence to be generated on the supplied
1913  * channel until it is disabled; if the channel cannot be put into SLINEAR
1914  * mode then the function will fail.
1915  *
1916  * \note
1917  * The pointer returned by this function must be preserved and passed to
1918  * ast_channel_stop_silence_generator when you wish to stop the silence
1919  * generation.
1920  */
1921 struct ast_silence_generator *ast_channel_start_silence_generator(struct ast_channel *chan);
1922
1923 /*!
1924  * \brief Stops a previously-started silence generator on the given channel.
1925  * \param chan The channel to operate on
1926  * \param state The ast_silence_generator pointer return by a previous call to
1927  * ast_channel_start_silence_generator.
1928  * \return nothing
1929  *
1930  * \details
1931  * This function will stop the operating silence generator and return the channel
1932  * to its previous write format.
1933  */
1934 void ast_channel_stop_silence_generator(struct ast_channel *chan, struct ast_silence_generator *state);
1935
1936 /*!
1937  * \brief Check if the channel can run in internal timing mode.
1938  * \param chan The channel to check
1939  * \return boolean
1940  *
1941  * \details
1942  * This function will return 1 if internal timing is enabled and the timing
1943  * device is available.
1944  */
1945 int ast_internal_timing_enabled(struct ast_channel *chan);
1946
1947 /* Misc. functions below */
1948
1949 /*!
1950  * \brief if fd is a valid descriptor, set *pfd with the descriptor
1951  * \return Return 1 (not -1!) if added, 0 otherwise (so we can add the
1952  * return value to the index into the array)
1953  */
1954 static inline int ast_add_fd(struct pollfd *pfd, int fd)
1955 {
1956         pfd->fd = fd;
1957         pfd->events = POLLIN | POLLPRI;
1958         return fd >= 0;
1959 }
1960
1961 /*! \brief Helper function for migrating select to poll */
1962 static inline int ast_fdisset(struct pollfd *pfds, int fd, int maximum, int *start)
1963 {
1964         int x;
1965         int dummy = 0;
1966
1967         if (fd < 0)
1968                 return 0;
1969         if (!start)
1970                 start = &dummy;
1971         for (x = *start; x < maximum; x++)
1972                 if (pfds[x].fd == fd) {
1973                         if (x == *start)
1974                                 (*start)++;
1975                         return pfds[x].revents;
1976                 }
1977         return 0;
1978 }
1979
1980 #ifndef HAVE_TIMERSUB
1981 static inline void timersub(struct timeval *tvend, struct timeval *tvstart, struct timeval *tvdiff)
1982 {
1983         tvdiff->tv_sec = tvend->tv_sec - tvstart->tv_sec;
1984         tvdiff->tv_usec = tvend->tv_usec - tvstart->tv_usec;
1985         if (tvdiff->tv_usec < 0) {
1986                 tvdiff->tv_sec --;
1987                 tvdiff->tv_usec += 1000000;
1988         }
1989
1990 }
1991 #endif
1992
1993 /*!
1994  * \brief Waits for activity on a group of channels
1995  * \param nfds the maximum number of file descriptors in the sets
1996  * \param rfds file descriptors to check for read availability
1997  * \param wfds file descriptors to check for write availability
1998  * \param efds file descriptors to check for exceptions (OOB data)
1999  * \param tvp timeout while waiting for events
2000  * \details
2001  * This is the same as a standard select(), except it guarantees the
2002  * behaviour where the passed struct timeval is updated with how much
2003  * time was not slept while waiting for the specified events
2004  */
2005 static inline int ast_select(int nfds, fd_set *rfds, fd_set *wfds, fd_set *efds, struct timeval *tvp)
2006 {
2007 #ifdef __linux__
2008         return select(nfds, rfds, wfds, efds, tvp);
2009 #else
2010         if (tvp) {
2011                 struct timeval tv, tvstart, tvend, tvlen;
2012                 int res;
2013
2014                 tv = *tvp;
2015                 gettimeofday(&tvstart, NULL);
2016                 res = select(nfds, rfds, wfds, efds, tvp);
2017                 gettimeofday(&tvend, NULL);
2018                 timersub(&tvend, &tvstart, &tvlen);
2019                 timersub(&tv, &tvlen, tvp);
2020                 if (tvp->tv_sec < 0 || (tvp->tv_sec == 0 && tvp->tv_usec < 0)) {
2021                         tvp->tv_sec = 0;
2022                         tvp->tv_usec = 0;
2023                 }
2024                 return res;
2025         }
2026         else
2027                 return select(nfds, rfds, wfds, efds, NULL);
2028 #endif
2029 }
2030
2031 /*! \brief Retrieves the current T38 state of a channel */
2032 static inline enum ast_t38_state ast_channel_get_t38_state(struct ast_channel *chan)
2033 {
2034         enum ast_t38_state state = T38_STATE_UNAVAILABLE;
2035         int datalen = sizeof(state);
2036
2037         ast_channel_queryoption(chan, AST_OPTION_T38_STATE, &state, &datalen, 0);
2038
2039         return state;
2040 }
2041
2042 #define CHECK_BLOCKING(c) do {   \
2043         if (ast_test_flag(c, AST_FLAG_BLOCKING)) {\
2044                 if (option_debug) \
2045                         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); \
2046         } else { \
2047                 (c)->blocker = pthread_self(); \
2048                 (c)->blockproc = __PRETTY_FUNCTION__; \
2049                 ast_set_flag(c, AST_FLAG_BLOCKING); \
2050         } } while (0)
2051
2052 ast_group_t ast_get_group(const char *s);
2053
2054 /*! \brief print call- and pickup groups into buffer */
2055 char *ast_print_group(char *buf, int buflen, ast_group_t group);
2056
2057 /*!
2058  * \brief Convert enum channelreloadreason to text string for manager event
2059  * \param reason The reason for reload (manager, cli, start etc)
2060  */
2061 const char *channelreloadreason2txt(enum channelreloadreason reason);
2062
2063 /*! \brief return an ast_variable list of channeltypes */
2064 struct ast_variable *ast_channeltype_list(void);
2065
2066 /*!
2067  * \brief return an english explanation of the code returned thru __ast_request_and_dial's 'outstate' argument
2068  * \param reason  The integer argument, usually taken from AST_CONTROL_ macros
2069  * \return char pointer explaining the code
2070  */
2071 const char *ast_channel_reason2str(int reason);
2072
2073 /*! \brief channel group info */
2074 struct ast_group_info {
2075         struct ast_channel *chan;
2076         char *category;
2077         char *group;
2078         AST_LIST_ENTRY(ast_group_info) group_list;
2079 };
2080
2081 #define ast_channel_lock(chan) ao2_lock(chan)
2082 #define ast_channel_unlock(chan) ao2_unlock(chan)
2083 #define ast_channel_trylock(chan) ao2_trylock(chan)
2084
2085 /*!
2086  * \brief Lock two channels.
2087  */
2088 #define ast_channel_lock_both(chan1, chan2) do { \
2089                 ast_channel_lock(chan1); \
2090                 while (ast_channel_trylock(chan2)) { \
2091                         ast_channel_unlock(chan1); \
2092                         sched_yield(); \
2093                         ast_channel_lock(chan1); \
2094                 } \
2095         } while (0)
2096
2097 /*!
2098  * \brief Increase channel reference count
2099  *
2100  * \param c the channel
2101  *
2102  * \retval c always
2103  *
2104  * \since 1.6.3
2105  */
2106 #define ast_channel_ref(c) ({ ao2_ref(c, +1); (c); })
2107
2108 /*!
2109  * \brief Decrease channel reference count
2110  *
2111  * \param c the channel
2112  *
2113  * \retval NULL always
2114  *
2115  * \since 1.6.3
2116  */
2117 #define ast_channel_unref(c) ({ ao2_ref(c, -1); (struct ast_channel *) (NULL); })
2118
2119 /*! Channel Iterating @{ */
2120
2121 /*!
2122  * \brief A channel iterator
2123  *
2124  * This is an opaque type.
2125  */
2126 struct ast_channel_iterator;
2127
2128 /*!
2129  * \brief Destroy a channel iterator
2130  *
2131  * \arg i the itereator to destroy
2132  *
2133  * This function is used to destroy a channel iterator that was retrieved by
2134  * using one of the channel_iterator_new() functions.
2135  *
2136  * \return NULL, for convenience to clear out the pointer to the iterator that
2137  * was just destroyed.
2138  *
2139  * \since 1.6.3
2140  */
2141 struct ast_channel_iterator *ast_channel_iterator_destroy(struct ast_channel_iterator *i);
2142
2143 /*!
2144  * \brief Create a new channel iterator based on extension
2145  *
2146  * \arg ao2_flags astobj2 iterator flags
2147  * \arg exten The extension that channels must be in
2148  * \arg context The context that channels must be in (optional)
2149  *
2150  * After creating an iterator using this function, the ast_channel_iterator_next()
2151  * function can be used to iterate through all channels that are currently
2152  * in the specified context and extension.
2153  *
2154  * \retval NULL on failure
2155  * \retval a new channel iterator based on the specified parameters
2156  *
2157  * \since 1.6.3
2158  */
2159 struct ast_channel_iterator *ast_channel_iterator_by_exten_new(int ao2_flags, const char *exten,
2160         const char *context);
2161
2162 /*!
2163  * \brief Create a new channel iterator based on name
2164  *
2165  * \arg ao2_flags astobj2 iterator flags
2166  * \arg name channel name or channel uniqueid to match
2167  * \arg name_len number of characters in the channel name to match on.  This
2168  *      would be used to match based on name prefix.  If matching on the full
2169  *      channel name is desired, then this parameter should be 0.
2170  *
2171  * After creating an iterator using this function, the ast_channel_iterator_next()
2172  * function can be used to iterate through all channels that exist that have
2173  * the specified name or name prefix.
2174  *
2175  * \retval NULL on failure
2176  * \retval a new channel iterator based on the specified parameters
2177  *
2178  * \since 1.6.3
2179  */
2180 struct ast_channel_iterator *ast_channel_iterator_by_name_new(int ao2_flags, const char *name,
2181         size_t name_len);
2182
2183 /*!
2184  * \brief Create a new channel iterator
2185  *
2186  * \arg ao2_flags astobj2 iterator flags
2187  *
2188  * After creating an iterator using this function, the ast_channel_iterator_next()
2189  * function can be used to iterate through all channels that exist.
2190  *
2191  * \retval NULL on failure
2192  * \retval a new channel iterator
2193  *
2194  * \since 1.6.3
2195  */
2196 struct ast_channel_iterator *ast_channel_iterator_all_new(int ao2_flags);
2197
2198 /*!
2199  * \brief Get the next channel for a channel iterator
2200  *
2201  * \arg i the channel iterator that was created using one of the
2202  *  channel_iterator_new() functions.
2203  *
2204  * This function should be used to iterate through all channels that match a
2205  * specified set of parameters that were provided when the iterator was created.
2206  *
2207  * \retval the next channel that matches the parameters used when the iterator
2208  *         was created.
2209  * \retval NULL, if no more channels match the iterator parameters.
2210  *
2211  * \since 1.6.3
2212  */
2213 struct ast_channel *ast_channel_iterator_next(struct ast_channel_iterator *i);
2214
2215 /*! @} End channel iterator definitions. */
2216
2217 /*!
2218  * \brief Call a function with every active channel
2219  *
2220  * This function executes a callback one time for each active channel on the
2221  * system.  The channel is provided as an argument to the function.
2222  *
2223  * \since 1.6.3
2224  */
2225 struct ast_channel *ast_channel_callback(ao2_callback_data_fn *cb_fn, void *arg,
2226                 void *data, int ao2_flags);
2227
2228 /*! @{ Channel search functions */
2229
2230 /*!
2231  * \brief Find a channel by name
2232  *
2233  * \arg name the name or uniqueid of the channel to search for
2234  *
2235  * Find a channel that has the same name as the provided argument.
2236  *
2237  * \retval a channel with the name specified by the argument
2238  * \retval NULL if no channel was found
2239  *
2240  * \since 1.6.3
2241  */
2242 struct ast_channel *ast_channel_get_by_name(const char *name);
2243
2244 /*!
2245  * \brief Find a channel by a name prefix
2246  *
2247  * \arg name The channel name or uniqueid prefix to search for
2248  * \arg name_len Only search for up to this many characters from the name
2249  *
2250  * Find a channel that has the same name prefix as specified by the arguments.
2251  *
2252  * \retval a channel with the name prefix specified by the arguments
2253  * \retval NULL if no channel was found
2254  *
2255  * \since 1.6.3
2256  */
2257 struct ast_channel *ast_channel_get_by_name_prefix(const char *name, size_t name_len);
2258
2259 /*!
2260  * \brief Find a channel by extension and context
2261  *
2262  * \arg exten the extension to search for
2263  * \arg context the context to search for (optional)
2264  *
2265  * Return a channel that is currently at the specified extension and context.
2266  *
2267  * \retval a channel that is at the specified extension and context
2268  * \retval NULL if no channel was found
2269  *
2270  * \since 1.6.3
2271  */
2272 struct ast_channel *ast_channel_get_by_exten(const char *exten, const char *context);
2273
2274 /*! @} End channel search functions. */
2275
2276 /*!
2277  * \since 1.6.3
2278  * \brief Copy the source caller information to the destination caller.
2279  *
2280  * \param dest Destination caller
2281  * \param src Source caller
2282  *
2283  * \return Nothing
2284  */
2285 void ast_party_caller_copy(struct ast_callerid *dest, const struct ast_callerid *src);
2286
2287 /*!
2288  * \since 1.6.3
2289  * \brief Initialize the given connected line structure.
2290  *
2291  * \param init Connected line structure to initialize.
2292  *
2293  * \return Nothing
2294  */
2295 void ast_party_connected_line_init(struct ast_party_connected_line *init);
2296
2297 /*!
2298  * \since 1.6.3
2299  * \brief Copy the source connected line information to the destination connected line.
2300  *
2301  * \param dest Destination connected line
2302  * \param src Source connected line
2303  *
2304  * \return Nothing
2305  */
2306 void ast_party_connected_line_copy(struct ast_party_connected_line *dest, const struct ast_party_connected_line *src);
2307
2308 /*!
2309  * \since 1.6.3
2310  * \brief Initialize the given connected line structure using the given
2311  * guide for a set update operation.
2312  *
2313  * \details
2314  * The initialization is needed to allow a set operation to know if a
2315  * value needs to be updated.  Simple integers need the guide's original
2316  * value in case the set operation is not trying to set a new value.
2317  * String values are simply set to NULL pointers if they are not going
2318  * to be updated.
2319  *
2320  * \param init Connected line structure to initialize.
2321  * \param guide Source connected line to use as a guide in initializing.
2322  *
2323  * \return Nothing
2324  */
2325 void ast_party_connected_line_set_init(struct ast_party_connected_line *init, const struct ast_party_connected_line *guide);
2326
2327 /*!
2328  * \since 1.6.3
2329  * \brief Set the connected line information based on another connected line source
2330  *
2331  * This is similar to ast_party_connected_line_copy, except that NULL values for
2332  * strings in the src parameter indicate not to update the corresponding dest values.
2333  *
2334  * \param src The source connected line to use as a guide to set the dest
2335  * \param dest The connected line one wishes to update
2336  *
2337  * \return Nada
2338  */
2339 void ast_party_connected_line_set(struct ast_party_connected_line *dest, const struct ast_party_connected_line *src);
2340
2341 /*!
2342  * \since 1.6.3
2343  * \brief Collect the caller party information into a connected line structure.
2344  *
2345  * \param connected Collected caller information for the connected line
2346  * \param cid Caller information.
2347  *
2348  * \return Nothing
2349  *
2350  * \warning This is a shallow copy.
2351  * \warning DO NOT call ast_party_connected_line_free() on the filled in
2352  * connected line structure!
2353  */
2354 void ast_party_connected_line_collect_caller(struct ast_party_connected_line *connected, struct ast_callerid *cid);
2355
2356 /*!
2357  * \since 1.6.3
2358  * \brief Destroy the connected line information contents
2359  *
2360  * \param doomed The connected line information to destroy.
2361  *
2362  * \return Nothing
2363  */
2364 void ast_party_connected_line_free(struct ast_party_connected_line *doomed);
2365
2366 /*!
2367  * \since 1.6.3
2368  * \brief Copy the source redirecting information to the destination redirecting.
2369  *
2370  * \param dest Destination redirecting
2371  * \param src Source redirecting
2372  *
2373  * \return Nothing
2374  */
2375 void ast_party_redirecting_copy(struct ast_party_redirecting *dest, const struct ast_party_redirecting *src);
2376
2377 /*!
2378  * \since 1.6.3
2379  * \brief Initialize the given redirecting id structure using the given guide
2380  * for a set update operation.
2381  *
2382  * \details
2383  * The initialization is needed to allow a set operation to know if a
2384  * value needs to be updated.  Simple integers need the guide's original
2385  * value in case the set operation is not trying to set a new value.
2386  * String values are simply set to NULL pointers if they are not going
2387  * to be updated.
2388  *
2389  * \param init Redirecting id structure to initialize.
2390  * \param guide Source redirecting id to use as a guide in initializing.
2391  *
2392  * \return Nothing
2393  */
2394 void ast_party_redirecting_set_init(struct ast_party_redirecting *init, const struct ast_party_redirecting *guide);
2395
2396 /*!
2397  * \since 1.6.3
2398  * \brief Destroy the redirecting information contents
2399  *
2400  * \param doomed The redirecting information to destroy.
2401  *
2402  * \return Nothing
2403  */
2404 void ast_party_redirecting_free(struct ast_party_redirecting *doomed);
2405
2406 /*!
2407  * \since 1.6.3
2408  * \brief Copy the caller information to the connected line information.
2409  *
2410  * \param dest Destination connected line information
2411  * \param src Source caller information
2412  *
2413  * \return Nothing
2414  *
2415  * \note Assumes locks are already acquired
2416  */
2417 void ast_connected_line_copy_from_caller(struct ast_party_connected_line *dest, const struct ast_callerid *src);
2418
2419 /*!
2420  * \since 1.6.3
2421  * \brief Copy the connected line information to the caller information.
2422  *
2423  * \param dest Destination caller information
2424  * \param src Source connected line information
2425  *
2426  * \return Nothing
2427  *
2428  * \note Assumes locks are already acquired
2429  */
2430 void ast_connected_line_copy_to_caller(struct ast_callerid *dest, const struct ast_party_connected_line *src);
2431
2432 /*!
2433  * \since 1.6.3
2434  * \brief Set the connected line information in the Asterisk channel
2435  *
2436  * \param chan Asterisk channel to set connected line information
2437  * \param connected Connected line information
2438  *
2439  * \return Nothing
2440  *
2441  * \note The channel does not need to be locked before calling this function.
2442  */
2443 void ast_channel_set_connected_line(struct ast_channel *chan, const struct ast_party_connected_line *connected);
2444
2445 /*!
2446  * \since 1.6.3
2447  * \brief Build the connected line information data frame.
2448  *
2449  * \param data Buffer to fill with the frame data
2450  * \param datalen Size of the buffer to fill
2451  * \param connected Connected line information
2452  *
2453  * \retval -1 if error
2454  * \retval Amount of data buffer used
2455  */
2456 int ast_connected_line_build_data(unsigned char *data, size_t datalen, const struct ast_party_connected_line *connected);
2457
2458 /*!
2459  * \since 1.6.3
2460  * \brief Parse connected line indication frame data
2461  *
2462  * \param data Buffer with the frame data to parse
2463  * \param datalen Size of the buffer
2464  * \param connected Extracted connected line information
2465  *
2466  * \retval 0 on success.
2467  * \retval -1 on error.
2468  *
2469  * \note The filled in connected line structure needs to be initialized by
2470  * ast_party_connected_line_set_init() before calling.  If defaults are not
2471  * required use ast_party_connected_line_init().
2472  * \note The filled in connected line structure needs to be destroyed by
2473  * ast_party_connected_line_free() when it is no longer needed.
2474  */
2475 int ast_connected_line_parse_data(const unsigned char *data, size_t datalen, struct ast_party_connected_line *connected);
2476
2477 /*!
2478  * \since 1.6.3
2479  * \brief Indicate that the connected line information has changed
2480  *
2481  * \param chan Asterisk channel to indicate connected line information
2482  * \param connected Connected line information
2483  *
2484  * \return Nothing
2485  */
2486 void ast_channel_update_connected_line(struct ast_channel *chan, const struct ast_party_connected_line *connected);
2487
2488 /*!
2489  * \since 1.6.3
2490  * \brief Queue a connected line update frame on a channel
2491  *
2492  * \param chan Asterisk channel to indicate connected line information
2493  * \param connected Connected line information
2494  *
2495  * \return Nothing
2496  */
2497 void ast_channel_queue_connected_line_update(struct ast_channel *chan, const struct ast_party_connected_line *connected);
2498
2499 /*!
2500  * \since 1.6.3
2501  * \brief Set the redirecting id information in the Asterisk channel
2502  *
2503  * \param chan Asterisk channel to set redirecting id information
2504  * \param redirecting Redirecting id information
2505  *
2506  * \return Nothing
2507  *
2508  * \note The channel does not need to be locked before calling this function.
2509  */
2510 void ast_channel_set_redirecting(struct ast_channel *chan, const struct ast_party_redirecting *redirecting);
2511
2512 /*!
2513  * \since 1.6.3
2514  * \brief Build the redirecting id data frame.
2515  *
2516  * \param data Buffer to fill with the frame data
2517  * \param datalen Size of the buffer to fill
2518  * \param redirecting Redirecting id information
2519  *
2520  * \retval -1 if error
2521  * \retval Amount of data buffer used
2522  */
2523 int ast_redirecting_build_data(unsigned char *data, size_t datalen, const struct ast_party_redirecting *redirecting);
2524
2525 /*!
2526  * \since 1.6.3
2527  * \brief Parse redirecting indication frame data
2528  *
2529  * \param data Buffer with the frame data to parse
2530  * \param datalen Size of the buffer
2531  * \param redirecting Extracted redirecting id information
2532  *
2533  * \retval 0 on success.
2534  * \retval -1 on error.
2535  *
2536  * \note The filled in id structure needs to be initialized by
2537  * ast_party_redirecting_set_init() before calling.
2538  * \note The filled in id structure needs to be destroyed by
2539  * ast_party_redirecting_free() when it is no longer needed.
2540  */
2541 int ast_redirecting_parse_data(const unsigned char *data, size_t datalen, struct ast_party_redirecting *redirecting);
2542
2543 /*!
2544  * \since 1.6.3
2545  * \brief Indicate that the redirecting id has changed
2546  *
2547  * \param chan Asterisk channel to indicate redirecting id information
2548  * \param redirecting Redirecting id information
2549  *
2550  * \return Nothing
2551  */
2552 void ast_channel_update_redirecting(struct ast_channel *chan, const struct ast_party_redirecting *redirecting);
2553
2554 /*!
2555  * \since 1.6.3
2556  * \brief Queue a redirecting update frame on a channel
2557  *
2558  * \param chan Asterisk channel to indicate redirecting id information
2559  * \param redirecting Redirecting id information
2560  *
2561  * \return Nothing
2562  */
2563 void ast_channel_queue_redirecting_update(struct ast_channel *chan, const struct ast_party_redirecting *redirecting);
2564
2565 /*!
2566  * \since 1.6.3
2567  * \brief Run a connected line interception macro and update a channel's connected line
2568  * information
2569  *
2570  * Whenever we want to update a channel's connected line information, we may need to run
2571  * a macro so that an administrator can manipulate the information before sending it 
2572  * out. This function both runs the macro and sends the update to the channel.
2573  *
2574  * \param autoservice_chan Channel to place into autoservice while the macro is running. 
2575  *      It is perfectly safe for this to be NULL 
2576  * \param macro_chan The channel to run the macro on. Also the channel from which we 
2577  *      determine which macro we need to run.
2578  * \param connected_info Either an ast_party_connected_line or ast_frame pointer of type 
2579  *      AST_CONTROL_CONNECTED_LINE
2580  * \param caller If true, then run CONNECTED_LINE_CALLER_SEND_MACRO, otherwise run 
2581  *      CONNECTED_LINE_CALLEE_SEND_MACRO
2582  * \param frame If true, then connected_info is an ast_frame pointer, otherwise it is an 
2583  *      ast_party_connected_line pointer.
2584  * \retval 0 Success
2585  * \retval -1 Either the macro does not exist, or there was an error while attempting to 
2586  *      run the macro
2587  *
2588  * \todo Have multiple return codes based on the MACRO_RESULT
2589  * \todo Make constants so that caller and frame can be more expressive than just '1' and
2590  *      '0'
2591  */
2592 int ast_channel_connected_line_macro(struct ast_channel *autoservice_chan, struct ast_channel *macro_chan, const void *connected_info, int caller, int frame);
2593 #if defined(__cplusplus) || defined(c_plusplus)
2594 }
2595 #endif
2596
2597 #endif /* _ASTERISK_CHANNEL_H */