NAME¶
egd_get_data - peek buffered data
SYNOPSIS¶
#include <eegdev.h>
ssize_t egd_get_available(struct eegdev* dev);
ssize_t egd_get_data(struct eegdev* dev, size_t
ns, ...);
DESCRIPTION¶
egd_get_available() returns the number of samples that have been buffered
by the device referenced by
dev and that have not been read yet.
egd_get_data() peeks the
ns next samples from the buffered data
acquired by the device referenced by
dev and fills the arrays provided
in the variable list of arguments with the obtained data. If all requested
samples have been already acquired, the function returns immediately.
Otherwise, the call blocks until the requested data is available, the
acquisition stops or a problem occurs. In the last two cases, the data read
may be less than requested.
The arrays provided in the variable list of argument are filled following the
formats specified by previous call to
egd_acq_setup(3). In particular,
the number of arrays supplied in the variable list of argument and their size
should be consistent with the number of arrays and strides specified by the
call to
egd_acq_setup(3).
RETURN VALUE¶
egd_get_available() returns the number of unread samples in case of
succes. Otherwise, -1 is returned and
errno is set accordingly.
In case of success,
egd_get_data() returns the number of read samples
(which can be less than the requested number). Otherwise, -1 is returned and
errno is set accordingly.
ERRORS¶
egd_get_available() and
egd_get_data() will fail if:
- EINVAL
- dev is NULL.
- ENOMEM
- The internal ringbuffer of the device referenced by dev is
full.
- EAGAIN
- The underlying hardware referenced by dev has encountered a loss of
connection, maybe due some cable disconnected or a power switch set to
off.
- EIO
- The underlying hardware referenced by dev has encountered a loss of
synchronization for an unknown reason.
NOTES¶
Please be aware that the user has no obligation to make all the calls to
egd_get_data() and
egd_get_available() during the acquisition.
He can also peform some of them after the acquisition which will correspond to
get the remaining buffered data.
For example, it might happened that a user want to wait for an certain external
event to occur before stopping the acquisition. In this situation, the usual
workflow would be to start the acquisition, get regurlarly some data while
scanning the event to occur. When this happens, the acquisition is immediately
stopped. However at the moment of stopping the acquisition, there might still
be some buffered data which could be important. Calling
egd_get_available() after
egd_stop(3) would then return the size
of the remaining data that could be obtained with
egd_get_data().
EXAMPLE¶
#define NEEG 8
#define NTRI 1
#define NS 4
int ns_tot;
ssize_t ns_read;
float eegarr[NEEG*NS];
int32_t triarr[NTRI*NS];
struct grpconf grp[2];
unsigned int strides[2];
/* Assume that a device has been successfully opened, i.e. there
is a valid 'dev' variable of type struct eegdev* */
strides[0] = NEEG*sizeof(float);
strides[1] = NTRI*sizeof(int32_t);
grp[0].sensortype = egd_sensor_type("eeg");
grp[0].index = 0;
grp[0].iarray = 0;
grp[0].arr_offset = 0;
grp[0].nch = NEEG;
grp[0].datatype = EGD_FLOAT;
grp[1].sensortype = egd_sensor_type("trigger");
grp[1].index = 0;
grp[1].iarray = 1;
grp[1].arr_offset = 0;
grp[1].nch = NTRI;
grp[1].datatype = EGD_INT32;
/* Setup how to get the data */
egd_acq_setup(dev, 2, strides, 2, grp);
/* Start the acquisition.
From now, all incoming samples will be buffered */
egd_start(dev);
ns_tot = 0;
while (ns_tot < 1000) {
/* Get the data */
ns_read = egd_get_data(dev, NS, eegarr, triarr);
if (ns_read < 0) {
/* Handle failure */
}
ns_tot += ns_read;
/* do something with the new data */
}
/* Stop the acquisition, i.e. no new data is buffered */
egd_stop(dev);
SEE ALSO¶
egd_acq_setup(3),
egd_start(3),
egd_stop(3)