architecture.h

Go to the documentation of this file.
00001 /*
00002  * Asterisk -- An open source telephony toolkit.
00003  *
00004  * Copyright (C) 2009, Digium, Inc.
00005  *
00006  * Russell Bryant <russell@digium.com>
00007  *
00008  * See http://www.asterisk.org for more information about
00009  * the Asterisk project. Please do not directly contact
00010  * any of the maintainers of this project for assistance;
00011  * the project provides a web site, mailing lists and IRC
00012  * channels for your use.
00013  *
00014  * This program is free software, distributed under the terms of
00015  * the GNU General Public License Version 2. See the LICENSE file
00016  * at the top of the source tree.
00017  */
00018 
00019 /*!
00020  * \file
00021  * \author Russell Bryant <russell@digium.com>
00022  */
00023 
00024 /*!
00025 \page AsteriskArchitecture Asterisk Architecture Overview
00026 \author Russell Bryant <russell@digium.com>
00027 
00028 <hr>
00029 
00030 \section ArchTOC Table of Contents
00031 
00032  -# \ref ArchIntro
00033  -# \ref ArchLayout
00034  -# \ref ArchInterfaces
00035     -# \ref ArchInterfaceCodec
00036     -# \ref ArchInterfaceFormat
00037     -# \ref ArchInterfaceAPIs
00038     -# \ref ArchInterfaceAMI
00039     -# \ref ArchInterfaceChannelDrivers
00040     -# \ref ArchInterfaceBridge
00041     -# \ref ArchInterfaceCDR
00042     -# \ref ArchInterfaceCEL
00043     -# \ref ArchInterfaceDialplanApps
00044     -# \ref ArchInterfaceDialplanFuncs
00045     -# \ref ArchInterfaceRTP
00046     -# \ref ArchInterfaceTiming
00047  -# \ref ArchThreadingModel
00048     -# \ref ArchChannelThreads
00049     -# \ref ArchMonitorThreads
00050     -# \ref ArchServiceThreads
00051     -# \ref ArchOtherThreads
00052  -# \ref ArchConcepts
00053     -# \ref ArchConceptBridging
00054  -# \ref ArchCodeFlows
00055     -# \ref ArchCodeFlowPlayback
00056     -# \ref ArchCodeFlowBridge
00057  -# \ref ArchDataStructures
00058     -# \ref ArchAstobj2
00059     -# \ref ArchLinkedLists
00060     -# \ref ArchDLinkedLists
00061     -# \ref ArchHeap
00062  -# \ref ArchDebugging
00063     -# \ref ArchThreadDebugging
00064     -# \ref ArchMemoryDebugging
00065 
00066 <hr>
00067 
00068 \section ArchIntro Introduction
00069 
00070 This section of the documentation includes an overview of the Asterisk architecture
00071 from a developer's point of view.  For detailed API discussion, see the documentation
00072 associated with public API header files.  This documentation assumes some knowledge
00073 of what Asterisk is and how to use it.
00074 
00075 The intent behind this documentation is to start looking at Asterisk from a high
00076 level and progressively dig deeper into the details.  It begins with talking about
00077 the different types of components that make up Asterisk and eventually will go
00078 through interactions between these components in different use cases.
00079 
00080 Throughout this documentation, many links are also provided as references to more
00081 detailed information on related APIs, as well as the related source code to what
00082 is being discussed.
00083 
00084 Feedback and contributions to this documentation are very welcome.  Please send your
00085 comments to the asterisk-dev mailing list on http://lists.digium.com/.
00086 
00087 Thank you, and enjoy Asterisk!
00088 
00089 
00090 \section ArchLayout Modular Architecture
00091 
00092 Asterisk is a highly modularized application.  There is a core application that
00093 is built from the source in the <code>main/</code> directory.  However, it is
00094 not very useful by itself.
00095 
00096 There are many modules that are loaded at runtime.  Asterisk modules have names that
00097 give an indication as to what functionality they provide, but the name is not special
00098 in any technical sense.  When Asterisk loads a module, the module registers the
00099 functionality that it provides with the Asterisk core.
00100 
00101  -# Asterisk starts
00102  -# Asterisk loads modules
00103  -# Modules say "Hey Asterisk!  I am a module.  I can provide functionality X, Y,
00104     and Z.  Let me know when you'd like to use my functionality!"
00105 
00106 
00107 \section ArchInterfaces Abstract Interface types
00108 
00109 There are many types of interfaces that modules can implement and register their
00110 implementations of with the Asterisk core.  Any module is allowed to register as
00111 many of these different interfaces as they would like.  Generally, related
00112 functionality is grouped into a single module.
00113 
00114 In this section, the types of interfaces are discussed.  Later, there will
00115 be discussions about how different components interact in various scenarios.
00116 
00117 \subsection ArchInterfaceCodec Codec Interpreter
00118 
00119 An implementation of the codec interpreter interface provides the ability to
00120 convert between two codecs.  Asterisk currently only has the ability to translate
00121 between audio codecs.
00122 
00123 These modules have no knowledge about phone calls or anything else about why
00124 they are being asked to convert audio.  They just get audio samples as input
00125 in their specified input format, and are expected to provide audio in the
00126 specified output format.
00127 
00128 It is possible to have multiple paths to get from codec A to codec B once many
00129 codec implementations are registered.  After modules have been loaded, Asterisk
00130 builds a translation table with measurements of the performance of each codec
00131 translator so that it can always find the best path to get from A to B.
00132 
00133 Codec modules typically live in the <code>codecs/</code> directory in the
00134 source tree.
00135 
00136 For a list of codec interpreter implementations, see \ref codecs.
00137 
00138 For additional information on the codec interpreter API, see the interface
00139 definition in <code>include/asterisk/translate.h</code>.
00140 
00141 For core implementation details related to the codec interpreter API, see
00142 <code>main/translate.c</code>.
00143 
00144 \subsection ArchInterfaceFormat File Format Handler
00145 
00146 An implementation of the file format handler interface provides Asterisk the
00147 ability to read and optionally write files.  File format handlers may provide
00148 access to audio, video, or image files.
00149 
00150 The interface for a file format handler is rather primitive.  A module simply
00151 tells the Asterisk core that it can handle files with a given %extension,
00152 for example, ".wav".  It also says that after reading the file, it will
00153 provide audio in the form of codec X.  If a file format handler provides the
00154 ability to write out files, it also must specify what codec the audio should
00155 be in before provided to the file format handler.
00156 
00157 File format modules typically live in the <code>formats/</code> directory in the
00158 source tree.
00159 
00160 For a list of file format handler implementations, see \ref formats.
00161 
00162 For additional information on the file format handler API, see the interface
00163 definition in <code>include/asterisk/file.h</code>.
00164 
00165 For core implementation details related to the file format API, see
00166 <code>main/file.c</code>.
00167 
00168 \subsection ArchInterfaceAPIs C API Providers
00169 
00170 There are some C APIs in Asterisk that are optional.  Core APIs are built into
00171 the main application and are always available.  Optional C APIs are provided
00172 by a module and are only available for use when the module is loaded.  Some of
00173 these API providers also contain their own interfaces that other modules can
00174 implement and register.
00175 
00176 Modules that provide a C API typically live in the <code>res/</code> directory
00177 in the source tree.
00178 
00179 Some examples of modules that provide C APIs (potentially among other things) are:
00180  - res_musiconhold.c
00181  - res_calendar.c
00182    - provides a calendar technology interface.
00183  - res_odbc.c
00184  - res_ael_share.c
00185  - res_crypto.c
00186  - res_curl.c
00187  - res_xmpp.c
00188  - res_monitor.c
00189  - res_smdi.c
00190  - res_speech.c
00191    - provides a speech recognition engine interface.
00192 
00193 \subsection ArchInterfaceAMI Manager Interface (AMI) Actions
00194 
00195 The Asterisk manager interface is a socket interface for monitoring and control
00196 of Asterisk.  It is a core feature built in to the main application.  However,
00197 modules can register %actions that may be requested by clients.
00198 
00199 Modules that register manager %actions typically do so as auxiliary functionality
00200 to complement whatever main functionality it provides.  For example, a module that
00201 provides call conferencing services may have a manager action that will return the
00202 list of participants in a conference.
00203 
00204 \subsection ArchInterfaceCLI CLI Commands
00205 
00206 The Asterisk CLI is a feature implemented in the main application.  Modules may
00207 register additional CLI commands.
00208 
00209 \subsection ArchInterfaceChannelDrivers Channel Drivers
00210 
00211 The Asterisk channel driver interface is the most complex and most important
00212 interface available.  The Asterisk channel API provides the telephony protocol
00213 abstraction which allows all other Asterisk features to work independently of
00214 the telephony protocol in use.
00215 
00216 The specific interface that channel drivers implement is the ast_channel_tech
00217 interface.  A channel driver must implement functions that perform various
00218 call signaling tasks.  For example, they must implement a method for initiating
00219 a call and hanging up a call.  The ast_channel data structure is the abstract
00220 channel data structure.  Each ast_channel instance has an associated
00221 ast_channel_tech which identifies the channel type.  An ast_channel instance
00222 represents one leg of a call (a connection between Asterisk and an endpoint).
00223 
00224 Channel drivers typically live in the <code>channels/</code> directory in the
00225 source tree.
00226 
00227 For a list of channel driver implementations, see \ref channel_drivers.
00228 
00229 For additional information on the channel API, see
00230 <code>include/asterisk/channel.h</code>.
00231 
00232 For additional implementation details regarding the core ast_channel API, see
00233 <code>main/channel.c</code>.
00234 
00235 \subsection ArchInterfaceBridge Bridging Technologies
00236 
00237 Bridging is the operation which connects two or more channels together.  A simple
00238 two channel bridge is a normal A to B phone call, while a multi-party bridge would
00239 be something like a 3-way call or a full conference call.
00240 
00241 The bridging API allows modules to register bridging technologies.  An implementation
00242 of a bridging technology knows how to take two (or optionally more) channels and
00243 connect them together.  Exactly how this happens is up to the implementation.
00244 
00245 This interface is used such that the code that needs to pass audio between channels
00246 doesn't need to know how it is done.  Underneath, the conferencing may be done in
00247 the kernel (via DAHDI), via software methods inside of Asterisk, or could be done
00248 in hardware in the future if someone implemented a module to do so.
00249 
00250 At the time of this writing, the bridging API is still relatively new, so it is
00251 not used everywhere that bridging operations are performed.  The ConfBridge dialplan
00252 application is a new conferencing application which has been implemented on top of
00253 this bridging API.
00254 
00255 Bridging technology modules typically live in the <code>bridges/</code> directory
00256 in the source tree.
00257 
00258 For a list of bridge technology implementations, see \ref bridges.
00259 
00260 For additional information on the bridging API, see
00261 \arg <code>include/asterisk/bridge.h</code>
00262 \arg <code>include/asterisk/bridge_technology.h</code>
00263 \arg <code>include/asterisk/bridge_channel.h</code>
00264 \arg <code>include/asterisk/bridge_features.h</code>
00265 \arg <code>include/asterisk/bridge_after.h</code>
00266 
00267 For additional implementation details regarding the core bridging API, see
00268 <code>main/bridge.c</code> and <code>main/bridge_channel.c</code>.
00269 
00270 \subsection ArchInterfaceCDR Call Detail Record (CDR) Handlers
00271 
00272 The Asterisk core implements functionality for keeping records of calls.  These
00273 records are built while calls are processed and live in data structures.  At the
00274 end of the call, these data structures are released.  Before the records are thrown
00275 away, they are passed in to all of the registered CDR handlers.  These handlers may
00276 write out the records to a file, post them to a database, etc.
00277 
00278 CDR modules typically live in the <code>cdr</code> directory in the source tree.
00279 
00280 For a list of CDR handlers, see \ref cdr_drivers.
00281 
00282 For additional information on the CDR API, see
00283 <code>include/asterisk/cdr.h</code>.
00284 
00285 For additional implementation details regarding CDR handling, see
00286 <code>main/cdr.c</code>.
00287 
00288 \subsection ArchInterfaceCEL Call Event Logging (CEL) Handlers
00289 
00290 The Asterisk core includes a generic event system that allows Asterisk components
00291 to report events that can be subscribed to by other parts of the system.  One of
00292 the things built on this event system is Call Event Logging (CEL).
00293 
00294 CEL is similar to CDR in that they are both for tracking call history.  While CDR
00295 records are typically have a one record to one call relationship, CEL events are
00296 many events to one call.  The CEL modules look very similar to CDR modules.
00297 
00298 CEL modules typically live in the <code>cel/</code> directory in the source tree.
00299 
00300 For a list of CEL handlers, see cel_drivers.
00301 
00302 For additional information about the CEL API, see
00303 <code>include/asterisk/cel.h</code>.
00304 
00305 For additional implementation details for the CEL API, see <code>main/cel.c</code>.
00306 
00307 \subsection ArchInterfaceDialplanApps Dialplan Applications
00308 
00309 Dialplan applications implement features that interact with calls that can be
00310 executed from the Asterisk dialplan.  For example, in <code>extensions.conf</code>:
00311 
00312 <code>exten => 123,1,NoOp()</code>
00313 
00314 In this case, NoOp is the application.  Of course, NoOp doesn't actually do
00315 anything.
00316 
00317 These applications use a %number of APIs available in Asterisk to interact with
00318 the channel.  One of the most important tasks of an application is to continuously
00319 read audio from the channel, and also write audio back to the channel.  The details
00320 of how this is done is usually hidden behind an API call used to play a file or wait
00321 for digits to be pressed by a caller.
00322 
00323 In addition to interacting with the channel that originally executed the application,
00324 dialplan applications sometimes also create additional outbound channels.
00325 For example, the Dial() application creates an outbound channel and bridges it to the
00326 inbound channel.  Further discussion about the functionality of applications will be
00327 discussed in detailed use cases.
00328 
00329 Dialplan applications are typically found in the <code>apps/</code> directory in
00330 the source tree.
00331 
00332 For a list of dialplan applications, see \ref applications.
00333 
00334 For details on the API used to register an application with the Asterisk core, see
00335 <code>include/asterisk/pbx.h</code>.
00336 
00337 \subsection ArchInterfaceDialplanFuncs Dialplan Functions
00338 
00339 As the name suggests, dialplan functions, like dialplan applications, are primarily
00340 used from the Asterisk dialplan.  Functions are used mostly in the same way that
00341 variables are used in the dialplan.  They provide a read and/or write interface, with
00342 optional arguments.  While they behave similarly to variables, they storage and
00343 retrieval of a value is more complex than a simple variable with a text value.
00344 
00345 For example, the <code>CHANNEL()</code> dialplan function allows you to access
00346 data on the current channel.
00347 
00348 <code>exten => 123,1,NoOp(This channel has the name: ${CHANNEL(name)})</code>
00349 
00350 Dialplan functions are typically found in the <code>funcs/</code> directory in
00351 the source tree.
00352 
00353 For a list of dialplan function implementations, see \ref functions.
00354 
00355 For details on the API used to register a dialplan function with the Asterisk core,
00356 see <code>include/asterisk/pbx.h</code>.
00357 
00358 \subsection ArchInterfaceRTP RTP Engines
00359 
00360 The Asterisk core provides an API for handling RTP streams.  However, the actual
00361 handling of these streams is done by modules that implement the RTP engine interface.
00362 Implementations of an RTP engine typically live in the <code>res/</code> directory
00363 of the source tree, and have a <code>res_rtp_</code> prefix in their name.
00364 
00365 \subsection ArchInterfaceTiming Timing Interfaces
00366 
00367 The Asterisk core implements an API that can be used by components that need access
00368 to timing services.  For example, a timer is used to send parts of an audio file at
00369 proper intervals when playing back a %sound file to a caller.  The API relies on
00370 timing interface implementations to provide a source for reliable timing.
00371 
00372 Timing interface implementations are typically found in the <code>res/</code>
00373 subdirectory of the source tree.
00374 
00375 For a list of timing interface implementations, see \ref timing_interfaces.
00376 
00377 For additional information on the timing API, see <code>include/asterisk/timing.h</code>.
00378 
00379 For additional implementation details for the timing API, see <code>main/timing.c</code>.
00380 
00381 
00382 \section ArchThreadingModel Asterisk Threading Model
00383 
00384 Asterisk is a very heavily multi threaded application.  It uses the POSIX threads API
00385 to manage threads and related services such as locking.  Almost all of the Asterisk code
00386 that interacts with pthreads does so by going through a set of wrappers used for
00387 debugging and code reduction.
00388 
00389 Threads in Asterisk can be classified as one of the following types:
00390 
00391  - Channel threads (sometimes referred to as PBX threads)
00392  - Network Monitor threads
00393  - Service connection threads
00394  - Other threads
00395 
00396 \subsection ArchChannelThreads Channel Threads
00397 
00398 A channel is a fundamental concept in Asterisk.  Channels are either inbound
00399 or outbound.  An inbound channel is created when a call comes in to the Asterisk
00400 system.  These channels are the ones that execute the Asterisk dialplan.  A thread
00401 is created for every channel that executes the dialplan.  These threads are referred
00402 to as a channel thread.  They are sometimes also referred to as a PBX thread, since
00403 one of the primary tasks of the thread is to execute the Asterisk dialplan for an
00404 inbound call.
00405 
00406 A channel thread starts out by only being responsible for a single Asterisk channel.
00407 However, there are cases where a second channel may also live in a channel thread.
00408 When an inbound channel executes an application such as <code>Dial()</code>, an
00409 outbound channel is created and bridged to the inbound channel once it answers.
00410 
00411 Dialplan applications always execute in the context of a channel thread.  Dialplan
00412 functions almost always do, as well.  However, it is possible to read and write
00413 dialplan functions from an asynchronous interface such as the Asterisk CLI or the
00414 manager interface (AMI).  However, it is still always the channel thread that is
00415 the owner of the ast_channel data structure.
00416 
00417 \subsection ArchMonitorThreads Network Monitor Threads
00418 
00419 Network monitor threads exist in almost every major channel driver in Asterisk.
00420 They are responsible for monitoring whatever network they are connected to (whether
00421 that is an IP network, the PSTN, etc.) and monitor for incoming calls or other types
00422 of incoming %requests.  They handle the initial connection setup steps such as
00423 authentication and dialed %number validation.  Finally, once the call setup has been
00424 completed, the monitor threads will create an instance of an Asterisk channel
00425 (ast_channel), and start a channel thread to handle the call for the rest of its
00426 lifetime.
00427 
00428 \subsection ArchServiceThreads Service Connection Threads
00429 
00430 There are a %number of TCP based services that use threads, as well.  Some examples
00431 include SIP and the AMI.  In these cases, threads are used to handle each TCP
00432 connection.
00433 
00434 The Asterisk CLI also operates in a similar manner.  However, instead of TCP, the
00435 Asterisk CLI operates using connections to a UNIX %domain socket.
00436 
00437 \subsection ArchOtherThreads Other Threads
00438 
00439 There are other miscellaneous threads throughout the system that perform a specific task.
00440 For example, the event API (include/asterisk/event.h) uses a thread internally
00441 (main/event.c) to handle asychronous event dispatching.  The devicestate API
00442 (include/asterisk/devicestate.h) uses a thread internally (main/devicestate.c)
00443 to asynchronously process device state changes.
00444 
00445 
00446 \section ArchConcepts Other Architecture Concepts
00447 
00448 This section covers some other important Asterisk architecture concepts.
00449 
00450 \subsection ArchConceptBridging Channel Bridging
00451 
00452 As previously mentioned when discussing the bridging technology interface
00453 (\ref ArchInterfaceBridge), bridging is the act of connecting one or more channel
00454 together so that they may pass audio between each other.  However, it was also
00455 mentioned that most of the code in Asterisk that does bridging today does not use
00456 this new bridging infrastructure.  So, this section discusses the legacy bridging
00457 functionality that is used by the <code>Dial()</code> and <code>Queue()</code>
00458 applications.
00459 
00460 When one of these applications decides it would like to bridge two channels together,
00461 it does so by executing the ast_channel_bridge() API call.  From there, there are
00462 two types of bridges that may occur.
00463 
00464  -# <b>Generic Bridge:</b> A generic bridge (ast_generic_bridge()) is a bridging
00465     method that works regardless of what channel technologies are in use.  It passes
00466     all audio and signaling through the Asterisk abstract channel and frame interfaces
00467     so that they can be communicated between channel drivers of any type.  While this
00468     is the most flexible, it is also the least efficient bridging method due to the
00469     levels of abstraction necessary.
00470  -# <b>Native Bridge:</b> Channel drivers have the option of implementing their own
00471     bridging functionality.  Specifically, this means to implement the bridge callback
00472     in the ast_channel_tech structure.  If two channels of the same type are bridged,
00473     a native bridge method is available, and Asterisk does not have a reason to force
00474     the call to stay in the core of Asterisk, then the native bridge function will be
00475     invoked.  This allows channel drivers to take advantage of the fact that the
00476     channels are the same type to optimize bridge processing.  In the case of a DAHDI
00477     channel, this may mean that the channels are bridged natively on hardware.  In the
00478     case of SIP, this means that Asterisk can direct the audio to flow between the
00479     endpoints and only require the signaling to continue to flow through Asterisk.
00480 
00481 
00482 \section ArchCodeFlows Code Flow Examples
00483 
00484 Now that there has been discussion about the various components that make up Asterisk,
00485 this section goes through examples to demonstrate how these components work together
00486 to provide useful functionality.
00487 
00488 \subsection ArchCodeFlowPlayback SIP Call to File Playback
00489 
00490 This example consists of a call that comes in to Asterisk via the SIP protocol.
00491 Asterisk accepts this call, plays back a %sound file to the caller, and then hangs up.
00492 
00493 Example dialplan:
00494 
00495 <code>exten => 5551212,1,Answer()</code><br/>
00496 <code>exten => 5551212,n,Playback(demo-congrats)</code><br/>
00497 <code>exten => 5551212,n,Hangup()</code><br/>
00498 
00499  -# <b>Call Setup:</b> An incoming SIP INVITE begins this scenario.  It is received by
00500     the SIP channel driver (chan_sip.c).  Specifically, the monitor thread in chan_sip
00501     is responsible for handling this incoming request.  Further, the monitor thread
00502     is responsible for completing any handshake necessary to complete the call setup
00503     process.
00504  -# <b>Accept Call:</b> Once the SIP channel driver has completed the call setup process,
00505     it accepts the call and initiates the call handling process in Asterisk.  To do so,
00506     it must allocate an instance of an abstract channel (ast_channel) using the
00507     ast_channel_alloc() API call.  This instance of an ast_channel will be referred to
00508     as a SIP channel.  The SIP channel driver will take care of SIP specific channel
00509     initialization.  Once the channel has been created and initialized, a channel thread
00510     is created to handle the call (ast_pbx_start()).
00511  -# <b>Run the Dialplan:</b>: The main loop that runs in the channel thread is the code
00512     responsible for looking for the proper extension and then executing it.  This loop
00513     lives in ast_pbx_run() in main/pbx.c.
00514  -# <b>Answer the Call:</b>: Once the dialplan is being executed, the first application
00515     that is executed is <code>Answer()</code>.  This application is a built in
00516     application that is defined in main/pbx.c.  The <code>Answer()</code> application
00517     code simply executes the ast_answer() API call.  This API call operates on an
00518     ast_channel.  It handles generic ast_channel hangup processing, as well as executes
00519     the answer callback function defined in the associated ast_channel_tech for the
00520     active channel.  In this case, the sip_answer() function in chan_sip.c will get
00521     executed to handle the SIP specific operations required to answer a call.
00522  -# <b>Play the File:</b> The next step of the dialplan says to play back a %sound file
00523     to the caller.  The <code>Playback()</code> application will be executed.
00524     The code for this application is in apps/app_playback.c.  The code in the application
00525     is pretty simple.  It does argument handling and uses API calls to play back the
00526     file, ast_streamfile(), ast_waitstream(), and ast_stopstream(), which set up file
00527     playback, wait for the file to finish playing, and then free up resources.  Some
00528     of the important operations of these API calls are described in steps here:
00529     -# <b>Open a File:</b> The file format API is responsible for opening the %sound file.
00530        It will start by looking for a file that is encoded in the same format that the
00531        channel is expecting to receive audio in.  If that is not possible, it will find
00532        another type of file that can be translated into the codec that the channel is
00533        expecting.  Once a file is found, the appropriate file format interface is invoked
00534        to handle reading the file and turning it into internal Asterisk audio frames.
00535     -# <b>Set up Translation:</b> If the encoding of the audio data in the file does not
00536        match what the channel is expecting, the file API will use the codec translation
00537        API to set up a translation path.  The translate API will invoke the appropriate
00538        codec translation interface(s) to get from the source to the destination format
00539        in the most efficient way available.
00540     -# <b>Feed Audio to the Caller:</b> The file API will invoke the timer API to know
00541        how to send out audio frames from the file in proper intervals.  At the same time,
00542        Asterisk must also continuously service the incoming audio from the channel since
00543        it will continue to arrive in real time.  However, in this scenario, it will just
00544        get thrown away.
00545  -# <b>Hang up the Call:</b> Once the <code>Playback()</code> application has finished,
00546     the dialplan execution loop continues to the next step in the dialplan, which is
00547     <code>Hangup()</code>.  This operates in a very similar manner to <code>Answer()</code>
00548     in that it handles channel type agnostic hangup handling, and then calls down into
00549     the SIP channel interface to handle SIP specific hangup processing.  At this point,
00550     even if there were more steps in the dialplan, processing would stop since the channel
00551     has been hung up.  The channel thread will exit the dialplan processing loop and
00552     destroy the ast_channel data structure.
00553 
00554 \subsection ArchCodeFlowBridge SIP to IAX2 Bridged Call
00555 
00556 This example consists of a call that comes in to Asterisk via the SIP protocol.  Asterisk
00557 then makes an outbound call via the IAX2 protocol.  When the far end over IAX2 answers,
00558 the call is bridged.
00559 
00560 Example dialplan:
00561 
00562 <code>exten => 5551212,n,Dial(IAX2/mypeer)</code><br/>
00563 
00564  -# <b>Call Setup:</b> An incoming SIP INVITE begins this scenario.  It is received by
00565     the SIP channel driver (chan_sip.c).  Specifically, the monitor thread in chan_sip
00566     is responsible for handling this incoming request.  Further, the monitor thread
00567     is responsible for completing any handshake necessary to complete the call setup
00568     process.
00569  -# <b>Accept Call:</b> Once the SIP channel driver has completed the call setup process,
00570     it accepts the call and initiates the call handling process in Asterisk.  To do so,
00571     it must allocate an instance of an abstract channel (ast_channel) using the
00572     ast_channel_alloc() API call.  This instance of an ast_channel will be referred to
00573     as a SIP channel.  The SIP channel driver will take care of SIP specific channel
00574     initialization.  Once the channel has been created and initialized, a channel thread
00575     is created to handle the call (ast_pbx_start()).
00576  -# <b>Run the Dialplan:</b>: The main loop that runs in the channel thread is the code
00577     responsible for looking for the proper extension and then executing it.  This loop
00578     lives in ast_pbx_run() in main/pbx.c.
00579  -# <b>Execute Dial()</b>: The only step in this dialplan is to execute the
00580     <code>Dial()</code> application.
00581     -# <b>Create an Outbound Channel:</b> The <code>Dial()</code> application needs to
00582        create an outbound ast_channel.  It does this by first using the ast_request()
00583        API call to request a channel called <code>IAX2/mypeer</code>.  This API call
00584        is a part of the core channel API (include/asterisk/channel.h).  It will find
00585        a channel driver of type <code>IAX2</code> and then execute the request callback
00586        in the appropriate ast_channel_tech interface.  In this case, it is iax2_request()
00587        in channels/chan_iax2.c.  This asks the IAX2 channel driver to allocate an
00588        ast_channel of type IAX2 and initialize it.  The <code>Dial()</code> application
00589        will then execute the ast_call() API call for this new ast_channel.  This will
00590        call into the call callback of the ast_channel_tech, iax2_call(), which requests
00591        that the IAX2 channel driver initiate the outbound call.
00592     -# <b>Wait for Answer:</b> At this point, the Dial() application waits for the
00593        outbound channel to answer the call.  While it does this, it must continue to
00594        service the incoming audio on both the inbound and outbound channels.  The loop
00595        that does this is very similar to every other channel servicing loop in Asterisk.
00596        The core features of a channel servicing loop include ast_waitfor() to wait for
00597        frames on a channel, and then ast_read() on a channel once frames are available.
00598     -# <b>Handle Answer:</b> Once the far end answers the call, the <code>Dial()</code>
00599        application will communicate this back to the inbound SIP channel.  It does this
00600        by calling the ast_answer() core channel API call.
00601     -# <b>Make Channels Compatible:</b> Before the two ends of the call can be connected,
00602        Asterisk must make them compatible to talk to each other.  Specifically, the two
00603        channels may be sending and expecting to receive audio in a different format than
00604        the other channel.  The API call ast_channel_make_compatible() sets up translation
00605        paths for each channel by instantiating codec translators as necessary.
00606     -# <b>Bridge the Channels:</b> Now that both the inbound and outbound channels are
00607        fully established, they can be connected together.  This connection between the
00608        two channels so that they can pass audio and signaling back and forth is referred
00609        to as a bridge.  The API call that handles the bridge is ast_channel_bridge().
00610        In this case, the main loop of the bridge is a generic bridge, ast_generic_bridge(),
00611        which is the type of bridge that works regardless of the two channel types.  A
00612        generic bridge will almost always be used if the two channels are not of the same
00613        type.  The core functionality of a bridge loop is ast_waitfor() on both channels.
00614        Then, when frames arrive on a channel, they are read using ast_read().  After reading
00615        a frame, they are written to the other channel using ast_write().
00616     -# <b>Breaking the Bridge</b>: This bridge will continue until some event occurs that
00617        causes the bridge to be broken, and control to be returned back down to the
00618        <code>Dial()</code> application.  For example, if one side of the call hangs up,
00619        the bridge will stop.
00620  -# <b>Hanging Up:</b>: After the bridge stops, control will return to the
00621     <code>Dial()</code> application.  The application owns the outbound channel since
00622     that is where it was created.  So, the outbound IAX2 channel will be destroyed
00623     before <code>Dial()</code> is complete.  Destroying the channel is done by using
00624     the ast_hangup() API call.  The application will return back to the dialplan
00625     processing loop.  From there, the loop will see that there is nothing else to
00626     execute, so it will hangup on the inbound channel as well using the ast_hangup()
00627     function.  ast_hangup() performs a number of channel type independent hangup
00628     tasks, but also executes the hangup callback of ast_channel_tech (sip_hangup()).
00629     Finally, the channel thread exits.
00630 
00631 
00632 \section ArchDataStructures Asterisk Data Structures
00633 
00634 Asterisk provides generic implementations of a number of data structures.
00635 
00636 \subsection ArchAstobj2 Astobj2
00637 
00638 Astobj2 stands for the Asterisk Object model, version 2.  The API is defined in
00639 include/asterisk/astobj2.h.  Some internal implementation details for astobj2 can
00640 be found in main/astobj2.c.  There is a version 1, and it still exists in the
00641 source tree.  However, it is considered deprecated.
00642 
00643 Astobj2 provides reference counted object handling.  It also provides a container
00644 interface for astobj2 objects.  The container provided is a hash table.
00645 
00646 See the astobj2 API for more details about how to use it.  Examples can be found
00647 all over the code base.
00648 
00649 \subsection ArchLinkedLists Linked Lists
00650 
00651 Asterisk provides a set of macros for handling linked lists.  They are defined in
00652 include/asterisk/linkedlists.h.
00653 
00654 \subsection ArchDLinkedLists Doubly Linked Lists
00655 
00656 Asterisk provides a set of macros for handling doubly linked lists, as well.  They
00657 are defined in include/asterisk/dlinkedlists.h.
00658 
00659 \subsection ArchHeap Heap
00660 
00661 Asterisk provides an implementation of the max heap data structure.  The API is defined
00662 in include/asterisk/heap.h.  The internal implementation details can be found in
00663 main/heap.c.
00664 
00665 
00666 \section ArchDebugging Asterisk Debugging Tools
00667 
00668 Asterisk includes a %number of built in debugging tools to help in diagnosing common
00669 types of problems.
00670 
00671 \subsection ArchThreadDebugging Thread Debugging
00672 
00673 Asterisk keeps track of a list of all active threads on the system.  A list of threads
00674 can be viewed from the Asterisk CLI by running the command
00675 <code>core show threads</code>.
00676 
00677 Asterisk has a compile time option called <code>DEBUG_THREADS</code>.  When this is on,
00678 the pthread wrapper API in Asterisk keeps track of additional information related to
00679 threads and locks to aid in debugging.  In addition to just keeping a list of threads,
00680 Asterisk also maintains information about every lock that is currently held by any
00681 thread on the system.  It also knows when a thread is blocking while attempting to
00682 acquire a lock.  All of this information is extremely useful when debugging a deadlock.
00683 This data can be acquired from the Asterisk CLI by running the
00684 <code>core show locks</code> CLI command.
00685 
00686 The definitions of these wrappers can be found in <code>include/asterisk/lock.h</code>
00687 and <code>include/asterisk/utils.h</code>.  Most of the implementation details can be
00688 found in <code>main/utils.c</code>.
00689 
00690 \subsection ArchMemoryDebugging Memory debugging
00691 
00692 Dynamic memory management in Asterisk is handled through a %number of wrappers defined
00693 in <code>include/asterisk/utils.h</code>.  By default, all of these wrappers use the
00694 standard C library malloc(), free(), etc. functions.  However, if Asterisk is compiled
00695 with the MALLOC_DEBUG option enabled, additional memory debugging is included.
00696 
00697 The Asterisk memory debugging system provides the following features:
00698 
00699  - Track all current allocations including their size and the file, function, and line
00700    %number where they were initiated.
00701  - When releasing memory, do some basic fence checking to see if anything wrote into the
00702    few bytes immediately surrounding an allocation.
00703  - Get notified when attempting to free invalid memory.
00704 
00705 A %number of CLI commands are provided to access data on the current set of memory
00706 allocations.  Those are:
00707 
00708  - <code>memory show summary</code>
00709  - <code>memory show allocations</code>
00710 
00711 The implementation of this memory debugging system can be found in
00712 <code>main/astmm.c</code>.
00713 
00714 
00715 <hr>
00716 Return to the \ref ArchTOC
00717  */
00718 

Generated on Thu Apr 16 06:27:13 2015 for Asterisk - The Open Source Telephony Project by  doxygen 1.5.6