.\"Copyright 2010 (c) EPFL
.TH XDF_SET_CHCONF 3 2010 "EPFL" "xdffileio library manual"
.SH NAME
xdf_set_chconf, xdf_get_chconf - set or get the configuration of a
channel descriptor handle
.SH SYNOPSIS
.LP
.B #include <xdfio.h>
.sp
.BI "int xdf_set_chconf(struct xdfch* " ch ", enum xdffield " field ", ...);"
.br
.BI "int xdf_get_chconf(const struct xdfch* " ch ", enum xdffield " field ", ...);"
.br
.SH DESCRIPTION
.LP
\fBxdf_set_chconf\fP() sets the configuration of the channel referenced
by \fIch\fP according to the variable list of argument. This list is
composed of successive couple grouping one variable of type enum xdffield
defining the feature to be set and a value whose type depends on the
previous field type. The list \fImust finish\fP by \fBXDF_NOF\fP.
.LP
\fBxdf_get_chconf\fP() gets the configuration of the channel referenced
by \fIch\fP according to the variable list of argument. The variable list is
the same list terminated by \fBXDF_NOF\fP as for
\fBxdf_set_chconf\fP() excepting that the second part of the couple is not
that value but a \fBpointer to the value\fP.
.LP
Both functions process the argument list \fIfrom left to right\fP. This
means that if a particular field request provokes an error, none of the
field requests on its right will be processed. The order of processing is
also important for field requests that influences the value of other fields
(like \fBXDF_CF_STOTYPE\fP).
.LP
Here is the list of admissible value. The expected type of value is provided
in the parenthesis (the expected type of the value for
\fBxdf_set_chconf\fP(), or a pointer to this type for
\fBxdf_get_chconf\fP()). The default value of each field is provided in
squared brackets (however these defaults can be overridden by a call to
\fBxdf_set_conf\fP(3) if the file is open for writing. If the file is
opened for reading, the default are meaningful only for the fields
\fBXDF_CF_ARR*\fP). 
If a list of data formats is specified in curl brackets, it means that the
field is supported only in those formats (no list means that all formats
support the field):
.TP
\fBXDF_CF_ARRINDEX\fP (int) [0]
Specify the array from/to which the channel value should be transfered. If
the mode of the file is \fBXDF_READ\fP and the value is negative, the
channel will not be read. If the mode is \fBXDF_WRITE\fP and the value is
negative, the function will fail.
.TP
\fBXDF_CF_ARROFFSET\fP (int) [0 for channel 0, packed channels for the rest]
Specify the offset in the array from/to which the channel value should be
transfered.
.TP
\fBXDF_CF_ARRDIGITAL\fP (int) [0 if writing, 1 if reading]
Indicate that the data in the array from/to which the channel value should
be transfered is provided in digital unit. This means in practice that no
scaling is performed during the transfer from/to the disk (non zero indicate
no scaling).
.TP
\fBXDF_CF_ARRTYPE\fP (enum xdftype) [same as \fBXDF_CF_STOTYPE\fP]
specify the type in the channel should casted to/from when accessed in the
array.
.TP
\fBXDF_CF_PMIN\fP (double) [min of \fBXDF_CF_ARRTYPE\fP]
Set/get the minimal value that a physical value can get. Cannot be set if
XDF_READ.
.TP
\fBXDF_CF_PMAX\fP (double) [max of \fBXDF_CF_ARRTYPE\fP]
Set/get the maximal value that a physical value can get. Cannot be set if
XDF_READ.
.TP
\fBXDF_CF_STOTYPE\fP (enum xdftype) [any datatype supported by file type]
Specify the type stored in the file of the channel value. If the XDF file
has been opened in XDF_READ, this field cannot be set. If this field is
successfully set, it will set as well the digital minimum
(\fBXDF_CF_DMIN\fP) and the digital maximum (\fBXDF_CF_MAX\fP) to the
minimum and maximum values allowed by the data type.
.TP
\fBXDF_CF_DMIN\fP (double) [min of \fBXDF_CF_STOTYPE\fP]
Set/get the minimal value that a digital value can get. Cannot be set if
XDF_READ. This is also automatically set by \fBXDF_CF_STOTYPE\fP.
.TP
\fBXDF_CF_DMAX\fP (double) [min of \fBXDF_CF_STOTYPE\fP]
Set/get the maximal value that a digital value can get. Cannot be set if
XDF_READ. This is also automatically set by \fBXDF_CF_STOTYPE\fP.
.TP
\fBXDF_CF_LABEL\fP (const char*) [""]
Set/get the label of the channel. Cannot be set if XDF_READ.
.TP
\fBXDF_CF_UNIT\fP (const char*) [""] {EDF BDF GDF}
Set/get the unit of the channel. Cannot be set if XDF_READ.
.TP
\fBXDF_CF_TRANSDUCTER\fP (const char*) [""] {EDF BDF GDF}
Set/get the type of sensor used for this channel. Cannot be set if XDF_READ.
.TP
\fBXDF_CF_PREFILTERING\fP (const char*) [""] {EDF BDF GDF}
Set/get the information about the filters already applied on channel data.
Cannot be set if XDF_READ.
.TP
\fBXDF_CF_ELECPOS\fP (double[3]) [0,0,0] {GDF}
Position of the sensor/electrode expressed in X,Y,Z components
Cannot be set if XDF_READ.
.TP
\fBXDF_CF_IMPEDANCE\fP (double) [0] {GDF}
Impedance of the sensor/electrode. Cannot be set if XDF_READ.
.SH "RETURN VALUE"
.LP
The two functions returns 0 in case of success. Otherwise \-1 is returned and
\fIerrno\fP is set appropriately.
.SH ERROR
.TP 7
.B EINVAL
\fIch\fP is NULL or \fIfield\fP is not a proper value of the enumeration
xdffield
.TP 7
.B EPERM
The request submitted to \fBxdf_set_chconf\fP() is not allowed for this
channel or is forbidden for file opened with the mode \fBXDF_READ\fP.
.TP 7
.B EDOM
The value set in \fBxdf_set_chconf\fP() as digital or physical min/max
(fields XDF_CF_{D/P}{MIN/MAX}) goes beyond the limits of respectively the
stored or array data type.
.SH EXAMPLES
.LP
Example of usage of \fBxdf_set_chconf\fP():
.sp
.RS
.nf
\fB
/* Assume xdf referenced an XDF file opened for writing */
unsigned int iarray = 2, offset = 0;
const char label[] = "Channel EEG";

hchxdf ch = xdf_add_channel(xdf);
xdf_set_chconf(ch, XDF_CF_ARRINDEX, iarray,
                        XDF_CF_ARROFFSET, offset,
                        XDF_CF_LABEL, label,
                        XDF_NOF);
\fP
.fi
.RE
.LP
Example of usage of \fBxdf_get_chconf\fP():
.sp
.RS
.nf
\fB
/* Assume xdf referenced an XDF file opened for reading */
unsigned int iarray, offset;
const char label[128];

hchxdf ch = xdf_get_channel(xdf, 1);
xdf_get_chconf(ch, XDF_CF_ARRINDEX, &iarray,
                        XDF_CF_ARROFFSET, &offset,
                        XDF_CF_LABEL, &label,
                        XDF_NOF);

printf("iarray = %u\\n", iarray);
printf("offset = %u\\n", offset);
printf("label = %s\\n", label);

\fP
.fi
.RE
.SH "SEE ALSO"
.BR xdf_copy_chconf (3)