Wed Jan 8 2020 09:49:42
Asterisk developer's documentation
Main Page
Related Pages
Modules
Data Structures
Files
File List
Globals
architecture.h
Go to the documentation of this file.
1
/*
2
* Asterisk -- An open source telephony toolkit.
3
*
4
* Copyright (C) 2009, Digium, Inc.
5
*
6
* Russell Bryant <russell@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
/*!
20
* \file
21
* \author Russell Bryant <russell@digium.com>
22
*/
23
24
/*!
25
\page AsteriskArchitecture Asterisk Architecture Overview
26
\author Russell Bryant <russell@digium.com>
27
\AsteriskTrunkWarning
28
29
<hr/>
30
31
\section ArchTOC Table of Contents
32
33
-# \ref ArchIntro
34
-# \ref ArchLayout
35
-# \ref ArchInterfaces
36
-# \ref ArchInterfaceCodec
37
-# \ref ArchInterfaceFormat
38
-# \ref ArchInterfaceAPIs
39
-# \ref ArchInterfaceAMI
40
-# \ref ArchInterfaceChannelDrivers
41
-# \ref ArchInterfaceBridge
42
-# \ref ArchInterfaceCDR
43
-# \ref ArchInterfaceCEL
44
-# \ref ArchInterfaceDialplanApps
45
-# \ref ArchInterfaceDialplanFuncs
46
-# \ref ArchInterfaceRTP
47
-# \ref ArchInterfaceTiming
48
-# \ref ArchThreadingModel
49
-# \ref ArchChannelThreads
50
-# \ref ArchMonitorThreads
51
-# \ref ArchServiceThreads
52
-# \ref ArchOtherThreads
53
-# \ref ArchConcepts
54
-# \ref ArchConceptBridging
55
-# \ref ArchCodeFlows
56
-# \ref ArchCodeFlowPlayback
57
-# \ref ArchCodeFlowBridge
58
-# \ref ArchDataStructures
59
-# \ref ArchAstobj2
60
-# \ref ArchLinkedLists
61
-# \ref ArchDLinkedLists
62
-# \ref ArchHeap
63
-# \ref ArchDebugging
64
-# \ref ArchThreadDebugging
65
-# \ref ArchMemoryDebugging
66
67
<hr/>
68
69
\section ArchIntro Introduction
70
71
This section of the documentation includes an overview of the Asterisk architecture
72
from a developer's point of view. For detailed API discussion, see the documentation
73
associated with public API header files. This documentation assumes some knowledge
74
of what Asterisk is and how to use it.
75
76
The intent behind this documentation is to start looking at Asterisk from a high
77
level and progressively dig deeper into the details. It begins with talking about
78
the different types of components that make up Asterisk and eventually will go
79
through interactions between these components in different use cases.
80
81
Throughout this documentation, many links are also provided as references to more
82
detailed information on related APIs, as well as the related source code to what
83
is being discussed.
84
85
Feedback and contributions to this documentation are very welcome. Please send your
86
comments to the asterisk-dev mailing list on http://lists.digium.com/.
87
88
Thank you, and enjoy Asterisk!
89
90
91
\section ArchLayout Modular Architecture
92
93
Asterisk is a highly modularized application. There is a core application that
94
is built from the source in the <code>main/</code> directory. However, it is
95
not very useful by itself.
96
97
There are many modules that are loaded at runtime. Asterisk modules have names that
98
give an indication as to what functionality they provide, but the name is not special
99
in any technical sense. When Asterisk loads a module, the module registers the
100
functionality that it provides with the Asterisk core.
101
102
-# Asterisk starts
103
-# Asterisk loads modules
104
-# Modules say "Hey Asterisk! I am a module. I can provide functionality X, Y,
105
and Z. Let me know when you'd like to use my functionality!"
106
107
108
\section ArchInterfaces Abstract Interface types
109
110
There are many types of interfaces that modules can implement and register their
111
implementations of with the Asterisk core. Any module is allowed to register as
112
many of these different interfaces as they would like. Generally, related
113
functionality is grouped into a single module.
114
115
In this section, the types of interfaces are discussed. Later, there will
116
be discussions about how different components interact in various scenarios.
117
118
\subsection ArchInterfaceCodec Codec Interpreter
119
120
An implementation of the codec interpreter interface provides the ability to
121
convert between two codecs. Asterisk currently only has the ability to translate
122
between audio codecs.
123
124
These modules have no knowledge about phone calls or anything else about why
125
they are being asked to convert audio. They just get audio samples as input
126
in their specified input format, and are expected to provide audio in the
127
specified output format.
128
129
It is possible to have multiple paths to get from codec A to codec B once many
130
codec implementations are registered. After modules have been loaded, Asterisk
131
builds a translation table with measurements of the performance of each codec
132
translator so that it can always find the best path to get from A to B.
133
134
Codec modules typically live in the <code>codecs/</code> directory in the
135
source tree.
136
137
For a list of codec interpreter implementations, see \ref codecs.
138
139
For additional information on the codec interpreter API, see the interface
140
definition in <code>include/asterisk/translate.h</code>.
141
142
For core implementation details related to the codec interpreter API, see
143
<code>main/translate.c</code>.
144
145
\subsection ArchInterfaceFormat File Format Handler
146
147
An implementation of the file format handler interface provides Asterisk the
148
ability to read and optionally write files. File format handlers may provide
149
access to audio, video, or image files.
150
151
The interface for a file format handler is rather primitive. A module simply
152
tells the Asterisk core that it can handle files with a given %extension,
153
for example, ".wav". It also says that after reading the file, it will
154
provide audio in the form of codec X. If a file format handler provides the
155
ability to write out files, it also must specify what codec the audio should
156
be in before provided to the file format handler.
157
158
File format modules typically live in the <code>formats/</code> directory in the
159
source tree.
160
161
For a list of file format handler implementations, see \ref formats.
162
163
For additional information on the file format handler API, see the interface
164
definition in <code>include/asterisk/file.h</code>.
165
166
For core implementation details related to the file format API, see
167
<code>main/file.c</code>.
168
169
\subsection ArchInterfaceAPIs C API Providers
170
171
There are some C APIs in Asterisk that are optional. Core APIs are built into
172
the main application and are always available. Optional C APIs are provided
173
by a module and are only available for use when the module is loaded. Some of
174
these API providers also contain their own interfaces that other modules can
175
implement and register.
176
177
Modules that provide a C API typically live in the <code>res/</code> directory
178
in the source tree.
179
180
Some examples of modules that provide C APIs (potentially among other things) are:
181
- res_musiconhold.c
182
- res_calendar.c
183
- provides a calendar technology interface.
184
- res_odbc.c
185
- res_ael_share.c
186
- res_crypto.c
187
- res_curl.c
188
- res_jabber.c
189
- res_monitor.c
190
- res_smdi.c
191
- res_speech.c
192
- provides a speech recognition engine interface.
193
194
\subsection ArchInterfaceAMI Manager Interface (AMI) Actions
195
196
The Asterisk manager interface is a socket interface for monitoring and control
197
of Asterisk. It is a core feature built in to the main application. However,
198
modules can register %actions that may be requested by clients.
199
200
Modules that register manager %actions typically do so as auxiliary functionality
201
to complement whatever main functionality it provides. For example, a module that
202
provides call conferencing services may have a manager action that will return the
203
list of participants in a conference.
204
205
\subsection ArchInterfaceCLI CLI Commands
206
207
The Asterisk CLI is a feature implemented in the main application. Modules may
208
register additional CLI commands.
209
210
\subsection ArchInterfaceChannelDrivers Channel Drivers
211
212
The Asterisk channel driver interface is the most complex and most important
213
interface available. The Asterisk channel API provides the telephony protocol
214
abstraction which allows all other Asterisk features to work independently of
215
the telephony protocol in use.
216
217
The specific interface that channel drivers implement is the ast_channel_tech
218
interface. A channel driver must implement functions that perform various
219
call signaling tasks. For example, they must implement a method for initiating
220
a call and hanging up a call. The ast_channel data structure is the abstract
221
channel data structure. Each ast_channel instance has an associated
222
ast_channel_tech which identifies the channel type. An ast_channel instance
223
represents one leg of a call (a connection between Asterisk and an endpoint).
224
225
Channel drivers typically live in the <code>channels/</code> directory in the
226
source tree.
227
228
For a list of channel driver implementations, see \ref channel_drivers.
229
230
For additional information on the channel API, see
231
<code>include/asterisk/channel.h</code>.
232
233
For additional implementation details regarding the core ast_channel API, see
234
<code>main/channel.c</code>.
235
236
\subsection ArchInterfaceBridge Bridging Technologies
237
238
Bridging is the operation which connects two or more channels together. A simple
239
two channel bridge is a normal A to B phone call, while a multi-party bridge would
240
be something like a 3-way call or a full conference call.
241
242
The bridging API allows modules to register bridging technologies. An implementation
243
of a bridging technology knows how to take two (or optionally more) channels and
244
connect them together. Exactly how this happens is up to the implementation.
245
246
This interface is used such that the code that needs to pass audio between channels
247
doesn't need to know how it is done. Underneath, the conferencing may be done in
248
the kernel (via DAHDI), via software methods inside of Asterisk, or could be done
249
in hardware in the future if someone implemented a module to do so.
250
251
At the time of this writing, the bridging API is still relatively new, so it is
252
not used everywhere that bridging operations are performed. The ConfBridge dialplan
253
application is a new conferencing application which has been implemented on top of
254
this bridging API.
255
256
Bridging technology modules typically live in the <code>bridges/</code> directory
257
in the source tree.
258
259
For a list of bridge technology implementations, see \ref bridges.
260
261
For additional information on the bridging API, see
262
<code>include/asterisk/bridging.h</code> and
263
<code>include/asterisk/bridging_technology.h</code>.
264
265
For additional implementation details regarding the core bridging API, see
266
<code>main/bridging.c</code>.
267
268
\subsection ArchInterfaceCDR Call Detail Record (CDR) Handlers
269
270
The Asterisk core implements functionality for keeping records of calls. These
271
records are built while calls are processed and live in data structures. At the
272
end of the call, these data structures are released. Before the records are thrown
273
away, they are passed in to all of the registered CDR handlers. These handlers may
274
write out the records to a file, post them to a database, etc.
275
276
CDR modules typically live in the <code>cdr</code> directory in the source tree.
277
278
For a list of CDR handlers, see \ref cdr_drivers.
279
280
For additional information on the CDR API, see
281
<code>include/asterisk/cdr.h</code>.
282
283
For additional implementation details regarding CDR handling, see
284
<code>main/cdr.c</code>.
285
286
\subsection ArchInterfaceCEL Call Event Logging (CEL) Handlers
287
288
The Asterisk core includes a generic event system that allows Asterisk components
289
to report events that can be subscribed to by other parts of the system. One of
290
the things built on this event system is Call Event Logging (CEL).
291
292
CEL is similar to CDR in that they are both for tracking call history. While CDR
293
records are typically have a one record to one call relationship, CEL events are
294
many events to one call. The CEL modules look very similar to CDR modules.
295
296
CEL modules typically live in the <code>cel/</code> directory in the source tree.
297
298
For a list of CEL handlers, see \ref cel_drivers.
299
300
For additional information about the CEL API, see
301
<code>include/asterisk/cel.h</code>.
302
303
For additional implementation details for the CEL API, see <code>main/cel.c</code>.
304
305
\subsection ArchInterfaceDialplanApps Dialplan Applications
306
307
Dialplan applications implement features that interact with calls that can be
308
executed from the Asterisk dialplan. For example, in <code>extensions.conf</code>:
309
310
<code>exten => 123,1,NoOp()</code>
311
312
In this case, NoOp is the application. Of course, NoOp doesn't actually do
313
anything.
314
315
These applications use a %number of APIs available in Asterisk to interact with
316
the channel. One of the most important tasks of an application is to continuously
317
read audio from the channel, and also write audio back to the channel. The details
318
of how this is done is usually hidden behind an API call used to play a file or wait
319
for digits to be pressed by a caller.
320
321
In addition to interacting with the channel that originally executed the application,
322
dialplan applications sometimes also create additional outbound channels.
323
For example, the Dial() application creates an outbound channel and bridges it to the
324
inbound channel. Further discussion about the functionality of applications will be
325
discussed in detailed use cases.
326
327
Dialplan applications are typically found in the <code>apps/</code> directory in
328
the source tree.
329
330
For a list of dialplan applications, see \ref applications.
331
332
For details on the API used to register an application with the Asterisk core, see
333
<code>include/asterisk/pbx.h</code>.
334
335
\subsection ArchInterfaceDialplanFuncs Dialplan Functions
336
337
As the name suggests, dialplan functions, like dialplan applications, are primarily
338
used from the Asterisk dialplan. Functions are used mostly in the same way that
339
variables are used in the dialplan. They provide a read and/or write interface, with
340
optional arguments. While they behave similarly to variables, they storage and
341
retrieval of a value is more complex than a simple variable with a text value.
342
343
For example, the <code>CHANNEL()</code> dialplan function allows you to access
344
data on the current channel.
345
346
<code>exten => 123,1,NoOp(This channel has the name: ${CHANNEL(name)})</code>
347
348
Dialplan functions are typically found in the <code>funcs/</code> directory in
349
the source tree.
350
351
For a list of dialplan function implementations, see \ref functions.
352
353
For details on the API used to register a dialplan function with the Asterisk core,
354
see <code>include/asterisk/pbx.h</code>.
355
356
\subsection ArchInterfaceRTP RTP Engines
357
358
The Asterisk core provides an API for handling RTP streams. However, the actual
359
handling of these streams is done by modules that implement the RTP engine interface.
360
Implementations of an RTP engine typically live in the <code>res/</code> directory
361
of the source tree, and have a <code>res_rtp_</code> prefix in their name.
362
363
\subsection ArchInterfaceTiming Timing Interfaces
364
365
The Asterisk core implements an API that can be used by components that need access
366
to timing services. For example, a timer is used to send parts of an audio file at
367
proper intervals when playing back a %sound file to a caller. The API relies on
368
timing interface implementations to provide a source for reliable timing.
369
370
Timing interface implementations are typically found in the <code>res/</code>
371
subdirectory of the source tree.
372
373
For a list of timing interface implementations, see \ref timing_interfaces.
374
375
For additional information on the timing API, see <code>include/asterisk/timing.h</code>.
376
377
For additional implementation details for the timing API, see <code>main/timing.c</code>.
378
379
380
\section ArchThreadingModel Asterisk Threading Model
381
382
Asterisk is a very heavily multi threaded application. It uses the POSIX threads API
383
to manage threads and related services such as locking. Almost all of the Asterisk code
384
that interacts with pthreads does so by going through a set of wrappers used for
385
debugging and code reduction.
386
387
Threads in Asterisk can be classified as one of the following types:
388
389
- Channel threads (sometimes referred to as PBX threads)
390
- Network Monitor threads
391
- Service connection threads
392
- Other threads
393
394
\subsection ArchChannelThreads Channel Threads
395
396
A channel is a fundamental concept in Asterisk. Channels are either inbound
397
or outbound. An inbound channel is created when a call comes in to the Asterisk
398
system. These channels are the ones that execute the Asterisk dialplan. A thread
399
is created for every channel that executes the dialplan. These threads are referred
400
to as a channel thread. They are sometimes also referred to as a PBX thread, since
401
one of the primary tasks of the thread is to execute the Asterisk dialplan for an
402
inbound call.
403
404
A channel thread starts out by only being responsible for a single Asterisk channel.
405
However, there are cases where a second channel may also live in a channel thread.
406
When an inbound channel executes an application such as <code>Dial()</code>, an
407
outbound channel is created and bridged to the inbound channel once it answers.
408
409
Dialplan applications always execute in the context of a channel thread. Dialplan
410
functions \i almost always do, as well. However, it is possible to read and write
411
dialplan functions from an asynchronous interface such as the Asterisk CLI or the
412
manager interface (AMI). However, it is still always the channel thread that is
413
the owner of the ast_channel data structure.
414
415
\subsection ArchMonitorThreads Network Monitor Threads
416
417
Network monitor threads exist in almost every major channel driver in Asterisk.
418
They are responsible for monitoring whatever network they are connected to (whether
419
that is an IP network, the PSTN, etc.) and monitor for incoming calls or other types
420
of incoming %requests. They handle the initial connection setup steps such as
421
authentication and dialed %number validation. Finally, once the call setup has been
422
completed, the monitor threads will create an instance of an Asterisk channel
423
(ast_channel), and start a channel thread to handle the call for the rest of its
424
lifetime.
425
426
\subsection ArchServiceThreads Service Connection Threads
427
428
There are a %number of TCP based services that use threads, as well. Some examples
429
include SIP and the AMI. In these cases, threads are used to handle each TCP
430
connection.
431
432
The Asterisk CLI also operates in a similar manner. However, instead of TCP, the
433
Asterisk CLI operates using connections to a UNIX %domain socket.
434
435
\subsection ArchOtherThreads Other Threads
436
437
There are other miscellaneous threads throughout the system that perform a specific task.
438
For example, the event API (include/asterisk/event.h) uses a thread internally
439
(main/event.c) to handle asychronous event dispatching. The devicestate API
440
(include/asterisk/devicestate.h) uses a thread internally (main/devicestate.c)
441
to asynchronously process device state changes.
442
443
444
\section ArchConcepts Other Architecture Concepts
445
446
This section covers some other important Asterisk architecture concepts.
447
448
\subsection ArchConceptBridging Channel Bridging
449
450
As previously mentioned when discussing the bridging technology interface
451
(\ref ArchInterfaceBridge), bridging is the act of connecting one or more channel
452
together so that they may pass audio between each other. However, it was also
453
mentioned that most of the code in Asterisk that does bridging today does not use
454
this new bridging infrastructure. So, this section discusses the legacy bridging
455
functionality that is used by the <code>Dial()</code> and <code>Queue()</code>
456
applications.
457
458
When one of these applications decides it would like to bridge two channels together,
459
it does so by executing the ast_channel_bridge() API call. From there, there are
460
two types of bridges that may occur.
461
462
-# <b>Generic Bridge:</b> A generic bridge (ast_generic_bridge()) is a bridging
463
method that works regardless of what channel technologies are in use. It passes
464
all audio and signaling through the Asterisk abstract channel and frame interfaces
465
so that they can be communicated between channel drivers of any type. While this
466
is the most flexible, it is also the least efficient bridging method due to the
467
levels of abstraction necessary.
468
-# <b>Native Bridge:</b> Channel drivers have the option of implementing their own
469
bridging functionality. Specifically, this means to implement the bridge callback
470
in the ast_channel_tech structure. If two channels of the same type are bridged,
471
a native bridge method is available, and Asterisk does not have a reason to force
472
the call to stay in the core of Asterisk, then the native bridge function will be
473
invoked. This allows channel drivers to take advantage of the fact that the
474
channels are the same type to optimize bridge processing. In the case of a DAHDI
475
channel, this may mean that the channels are bridged natively on hardware. In the
476
case of SIP, this means that Asterisk can direct the audio to flow between the
477
endpoints and only require the signaling to continue to flow through Asterisk.
478
479
480
\section ArchCodeFlows Code Flow Examples
481
482
Now that there has been discussion about the various components that make up Asterisk,
483
this section goes through examples to demonstrate how these components work together
484
to provide useful functionality.
485
486
\subsection ArchCodeFlowPlayback SIP Call to File Playback
487
488
This example consists of a call that comes in to Asterisk via the SIP protocol.
489
Asterisk accepts this call, plays back a %sound file to the caller, and then hangs up.
490
491
Example dialplan:
492
493
<code>exten => 5551212,1,Answer()</code><br/>
494
<code>exten => 5551212,n,Playback(demo-congrats)</code><br/>
495
<code>exten => 5551212,n,Hangup()</code><br/>
496
497
-# <b>Call Setup:</b> An incoming SIP INVITE begins this scenario. It is received by
498
the SIP channel driver (chan_sip.c). Specifically, the monitor thread in chan_sip
499
is responsible for handling this incoming request. Further, the monitor thread
500
is responsible for completing any handshake necessary to complete the call setup
501
process.
502
-# <b>Accept Call:</b> Once the SIP channel driver has completed the call setup process,
503
it accepts the call and initiates the call handling process in Asterisk. To do so,
504
it must allocate an instance of an abstract channel (ast_channel) using the
505
ast_channel_alloc() API call. This instance of an ast_channel will be referred to
506
as a SIP channel. The SIP channel driver will take care of SIP specific channel
507
initialization. Once the channel has been created and initialized, a channel thread
508
is created to handle the call (ast_pbx_start()).
509
-# <b>Run the Dialplan:</b>: The main loop that runs in the channel thread is the code
510
responsible for looking for the proper extension and then executing it. This loop
511
lives in ast_pbx_run() in main/pbx.c.
512
-# <b>Answer the Call:</b>: Once the dialplan is being executed, the first application
513
that is executed is <code>Answer()</code>. This application is a built in
514
application that is defined in main/pbx.c. The <code>Answer()</code> application
515
code simply executes the ast_answer() API call. This API call operates on an
516
ast_channel. It handles generic ast_channel hangup processing, as well as executes
517
the answer callback function defined in the associated ast_channel_tech for the
518
active channel. In this case, the sip_answer() function in chan_sip.c will get
519
executed to handle the SIP specific operations required to answer a call.
520
-# <b>Play the File:</b> The next step of the dialplan says to play back a %sound file
521
to the caller. The <code>Playback()</code> application will be executed.
522
The code for this application is in apps/app_playback.c. The code in the application
523
is pretty simple. It does argument handling and uses API calls to play back the
524
file, ast_streamfile(), ast_waitstream(), and ast_stopstream(), which set up file
525
playback, wait for the file to finish playing, and then free up resources. Some
526
of the important operations of these API calls are described in steps here:
527
-# <b>Open a File:</b> The file format API is responsible for opening the %sound file.
528
It will start by looking for a file that is encoded in the same format that the
529
channel is expecting to receive audio in. If that is not possible, it will find
530
another type of file that can be translated into the codec that the channel is
531
expecting. Once a file is found, the appropriate file format interface is invoked
532
to handle reading the file and turning it into internal Asterisk audio frames.
533
-# <b>Set up Translation:</b> If the encoding of the audio data in the file does not
534
match what the channel is expecting, the file API will use the codec translation
535
API to set up a translation path. The translate API will invoke the appropriate
536
codec translation interface(s) to get from the source to the destination format
537
in the most efficient way available.
538
-# <b>Feed Audio to the Caller:</b> The file API will invoke the timer API to know
539
how to send out audio frames from the file in proper intervals. At the same time,
540
Asterisk must also continuously service the incoming audio from the channel since
541
it will continue to arrive in real time. However, in this scenario, it will just
542
get thrown away.
543
-# <b>Hang up the Call:</b> Once the <code>Playback()</code> application has finished,
544
the dialplan execution loop continues to the next step in the dialplan, which is
545
<code>Hangup()</code>. This operates in a very similar manner to <code>Answer()</code>
546
in that it handles channel type agnostic hangup handling, and then calls down into
547
the SIP channel interface to handle SIP specific hangup processing. At this point,
548
even if there were more steps in the dialplan, processing would stop since the channel
549
has been hung up. The channel thread will exit the dialplan processing loop and
550
destroy the ast_channel data structure.
551
552
\subsection ArchCodeFlowBridge SIP to IAX2 Bridged Call
553
554
This example consists of a call that comes in to Asterisk via the SIP protocol. Asterisk
555
then makes an outbound call via the IAX2 protocol. When the far end over IAX2 answers,
556
the call is bridged.
557
558
Example dialplan:
559
560
<code>exten => 5551212,n,Dial(IAX2/mypeer)</code><br/>
561
562
-# <b>Call Setup:</b> An incoming SIP INVITE begins this scenario. It is received by
563
the SIP channel driver (chan_sip.c). Specifically, the monitor thread in chan_sip
564
is responsible for handling this incoming request. Further, the monitor thread
565
is responsible for completing any handshake necessary to complete the call setup
566
process.
567
-# <b>Accept Call:</b> Once the SIP channel driver has completed the call setup process,
568
it accepts the call and initiates the call handling process in Asterisk. To do so,
569
it must allocate an instance of an abstract channel (ast_channel) using the
570
ast_channel_alloc() API call. This instance of an ast_channel will be referred to
571
as a SIP channel. The SIP channel driver will take care of SIP specific channel
572
initialization. Once the channel has been created and initialized, a channel thread
573
is created to handle the call (ast_pbx_start()).
574
-# <b>Run the Dialplan:</b>: The main loop that runs in the channel thread is the code
575
responsible for looking for the proper extension and then executing it. This loop
576
lives in ast_pbx_run() in main/pbx.c.
577
-# <b>Execute Dial()</b>: The only step in this dialplan is to execute the
578
<code>Dial()</code> application.
579
-# <b>Create an Outbound Channel:</b> The <code>Dial()</code> application needs to
580
create an outbound ast_channel. It does this by first using the ast_request()
581
API call to request a channel called <code>IAX2/mypeer</code>. This API call
582
is a part of the core channel API (include/asterisk/channel.h). It will find
583
a channel driver of type <code>IAX2</code> and then execute the request callback
584
in the appropriate ast_channel_tech interface. In this case, it is iax2_request()
585
in channels/chan_iax2.c. This asks the IAX2 channel driver to allocate an
586
ast_channel of type IAX2 and initialize it. The <code>Dial()</code> application
587
will then execute the ast_call() API call for this new ast_channel. This will
588
call into the call callback of the ast_channel_tech, iax2_call(), which requests
589
that the IAX2 channel driver initiate the outbound call.
590
-# <b>Wait for Answer:</b> At this point, the Dial() application waits for the
591
outbound channel to answer the call. While it does this, it must continue to
592
service the incoming audio on both the inbound and outbound channels. The loop
593
that does this is very similar to every other channel servicing loop in Asterisk.
594
The core features of a channel servicing loop include ast_waitfor() to wait for
595
frames on a channel, and then ast_read() on a channel once frames are available.
596
-# <b>Handle Answer:</b> Once the far end answers the call, the <code>Dial()</code>
597
application will communicate this back to the inbound SIP channel. It does this
598
by calling the ast_answer() core channel API call.
599
-# <b>Make Channels Compatible:</b> Before the two ends of the call can be connected,
600
Asterisk must make them compatible to talk to each other. Specifically, the two
601
channels may be sending and expecting to receive audio in a different format than
602
the other channel. The API call ast_channel_make_compatible() sets up translation
603
paths for each channel by instantiating codec translators as necessary.
604
-# <b>Bridge the Channels:</b> Now that both the inbound and outbound channels are
605
fully established, they can be connected together. This connection between the
606
two channels so that they can pass audio and signaling back and forth is referred
607
to as a bridge. The API call that handles the bridge is ast_channel_bridge().
608
In this case, the main loop of the bridge is a generic bridge, ast_generic_bridge(),
609
which is the type of bridge that works regardless of the two channel types. A
610
generic bridge will almost always be used if the two channels are not of the same
611
type. The core functionality of a bridge loop is ast_waitfor() on both channels.
612
Then, when frames arrive on a channel, they are read using ast_read(). After reading
613
a frame, they are written to the other channel using ast_write().
614
-# <b>Breaking the Bridge</b>: This bridge will continue until some event occurs that
615
causes the bridge to be broken, and control to be returned back down to the
616
<code>Dial()</code> application. For example, if one side of the call hangs up,
617
the bridge will stop.
618
-# <b>Hanging Up:</b>: After the bridge stops, control will return to the
619
<code>Dial()</code> application. The application owns the outbound channel since
620
that is where it was created. So, the outbound IAX2 channel will be destroyed
621
before <code>Dial()</code> is complete. Destroying the channel is done by using
622
the ast_hangup() API call. The application will return back to the dialplan
623
processing loop. From there, the loop will see that there is nothing else to
624
execute, so it will hangup on the inbound channel as well using the ast_hangup()
625
function. ast_hangup() performs a number of channel type independent hangup
626
tasks, but also executes the hangup callback of ast_channel_tech (sip_hangup()).
627
Finally, the channel thread exits.
628
629
630
\section ArchDataStructures Asterisk Data Structures
631
632
Asterisk provides generic implementations of a number of data structures.
633
634
\subsection ArchAstobj2 Astobj2
635
636
Astobj2 stands for the Asterisk Object model, version 2. The API is defined in
637
include/asterisk/astobj2.h. Some internal implementation details for astobj2 can
638
be found in main/astobj2.c. There is a version 1, and it still exists in the
639
source tree. However, it is considered deprecated.
640
641
Astobj2 provides reference counted object handling. It also provides a container
642
interface for astobj2 objects. The container provided is a hash table.
643
644
See the astobj2 API for more details about how to use it. Examples can be found
645
all over the code base.
646
647
\subsection ArchLinkedLists Linked Lists
648
649
Asterisk provides a set of macros for handling linked lists. They are defined in
650
include/asterisk/linkedlists.h.
651
652
\subsection ArchDLinkedLists Doubly Linked Lists
653
654
Asterisk provides a set of macros for handling doubly linked lists, as well. They
655
are defined in include/asterisk/dlinkedlists.h.
656
657
\subsection ArchHeap Heap
658
659
Asterisk provides an implementation of the max heap data structure. The API is defined
660
in include/asterisk/heap.h. The internal implementation details can be found in
661
main/heap.c.
662
663
664
\section ArchDebugging Asterisk Debugging Tools
665
666
Asterisk includes a %number of built in debugging tools to help in diagnosing common
667
types of problems.
668
669
\subsection ArchThreadDebugging Thread Debugging
670
671
Asterisk keeps track of a list of all active threads on the system. A list of threads
672
can be viewed from the Asterisk CLI by running the command
673
<code>core show threads</code>.
674
675
Asterisk has a compile time option called <code>DEBUG_THREADS</code>. When this is on,
676
the pthread wrapper API in Asterisk keeps track of additional information related to
677
threads and locks to aid in debugging. In addition to just keeping a list of threads,
678
Asterisk also maintains information about every lock that is currently held by any
679
thread on the system. It also knows when a thread is blocking while attempting to
680
acquire a lock. All of this information is extremely useful when debugging a deadlock.
681
This data can be acquired from the Asterisk CLI by running the
682
<code>core show locks</code> CLI command.
683
684
The definitions of these wrappers can be found in <code>include/asterisk/lock.h</code>
685
and <code>include/asterisk/utils.h</code>. Most of the implementation details can be
686
found in <code>main/utils.c</code>.
687
688
\subsection ArchMemoryDebugging Memory debugging
689
690
Dynamic memory management in Asterisk is handled through a %number of wrappers defined
691
in <code>include/asterisk/utils.h</code>. By default, all of these wrappers use the
692
standard C library malloc(), free(), etc. functions. However, if Asterisk is compiled
693
with the MALLOC_DEBUG option enabled, additional memory debugging is included.
694
695
The Asterisk memory debugging system provides the following features:
696
697
- Track all current allocations including their size and the file, function, and line
698
%number where they were initiated.
699
- When releasing memory, do some basic fence checking to see if anything wrote into the
700
few bytes immediately surrounding an allocation.
701
- Get notified when attempting to free invalid memory.
702
703
A %number of CLI commands are provided to access data on the current set of memory
704
allocations. Those are:
705
706
- <code>memory show summary</code>
707
- <code>memory show allocations</code>
708
709
The implementation of this memory debugging system can be found in
710
<code>main/astmm.c</code>.
711
712
713
<hr/>
714
Return to the \ref ArchTOC
715
*/
716
include
asterisk
doxygen
architecture.h
Generated by
1.8.5