\hypertarget{cue_8c}{
\section{cue.c File Reference}
\label{cue_8c}\index{cue.c@{cue.c}}
}
Routines that act upon the cue structure. 

{\tt \#include \char`\"{}LCI/LCI\_\-msgs.h\char`\"{}}\par
{\tt \#include \char`\"{}cue\_\-p.h\char`\"{}}\par
{\tt \#include \char`\"{}LEM/msg\_\-macros.h\char`\"{}}\par
{\tt \#include \char`\"{}MSG/MSG\_\-pubdefs.h\char`\"{}}\par
{\tt \#include \char`\"{}PBS/MBA.h\char`\"{}}\par
{\tt \#include \char`\"{}PBS/WUT.h\char`\"{}}\par
{\tt \#include \char`\"{}PBS/SEM.h\char`\"{}}\par
{\tt \#include $<$string.h$>$}\par
\subsection*{Functions}
\begin{CompactItemize}
\item 
static WUT\_\-cb\_\-status \hyperlink{cue_8c_aba4b9aa5e0b5190c6405dd80b750066}{cue\_\-wut\_\-cb} (void $\ast$prm, WUT\_\-tmr $\ast$wut)
\begin{CompactList}\small\item\em Timer callback. \item\end{CompactList}\item 
\hyperlink{struct__LCI__cue}{LCI\_\-cue} $\ast$ \hyperlink{cue_8c_31b61a3f852fcd8c2cd9dd36c5e682a4}{LCI\_\-newCue} (void)
\begin{CompactList}\small\item\em Create a new cue. \item\end{CompactList}\item 
unsigned \hyperlink{cue_8c_06983ef6516cc9e991d7baf115e9fffd}{LCI\_\-deleteCue} (\hyperlink{struct__LCI__cue}{LCI\_\-cue} $\ast$cue)
\begin{CompactList}\small\item\em Delete a cue. \item\end{CompactList}\item 
void \hyperlink{cue_8c_68e03f7db1f5486592fd6a56c74704f3}{LCI\_\-clearCue} (\hyperlink{struct__LCI__cue}{LCI\_\-cue} $\ast$cue)
\begin{CompactList}\small\item\em Clear a cue. \item\end{CompactList}\item 
unsigned \hyperlink{cue_8c_5542d4f986974bee670ebb3cf8adeeda}{LCI\_\-waitCue} (\hyperlink{struct__LCI__cue}{LCI\_\-cue} $\ast$cue, unsigned timeout)
\begin{CompactList}\small\item\em Wait for a cue to complete or time out. \item\end{CompactList}\item 
void \hyperlink{cue_8c_9e35d61657eb30d22f26d68392f52e05}{LCI\_\-signalCue} (\hyperlink{struct__LCI__cue}{LCI\_\-cue} $\ast$cue)
\begin{CompactList}\small\item\em Signal cue completion. \item\end{CompactList}\item 
void \hyperlink{cue_8c_21e53f5c9579985fb457442bee8c8c4e}{LCI\_\-clearCueCounts} (\hyperlink{struct__LCI__cue}{LCI\_\-cue} $\ast$cue)
\begin{CompactList}\small\item\em Clear cue counters. \item\end{CompactList}\item 
void \hyperlink{cue_8c_d425faf1408ffb559d469279fe44722e}{LCI\_\-getCueCounts} (\hyperlink{struct__LCI__cue}{LCI\_\-cue} $\ast$cue, unsigned int $\ast$nWait, unsigned int $\ast$nSignal, unsigned int $\ast$nTimeout)
\begin{CompactList}\small\item\em Get cue counters. \item\end{CompactList}\end{CompactItemize}


\subsection{Detailed Description}
Routines that act upon the cue structure. 

\begin{Desc}
\item[Author:]James Swain \& Owen Saxton\end{Desc}
The order of calling the functions presented here should be LCI\_\-newCue LCI\_\-clearCue --$>$ LCI\_\-waitCue --$>$ In another task --$>$ LCI\_\-signalCue : Repeat as necessary : LCI\_\-deleteCue

\begin{Desc}
\item[Id]\end{Desc}


\subsection{Function Documentation}
\hypertarget{cue_8c_aba4b9aa5e0b5190c6405dd80b750066}{
\index{cue.c@{cue.c}!cue_wut_cb@{cue\_\-wut\_\-cb}}
\index{cue_wut_cb@{cue\_\-wut\_\-cb}!cue.c@{cue.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}WUT\_\-cb\_\-status cue\_\-wut\_\-cb (void $\ast$ {\em prm}, WUT\_\-tmr $\ast$ {\em wut})\hspace{0.3cm}{\tt  \mbox{[}static\mbox{]}}}}
\label{cue_8c_aba4b9aa5e0b5190c6405dd80b750066}


Timer callback. 

This routine is called back when the wake-up timer goes off. It sets the end state to LCI\_\-CUE\_\-TIMEDOUT and gives the semaphore

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em prm}]Pointer to the LCI\_\-cue structure\item[{\em wut}]Pointer to the wake-up timer\end{description}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em WUT\_\-K\_\-STATE\_\-CHANGE\_\-YES}]\end{description}
\end{Desc}
\hypertarget{cue_8c_68e03f7db1f5486592fd6a56c74704f3}{
\index{cue.c@{cue.c}!LCI_clearCue@{LCI\_\-clearCue}}
\index{LCI_clearCue@{LCI\_\-clearCue}!cue.c@{cue.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void LCI\_\-clearCue ({\bf LCI\_\-cue} $\ast$ {\em cue})}}
\label{cue_8c_68e03f7db1f5486592fd6a56c74704f3}


Clear a cue. 

This routine puts the cue into a known cleared state, ready for the next wait.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em cue}]Pointer to an allocated, initialised cue structure (from LCI\_\-newCue) \end{description}
\end{Desc}
\hypertarget{cue_8c_21e53f5c9579985fb457442bee8c8c4e}{
\index{cue.c@{cue.c}!LCI_clearCueCounts@{LCI\_\-clearCueCounts}}
\index{LCI_clearCueCounts@{LCI\_\-clearCueCounts}!cue.c@{cue.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void LCI\_\-clearCueCounts ({\bf LCI\_\-cue} $\ast$ {\em cue})}}
\label{cue_8c_21e53f5c9579985fb457442bee8c8c4e}


Clear cue counters. 

This routine zeroes the counts of waits, signals and timeouts.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em cue}]Pointer to a cue being used. \end{description}
\end{Desc}
\hypertarget{cue_8c_06983ef6516cc9e991d7baf115e9fffd}{
\index{cue.c@{cue.c}!LCI_deleteCue@{LCI\_\-deleteCue}}
\index{LCI_deleteCue@{LCI\_\-deleteCue}!cue.c@{cue.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}unsigned LCI\_\-deleteCue ({\bf LCI\_\-cue} $\ast$ {\em cue})}}
\label{cue_8c_06983ef6516cc9e991d7baf115e9fffd}


Delete a cue. 

This routine destroys the semaphore and wake-up timer and then frees the memory associated with the cue structure

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em cue}]Pointer to an initialised cue structure (make sure that it is not currently running!)\end{description}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em LCI\_\-SUCCESS}]if all goes well \item[{\em LCI\_\-WUTDFAIL}]if the wake-up timer could not be destroyed, because it was in a bad state \end{description}
\end{Desc}
\hypertarget{cue_8c_d425faf1408ffb559d469279fe44722e}{
\index{cue.c@{cue.c}!LCI_getCueCounts@{LCI\_\-getCueCounts}}
\index{LCI_getCueCounts@{LCI\_\-getCueCounts}!cue.c@{cue.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void LCI\_\-getCueCounts ({\bf LCI\_\-cue} $\ast$ {\em cue}, unsigned int $\ast$ {\em nWait}, unsigned int $\ast$ {\em nSignal}, unsigned int $\ast$ {\em nTimeout})}}
\label{cue_8c_d425faf1408ffb559d469279fe44722e}


Get cue counters. 

This routine obtains the counts of waits, signals and timeouts since the last time the cue was cleared.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em cue}]Pointer to a cue being used.\item[{\em nWait}]Address of an integer to receive the number of wait calls, or NULL if not needed.\item[{\em nSignal}]Address of an integer to receive the number of signal calls, or NULL if not needed.\item[{\em nTimeout}]Address of an integer to receive the number of timeouts, or NULL if not needed. \end{description}
\end{Desc}
\hypertarget{cue_8c_31b61a3f852fcd8c2cd9dd36c5e682a4}{
\index{cue.c@{cue.c}!LCI_newCue@{LCI\_\-newCue}}
\index{LCI_newCue@{LCI\_\-newCue}!cue.c@{cue.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}{\bf LCI\_\-cue}$\ast$ LCI\_\-newCue (void)}}
\label{cue_8c_31b61a3f852fcd8c2cd9dd36c5e682a4}


Create a new cue. 

This routine allocates memory for the cue structure then creates the timer and semaphore to be held by the structure

\begin{Desc}
\item[Returns:]Pointer to an allocated and initialised cue structure, or NULL if there is an error. \end{Desc}
\hypertarget{cue_8c_9e35d61657eb30d22f26d68392f52e05}{
\index{cue.c@{cue.c}!LCI_signalCue@{LCI\_\-signalCue}}
\index{LCI_signalCue@{LCI\_\-signalCue}!cue.c@{cue.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void LCI\_\-signalCue ({\bf LCI\_\-cue} $\ast$ {\em cue})}}
\label{cue_8c_9e35d61657eb30d22f26d68392f52e05}


Signal cue completion. 

This routine signals completion by setting the end state to LCI\_\-CUE\_\-SIGNALED and giving the semaphore

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em cue}]Pointer to a cue that is being waited upon \end{description}
\end{Desc}
\hypertarget{cue_8c_5542d4f986974bee670ebb3cf8adeeda}{
\index{cue.c@{cue.c}!LCI_waitCue@{LCI\_\-waitCue}}
\index{LCI_waitCue@{LCI\_\-waitCue}!cue.c@{cue.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}unsigned LCI\_\-waitCue ({\bf LCI\_\-cue} $\ast$ {\em cue}, unsigned {\em timeout})}}
\label{cue_8c_5542d4f986974bee670ebb3cf8adeeda}


Wait for a cue to complete or time out. 

This routine starts the wake-up timer and takes the semaphore

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em cue}]Pointer to an allocated, initialised cue structure (from LCI\_\-newCue)\item[{\em timeout}]Time, in microseconds, until the call times out.\end{description}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em LCI\_\-CUE\_\-SIGNALED}]Another task called signal \item[{\em LCI\_\-CUE\_\-TIMEDOUT}]If the timer expired before the cue was signalled. \item[{\em LCI\_\-CUE\_\-FAILED}]Timer failed to start (because of incorrect state) \end{description}
\end{Desc}
