/***
 *** CapsClientApi.h ---- Capacisense monitor client DLL API functions
 *** Copyright (c), Tyco Thermal Systems, Ltd., 2009
 *** Copyright (c), Engineering Design and Analysis Solutions, Inc., 2009
 ***/
#ifndef __CAPSCLIENTAPI_H_INCLUDED__
#define __CAPSCLIENTAPI_H_INCLUDED__

/**\file
 * Network client API functions for retrieving data from a running CapaciSense acquisition server in user written
 * applications. The API also supports opening CapaciSense data files and streaming data from them using the same
 * calls. The functions in this file are distributed as a DLL that can be linked with a variety of languages
 * such as C, C++, LabView, Matlab, Visual Basic, etc.
 */

#if     defined(_NI_mswin32_)
#ifndef _MSC_VER
#define _MSC_VER
#endif
#ifndef _WIN32
#define _WIN32
#endif
#endif

#if	defined(_WIN32) || defined(_WIN64)
#ifndef DLLEXPORT
#define DLLEXPORT	__declspec(dllexport)     /**< WIN32 DLL interface stuff */
#endif
#ifndef STDCALL
#define STDCALL		_stdcall                  /**< WIN32 DLL interface stuff */
#endif
#else
#ifndef DLLEXPORT
#define DLLEXPORT                                 /**< WIN32 DLL interface stuff */
#endif
#ifndef STDCALL
#define STDCALL                                   /**< WIN32 DLL interface stuff */
#endif
#endif
#ifndef C_EXTERN
#ifdef	__cplusplus
#define C_EXTERN	extern "C"                /**< C++ linkage */
#else
#define C_EXTERN	extern                    /**< C++ linkage */
#endif
#endif

/**
 * Establishes a connection to a running CapaciSense acquisition system. Once the connection is established
 * the client starts receiving data continuously in the background. The received data is used to update a
 * "current value" table. User code can retrieve the current values at its own pace. If the client retrieves
 * data at a slower rate than it is received then the receivbed revolutions will be averaged between data
 * retrieval calls.
 * @param host The name of the computer to which to connect. This should be any server host of a running CapaciSense
 * configuration.
 * @param rate The update rate in seconds with which the servers will send data packets to the client.
 * @return A "handle" that should be passed to subsequent calls. The handle value is non zero upon successful connection,
 * zero otherwise.
 */
C_EXTERN unsigned long DLLEXPORT STDCALL CapsClientConnect(const char *host, double rate);

/**
 * Opens one or more Capacisense data files. If multiple files are opened they will be played in proper acqusition time order.
 * @param name The name of the file to open. Wildcards are accepted, in this case all files matching the pattern are opened.
 * A directory name is also accepted, in this case the latest file and all matching configuration previous files in the
 * given directory are opened.
 * @return A "handle" that should be passed to subsequent calls. The handle value is non zero upon successful connection,
 * zero otherwise.
 */
C_EXTERN unsigned long DLLEXPORT STDCALL CapsClientOpen(const char *name);

/**
 * Destroys the connection to the CapaciSense acquisition system.
 * @param handle The handle value as returned by CapsClientConnect() or CapsClientOpen().
 */
C_EXTERN void DLLEXPORT STDCALL CapsClientClose(unsigned long handle);

/**
 * Setup retrieval function.
 * @param handle The handle value as returned by CapsClientConnect() or CapsClientOpen().
 * @return The number of engine stages in the configuration.
 */
C_EXTERN int DLLEXPORT STDCALL CapsClientNumStages(unsigned long handle);

/**
 * Setup retrieval function.
 * @param handle The handle value as returned by CapsClientConnect() or CapsClientOpen().
 * @param stage The stage index. Must be in the range of [0 ... return value of CapsClientNumStages() - 1]
 * @return The blade count on the indexed stage of the configuration.
 */
C_EXTERN int DLLEXPORT STDCALL CapsClientNumStageBlades(unsigned long handle, int stage);

/**
 * Setup retrieval function.
 * @param handle The handle value as returned by CapsClientConnect() or CapsClientOpen().
 * @param stage The stage index. Must be in the range of [0 ... return value of CapsClientNumStages() - 1]
 * @return The number of probes on the indexed stage of the configuration.
 */
C_EXTERN int DLLEXPORT STDCALL CapsClientNumStageProbes(unsigned long handle, int stage);

/**
 * Setup retrieval function.
 * @param handle The handle value as returned by CapsClientConnect() or CapsClientOpen().
 * @param stage The stage index. Must be in the range of [0 ... return value of CapsClientNumStages() - 1]
 * @return The diameter of the indexed stage of the configuration.
 */
C_EXTERN double DLLEXPORT STDCALL CapsClientStageDiameter(unsigned long handle, int stage);

/**
 * Setup retrieval function. Copies the radial locations of all probes on an engine stage into a vector.
 * @param handle The handle value as returned by CapsClientConnect() or CapsClientOpen().
 * @param stage The stage index. Must be in the range of [0 ... return value of CapsClientNumStages() - 1]
 * @param nangles The size of the angles array. Should be big enough to accommodate all the probes
 * reported by CapsClientNumStageProbes() for this stage. If a smaller array is passed only the first
 * nangles values are copied.
 * @param angles Array into which each probe's radial location is copied.
 */
C_EXTERN void DLLEXPORT STDCALL CapsClientStageProbeLocations(unsigned long handle, int stage, int nangles, double angles[]);

/**
 * Setup retrieval function. Retrieves the name of a stage
 * @param handle The handle value as returned by CapsClientConnect() or CapsClientOpen().
 * @param stage The stage index. Must be in the range of [0 ... return value of CapsClientNumStages() - 1]
 * @param name The character buffer into which the name will be copied. (Zero terminated "C" string.)
 * @param maxsize The maximum length of the character buffer for the name.
 */
C_EXTERN void DLLEXPORT STDCALL CapsClientStageName(unsigned long handle, int stage, char name[], int maxsize);

/**
 * Setup retrieval function. Retrieves the name of a probe
 * @param handle The handle value as returned by CapsClientConnect() or CapsClientOpen().
 * @param stage The stage index. Must be in the range of [0 ... return value of CapsClientNumStages() - 1]
 * @param probe The index of the probe for which the name is to be retrieved. Must be in the range of
 * [0 ... return value of CapsClientNumStageProbes() - 1]
 * @param name The character buffer into which the name will be copied. (Zero terminated "C" string.)
 * @param maxsize The maximum length of the character buffer for the name.
 */
C_EXTERN void DLLEXPORT STDCALL CapsClientProbeName(unsigned long handle, int stage, int probe, char name[], int maxsize);

/**
 * Retrieves the last received full revolution's data from the DLL's receive buffer and locks it into the "current value"
 * buffer for later "disassembly" with the rev data processing DLL entries (below). If the handle was created by opening
 * files, then a set of data blocks is read and stored for further processing. If no data is available the function will
 * return immediately with a zero return value. In this case the error argument should be examined. If error is zero, then
 * there is simply no new data available since the last call. If error is non-zero then some kind of error occurred (most
 * likely the Capacisense acquisition system stopped). File mode never returns an error condition, if the handle is zero
 * that means that the end of the file (or all opened files) has been reached.
 * @param handle The handle value as returned by CapsClientConnect() or CapsClientOpen().
 * @param wait If positive the call will block for the given time (in seconds) or until new data is available. If zero
 * the call returns immediately. If negative the call waits until new data is available (or an error occurs). This parameter
 * is ignored in file replay mode.
 * @param error Set when the no data condition is caused by some kind of error.
 * @return A handle to the buffered data. Use this for subsequenct data retrieval calls. 0 is returned when no data is
 * available. This handle is valid until the next CapsClientGetNextRev or CapsClientClose call.
 */
C_EXTERN unsigned long DLLEXPORT STDCALL CapsClientGetNextRev(unsigned long handle, double wait, int *error);

/**
 * Retrieve information from the current locked revolutions's data. 
 * @param rhandle The handle to the currently processed revolution's data as returned by CapsClientGetNextRev().
 * @return The current revolution number. Revolutions are numbered from the start of the acquistion.
 */
C_EXTERN unsigned long DLLEXPORT STDCALL CapsClientRevNumber(unsigned long rhandle);

/**
 * Retrieve information from the current locked revolutions's data.
 * @param rhandle The handle to the currently processed revolution's data as returned by CapsClientGetNextRev().
 * @param speed Receives the current engine speed (in RPM units) upon return.
 * @return A flag indicating whether the system is acquiring data synchronized with engine revolutions (locked) or not.
 */
C_EXTERN int DLLEXPORT STDCALL CapsClientRevSpeed(unsigned long rhandle, double *speed);

/**
 * Retrieve information from the current locked revolutions's data. This function copies the RMS clearance values
 * of all blades on an engine stage into a vector.
 * @param rhandle The handle to the currently processed revolution's data as returned by CapsClientGetNextRev().
 * @param stage The stage index. Must be in the range of [0 ... return value of CapsClientNumStages() - 1]
 * @param probe The index of the probe for which the data is to be retrieved. Must be in the range of
 * [0 ... return value of CapsClientNumStageProbes() - 1]
 * @return The averege RMS clearance for the entire revolution measured by the probe.
 */
C_EXTERN double DLLEXPORT STDCALL CapsClientRevRmsClearance(unsigned long rhandle, int stage, int probe);

/**
 * Retrieve information from the current locked revolutions's data. This function copies the DNS clearance values
 * of all blades on an engine stage into a vector.
 * @param rhandle The handle to the currently processed revolution's data as returned by CapsClientGetNextRev().
 * @param stage The stage index. Must be in the range of [0 ... return value of CapsClientNumStages() - 1]
 * @param probe The index of the probe for which the data is to be retrieved. Must be in the range of
 * [0 ... return value of CapsClientNumStageProbes() - 1]
 * @param ndata The size of the ndata array. Should be big enough to accommodate all the blades
 * reported by CapsClientNumStageBlades() for this stage. If a smaller array is passed only the first
 * ndata values are copied.
 * @param data Array into which each blade's data is copied.
 */
C_EXTERN void DLLEXPORT STDCALL CapsClientRevDnsClearance(unsigned long rhandle, int stage, int probe, int ndata, double data[]);

/**
 * Retrieve information from the current locked revolutions's data. This function copies the deflection (distance between the blade tip's
 * measured and nominal radial locations) values of all blades on an engine stage into a vector.
 * @param rhandle The handle to the currently processed revolution's data as returned by CapsClientGetNextRev().
 * @param stage The stage index. Must be in the range of [0 ... return value of CapsClientNumStages() - 1]
 * @param probe The index of the probe for which the data is to be retrieved. Must be in the range of
 * [0 ... return value of CapsClientNumStageProbes() - 1]
 * @param ndata The size of the ndata array. Should be big enough to accommodate all the blades
 * reported by CapsClientNumStageBlades() for this stage. If a smaller array is passed only the first
 * ndata values are copied.
 * @param data Array into which each blade's data is copied.
 */
C_EXTERN void DLLEXPORT STDCALL CapsClientRevDeflection(unsigned long rhandle, int stage, int probe, int ndata, double data[]);

/**
 * Retrieve information from the current locked revolutions's data. This function copies the BPS waveform into a user supplied buffer.
 * @param rhandle The handle to the currently processed revolution's data as returned by CapsClientGetNextRev().
 * @param stage The stage index. Must be in the range of [0 ... return value of CapsClientNumStages() - 1]
 * @param probe The index of the probe for which the data is to be retrieved. Must be in the range of
 * [0 ... return value of CapsClientNumStageProbes() - 1]
 * @param data array into which the probe's time domain data is copied (scaled to volts). One revolution is always resampled to 4096 points.
 * @return A flag indicating whether scope data was available or not. Note that scope data may ve received less frequently than 
 * clearance data so even though CapsClientGetNextRev() may lock a revolution's data, the scope record may not be available
 * for this revolution.
 */
C_EXTERN int DLLEXPORT STDCALL CapsClientRevScopeData(unsigned long rhandle, int stage, int probe, float data[4096]);

/**
 * Retrieve information from the current locked revolutions's data. 
 * @param rhandle The handle to the currently processed revolution's data as returned by CapsClientGetNextRev().
 * @param stage The stage index. Must be in the range of [0 ... return value of CapsClientNumStages() - 1]
 * @param probe The index of the probe for which the data is to be retrieved. Must be in the range of
 * [0 ... return value of CapsClientNumStageProbes() - 1]
 * @param osc Receives current oscillator power status value upon return
 * @param gain Receives current demodulator gain status value upon return
 * @param ac Receives current demodulator coupling value upon return
 * @param filter Receives current demodulator filter setting upon return
 * @param status Receives current PLL status value upon return
 * @param range Receives current A/D range setting (in millivolts) upon return
 * @return A flag indicating the current calibration status of the probe, i.e. whether clearance data is valid or not.
 */
C_EXTERN int DLLEXPORT STDCALL CapsClientRevProbeStatus(unsigned long rhandle, int stage, int probe, int *osc, int *gain, int *ac, int *filter, int *status, int *range);

#endif	/* whole file */
