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