Function GetSamples

TMSi Data Acquisition SDK

 
TMS International BV

GetSamples

LONG GetSamples( 
IN HANDLE Handle,
OUT PULONG SampleBuffer,
IN ULONG Size
);

Parameters

Handle
   
Handle of the library

SampleBuffer
   Pointer to a user-allocated buffer where this function will store the samples

Size
   Size of this buffer in bytes

    

Return Value

Returns the total number of bytes put into the user-allocated buffer. Return 0 if no new data is available. Returns a negative value (which is the error code) if an error occurred.

 

Comments

This function is used to write one or more samples to the user-allocated buffer. A pointer to a buffer allocated by the application and the size of this buffer in bytes are used as input parameters. The size of the input buffer in samples should be larger or the same as the size of the internal buffer as previously set using the SetSignalBuffer function.

The driver will fill the user-allocated buffer with the available samples. The number of samples returned depends on the size of this user-allocated buffer and the amount of samples available. One sample means one conversion result from each channel of the device. All samples read by the application are no longer available from the driver. Use the function GetSignalFormat to interpret the sample data returned by the Getsample function. The values are always stored in the buffer as 32-bit numbers, i.e. they need 4 bytes each, regardless of the channel size as given by the GetSignalformat.

Example: a device has 6 input signals, while running at a sample rate of 100 Hz. As stated before, each signal needs 4 bytes for storing the conversion result. The buffer must be at least 6*4 = 24 bytes for one sample. When acquiring 100 samples, you need a buffer of 6*4*100 = 2400 bytes.


When a channel of type EXG, BIP, AUX is not connected or out-of-range, the value returned is 0x80000000.

The only allowed function after this call is the Stop() function.

 

Warning

When using Bluetooth or WLAN, do NOT use the Windows OS functions to scan for other Bluetooth or WLAN frontends. The scan will access the Bluetooth or WLAN dongle,  and disturb the received signal from the sampling frontend, with loss of samples as a result.

The GetSamples function should be called at least 16 times per second. If you prefer to call it less often, you have to make sure that your defined buffer is large enough to store all incoming samples.

When GetSamples() returns a negative value, the application should try to stop the frontend by calling Stop() and after that calling Close(). Then the application should try to reconnect using Open().





 Also see

GetBufferInfo, GetSignalFormat