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