[svn-commits] russell: trunk r226606 - in /trunk: contrib/ include/asterisk/ include/asteri...
SVN commits to the Digium repositories
svn-commits at lists.digium.com
Thu Oct 29 23:08:43 CDT 2009
Author: russell
Date: Thu Oct 29 23:08:39 2009
New Revision: 226606
URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=226606
Log:
Add an "Asterisk Architecture Overview" section to the doxygen documentation.
This is a side project I've been poking at this week. The intent is to discuss
Asterisk architecture in a top down fashion to help new developers understand how
Asterisk is put together. There is a ton of stuff to write about, so this will
just continue to evolve over time.
Added:
trunk/include/asterisk/doxygen/architecture.h (with props)
Modified:
trunk/contrib/asterisk-ng-doxygen
trunk/include/asterisk/doxyref.h
trunk/main/asterisk.c
trunk/res/res_rtp_asterisk.c
trunk/res/res_rtp_multicast.c
Modified: trunk/contrib/asterisk-ng-doxygen
URL: http://svnview.digium.com/svn/asterisk/trunk/contrib/asterisk-ng-doxygen?view=diff&rev=226606&r1=226605&r2=226606
==============================================================================
--- trunk/contrib/asterisk-ng-doxygen (original)
+++ trunk/contrib/asterisk-ng-doxygen Thu Oct 29 23:08:39 2009
@@ -25,7 +25,7 @@
# The PROJECT_NAME tag is a single word (or a sequence of words surrounded
# by quotes) that should identify the project.
-PROJECT_NAME = "Asterisk - the Open Source PBX"
+PROJECT_NAME = "Asterisk - The Open Source Telephony Project"
# The PROJECT_NUMBER tag can be used to enter a project or revision number.
# This could be handy for archiving the generated documentation or
Added: trunk/include/asterisk/doxygen/architecture.h
URL: http://svnview.digium.com/svn/asterisk/trunk/include/asterisk/doxygen/architecture.h?view=auto&rev=226606
==============================================================================
--- trunk/include/asterisk/doxygen/architecture.h (added)
+++ trunk/include/asterisk/doxygen/architecture.h Thu Oct 29 23:08:39 2009
@@ -1,0 +1,716 @@
+/*
+ * Asterisk -- An open source telephony toolkit.
+ *
+ * Copyright (C) 2009, Digium, Inc.
+ *
+ * Russell Bryant <russell at digium.com>
+ *
+ * See http://www.asterisk.org for more information about
+ * the Asterisk project. Please do not directly contact
+ * any of the maintainers of this project for assistance;
+ * the project provides a web site, mailing lists and IRC
+ * channels for your use.
+ *
+ * This program is free software, distributed under the terms of
+ * the GNU General Public License Version 2. See the LICENSE file
+ * at the top of the source tree.
+ */
+
+/*!
+ * \file
+ * \author Russell Bryant <russell at digium.com>
+ */
+
+/*!
+\page AsteriskArchitecture Asterisk Architecture Overview
+\author Russell Bryant <russell at digium.com>
+\AsteriskTrunkWarning
+
+<hr/>
+
+\section ArchTOC Table of Contents
+
+ -# \ref ArchIntro
+ -# \ref ArchLayout
+ -# \ref ArchInterfaces
+ -# \ref ArchInterfaceCodec
+ -# \ref ArchInterfaceFormat
+ -# \ref ArchInterfaceAPIs
+ -# \ref ArchInterfaceAMI
+ -# \ref ArchInterfaceChannelDrivers
+ -# \ref ArchInterfaceBridge
+ -# \ref ArchInterfaceCDR
+ -# \ref ArchInterfaceCEL
+ -# \ref ArchInterfaceDialplanApps
+ -# \ref ArchInterfaceDialplanFuncs
+ -# \ref ArchInterfaceRTP
+ -# \ref ArchInterfaceTiming
+ -# \ref ArchThreadingModel
+ -# \ref ArchChannelThreads
+ -# \ref ArchMonitorThreads
+ -# \ref ArchServiceThreads
+ -# \ref ArchOtherThreads
+ -# \ref ArchConcepts
+ -# \ref ArchConceptBridging
+ -# \ref ArchCodeFlows
+ -# \ref ArchCodeFlowPlayback
+ -# \ref ArchCodeFlowBridge
+ -# \ref ArchDataStructures
+ -# \ref ArchAstobj2
+ -# \ref ArchLinkedLists
+ -# \ref ArchDLinkedLists
+ -# \ref ArchHeap
+ -# \ref ArchDebugging
+ -# \ref ArchThreadDebugging
+ -# \ref ArchMemoryDebugging
+
+<hr/>
+
+\section ArchIntro Introduction
+
+This section of the documentation includes an overview of the Asterisk architecture
+from a developer's point of view. For detailed API discussion, see the documentation
+associated with public API header files. This documentation assumes some knowledge
+of what Asterisk is and how to use it.
+
+The intent behind this documentation is to start looking at Asterisk from a high
+level and progressively dig deeper into the details. It begins with talking about
+the different types of components that make up Asterisk and eventually will go
+through interactions between these components in different use cases.
+
+Throughout this documentation, many links are also provided as references to more
+detailed information on related APIs, as well as the related source code to what
+is being discussed.
+
+Feedback and contributions to this documentation are very welcome. Please send your
+comments to the asterisk-dev mailing list on http://lists.digium.com/.
+
+Thank you, and enjoy Asterisk!
+
+
+\section ArchLayout Modular Architecture
+
+Asterisk is a highly modularized application. There is a core application that
+is built from the source in the <code>main/</code> directory. However, it is
+not very useful by itself.
+
+There are many modules that are loaded at runtime. Asterisk modules have names that
+give an indication as to what functionality they provide, but the name is not special
+in any technical sense. When Asterisk loads a module, the module registers the
+functionality that it provides with the Asterisk core.
+
+ -# Asterisk starts
+ -# Asterisk loads modules
+ -# Modules say "Hey Asterisk! I am a module. I can provide functionality X, Y,
+ and Z. Let me know when you'd like to use my functionality!"
+
+
+\section ArchInterfaces Abstract Interface types
+
+There are many types of interfaces that modules can implement and register their
+implementations of with the Asterisk core. Any module is allowed to register as
+many of these different interfaces as they would like. Generally, related
+functionality is grouped into a single module.
+
+In this section, the types of interfaces are discussed. Later, there will
+be discussions about how different components interact in various scenarios.
+
+\subsection ArchInterfaceCodec Codec Interpreter
+
+An implementation of the codec interpreter interface provides the ability to
+convert between two codecs. Asterisk currently only has the ability to translate
+between audio codecs.
+
+These modules have no knowledge about phone calls or anything else about why
+they are being asked to convert audio. They just get audio samples as input
+in their specified input format, and are expected to provide audio in the
+specified output format.
+
+It is possible to have multiple paths to get from codec A to codec B once many
+codec implementations are registered. After modules have been loaded, Asterisk
+builds a translation table with measurements of the performance of each codec
+translator so that it can always find the best path to get from A to B.
+
+Codec modules typically live in the <code>codecs/</code> directory in the
+source tree.
+
+For a list of codec interpreter implementations, see \ref codecs.
+
+For additional information on the codec interpreter API, see the interface
+definition in <code>include/asterisk/translate.h</code>.
+
+For core implementation details related to the codec interpreter API, see
+<code>main/translate.c</code>.
+
+\subsection ArchInterfaceFormat File Format Handler
+
+An implementation of the file format handler interface provides Asterisk the
+ability to read and optionally write files. File format handlers may provide
+access to audio, video, or image files.
+
+The interface for a file format handler is rather primitive. A module simply
+tells the Asterisk core that it can handle files with a given %extension,
+for example, ".wav". It also says that after reading the file, it will
+provide audio in the form of codec X. If a file format handler provides the
+ability to write out files, it also must specify what codec the audio should
+be in before provided to the file format handler.
+
+File format modules typically live in the <code>formats/</code> directory in the
+source tree.
+
+For a list of file format handler implementations, see \ref formats.
+
+For additional information on the file format handler API, see the interface
+definition in <code>include/asterisk/file.h</code>.
+
+For core implementation details related to the file format API, see
+<code>main/file.c</code>.
+
+\subsection ArchInterfaceAPIs C API Providers
+
+There are some C APIs in Asterisk that are optional. Core APIs are built into
+the main application and are always available. Optional C APIs are provided
+by a module and are only available for use when the module is loaded. Some of
+these API providers also contain their own interfaces that other modules can
+implement and register.
+
+Modules that provide a C API typically live in the <code>res/</code> directory
+in the source tree.
+
+Some examples of modules that provide C APIs (potentially among other things) are:
+ - res_musiconhold.c
+ - res_calendar.c
+ - provides a calendar technology interface.
+ - res_odbc.c
+ - res_ael_share.c
+ - res_crypto.c
+ - res_curl.c
+ - res_jabber.c
+ - res_monitor.c
+ - res_smdi.c
+ - res_speech.c
+ - provides a speech recognition engine interface.
+
+\subsection ArchInterfaceAMI Manager Interface (AMI) Actions
+
+The Asterisk manager interface is a socket interface for monitoring and control
+of Asterisk. It is a core feature built in to the main application. However,
+modules can register %actions that may be requested by clients.
+
+Modules that register manager %actions typically do so as auxiliary functionality
+to complement whatever main functionality it provides. For example, a module that
+provides call conferencing services may have a manager action that will return the
+list of participants in a conference.
+
+\subsection ArchInterfaceCLI CLI Commands
+
+The Asterisk CLI is a feature implemented in the main application. Modules may
+register additional CLI commands.
+
+\subsection ArchInterfaceChannelDrivers Channel Drivers
+
+The Asterisk channel driver interface is the most complex and most important
+interface available. The Asterisk channel API provides the telephony protocol
+abstraction which allows all other Asterisk features to work independently of
+the telephony protocol in use.
+
+The specific interface that channel drivers implement is the ast_channel_tech
+interface. A channel driver must implement functions that perform various
+call signaling tasks. For example, they must implement a method for initiating
+a call and hanging up a call. The ast_channel data structure is the abstract
+channel data structure. Each ast_channel instance has an associated
+ast_channel_tech which identifies the channel type. An ast_channel instance
+represents one leg of a call (a connection between Asterisk and an endpoint).
+
+Channel drivers typically live in the <code>channels/</code> directory in the
+source tree.
+
+For a list of channel driver implementations, see \ref channel_drivers.
+
+For additional information on the channel API, see
+<code>include/asterisk/channel.h</code>.
+
+For additional implementation details regarding the core ast_channel API, see
+<code>main/channel.c</code>.
+
+\subsection ArchInterfaceBridge Bridging Technologies
+
+Bridging is the operation which connects two or more channels together. A simple
+two channel bridge is a normal A to B phone call, while a multi-party bridge would
+be something like a 3-way call or a full conference call.
+
+The bridging API allows modules to register bridging technologies. An implementation
+of a bridging technology knows how to take two (or optionally more) channels and
+connect them together. Exactly how this happens is up to the implementation.
+
+This interface is used such that the code that needs to pass audio between channels
+doesn't need to know how it is done. Underneath, the conferencing may be done in
+the kernel (via DAHDI), via software methods inside of Asterisk, or could be done
+in hardware in the future if someone implemented a module to do so.
+
+At the time of this writing, the bridging API is still relatively new, so it is
+not used everywhere that bridging operations are performed. The ConfBridge dialplan
+application is a new conferencing application which has been implemented on top of
+this bridging API.
+
+Bridging technology modules typically live in the <code>bridges/</code> directory
+in the source tree.
+
+For a list of bridge technology implementations, see \ref bridges.
+
+For additional information on the bridging API, see
+<code>include/asterisk/bridging.h</code> and
+<code>include/asterisk/bridging_technology.h</code>.
+
+For additional implementation details regarding the core bridging API, see
+<code>main/bridging.c</code>.
+
+\subsection ArchInterfaceCDR Call Detail Record (CDR) Handlers
+
+The Asterisk core implements functionality for keeping records of calls. These
+records are built while calls are processed and live in data structures. At the
+end of the call, these data structures are released. Before the records are thrown
+away, they are passed in to all of the registered CDR handlers. These handlers may
+write out the records to a file, post them to a database, etc.
+
+CDR modules typically live in the <code>cdr</code> directory in the source tree.
+
+For a list of CDR handlers, see \ref cdr_drivers.
+
+For additional information on the CDR API, see
+<code>include/asterisk/cdr.h</code>.
+
+For additional implementation details regarding CDR handling, see
+<code>main/cdr.c</code>.
+
+\subsection ArchInterfaceCEL Call Event Logging (CEL) Handlers
+
+The Asterisk core includes a generic event system that allows Asterisk components
+to report events that can be subscribed to by other parts of the system. One of
+the things built on this event system is Call Event Logging (CEL).
+
+CEL is similar to CDR in that they are both for tracking call history. While CDR
+records are typically have a one record to one call relationship, CEL events are
+many events to one call. The CEL modules look very similar to CDR modules.
+
+CEL modules typically live in the <code>cel/</code> directory in the source tree.
+
+For a list of CEL handlers, see \ref cel_drivers.
+
+For additional information about the CEL API, see
+<code>include/asterisk/cel.h</code>.
+
+For additional implementation details for the CEL API, see <code>main/cel.c</code>.
+
+\subsection ArchInterfaceDialplanApps Dialplan Applications
+
+Dialplan applications implement features that interact with calls that can be
+executed from the Asterisk dialplan. For example, in <code>extensions.conf</code>:
+
+<code>exten => 123,1,NoOp()</code>
+
+In this case, NoOp is the application. Of course, NoOp doesn't actually do
+anything.
+
+These applications use a %number of APIs available in Asterisk to interact with
+the channel. One of the most important tasks of an application is to continuously
+read audio from the channel, and also write audio back to the channel. The details
+of how this is done is usually hidden behind an API call used to play a file or wait
+for digits to be pressed by a caller.
+
+In addition to interacting with the channel that originally executed the application,
+dialplan applications sometimes also create additional outbound channels.
+For example, the Dial() application creates an outbound channel and bridges it to the
+inbound channel. Further discussion about the functionality of applications will be
+discussed in detailed use cases.
+
+Dialplan applications are typically found in the <code>apps/</code> directory in
+the source tree.
+
+For a list of dialplan applications, see \ref applications.
+
+For details on the API used to register an application with the Asterisk core, see
+<code>include/asterisk/pbx.h</code>.
+
+\subsection ArchInterfaceDialplanFuncs Dialplan Functions
+
+As the name suggests, dialplan functions, like dialplan applications, are primarily
+used from the Asterisk dialplan. Functions are used mostly in the same way that
+variables are used in the dialplan. They provide a read and/or write interface, with
+optional arguments. While they behave similarly to variables, they storage and
+retrieval of a value is more complex than a simple variable with a text value.
+
+For example, the <code>CHANNEL()</code> dialplan function allows you to access
+data on the current channel.
+
+<code>exten => 123,1,NoOp(This channel has the name: ${CHANNEL(name)})</code>
+
+Dialplan functions are typically found in the <code>funcs/</code> directory in
+the source tree.
+
+For a list of dialplan function implementations, see \ref functions.
+
+For details on the API used to register a dialplan function with the Asterisk core,
+see <code>include/asterisk/pbx.h</code>.
+
+\subsection ArchInterfaceRTP RTP Engines
+
+The Asterisk core provides an API for handling RTP streams. However, the actual
+handling of these streams is done by modules that implement the RTP engine interface.
+Implementations of an RTP engine typically live in the <code>res/</code> directory
+of the source tree, and have a <code>res_rtp_</code> prefix in their name.
+
+\subsection ArchInterfaceTiming Timing Interfaces
+
+The Asterisk core implements an API that can be used by components that need access
+to timing services. For example, a timer is used to send parts of an audio file at
+proper intervals when playing back a %sound file to a caller. The API relies on
+timing interface implementations to provide a source for reliable timing.
+
+Timing interface implementations are typically found in the <code>res/</code>
+subdirectory of the source tree.
+
+For a list of timing interface implementations, see \ref timing_interfaces.
+
+For additional information on the timing API, see <code>include/asterisk/timing.h</code>.
+
+For additional implementation details for the timing API, see <code>main/timing.c</code>.
+
+
+\section ArchThreadingModel Asterisk Threading Model
+
+Asterisk is a very heavily multi threaded application. It uses the POSIX threads API
+to manage threads and related services such as locking. Almost all of the Asterisk code
+that interacts with pthreads does so by going through a set of wrappers used for
+debugging and code reduction.
+
+Threads in Asterisk can be classified as one of the following types:
+
+ - Channel threads (sometimes referred to as PBX threads)
+ - Network Monitor threads
+ - Service connection threads
+ - Other threads
+
+\subsection ArchChannelThreads Channel Threads
+
+A channel is a fundamental concept in Asterisk. Channels are either inbound
+or outbound. An inbound channel is created when a call comes in to the Asterisk
+system. These channels are the ones that execute the Asterisk dialplan. A thread
+is created for every channel that executes the dialplan. These threads are referred
+to as a channel thread. They are sometimes also referred to as a PBX thread, since
+one of the primary tasks of the thread is to execute the Asterisk dialplan for an
+inbound call.
+
+A channel thread starts out by only being responsible for a single Asterisk channel.
+However, there are cases where a second channel may also live in a channel thread.
+When an inbound channel executes an application such as <code>Dial()</code>, an
+outbound channel is created and bridged to the inbound channel once it answers.
+
+Dialplan applications always execute in the context of a channel thread. Dialplan
+functions \i almost always do, as well. However, it is possible to read and write
+dialplan functions from an asynchronous interface such as the Asterisk CLI or the
+manager interface (AMI). However, it is still always the channel thread that is
+the owner of the ast_channel data structure.
+
+\subsection ArchMonitorThreads Network Monitor Threads
+
+Network monitor threads exist in almost every major channel driver in Asterisk.
+They are responsible for monitoring whatever network they are connected to (whether
+that is an IP network, the PSTN, etc.) and monitor for incoming calls or other types
+of incoming %requests. They handle the initial connection setup steps such as
+authentication and dialed %number validation. Finally, once the call setup has been
+completed, the monitor threads will create an instance of an Asterisk channel
+(ast_channel), and start a channel thread to handle the call for the rest of its
+lifetime.
+
+\subsection ArchServiceThreads Service Connection Threads
+
+There are a %number of TCP based services that use threads, as well. Some examples
+include SIP and the AMI. In these cases, threads are used to handle each TCP
+connection.
+
+The Asterisk CLI also operates in a similar manner. However, instead of TCP, the
+Asterisk CLI operates using connections to a UNIX %domain socket.
+
+\subsection ArchOtherThreads Other Threads
+
+There are other miscellaneous threads throughout the system that perform a specific task.
+For example, the event API (include/asterisk/event.h) uses a thread internally
+(main/event.c) to handle asychronous event dispatching. The devicestate API
+(include/asterisk/devicestate.h) uses a thread internally (main/devicestate.c)
+to asynchronously process device state changes.
+
+
+\section ArchConcepts Other Architecture Concepts
+
+This section covers some other important Asterisk architecture concepts.
+
+\subsection ArchConceptBridging Channel Bridging
+
+As previously mentioned when discussing the bridging technology interface
+(\ref ArchInterfaceBridge), bridging is the act of connecting one or more channel
+together so that they may pass audio between each other. However, it was also
+mentioned that most of the code in Asterisk that does bridging today does not use
+this new bridging infrastructure. So, this section discusses the legacy bridging
+functionality that is used by the <code>Dial()</code> and <code>Queue()</code>
+applications.
+
+When one of these applications decides it would like to bridge two channels together,
+it does so by executing the ast_channel_bridge() API call. From there, there are
+two types of bridges that may occur.
+
+ -# <b>Generic Bridge:</b> A generic bridge (ast_generic_bridge()) is a bridging
+ method that works regardless of what channel technologies are in use. It passes
+ all audio and signaling through the Asterisk abstract channel and frame interfaces
+ so that they can be communicated between channel drivers of any type. While this
+ is the most flexible, it is also the least efficient bridging method due to the
+ levels of abstraction necessary.
+ -# <b>Native Bridge:</b> Channel drivers have the option of implementing their own
+ bridging functionality. Specifically, this means to implement the bridge callback
+ in the ast_channel_tech structure. If two channels of the same type are bridged,
+ a native bridge method is available, and Asterisk does not have a reason to force
+ the call to stay in the core of Asterisk, then the native bridge function will be
+ invoked. This allows channel drivers to take advantage of the fact that the
+ channels are the same type to optimize bridge processing. In the case of a DAHDI
+ channel, this may mean that the channels are bridged natively on hardware. In the
+ case of SIP, this means that Asterisk can direct the audio to flow between the
+ endpoints and only require the signaling to continue to flow through Asterisk.
+
+
+\section ArchCodeFlows Code Flow Examples
+
+Now that there has been discussion about the various components that make up Asterisk,
+this section goes through examples to demonstrate how these components work together
+to provide useful functionality.
+
+\subsection ArchCodeFlowPlayback SIP Call to File Playback
+
+This example consists of a call that comes in to Asterisk via the SIP protocol.
+Asterisk accepts this call, plays back a %sound file to the caller, and then hangs up.
+
+Example dialplan:
+
+<code>exten => 5551212,1,Answer()</code><br/>
+<code>exten => 5551212,n,Playback(demo-congrats)</code><br/>
+<code>exten => 5551212,n,Hangup()</code><br/>
+
+ -# <b>Call Setup:</b> An incoming SIP INVITE begins this scenario. It is received by
+ the SIP channel driver (chan_sip.c). Specifically, the monitor thread in chan_sip
+ is responsible for handling this incoming request. Further, the monitor thread
+ is responsible for completing any handshake necessary to complete the call setup
+ process.
+ -# <b>Accept Call:</b> Once the SIP channel driver has completed the call setup process,
+ it accepts the call and initiates the call handling process in Asterisk. To do so,
+ it must allocate an instance of an abstract channel (ast_channel) using the
+ ast_channel_alloc() API call. This instance of an ast_channel will be referred to
+ as a SIP channel. The SIP channel driver will take care of SIP specific channel
+ initialization. Once the channel has been created and initialized, a channel thread
+ is created to handle the call (ast_pbx_start()).
+ -# <b>Run the Dialplan:</b>: The main loop that runs in the channel thread is the code
+ responsible for looking for the proper extension and then executing it. This loop
+ lives in ast_pbx_run() in main/pbx.c.
+ -# <b>Answer the Call:</b>: Once the dialplan is being executed, the first application
+ that is executed is <code>Answer()</code>. This application is a built in
+ application that is defined in main/pbx.c. The <code>Answer()</code> application
+ code simply executes the ast_answer() API call. This API call operates on an
+ ast_channel. It handles generic ast_channel hangup processing, as well as executes
+ the answer callback function defined in the associated ast_channel_tech for the
+ active channel. In this case, the sip_answer() function in chan_sip.c will get
+ executed to handle the SIP specific operations required to answer a call.
+ -# <b>Play the File:</b> The next step of the dialplan says to play back a %sound file
+ to the caller. The <code>Playback()</code> application will be executed.
+ The code for this application is in apps/app_playback.c. The code in the application
+ is pretty simple. It does argument handling and uses API calls to play back the
+ file, ast_streamfile(), ast_waitstream(), and ast_stopstream(), which set up file
+ playback, wait for the file to finish playing, and then free up resources. Some
+ of the important operations of these API calls are described in steps here:
+ -# <b>Open a File:</b> The file format API is responsible for opening the %sound file.
+ It will start by looking for a file that is encoded in the same format that the
+ channel is expecting to receive audio in. If that is not possible, it will find
+ another type of file that can be translated into the codec that the channel is
+ expecting. Once a file is found, the appropriate file format interface is invoked
+ to handle reading the file and turning it into internal Asterisk audio frames.
+ -# <b>Set up Translation:</b> If the encoding of the audio data in the file does not
+ match what the channel is expecting, the file API will use the codec translation
+ API to set up a translation path. The translate API will invoke the appropriate
+ codec translation interface(s) to get from the source to the destination format
+ in the most efficient way available.
+ -# <b>Feed Audio to the Caller:</b> The file API will invoke the timer API to know
+ how to send out audio frames from the file in proper intervals. At the same time,
+ Asterisk must also continuously service the incoming audio from the channel since
+ it will continue to arrive in real time. However, in this scenario, it will just
+ get thrown away.
+ -# <b>Hang up the Call:</b> Once the <code>Playback()</code> application has finished,
+ the dialplan execution loop continues to the next step in the dialplan, which is
+ <code>Hangup()</code>. This operates in a very similar manner to <code>Answer()</code>
+ in that it handles channel type agnostic hangup handling, and then calls down into
+ the SIP channel interface to handle SIP specific hangup processing. At this point,
+ even if there were more steps in the dialplan, processing would stop since the channel
+ has been hung up. The channel thread will exit the dialplan processing loop and
+ destroy the ast_channel data structure.
+
+\subsection ArchCodeFlowBridge SIP to IAX2 Bridged Call
+
+This example consists of a call that comes in to Asterisk via the SIP protocol. Asterisk
+then makes an outbound call via the IAX2 protocol. When the far end over IAX2 answers,
+the call is bridged.
+
+Example dialplan:
+
+<code>exten => 5551212,n,Dial(IAX2/mypeer)</code><br/>
+
+ -# <b>Call Setup:</b> An incoming SIP INVITE begins this scenario. It is received by
+ the SIP channel driver (chan_sip.c). Specifically, the monitor thread in chan_sip
+ is responsible for handling this incoming request. Further, the monitor thread
+ is responsible for completing any handshake necessary to complete the call setup
+ process.
+ -# <b>Accept Call:</b> Once the SIP channel driver has completed the call setup process,
+ it accepts the call and initiates the call handling process in Asterisk. To do so,
+ it must allocate an instance of an abstract channel (ast_channel) using the
+ ast_channel_alloc() API call. This instance of an ast_channel will be referred to
+ as a SIP channel. The SIP channel driver will take care of SIP specific channel
+ initialization. Once the channel has been created and initialized, a channel thread
+ is created to handle the call (ast_pbx_start()).
+ -# <b>Run the Dialplan:</b>: The main loop that runs in the channel thread is the code
+ responsible for looking for the proper extension and then executing it. This loop
+ lives in ast_pbx_run() in main/pbx.c.
+ -# <b>Execute Dial()</b>: The only step in this dialplan is to execute the
+ <code>Dial()</code> application.
+ -# <b>Create an Outbound Channel:</b> The <code>Dial()</code> application needs to
+ create an outbound ast_channel. It does this by first using the ast_request()
+ API call to request a channel called <code>IAX2/mypeer</code>. This API call
+ is a part of the core channel API (include/asterisk/channel.h). It will find
+ a channel driver of type <code>IAX2</code> and then execute the request callback
+ in the appropriate ast_channel_tech interface. In this case, it is iax2_request()
+ in channels/chan_iax2.c. This asks the IAX2 channel driver to allocate an
+ ast_channel of type IAX2 and initialize it. The <code>Dial()</code> application
+ will then execute the ast_call() API call for this new ast_channel. This will
+ call into the call callback of the ast_channel_tech, iax2_call(), which requests
+ that the IAX2 channel driver initiate the outbound call.
+ -# <b>Wait for Answer:</b> At this point, the Dial() application waits for the
+ outbound channel to answer the call. While it does this, it must continue to
+ service the incoming audio on both the inbound and outbound channels. The loop
+ that does this is very similar to every other channel servicing loop in Asterisk.
+ The core features of a channel servicing loop include ast_waitfor() to wait for
+ frames on a channel, and then ast_read() on a channel once frames are available.
+ -# <b>Handle Answer:</b> Once the far end answers the call, the <code>Dial()</code>
+ application will communicate this back to the inbound SIP channel. It does this
+ by calling the ast_answer() core channel API call.
+ -# <b>Make Channels Compatible:</b> Before the two ends of the call can be connected,
+ Asterisk must make them compatible to talk to each other. Specifically, the two
+ channels may be sending and expecting to receive audio in a different format than
+ the other channel. The API call ast_channel_make_compatible() sets up translation
+ paths for each channel by instantiating codec translators as necessary.
+ -# <b>Bridge the Channels:</b> Now that both the inbound and outbound channels are
+ fully established, they can be connected together. This connection between the
+ two channels so that they can pass audio and signaling back and forth is referred
+ to as a bridge. The API call that handles the bridge is ast_channel_bridge().
+ In this case, the main loop of the bridge is a generic bridge, ast_generic_bridge(),
+ which is the type of bridge that works regardless of the two channel types. A
+ generic bridge will almost always be used if the two channels are not of the same
+ type. The core functionality of a bridge loop is ast_waitfor() on both channels.
+ Then, when frames arrive on a channel, they are read using ast_read(). After reading
+ a frame, they are written to the other channel using ast_write().
+ -# <b>Breaking the Bridge</b>: This bridge will continue until some event occurs that
+ causes the bridge to be broken, and control to be returned back down to the
+ <code>Dial()</code> application. For example, if one side of the call hangs up,
+ the bridge will stop.
+ -# <b>Hanging Up:</b>: After the bridge stops, control will return to the
+ <code>Dial()</code> application. The application owns the outbound channel since
+ that is where it was created. So, the outbound IAX2 channel will be destroyed
+ before <code>Dial()</code> is complete. Destroying the channel is done by using
+ the ast_hangup() API call. The application will return back to the dialplan
+ processing loop. From there, the loop will see that there is nothing else to
+ execute, so it will hangup on the inbound channel as well using the ast_hangup()
+ function. ast_hangup() performs a number of channel type independent hangup
+ tasks, but also executes the hangup callback of ast_channel_tech (sip_hangup()).
+ Finally, the channel thread exits.
+
+
+\section ArchDataStructures Asterisk Data Structures
+
+Asterisk provides generic implementations of a number of data structures.
+
+\subsection ArchAstobj2 Astobj2
+
+Astobj2 stands for the Asterisk Object model, version 2. The API is defined in
+include/asterisk/astobj2.h. Some internal implementation details for astobj2 can
+be found in main/astobj2.c. There is a version 1, and it still exists in the
+source tree. However, it is considered deprecated.
+
+Astobj2 provides reference counted object handling. It also provides a container
+interface for astobj2 objects. The container provided is a hash table.
+
+See the astobj2 API for more details about how to use it. Examples can be found
+all over the code base.
+
+\subsection ArchLinkedLists Linked Lists
+
+Asterisk provides a set of macros for handling linked lists. They are defined in
+include/asterisk/linkedlists.h.
+
+\subsection ArchDLinkedLists Doubly Linked Lists
+
+Asterisk provides a set of macros for handling doubly linked lists, as well. They
+are defined in include/asterisk/dlinkedlists.h.
+
+\subsection ArchHeap Heap
+
+Asterisk provides an implementation of the max heap data structure. The API is defined
+in include/asterisk/heap.h. The internal implementation details can be found in
+main/heap.c.
+
+
+\section ArchDebugging Asterisk Debugging Tools
+
+Asterisk includes a %number of built in debugging tools to help in diagnosing common
+types of problems.
+
+\subsection ArchThreadDebugging Thread Debugging
+
+Asterisk keeps track of a list of all active threads on the system. A list of threads
+can be viewed from the Asterisk CLI by running the command
+<code>core show threads</code>.
+
+Asterisk has a compile time option called <code>DEBUG_THREADS</code>. When this is on,
+the pthread wrapper API in Asterisk keeps track of additional information related to
+threads and locks to aid in debugging. In addition to just keeping a list of threads,
+Asterisk also maintains information about every lock that is currently held by any
+thread on the system. It also knows when a thread is blocking while attempting to
+acquire a lock. All of this information is extremely useful when debugging a deadlock.
+This data can be acquired from the Asterisk CLI by running the
+<code>core show locks</code> CLI command.
+
+The definitions of these wrappers can be found in <code>include/asterisk/lock.h</code>
+and <code>include/asterisk/utils.h</code>. Most of the implementation details can be
+found in <code>main/utils.c</code>.
+
+\subsection ArchMemoryDebugging Memory debugging
+
+Dynamic memory management in Asterisk is handled through a %number of wrappers defined
+in <code>include/asterisk/utils.h</code>. By default, all of these wrappers use the
+standard C library malloc(), free(), etc. functions. However, if Asterisk is compiled
+with the MALLOC_DEBUG option enabled, additional memory debugging is included.
+
+The Asterisk memory debugging system provides the following features:
+
+ - Track all current allocations including their size and the file, function, and line
+ %number where they were initiated.
+ - When releasing memory, do some basic fence checking to see if anything wrote into the
+ few bytes immediately surrounding an allocation.
+ - Get notified when attempting to free invalid memory.
+
+A %number of CLI commands are provided to access data on the current set of memory
+allocations. Those are:
+
+ - <code>memory show summary</code>
+ - <code>memory show allocations</code>
+
+The implementation of this memory debugging system can be found in
+<code>main/astmm.c</code>.
+
+
+<hr/>
+Return to the \ref ArchTOC
+ */
+
Propchange: trunk/include/asterisk/doxygen/architecture.h
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: trunk/include/asterisk/doxygen/architecture.h
------------------------------------------------------------------------------
svn:keywords = Author Date Id Revision
Propchange: trunk/include/asterisk/doxygen/architecture.h
------------------------------------------------------------------------------
svn:mime-type = text/plain
Modified: trunk/include/asterisk/doxyref.h
URL: http://svnview.digium.com/svn/asterisk/trunk/include/asterisk/doxyref.h?view=diff&rev=226606&r1=226605&r2=226606
==============================================================================
--- trunk/include/asterisk/doxyref.h (original)
+++ trunk/include/asterisk/doxyref.h Thu Oct 29 23:08:39 2009
@@ -659,6 +659,11 @@
*/
/*!
+ * \addtogroup rtp_engines Module: RTP Engines
+ * \section rtp_engine_blah Asterisk RTP Engines
+ */
+
+/*!
* \page AstHTTP AMI over HTTP support
* The http.c file includes support for manager transactions over
* http.
Modified: trunk/main/asterisk.c
URL: http://svnview.digium.com/svn/asterisk/trunk/main/asterisk.c?view=diff&rev=226606&r1=226605&r2=226606
==============================================================================
--- trunk/main/asterisk.c (original)
+++ trunk/main/asterisk.c Thu Oct 29 23:08:39 2009
@@ -19,7 +19,7 @@
/* Doxygenified Copyright Header */
/*!
- * \mainpage Asterisk -- An Open Source Telephony Toolkit
+ * \mainpage Asterisk -- The Open Source Telephony Project
*
* \par Developer Documentation for Asterisk
*
@@ -29,6 +29,8 @@
* In addition to the information available on the Asterisk source code,
* please see the appendices for information on coding guidelines,
* release management, commit policies, and more.
+ *
+ * \arg \ref AsteriskArchitecture
*
* \par Additional documentation
* \arg \ref Licensing
Modified: trunk/res/res_rtp_asterisk.c
[... 29 lines stripped ...]
More information about the svn-commits
mailing list