\hypertarget{a00905}{}\doxysection{Token protocol}
\label{a00905}\index{Token protocol@{Token protocol}}
Communicating parameter state with the host. 

\hypertarget{a00905_advancedTopics_parameterUpdates_tokenProtocol_contents}{}\doxysubsection{On this page}\label{a00905_advancedTopics_parameterUpdates_tokenProtocol_contents}
\begin{DoxyItemize}
\item \mbox{\hyperlink{a00905_tokenProtocol_introductionToTokens}{An Introduction to Tokens}} \item \mbox{\hyperlink{a00905_tokenProtocol_standardTokenOperation}{Basic Token Operation}}\end{DoxyItemize}
 \hypertarget{a00905_tokenProtocol_introductionToTokens}{}\doxysubsection{An Introduction to Tokens}\label{a00905_tokenProtocol_introductionToTokens}
One way in which a plug-\/in can communicate with the \char`\"{}outside world\char`\"{} is through Shared Data Services, also known as the Token System. This is a mechanism that allows Pro Tools to share parameter information with external hardware and software modules. While the AAX SDK only uses the Token System indirectly, knowing how it works will provide a good understanding of how linked parameters should operate.

\hypertarget{a00905_tokenProtocol_introductionToTokens_touch}{}\doxysubsubsection{Touch}\label{a00905_tokenProtocol_introductionToTokens_touch}
Touch tokens inform the system of user interaction with a parameter. When a parameter is being touched the system knows to stop sending automation data to the plug-\/in and just use the SET value of the parameter. It is also used to tell the system when to start/stop recording new automation data.

In AAX, the touch message is sent to the host by \mbox{\hyperlink{a02185_a30fdb67042b8dc9fb42fa9023ed9cce0}{AAX\+\_\+\+IAutomation\+Delegate\+::\+Post\+Touch\+Request()}}. The most common way to call this method is via the following methods\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{\textcolor{keyword}{class\ }\mbox{\hyperlink{a02245}{AAX\_IEffectParameters}}}
\DoxyCodeLine{\{}
\DoxyCodeLine{\ \ \ \ \textcolor{keyword}{virtual}\ \mbox{\hyperlink{a00533_a4d8f69a697df7f70c3a8e9b8ee130d2f}{AAX\_Result}}\ \mbox{\hyperlink{a02049_ae82e80cbfd9cb837f8101a85f06856ba}{TouchParameter}}\ (\ \mbox{\hyperlink{a00533_a1440c756fe5cb158b78193b2fc1780d1}{AAX\_CParamID}}\ inParameterID\ );}
\DoxyCodeLine{\ \ \ \ \textcolor{keyword}{virtual}\ \mbox{\hyperlink{a00533_a4d8f69a697df7f70c3a8e9b8ee130d2f}{AAX\_Result}}\ \mbox{\hyperlink{a02049_a2caf1b7b8e2dad62cf96f144479dee60}{ReleaseParameter}}\ (\ \mbox{\hyperlink{a00533_a1440c756fe5cb158b78193b2fc1780d1}{AAX\_CParamID}}\ inParameterID\ );}
\DoxyCodeLine{\};}
\DoxyCodeLine{}
\DoxyCodeLine{\textcolor{keyword}{class\ }\mbox{\hyperlink{a02277}{AAX\_IParameter}}}
\DoxyCodeLine{\{}
\DoxyCodeLine{\ \ \ \ \textcolor{keyword}{virtual}\ \textcolor{keywordtype}{void}\ \mbox{\hyperlink{a02277_a74c71243313f9d817c8bcb77550969aa}{Touch}}\ ();\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ }
\DoxyCodeLine{\ \ \ \ \textcolor{keyword}{virtual}\ \textcolor{keywordtype}{void}\ \mbox{\hyperlink{a02277_a3d4869d9b6ec03d4f95f33f56479756f}{Release}}\ ();}
\DoxyCodeLine{\};}

\end{DoxyCode}


However, AAX plug-\/ins will rarely need to call these methods directly since the \mbox{\hyperlink{a01893}{AAX\+\_\+\+CParameter}} and \mbox{\hyperlink{a01837}{AAX\+\_\+\+CEffect\+Parameters}} implementations will automatically handle parameter touch and release tokens whenever a new value is set on the parameter by the plug-\/in.

Other clients besides the plug-\/in may touch a parameter. Since the TOUCH token can come from a control surface the touch state will actually come back to the plug-\/in via\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{\textcolor{keyword}{class\ }\mbox{\hyperlink{a02245}{AAX\_IEffectParameters}}}
\DoxyCodeLine{\{}
\DoxyCodeLine{\ \ \ \ \textcolor{keyword}{virtual}\ \mbox{\hyperlink{a00533_a4d8f69a697df7f70c3a8e9b8ee130d2f}{AAX\_Result}}\ \mbox{\hyperlink{a02049_a93483f44315bdf3adf60bf5bf773fbb8}{UpdateParameterTouch}}\ (\ \mbox{\hyperlink{a00533_a1440c756fe5cb158b78193b2fc1780d1}{AAX\_CParamID}}\ iParameterID,\ \mbox{\hyperlink{a00533_aa216506530f1d19a2965931ced2b274b}{AAX\_CBoolean}}\ iTouchState\ );}
\DoxyCodeLine{\};}

\end{DoxyCode}


This method is mainly important for \mbox{\hyperlink{a00907}{linked parameters}}.


\begin{DoxyImage}
\includegraphics[width=\textwidth,height=\textheight/2,keepaspectratio=true]{dot_aax_parameter_entities_touch_handled}
\doxyfigcaption{Touch request from a view controller, with resulting async touch update}
\end{DoxyImage}


\hypertarget{a00905_tokenProtocol_introductionToTokens_set}{}\doxysubsubsection{Set}\label{a00905_tokenProtocol_introductionToTokens_set}
SET tokens can come from many different locations\+: the plug-\/in GUI, a control surface, loading a chunk or automation playback. Eventually the value of a SET token comes into the plug-\/in and that\textquotesingle{}s when the internal value of the parameter gets updated. In AAX the SET token will be sent as a result of calling the following method\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{\textcolor{keyword}{class\ }AAX\_CParemeter<T>}
\DoxyCodeLine{\{}
\DoxyCodeLine{\ \ \ \ \textcolor{keywordtype}{void}\ SetValue\ (\ T\ newValue\ );}
\DoxyCodeLine{\};}

\end{DoxyCode}


which will be called from many other supporting methods\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{\textcolor{keyword}{class\ }\mbox{\hyperlink{a01893}{AAX\_CParameter}}<T>}
\DoxyCodeLine{\{}
\DoxyCodeLine{\ \ \ \ \textcolor{keywordtype}{bool}\ \mbox{\hyperlink{a01893_a2089ea0d243087c562ce8b1bd89a495a}{SetValueWithBool}}\ (\ \textcolor{keywordtype}{bool}\ value\ );}
\DoxyCodeLine{\ \ \ \ \textcolor{keywordtype}{bool}\ \mbox{\hyperlink{a01893_aaf45f020a267f894429b4a75ddbe9c6c}{SetValueWithInt32}}\ (\ int32\_t\ value\ );}
\DoxyCodeLine{\ \ \ \ \textcolor{keywordtype}{bool}\ \mbox{\hyperlink{a01893_ab3f589671d20c826859b4398e96ee9bb}{SetValueWithFloat}}\ (\ \textcolor{keywordtype}{float}\ value\ );}
\DoxyCodeLine{\ \ \ \ \textcolor{keywordtype}{bool}\ \mbox{\hyperlink{a01893_a7551c4071f91cb48103b5a8dda8f73eb}{SetValueWithDouble}}\ (\ \textcolor{keywordtype}{double}\ value\ );}
\DoxyCodeLine{\ \ \ \ \textcolor{keywordtype}{void}\ \mbox{\hyperlink{a01893_a9ae87f0a8655c68ac7c59bec3f476c48}{SetToDefaultValue}}\ ();}
\DoxyCodeLine{\ \ \ \ \textcolor{keywordtype}{void}\ \mbox{\hyperlink{a01893_ac4f8ae8c5ecb2cd04ebc3aa2523449f7}{SetNormalizedValue}}\ (\ \textcolor{keywordtype}{double}\ normalizedNewValue\ );}
\DoxyCodeLine{\ \ \ \ \textcolor{keywordtype}{bool}\ \mbox{\hyperlink{a01893_aa9194daefda8f6491849819fb25a73d2}{SetValueFromString}}\ (\ \textcolor{keyword}{const}\ \mbox{\hyperlink{a01933}{AAX\_CString}}\ \&\ newValueString\ );}
\DoxyCodeLine{\};}

\end{DoxyCode}


When a SET token enters the system from the GUI, control surface or automation the value comes bak to the plug-\/in via the following method\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{\textcolor{keyword}{class\ }\mbox{\hyperlink{a01837}{AAX\_CEffectParameters}}}
\DoxyCodeLine{\{}
\DoxyCodeLine{\ \ \ \ \mbox{\hyperlink{a00533_a4d8f69a697df7f70c3a8e9b8ee130d2f}{AAX\_Result}}\ \mbox{\hyperlink{a01837_aeff79c1e5cc6b65c7ed21d9912f87caf}{UpdateParameterNormalizedValue}}\ (\ \mbox{\hyperlink{a00533_a1440c756fe5cb158b78193b2fc1780d1}{AAX\_CParamID}}\ iParameterID,\ \textcolor{keywordtype}{double}\ aValue,\ \mbox{\hyperlink{a00443_a30be0398faf20c6b121239eb9399f3f7}{AAX\_EUpdateSource}}\ inSource);}
\DoxyCodeLine{\};}

\end{DoxyCode}


At this point the internal contents of the plug-\/in are set.


\begin{DoxyImage}
\includegraphics[width=\textwidth,height=\textheight/2,keepaspectratio=true]{dot_aax_parameter_entities_update}
\doxyfigcaption{Set token asynchronously changes state of the parameter data}
\end{DoxyImage}


\hypertarget{a00905_tokenProtocol_introductionToTokens_update}{}\doxysubsubsection{Update}\label{a00905_tokenProtocol_introductionToTokens_update}
An update token is generated when the internal value of a parameter has been set. GUIs and control surfaces listen for UPDATE tokens to update the displayed values. In AAX the UPDATE token is sent by calling the following method\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{\textcolor{keyword}{class\ }\mbox{\hyperlink{a01893}{AAX\_CParameter}}<T>}
\DoxyCodeLine{\{}
\DoxyCodeLine{\ \ \ \ \textcolor{keywordtype}{void}\ \mbox{\hyperlink{a01893_a8a70b3c8bcff486c18e9a6e5c8ce4dda}{UpdateNormalizedValue}}\ (\ \textcolor{keywordtype}{double}\ newNormalizedValue\ );}
\DoxyCodeLine{\};}

\end{DoxyCode}


All views of the parameter are then asynchronously notified that the value has changed. The plug-\/in GUI is notified via a call to \mbox{\hyperlink{a02045_a45b468fef806611581f748af9301ab4d}{AAX\+\_\+\+IEffect\+GUI\+::\+Parameter\+Updated()}}.


\begin{DoxyImage}
\includegraphics[width=\textwidth,height=\textheight/2,keepaspectratio=true]{dot_aax_parameter_entities_curvalue}
\doxyfigcaption{Update token triggers async updates to all views}
\end{DoxyImage}
 

 \hypertarget{a00905_tokenProtocol_standardTokenOperation}{}\doxysubsection{Basic Token Operation}\label{a00905_tokenProtocol_standardTokenOperation}
The lists below indicate how the system works in a few different standard update scenarios. To enable logging for these events set {\ttfamily DTF\+\_\+\+AUTOMATION=file@DTP\+\_\+\+LOW} in the \mbox{\hyperlink{a00917}{Digi\+Trace}} configuration file. For more detailed information about the sequence of calls used to update parameters in different situations, see \mbox{\hyperlink{a00906}{Basic parameter update sequences}}.

\hypertarget{a00905_tokenProtocol_standardTokenOperation_userEditing}{}\doxysubsubsection{User Editing}\label{a00905_tokenProtocol_standardTokenOperation_userEditing}

\begin{DoxyEnumerate}
\item User clicks on a parameter in the GUI or grabs a parameter on the controls surface. A TOUCH token should be sent at this point.
\item The user changes the parameter from the GUI or controls surface. A SET token should be sent at this point.
\item The SET token goes into the system and comes back to the plugin via Update\+Parameter\+Normalized\+Value().
\item The plug-\/in updates it\textquotesingle{}s internal state and sends an UPDATE token.
\item Repeat steps 2-\/4 while changing the parameter.
\item The user lets go of the GUI or controls surface. A TOUCH token with the released state should be sent.
\end{DoxyEnumerate}

\hypertarget{a00905_tokenProtocol_standardTokenOperation_automationPlayback}{}\doxysubsubsection{Automation Playback}\label{a00905_tokenProtocol_standardTokenOperation_automationPlayback}

\begin{DoxyEnumerate}
\item The SET token comes from the automation system and enters the plugin via Update\+Parameter\+Normalized\+Value().
\item The plug-\/in updates it\textquotesingle{}s internal state and sends an UPDATE token.
\item Repeat steps 1-\/2 while playing back automation.
\end{DoxyEnumerate}

\hypertarget{a00905_tokenProtocol_standardTokenOperation_chunkRestoring}{}\doxysubsubsection{Chunk Restoring}\label{a00905_tokenProtocol_standardTokenOperation_chunkRestoring}

\begin{DoxyEnumerate}
\item Plug-\/in loads the chunk.
\item The plug-\/in sets every parameters value. Another thing to note is that the
\item Set\+Value() method also contains Touch() and Release() calls. So, while setting every parameter there is a combination of TOUCH and SET tokens sent to the system.
\item The SET tokens comes back to the plugin via Update\+Parameter\+Normalized\+Value().
\item The plug-\/in updates it\textquotesingle{}s internal state and sends out UPDATE tokens.
\end{DoxyEnumerate}

 Collaboration diagram for Token protocol\+:
\nopagebreak
\begin{figure}[H]
\begin{center}
\leavevmode
\includegraphics[width=295pt]{a00905}
\end{center}
\end{figure}
