/
channel.h
4768 lines (4335 loc) · 170 KB
/
channel.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
/*
* Asterisk -- An open source telephony toolkit.
*
* Copyright (C) 1999 - 2006, Digium, Inc.
*
* Mark Spencer <markster@digium.com>
*
* See http://www.asterisk.org for more information about
* the Asterisk project. Please do not directly contact
* any of the maintainers of this project for assistance;
* the project provides a web site, mailing lists and IRC
* channels for your use.
*
* This program is free software, distributed under the terms of
* the GNU General Public License Version 2. See the LICENSE file
* at the top of the source tree.
*/
/*! \file
* \brief General Asterisk PBX channel definitions.
* \par See also:
* \arg \ref Def_Channel
* \arg \ref channel_drivers
*/
/*! \page Def_Channel Asterisk Channels
\par What is a Channel?
A phone call through Asterisk consists of an incoming
connection and an outbound connection. Each call comes
in through a channel driver that supports one technology,
like SIP, DAHDI, IAX2 etc.
\par
Each channel driver, technology, has it's own private
channel or dialog structure, that is technology-dependent.
Each private structure is "owned" by a generic Asterisk
channel structure, defined in channel.h and handled by
channel.c .
\par Call scenario
This happens when an incoming call arrives to Asterisk
-# Call arrives on a channel driver interface
-# Channel driver creates a PBX channel and starts a
pbx thread on the channel
-# The dial plan is executed
-# At this point at least two things can happen:
-# The call is answered by Asterisk and
Asterisk plays a media stream or reads media
-# The dial plan forces Asterisk to create an outbound
call somewhere with the dial (see \ref app_dial.c)
application
.
\par Bridging channels
If Asterisk dials out this happens:
-# Dial creates an outbound PBX channel and asks one of the
channel drivers to create a call
-# When the call is answered, Asterisk bridges the media streams
so the caller on the first channel can speak with the callee
on the second, outbound channel
-# In some cases where we have the same technology on both
channels and compatible codecs, a native bridge is used.
In a native bridge, the channel driver handles forwarding
of incoming audio to the outbound stream internally, without
sending audio frames through the PBX.
-# In SIP, theres an "external native bridge" where Asterisk
redirects the endpoint, so audio flows directly between the
caller's phone and the callee's phone. Signalling stays in
Asterisk in order to be able to provide a proper CDR record
for the call.
\par Masquerading channels
In some cases, a channel can masquerade itself into another
channel. This happens frequently in call transfers, where
a new channel takes over a channel that is already involved
in a call. The new channel sneaks in and takes over the bridge
and the old channel, now a zombie, is hung up.
\par Reference
\arg channel.c - generic functions
\arg channel.h - declarations of functions, flags and structures
\arg translate.h - Transcoding support functions
\arg \ref channel_drivers - Implemented channel drivers
\arg \ref Def_Frame Asterisk Multimedia Frames
\arg \ref Def_Bridge
*/
/*! \page Def_Bridge Asterisk Channel Bridges
In Asterisk, there's several media bridges.
The Core bridge handles two channels (a "phone call") and bridge
them together.
The conference bridge (meetme) handles several channels simultaneously
with the support of an external timer (DAHDI timer). This is used
not only by the Conference application (meetme) but also by the
page application and the SLA system introduced in 1.4.
The conference bridge does not handle video.
When two channels of the same type connect, the channel driver
or the media subsystem used by the channel driver (i.e. RTP)
can create a native bridge without sending media through the
core.
Native bridging can be disabled by a number of reasons,
like DTMF being needed by the core or codecs being incompatible
so a transcoding module is needed.
References:
\li \see ast_channel_early_bridge()
\li \see ast_channel_bridge()
\li \see app_meetme.c
\li \ref AstRTPbridge
\li \see ast_rtp_bridge()
\li \ref Def_Channel
*/
/*! \page AstFileDesc File descriptors
Asterisk File descriptors are connected to each channel (see \ref Def_Channel)
in the \ref ast_channel structure.
*/
#ifndef _ASTERISK_CHANNEL_H
#define _ASTERISK_CHANNEL_H
#include "asterisk/abstract_jb.h"
#include "asterisk/astobj2.h"
#include "asterisk/poll-compat.h"
#if defined(__cplusplus) || defined(c_plusplus)
extern "C" {
#endif
#define AST_MAX_EXTENSION 80 /*!< Max length of an extension */
#define AST_MAX_CONTEXT 80 /*!< Max length of a context */
/*!
* Max length of a channel uniqueid reported to the outside world.
*
* \details
* 149 = 127 (max systemname) + "-" + 10 (epoch timestamp)
* + "." + 10 (monotonically incrementing integer).
*
* \note If this value is ever changed, MAX_CHANNEL_ID should
* be updated in rtp_engine.h.
*/
#define AST_MAX_PUBLIC_UNIQUEID 149
/*!
* Maximum size of an internal Asterisk channel unique ID.
*
* \details
* Add two for the Local;2 channel to append a ';2' if needed
* plus nul terminator.
*
* \note If this value is ever changed, MAX_CHANNEL_ID should
* be updated in rtp_engine.h.
*/
#define AST_MAX_UNIQUEID (AST_MAX_PUBLIC_UNIQUEID + 2 + 1)
#define AST_MAX_ACCOUNT_CODE 80 /*!< Max length of an account code */
#define AST_CHANNEL_NAME 80 /*!< Max length of an ast_channel name */
#define MAX_LANGUAGE 40 /*!< Max length of the language setting */
#define MAX_MUSICCLASS 80 /*!< Max length of the music class setting */
#define AST_MAX_USER_FIELD 256 /*!< Max length of the channel user field */
#include "asterisk/frame.h"
#include "asterisk/chanvars.h"
#include "asterisk/config.h"
#include "asterisk/lock.h"
#include "asterisk/cdr.h"
#include "asterisk/utils.h"
#include "asterisk/linkedlists.h"
#include "asterisk/stringfields.h"
#include "asterisk/datastore.h"
#include "asterisk/data.h"
#include "asterisk/channelstate.h"
#include "asterisk/ccss.h"
#include "asterisk/framehook.h"
#include "asterisk/stasis.h"
#include "asterisk/json.h"
#include "asterisk/endpoints.h"
#define DATASTORE_INHERIT_FOREVER INT_MAX
#define AST_MAX_FDS 11
/*
* We have AST_MAX_FDS file descriptors in a channel.
* Some of them have a fixed use:
*/
#define AST_ALERT_FD (AST_MAX_FDS-1) /*!< used for alertpipe */
#define AST_TIMING_FD (AST_MAX_FDS-2) /*!< used for timingfd */
#define AST_AGENT_FD (AST_MAX_FDS-3) /*!< used by agents for pass through */
#define AST_GENERATOR_FD (AST_MAX_FDS-4) /*!< used by generator */
#define AST_JITTERBUFFER_FD (AST_MAX_FDS-5) /*!< used by generator */
enum ast_bridge_result {
AST_BRIDGE_COMPLETE = 0,
AST_BRIDGE_FAILED = -1,
AST_BRIDGE_FAILED_NOWARN = -2,
AST_BRIDGE_RETRY = -3,
};
typedef unsigned long long ast_group_t;
/*! \todo Add an explanation of an Asterisk generator
*/
struct ast_generator {
void *(*alloc)(struct ast_channel *chan, void *params);
/*! Channel is locked during this function callback. */
void (*release)(struct ast_channel *chan, void *data);
/*! This function gets called with the channel unlocked, but is called in
* the context of the channel thread so we know the channel is not going
* to disappear. This callback is responsible for locking the channel as
* necessary. */
int (*generate)(struct ast_channel *chan, void *data, int len, int samples);
/*! This gets called when DTMF_END frames are read from the channel */
void (*digit)(struct ast_channel *chan, char digit);
/*! This gets called when the write format on a channel is changed while
* generating. The channel is locked during this callback. */
void (*write_format_change)(struct ast_channel *chan, void *data);
};
/*! Party name character set enumeration values (values from Q.SIG) */
enum AST_PARTY_CHAR_SET {
AST_PARTY_CHAR_SET_UNKNOWN = 0,
AST_PARTY_CHAR_SET_ISO8859_1 = 1,
AST_PARTY_CHAR_SET_WITHDRAWN = 2,/* ITU withdrew this enum value. */
AST_PARTY_CHAR_SET_ISO8859_2 = 3,
AST_PARTY_CHAR_SET_ISO8859_3 = 4,
AST_PARTY_CHAR_SET_ISO8859_4 = 5,
AST_PARTY_CHAR_SET_ISO8859_5 = 6,
AST_PARTY_CHAR_SET_ISO8859_7 = 7,
AST_PARTY_CHAR_SET_ISO10646_BMPSTRING = 8,
AST_PARTY_CHAR_SET_ISO10646_UTF_8STRING = 9,
};
/*!
* \since 1.8
* \brief Information needed to specify a name in a call.
* \note All string fields here are malloc'ed, so they need to be
* freed when the structure is deleted.
* \note NULL and "" must be considered equivalent.
*/
struct ast_party_name {
/*! \brief Subscriber name (Malloced) */
char *str;
/*!
* \brief Character set the name is using.
* \see enum AST_PARTY_CHAR_SET
* \note
* Set to AST_PARTY_CHAR_SET_ISO8859_1 if unsure what to use.
* \todo Start using the party name character set value. Not currently used.
*/
int char_set;
/*!
* \brief Q.931 encoded presentation-indicator encoded field
* \note Must tolerate the Q.931 screening-indicator field values being present.
*/
int presentation;
/*! \brief TRUE if the name information is valid/present */
unsigned char valid;
};
/*!
* \since 1.8
* \brief Information needed to specify a number in a call.
* \note All string fields here are malloc'ed, so they need to be
* freed when the structure is deleted.
* \note NULL and "" must be considered equivalent.
*/
struct ast_party_number {
/*! \brief Subscriber phone number (Malloced) */
char *str;
/*! \brief Q.931 Type-Of-Number and Numbering-Plan encoded fields */
int plan;
/*! \brief Q.931 presentation-indicator and screening-indicator encoded fields */
int presentation;
/*! \brief TRUE if the number information is valid/present */
unsigned char valid;
};
/*!
* \since 1.8
* \brief Information needed to specify a subaddress in a call.
* \note All string fields here are malloc'ed, so they need to be
* freed when the structure is deleted.
* \note NULL and "" must be considered equivalent.
*/
struct ast_party_subaddress {
/*!
* \brief Malloced subaddress string.
* \note If the subaddress type is user specified then the subaddress is
* a string of ASCII hex because the actual subaddress is likely BCD encoded.
*/
char *str;
/*!
* \brief Q.931 subaddress type.
* \details
* nsap(0),
* user_specified(2)
*/
int type;
/*!
* \brief TRUE if odd number of address signals
* \note The odd/even indicator is used when the type of subaddress is
* user_specified and the coding is BCD.
*/
unsigned char odd_even_indicator;
/*! \brief TRUE if the subaddress information is valid/present */
unsigned char valid;
};
/*!
* \since 1.8
* \brief Information needed to identify an endpoint in a call.
* \note All string fields here are malloc'ed, so they need to be
* freed when the structure is deleted.
* \note NULL and "" must be considered equivalent.
*/
struct ast_party_id {
/*! \brief Subscriber name */
struct ast_party_name name;
/*! \brief Subscriber phone number */
struct ast_party_number number;
/*! \brief Subscriber subaddress. */
struct ast_party_subaddress subaddress;
/*!
* \brief User-set "tag"
* \details
* A user-settable field used to help associate some extrinsic information
* about the channel or user of the channel to the party ID. This information
* is normally not transmitted over the wire and so is only useful within an
* Asterisk environment.
*/
char *tag;
};
/*!
* \since 1.8
* \brief Indicate what information in ast_party_id should be set.
*/
struct ast_set_party_id {
/*! TRUE if the ast_party_name information should be set. */
unsigned char name;
/*! TRUE if the ast_party_number information should be set. */
unsigned char number;
/*! TRUE if the ast_party_subaddress information should be set. */
unsigned char subaddress;
};
/*!
* \since 1.8
* \brief Dialed/Called Party information.
* \note Dialed Number Identifier (DNID)
* \note All string fields here are malloc'ed, so they need to be
* freed when the structure is deleted.
* \note NULL and "" must be considered equivalent.
*/
struct ast_party_dialed {
/*!
* \brief Dialed/Called number
* \note Done this way in case we ever really need to use ast_party_number.
* We currently do not need all of the ast_party_number fields.
*/
struct {
/*! \brief Subscriber phone number (Malloced) */
char *str;
/*! \brief Q.931 Type-Of-Number and Numbering-Plan encoded fields */
int plan;
} number;
/*! \brief Dialed/Called subaddress */
struct ast_party_subaddress subaddress;
/*!
* \brief Transit Network Select
* \note Currently this value is just passed around the system.
* You can read it and set it but it is never used for anything.
*/
int transit_network_select;
};
/*!
* \since 1.8
* \brief Caller Party information.
* \note All string fields here are malloc'ed, so they need to be
* freed when the structure is deleted.
* \note NULL and "" must be considered equivalent.
*
* \note SIP and IAX2 has UTF8 encoded Unicode Caller ID names.
* In some cases, we also have an alternative (RPID) E.164 number that can
* be used as Caller ID on numeric E.164 phone networks (DAHDI or SIP/IAX2 to
* PSTN gateway).
*
* \todo Implement settings for transliteration between UTF8 Caller ID names in
* to ASCII Caller ID's (DAHDI). Östen Åsklund might be transliterated into
* Osten Asklund or Oesten Aasklund depending upon language and person...
* We need automatic routines for incoming calls and static settings for
* our own accounts.
*/
struct ast_party_caller {
/*! \brief Caller party ID */
struct ast_party_id id;
/*!
* \brief Automatic Number Identification (ANI)
* \note The name subcomponent is only likely to be used by SIP.
* \note The subaddress subcomponent is not likely to be used.
*/
struct ast_party_id ani;
/*! \brief Private caller party ID */
struct ast_party_id priv;
/*! \brief Automatic Number Identification 2 (Info Digits) */
int ani2;
};
/*!
* \since 1.8
* \brief Indicate what information in ast_party_caller should be set.
*/
struct ast_set_party_caller {
/*! What caller id information to set. */
struct ast_set_party_id id;
/*! What ANI id information to set. */
struct ast_set_party_id ani;
/*! What private caller id information to set. */
struct ast_set_party_id priv;
};
/*!
* \since 1.8
* \brief Connected Line/Party information.
* \note All string fields here are malloc'ed, so they need to be
* freed when the structure is deleted.
* \note NULL and "" must be considered equivalent.
*/
struct ast_party_connected_line {
/*! \brief Connected party ID */
struct ast_party_id id;
/*!
* \brief Automatic Number Identification (ANI)
* \note Not really part of connected line data but needed to
* save the corresponding caller id value.
*/
struct ast_party_id ani;
/*! \brief Private connected party ID */
struct ast_party_id priv;
/*!
* \brief Automatic Number Identification 2 (Info Digits)
* \note Not really part of connected line data but needed to
* save the corresponding caller id value.
*/
int ani2;
/*!
* \brief Information about the source of an update.
* \note enum AST_CONNECTED_LINE_UPDATE_SOURCE values
* for Normal-Answer and Call-transfer.
*/
int source;
};
/*!
* \since 1.8
* \brief Indicate what information in ast_party_connected_line should be set.
*/
struct ast_set_party_connected_line {
/*! What connected line id information to set. */
struct ast_set_party_id id;
/*! What ANI id information to set. */
struct ast_set_party_id ani;
/*! What private connected line id information to set. */
struct ast_set_party_id priv;
};
/*!
* \brief Redirecting reason information
*/
struct ast_party_redirecting_reason {
/*! \brief a string value for the redirecting reason
*
* Useful for cases where an endpoint has specified a redirecting reason
* that does not correspond to an enum AST_REDIRECTING_REASON
*/
char *str;
/*! \brief enum AST_REDIRECTING_REASON value for redirection */
int code;
};
/*!
* \since 1.8
* \brief Redirecting Line information.
* RDNIS (Redirecting Directory Number Information Service)
* Where a call diversion or transfer was invoked.
* \note All string fields here are malloc'ed, so they need to be
* freed when the structure is deleted.
* \note NULL and "" must be considered equivalent.
*/
struct ast_party_redirecting {
/*! \brief Who originally redirected the call (Sent to the party the call is redirected toward) */
struct ast_party_id orig;
/*! \brief Who is redirecting the call (Sent to the party the call is redirected toward) */
struct ast_party_id from;
/*! \brief Call is redirecting to a new party (Sent to the caller) */
struct ast_party_id to;
/*! \brief Who originally redirected the call (Sent to the party the call is redirected toward) - private representation */
struct ast_party_id priv_orig;
/*! \brief Who is redirecting the call (Sent to the party the call is redirected toward) - private representation */
struct ast_party_id priv_from;
/*! \brief Call is redirecting to a new party (Sent to the caller) - private representation */
struct ast_party_id priv_to;
/*! \brief Reason for the redirection */
struct ast_party_redirecting_reason reason;
/*! \brief Reason for the redirection by the original party */
struct ast_party_redirecting_reason orig_reason;
/*! \brief Number of times the call was redirected */
int count;
};
/*!
* \since 1.8
* \brief Indicate what information in ast_party_redirecting should be set.
*/
struct ast_set_party_redirecting {
/*! What redirecting-orig id information to set. */
struct ast_set_party_id orig;
/*! What redirecting-from id information to set. */
struct ast_set_party_id from;
/*! What redirecting-to id information to set. */
struct ast_set_party_id to;
/*! What private redirecting-orig id information to set. */
struct ast_set_party_id priv_orig;
/*! What private redirecting-from id information to set. */
struct ast_set_party_id priv_from;
/*! What private redirecting-to id information to set. */
struct ast_set_party_id priv_to;
};
/*!
* \brief Typedef for a custom read function
* \note data should be treated as const char *.
*/
typedef int (*ast_acf_read_fn_t)(struct ast_channel *chan, const char *function, char *data, char *buf, size_t len);
/*!
* \brief Typedef for a custom read2 function
* \note data should be treated as const char *.
*/
typedef int (*ast_acf_read2_fn_t)(struct ast_channel *chan, const char *cmd, char *data, struct ast_str **str, ssize_t len);
/*!
* \brief Typedef for a custom write function
* \note data should be treated as const char *.
*/
typedef int (*ast_acf_write_fn_t)(struct ast_channel *chan, const char *function, char *data, const char *value);
/*! \brief Structure to handle passing func_channel_write info to channels via setoption */
typedef struct {
/*! \brief ast_chan_write_info_t version. Must be incremented if structure is changed */
#define AST_CHAN_WRITE_INFO_T_VERSION 1
uint32_t version;
ast_acf_write_fn_t write_fn;
struct ast_channel *chan;
const char *function;
char *data;
const char *value;
} ast_chan_write_info_t;
/*!
* \brief Structure to pass both assignedid values to channel drivers
* \note The second value is used only by core_unreal (LOCAL)
*/
struct ast_assigned_ids {
const char *uniqueid;
const char *uniqueid2;
};
/*!
* \brief
* Structure to describe a channel "technology", ie a channel driver
* See for examples:
* \arg chan_iax2.c - The Inter-Asterisk exchange protocol
* \arg chan_sip.c - The SIP channel driver
* \arg chan_dahdi.c - PSTN connectivity (TDM, PRI, T1/E1, FXO, FXS)
*
* \details
* If you develop your own channel driver, this is where you
* tell the PBX at registration of your driver what properties
* this driver supports and where different callbacks are
* implemented.
*/
struct ast_channel_tech {
const char * const type;
const char * const description;
struct ast_format_cap *capabilities; /*!< format capabilities this channel can handle */
int properties; /*!< Technology Properties */
/*!
* \brief Requester - to set up call data structures (pvt's)
*
* \param type type of channel to request
* \param cap Format capabilities for requested channel
* \param assignedid Unique ID string to assign to channel
* \param requestor channel asking for data
* \param addr destination of the call
* \param cause Cause of failure
*
* \details
* Request a channel of a given type, with addr as optional information used
* by the low level module
*
* \retval NULL failure
* \retval non-NULL channel on success
*/
struct ast_channel *(* const requester)(const char *type, struct ast_format_cap *cap, const struct ast_assigned_ids *assignedids, const struct ast_channel *requestor, const char *addr, int *cause);
int (* const devicestate)(const char *device_number); /*!< Devicestate call back */
int (* const presencestate)(const char *presence_provider, char **subtype, char **message); /*!< Presencestate callback */
/*!
* \brief Start sending a literal DTMF digit
*
* \note The channel is not locked when this function gets called.
*/
int (* const send_digit_begin)(struct ast_channel *chan, char digit);
/*!
* \brief Stop sending a literal DTMF digit
*
* \note The channel is not locked when this function gets called.
*/
int (* const send_digit_end)(struct ast_channel *chan, char digit, unsigned int duration);
/*!
* \brief Make a call
* \note The channel is locked when called.
* \param chan which channel to make the call on
* \param addr destination of the call
* \param timeout time to wait on for connect (Doesn't seem to be used.)
* \retval 0 on success
* \retval -1 on failure
*/
int (* const call)(struct ast_channel *chan, const char *addr, int timeout);
/*! \brief Hangup (and possibly destroy) the channel */
int (* const hangup)(struct ast_channel *chan);
/*! \brief Answer the channel */
int (* const answer)(struct ast_channel *chan);
/*! \brief Read a frame, in standard format (see frame.h) */
struct ast_frame * (* const read)(struct ast_channel *chan);
/*! \brief Write a frame, in standard format (see frame.h) */
int (* const write)(struct ast_channel *chan, struct ast_frame *frame);
/*! \brief Display or transmit text */
int (* const send_text)(struct ast_channel *chan, const char *text);
/*! \brief Display or send an image */
int (* const send_image)(struct ast_channel *chan, struct ast_frame *frame);
/*! \brief Send HTML data */
int (* const send_html)(struct ast_channel *chan, int subclass, const char *data, int len);
/*! \brief Handle an exception, reading a frame */
struct ast_frame * (* const exception)(struct ast_channel *chan);
/*! \brief Bridge two channels of the same type together (early) */
enum ast_bridge_result (* const early_bridge)(struct ast_channel *c0, struct ast_channel *c1);
/*! \brief Indicate a particular condition (e.g. AST_CONTROL_BUSY or AST_CONTROL_RINGING or AST_CONTROL_CONGESTION */
int (* const indicate)(struct ast_channel *c, int condition, const void *data, size_t datalen);
/*! \brief Fix up a channel: If a channel is consumed, this is called. Basically update any ->owner links */
int (* const fixup)(struct ast_channel *oldchan, struct ast_channel *newchan);
/*! \brief Set a given option. Called with chan locked */
int (* const setoption)(struct ast_channel *chan, int option, void *data, int datalen);
/*! \brief Query a given option. Called with chan locked */
int (* const queryoption)(struct ast_channel *chan, int option, void *data, int *datalen);
/*! \brief Blind transfer other side (see app_transfer.c and ast_transfer() */
int (* const transfer)(struct ast_channel *chan, const char *newdest);
/*! \brief Write a frame, in standard format */
int (* const write_video)(struct ast_channel *chan, struct ast_frame *frame);
/*! \brief Write a text frame, in standard format */
int (* const write_text)(struct ast_channel *chan, struct ast_frame *frame);
/*!
* \brief Provide additional read items for CHANNEL() dialplan function
* \note data should be treated as a const char *.
*/
int (* func_channel_read)(struct ast_channel *chan, const char *function, char *data, char *buf, size_t len);
/*!
* \brief Provide additional write items for CHANNEL() dialplan function
* \note data should be treated as a const char *.
*/
int (* func_channel_write)(struct ast_channel *chan, const char *function, char *data, const char *value);
/*! \brief Get the unique identifier for the PVT, i.e. SIP call-ID for SIP */
const char * (* get_pvt_uniqueid)(struct ast_channel *chan);
/*! \brief Call a function with cc parameters as a function parameter
*
* \details
* This is a highly specialized callback that is not likely to be needed in many
* channel drivers. When dealing with a busy channel, for instance, most channel
* drivers will successfully return a channel to the requester. Once called, the channel
* can then queue a busy frame when it receives an appropriate message from the far end.
* In such a case, the channel driver has the opportunity to also queue a CC frame.
* The parameters for the CC channel can be retrieved from the channel structure.
*
* For other channel drivers, notably those that deal with "dumb" phones, the channel
* driver will not return a channel when one is requested. In such a scenario, there is never
* an opportunity for the channel driver to queue a CC frame since the channel is never
* called. Furthermore, it is not possible to retrieve the CC configuration parameters
* for the desired channel because no channel is ever allocated or returned to the
* requester. In such a case, call completion may still be a viable option. What we do is
* pass the same string that the requester used originally to request the channel to the
* channel driver. The channel driver can then find any potential channels/devices that
* match the input and return call the designated callback with the device's call completion
* parameters as a parameter.
*/
int (* cc_callback)(struct ast_channel *inbound, const char *dest, ast_cc_callback_fn callback);
/*!
* \brief Execute a Gosub call on the channel in a technology specific way before a call is placed.
* \since 11.0
*
* \param chan Channel to execute Gosub in a tech specific way.
* \param sub_args Gosub application parameter string.
*
* \note The chan is locked before calling.
*
* \retval 0 on success.
* \retval -1 on error.
*/
int (*pre_call)(struct ast_channel *chan, const char *sub_args);
};
/*! Kill the channel channel driver technology descriptor. */
extern const struct ast_channel_tech ast_kill_tech;
struct ast_epoll_data;
/*!
* The high bit of the frame count is used as a debug marker, so
* increments of the counters must be done with care.
* Please use c->fin = FRAMECOUNT_INC(c->fin) and the same for c->fout.
*/
#define DEBUGCHAN_FLAG 0x80000000
/* XXX not ideal to evaluate x twice... */
#define FRAMECOUNT_INC(x) ( ((x) & DEBUGCHAN_FLAG) | (((x)+1) & ~DEBUGCHAN_FLAG) )
/*!
* The current value of the debug flags is stored in the two
* variables global_fin and global_fout (declared in main/channel.c)
*/
extern unsigned long global_fin, global_fout;
enum ast_channel_adsicpe {
AST_ADSI_UNKNOWN,
AST_ADSI_AVAILABLE,
AST_ADSI_UNAVAILABLE,
AST_ADSI_OFFHOOKONLY,
};
/*!
* \brief Possible T38 states on channels
*/
enum ast_t38_state {
T38_STATE_UNAVAILABLE, /*!< T38 is unavailable on this channel or disabled by configuration */
T38_STATE_UNKNOWN, /*!< The channel supports T38 but the current status is unknown */
T38_STATE_NEGOTIATING, /*!< T38 is being negotiated */
T38_STATE_REJECTED, /*!< Remote side has rejected our offer */
T38_STATE_NEGOTIATED, /*!< T38 established */
};
/*! Hangup handler instance node. */
struct ast_hangup_handler {
/*! Next hangup handler node. */
AST_LIST_ENTRY(ast_hangup_handler) node;
/*! Hangup handler arg string passed to the Gosub application */
char args[0];
};
AST_LIST_HEAD_NOLOCK(ast_hangup_handler_list, ast_hangup_handler);
AST_LIST_HEAD_NOLOCK(ast_datastore_list, ast_datastore);
AST_LIST_HEAD_NOLOCK(ast_autochan_list, ast_autochan);
AST_LIST_HEAD_NOLOCK(ast_readq_list, ast_frame);
typedef int(*ast_timing_func_t)(const void *data);
/*!
* \page AstChannel ast_channel locking and reference tracking
*
* \par Creating Channels
* A channel is allocated using the ast_channel_alloc() function. When created, it is
* automatically inserted into the main channels hash table that keeps track of all
* active channels in the system. The hash key is based on the channel name. Because
* of this, if you want to change the name, you _must_ use ast_change_name(), not change
* the name field directly. When ast_channel_alloc() returns a channel pointer, you now
* hold both a reference to that channel and a lock on the channel. Once the channel has
* been set up the lock can be released. In most cases the reference is given to ast_pbx_run().
*
* \par Channel Locking
* There is a lock associated with every ast_channel. It is allocated internally via astobj2.
* To lock or unlock a channel, you must use the ast_channel_lock() wrappers.
*
* Previously, before ast_channel was converted to astobj2, the channel lock was used in some
* additional ways that are no longer necessary. Before, the only way to ensure that a channel
* did not disappear out from under you if you were working with a channel outside of the channel
* thread that owns it, was to hold the channel lock. Now, that is no longer necessary.
* You simply must hold a reference to the channel to ensure it does not go away.
*
* The channel must be locked if you need to ensure that data that you reading from the channel
* does not change while you access it. Further, you must hold the channel lock if you are
* making a non-atomic change to channel data.
*
* \par Channel References
* There are multiple ways to get a reference to a channel. The first is that you hold a reference
* to a channel after creating it. The other ways involve using the channel search or the channel
* traversal APIs. These functions are the ast_channel_get_*() functions or ast_channel_iterator_*()
* functions. Once a reference is retrieved by one of these methods, you know that the channel will
* not go away. So, the channel should only get locked as needed for data access or modification.
* But, make sure that the reference gets released when you are done with it!
*
* There are different things you can do when you are done with a reference to a channel. The first
* is to simply release the reference using ast_channel_unref(). The other option is to call
* ast_channel_release(). This function is generally used where ast_channel_free() was used in
* the past. The release function releases a reference as well as ensures that the channel is no
* longer in the global channels container. That way, the channel will get destroyed as soon as any
* other pending references get released.
*
* \par Exceptions to the rules
* Even though ast_channel is reference counted, there are some places where pointers to an ast_channel
* get stored, but the reference count does not reflect it. The reason is mostly historical.
* The only places where this happens should be places where because of how the code works, we
* _know_ that the pointer to the channel will get removed before the channel goes away. The main
* example of this is in channel drivers. Channel drivers generally store a pointer to their owner
* ast_channel in their technology specific pvt struct. In this case, the channel drivers _know_
* that this pointer to the channel will be removed in time, because the channel's hangup callback
* gets called before the channel goes away.
*/
struct ast_channel;
/*! \brief ast_channel_tech Properties */
enum {
/*!
* \brief Channels have this property if they can accept input with jitter;
* i.e. most VoIP channels
*/
AST_CHAN_TP_WANTSJITTER = (1 << 0),
/*!
* \brief Channels have this property if they can create jitter;
* i.e. most VoIP channels
*/
AST_CHAN_TP_CREATESJITTER = (1 << 1),
/*!
* \brief Channels with this particular technology are an implementation detail of
* Asterisk and should generally not be exposed or manipulated by the outside
* world
*/
AST_CHAN_TP_INTERNAL = (1 << 2),
};
/*! \brief ast_channel flags */
enum {
/*! Queue incoming DTMF, to be released when this flag is turned off */
AST_FLAG_DEFER_DTMF = (1 << 1),
/*! write should be interrupt generator */
AST_FLAG_WRITE_INT = (1 << 2),
/*! a thread is blocking on this channel */
AST_FLAG_BLOCKING = (1 << 3),
/*! This is a zombie channel */
AST_FLAG_ZOMBIE = (1 << 4),
/*! There is an exception pending */
AST_FLAG_EXCEPTION = (1 << 5),
/*! Listening to moh XXX anthm promises me this will disappear XXX */
AST_FLAG_MOH = (1 << 6),
/*! This channel is spying on another channel */
AST_FLAG_SPYING = (1 << 7),
/*! the channel is in an auto-incrementing dialplan processor,
* so when ->priority is set, it will get incremented before
* finding the next priority to run */
AST_FLAG_IN_AUTOLOOP = (1 << 9),
/*! This is an outgoing call */
AST_FLAG_OUTGOING = (1 << 10),
/*! A DTMF_BEGIN frame has been read from this channel, but not yet an END */
AST_FLAG_IN_DTMF = (1 << 12),
/*! A DTMF_END was received when not IN_DTMF, so the length of the digit is
* currently being emulated */
AST_FLAG_EMULATE_DTMF = (1 << 13),
/*! This is set to tell the channel not to generate DTMF begin frames, and
* to instead only generate END frames. */
AST_FLAG_END_DTMF_ONLY = (1 << 14),
/* OBSOLETED in favor of AST_CAUSE_ANSWERED_ELSEWHERE
* Flag to show channels that this call is hangup due to the fact that the call
* was indeed answered, but in another channel */
/* AST_FLAG_ANSWERED_ELSEWHERE = (1 << 15), */
/*! This flag indicates that on a masquerade, an active stream should not
* be carried over */
AST_FLAG_MASQ_NOSTREAM = (1 << 16),
/*! This flag indicates that the hangup exten was run when the bridge terminated,
* a message aimed at preventing a subsequent hangup exten being run at the pbx_run
* level */
AST_FLAG_BRIDGE_HANGUP_RUN = (1 << 17),
/*! Disable certain workarounds. This reintroduces certain bugs, but allows
* some non-traditional dialplans (like AGI) to continue to function.
*/
AST_FLAG_DISABLE_WORKAROUNDS = (1 << 20),
/*!
* Disable device state event caching. This allows channel
* drivers to selectively prevent device state events from being
* cached by certain channels such as anonymous calls which have
* no persistent represenatation that can be tracked.
*/
AST_FLAG_DISABLE_DEVSTATE_CACHE = (1 << 21),
/*!
* This flag indicates that a dual channel redirect is in
* progress. The bridge needs to wait until the flag is cleared
* to continue.
*/
AST_FLAG_BRIDGE_DUAL_REDIRECT_WAIT = (1 << 22),
/*!
* This flag indicates that the channel was originated.
*/
AST_FLAG_ORIGINATED = (1 << 23),
/*!
* The channel is well and truly dead. Once this is set and published, no further
* actions should be taken upon the channel, and no further publications should
* occur.
*/
AST_FLAG_DEAD = (1 << 24),
/*!
* Channel snapshot should not be published, it is being staged for an explicit
* publish.
*/
AST_FLAG_SNAPSHOT_STAGE = (1 << 25),
/*!
* The data on chan->timingdata is an astobj2 object.
*/
AST_FLAG_TIMINGDATA_IS_AO2_OBJ = (1 << 26),
/*!
* The channel is executing a subroutine or macro
*/
AST_FLAG_SUBROUTINE_EXEC = (1 << 27),
/*!
* The channel is currently in an operation where
* frames should be deferred.
*/
AST_FLAG_DEFER_FRAMES = (1 << 28),
/*!
* The channel is currently deferring hangup frames
* in addition to other frame types.
*/
AST_FLAG_DEFER_HANGUP_FRAMES = (1 << 29),
};
/*! \brief ast_bridge_config flags */
enum {
AST_FEATURE_PLAY_WARNING = (1 << 0),
AST_FEATURE_REDIRECT = (1 << 1),
AST_FEATURE_DISCONNECT = (1 << 2),
AST_FEATURE_ATXFER = (1 << 3),
AST_FEATURE_AUTOMON = (1 << 4),
AST_FEATURE_PARKCALL = (1 << 5),
AST_FEATURE_AUTOMIXMON = (1 << 6),
};
#define AST_FEATURE_DTMF_MASK (AST_FEATURE_REDIRECT | AST_FEATURE_DISCONNECT |\
AST_FEATURE_ATXFER | AST_FEATURE_AUTOMON | AST_FEATURE_PARKCALL | AST_FEATURE_AUTOMIXMON)
/*! \brief bridge configuration */
struct ast_bridge_config {
struct ast_flags features_caller;
struct ast_flags features_callee;
struct timeval start_time;