\hypertarget{a00893}{}\doxysection{AAX communication protocols}
\label{a00893}\index{AAX communication protocols@{AAX communication protocols}}
How to transfer data between different parts of an AAX plug-\/in. 

AAX is a highly modular architecture. This section describes the various means by which AAX plug-\/in modules may communicate with one another and with the host.

There are two fundamental categories of communication in \mbox{\hyperlink{a00948}{AAX}}\+:
\begin{DoxyEnumerate}
\item \mbox{\hyperlink{a00893_CommonInterface_Communication_hostmodules}{Communication with the C++ interface objects}}
\item \mbox{\hyperlink{a00893_CommonInterface_Communication_algorithm}{Communication with the real-\/time algorithm}}
\end{DoxyEnumerate}\hypertarget{a00893_CommonInterface_Communication_hostmodules}{}\doxysubsection{Communication with the C++ interface objects}\label{a00893_CommonInterface_Communication_hostmodules}
\hypertarget{a00893_CommonInterface_Communication_hostmodules_controller}{}\doxysubsubsection{Direct host communication}\label{a00893_CommonInterface_Communication_hostmodules_controller}
Most communication between the AAX host and the plug-\/in is accomplished via the \mbox{\hyperlink{a02222}{AAX\+\_\+\+IController}} interface. This interface contains methods for such things as\+:
\begin{DoxyItemize}
\item Retrieving environment information such as the current \mbox{\hyperlink{a02222_afa1f9f64eeeab9570e5599f466fa699e}{sample rate}}
\item Getting and setting Effect parameters such as the Effect\textquotesingle{}s \mbox{\hyperlink{a02222_ad50aa6fd54e39623a58debd63d9551e1}{algorithmic delay}}
\item Accessing host-\/managed information such as \mbox{\hyperlink{a00902}{Plug-\/in meters}} and MIDI
\item Accessing other host-\/managed communications protocols like \mbox{\hyperlink{a00893_CommonInterface_Communication_algorithm_datapackets}{Data packets}} and MIDI
\end{DoxyItemize}

In addition, the GUI uses a separate interface for managing view and event details with the host. This interface, \mbox{\hyperlink{a02354}{AAX\+\_\+\+IView\+Container}}, includes methods for\+:
\begin{DoxyItemize}
\item Retrieving information like the raw view and the currently held modifier keys
\item Requesting changes to view parameters (e.\+g. size)
\item Passing GUI events on to the host.
\begin{DoxyItemize}
\item This is an important function because the host may require its own specific behavior for certain events. For example, a command-\/control-\/option click in Pro Tools should bring up the parameter\textquotesingle{}s automation menu.
\end{DoxyItemize}
\end{DoxyItemize}\hypertarget{a00893_CommonInterface_Communication_hostmodules_customdata}{}\doxysubsubsection{Custom data blocks}\label{a00893_CommonInterface_Communication_hostmodules_customdata}
Often it is necessary to transmit arbitrary blocks of custom plug-\/in data between different plug-\/in modules. In AAX, this is accomplished by \char`\"{}pushing\char`\"{} data to and \char`\"{}pulling\char`\"{} it from the plug-\/in\textquotesingle{}s \mbox{\hyperlink{a00891}{data model}}.

The abstract data model interface includes two custom data methods for this\+: \begin{DoxyItemize}
\item \mbox{\hyperlink{a02066_a4728fcad006d921a07489144360f447e}{AAX\+\_\+\+IEffect\+Parameters\+::\+Get\+Custom\+Data()}} \item \mbox{\hyperlink{a02066_aa838cad04781853ef2e0b9df22a05170}{AAX\+\_\+\+IEffect\+Parameters\+::\+Set\+Custom\+Data()}}\end{DoxyItemize}
It is the data model\textquotesingle{}s job to act as a go-\/between when custom data must be transmitted between a plug-\/in\textquotesingle{}s other modules.

For example, a plug-\/in may wish to send analysis data from its \mbox{\hyperlink{a00899}{direct data module}} to its \mbox{\hyperlink{a00892}{GUI}}. In this situation, the Direct Data object would call \mbox{\hyperlink{a02066_aa838cad04781853ef2e0b9df22a05170}{Set\+Custom\+Data()}} to update the data model whenever new data was available, while the GUI would \char`\"{}pull\char`\"{} the most up-\/to-\/date data via \mbox{\hyperlink{a02066_a4728fcad006d921a07489144360f447e}{Get\+Custom\+Data()}} whenever an update was required.

Note that the default implementations of these methods are empty and thus all implementation details, including thread safety guards, are left to the plug-\/in.\hypertarget{a00893_CommonInterface_Communication_hostmodules_notifications}{}\doxysubsubsection{Notifications}\label{a00893_CommonInterface_Communication_hostmodules_notifications}
The \mbox{\hyperlink{a00891}{data model}} and \mbox{\hyperlink{a00892}{GUI}} interfaces include \mbox{\hyperlink{a02066_aa3eaeb292d2ca84086a5a058171994fd}{notification hook}} methods. These methods used for \mbox{\hyperlink{a00446_afab5ea2cfd731fc8f163b6caa685406e}{host-\/to-\/\+Effect notifications}} by default, but may also be called with custom notification IDs in order to create custom notifications within a plug-\/in.\hypertarget{a00893_CommonInterface_Communication_hostmodules_directpointersharing}{}\doxysubsubsection{Direct pointer sharing}\label{a00893_CommonInterface_Communication_hostmodules_directpointersharing}
If co-\/location is guaranteed, plug-\/in modules may directly share data pointers. For example, a non-\/real-\/time plug-\/in\textquotesingle{}s \mbox{\hyperlink{a00904}{Host Processor}} object may share a {\ttfamily this} pointer with its \mbox{\hyperlink{a00891}{data model}} object.

To guarantee co-\/location between modules that could normally be placed into different memory spaces by the host, use \char`\"{}constraint\char`\"{} properties\+:

\begin{DoxyItemize}
\item \mbox{\hyperlink{a00608_a13e384f22825afd3db6d68395b79ce0da79a0815fea6c8f1a0d8ed511aa88e9ff}{AAX\+\_\+e\+Property\+\_\+\+Constraint\+\_\+\+Location}} \item \mbox{\hyperlink{a00608_a13e384f22825afd3db6d68395b79ce0da5d7fca796aba48b5dc364af0cc633a02}{AAX\+\_\+e\+Property\+\_\+\+Constraint\+\_\+\+Topology}}\end{DoxyItemize}
To help avoid forwards-\/compatibility issues with future devices that support AAX, these constraints should be set whenever a plug-\/in requires co-\/location of its components. Note, however, that using a design that relies on co-\/location will prevent the plug-\/in from running in distributed environments and should therefore be avoided when possible.\hypertarget{a00893_CommonInterface_Communication_algorithm}{}\doxysubsection{Communication with the real-\/time algorithm}\label{a00893_CommonInterface_Communication_algorithm}
An AAX plug-\/in\textquotesingle{}s algorithm is essentially a stateless callback and, therefore, all of its state data must at some level be managed by the host. This model is fundamentally different from the other plug-\/in modules, which are each objects with their own memory and state.

Most algorithmic data management is performed via the algorithm\textquotesingle{}s context structure. More information about memory management in AAX real-\/time algorithms can be found \mbox{\hyperlink{a00890_alg_memmgmt}{here}}.\hypertarget{a00893_CommonInterface_Communication_algorithm_datapackets}{}\doxysubsubsection{Data packets}\label{a00893_CommonInterface_Communication_algorithm_datapackets}
The most common form of communication with a plug-\/in\textquotesingle{}s real-\/time algorithm callback is the transmission of read-\/only data from the data model to the context structure.

AAX includes a dedicated API for this task that provides buffered, optimized delivery of read-\/only data packets to the algorithm. For more information, see \mbox{\hyperlink{a00890_alg_comm}{Communicating with the algorithm}} .\hypertarget{a00893_CommonInterface_Communication_algorithm_fields}{}\doxysubsubsection{Host-\/managed context fields}\label{a00893_CommonInterface_Communication_algorithm_fields}
Algorithms can also send data to the host and receive environment information through dedicated context fields. For example, the host can provide access to DMA facilities through an object accessed via a DMA field, and a plug-\/in can report meter values to the host via a dedicated meter field. For more information, see \mbox{\hyperlink{a00890_alg_comm}{Communicating with the algorithm}} .\hypertarget{a00893_CommonInterface_Communication_algorithm_directdata}{}\doxysubsubsection{Direct data transfers}\label{a00893_CommonInterface_Communication_algorithm_directdata}
When other modules in the plug-\/in must interact directly with the algorithm\textquotesingle{}s state information this is accomplished via the \mbox{\hyperlink{a00899}{Direct Data}} interface. This interface provides an idle-\/time context in which the plug-\/in may read from or write to the algorithm\textquotesingle{}s private data memory. These transfers are unbuffered and therefore the plug-\/in must handle any appropriate thread-\/safety considerations. Collaboration diagram for AAX communication protocols\+:
% FIG 0
