egd_get_available(3)

1EGD_GET_DATA(3)              EEGDEV library manual             EGD_GET_DATA(3)
2
3
4

NAME

6       egd_get_data - peek buffered data
7

SYNOPSIS

9       #include <eegdev.h>
10
11       ssize_t egd_get_available(struct eegdev* dev);
12       ssize_t egd_get_data(struct eegdev* dev, size_t ns, ...);
13

DESCRIPTION

15       egd_get_available()  returns  the  number  of  samples  that  have been
16       buffered by the device referenced by dev and that have  not  been  read
17       yet.
18
19       egd_get_data()  peeks  the  ns  next  samples  from  the  buffered data
20       acquired by the device referenced by dev and fills the arrays  provided
21       in  the  variable  list  of  arguments  with  the obtained data. If all
22       requested samples have been  already  acquired,  the  function  returns
23       immediately.  Otherwise,  the  call  blocks until the requested data is
24       available, the acquisition stops or a problem occurs. In the  last  two
25       cases, the data read may be less than requested.
26
27       The arrays provided in the variable list of argument are filled follow‐
28       ing the formats specified by previous call to egd_acq_setup(3). In par‐
29       ticular, the number of arrays supplied in the variable list of argument
30       and their size should be consistent  with  the  number  of  arrays  and
31       strides specified by the call to egd_acq_setup(3).
32

RETURN VALUE

34       egd_get_available()  returns  the  number  of unread samples in case of
35       succes. Otherwise, -1 is returned and errno is set accordingly.
36
37       In case of success, egd_get_data() returns the number of  read  samples
38       (which  can  be  less  than  the  requested  number).  Otherwise, -1 is
39       returned and errno is set accordingly.
40

ERRORS

42       egd_get_available() and egd_get_data() will fail if:
43
44       EINVAL dev is NULL.
45
46       ENOMEM The internal ringbuffer of the device referenced by dev is full.
47
48       EAGAIN The underlying hardware referenced by dev has encountered a loss
49              of  connection,  maybe  due  some  cable disconnected or a power
50              switch set to off.
51
52       EIO    The underlying hardware referenced by dev has encountered a loss
53              of synchronization for an unknown reason.
54

NOTES

56       Please  be  aware that the user has no obligation to make all the calls
57       to egd_get_data() and egd_get_available() during the  acquisition.   He
58       can  also  peform  some of them after the acquisition which will corre‐
59       spond to get the remaining buffered data.
60
61       For example, it might happened that a user want to wait for an  certain
62       external event to occur before stopping the acquisition. In this situa‐
63       tion, the usual  workflow  would  be  to  start  the  acquisition,  get
64       regurlarly  some data while scanning the event to occur. When this hap‐
65       pens, the acquisition is immediately stopped. However at the moment  of
66       stopping the acquisition, there might still be some buffered data which
67       could be  important.   Calling  egd_get_available()  after  egd_stop(3)
68       would then return the size of the remaining data that could be obtained
69       with egd_get_data().
70

EXAMPLE

72              #define NEEG   8
73              #define NTRI   1
74              #define NS     4
75
76              int ns_tot;
77              ssize_t ns_read;
78              float eegarr[NEEG*NS];
79              int32_t triarr[NTRI*NS];
80              struct grpconf grp[2];
81              unsigned int strides[2];
82
83              /* Assume that a device has been successfully opened, i.e. there
84              is a valid 'dev' variable of type struct eegdev* */
85
86              strides[0] = NEEG*sizeof(float);
87              strides[1] = NTRI*sizeof(int32_t);
88
89              grp[0].sensortype = egd_sensor_type("eeg");
90              grp[0].index = 0;
91              grp[0].iarray = 0;
92              grp[0].arr_offset = 0;
93              grp[0].nch = NEEG;
94              grp[0].datatype = EGD_FLOAT;
95              grp[1].sensortype = egd_sensor_type("trigger");
96              grp[1].index = 0;
97              grp[1].iarray = 1;
98              grp[1].arr_offset = 0;
99              grp[1].nch = NTRI;
100              grp[1].datatype = EGD_INT32;
101
102              /* Setup how to get the data */
103              egd_acq_setup(dev, 2, strides, 2, grp);
104
105              /* Start the acquisition.
106              From now, all incoming samples will be buffered */
107              egd_start(dev);
108              ns_tot = 0;
109
110              while (ns_tot < 1000) {
111                   /* Get the data */
112                   ns_read = egd_get_data(dev, NS, eegarr, triarr);
113                   if (ns_read < 0) {
114                        /* Handle failure */
115                   }
116                   ns_tot += ns_read;
117
118                   /* do something with the new data */
119              }
120
121              /* Stop the acquisition, i.e. no new data is buffered */
122              egd_stop(dev);
123