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)