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)

EPFL                                                  2010                                       EGD_GET_DATA(3)