path: root/lib/libsndio/sioctl_open.3

.\" $OpenBSD: sioctl_open.3,v 1.4 2020/04/19 09:54:56 jmc Exp $
.\"
.\" Copyright (c) 2011-2020 Alexandre Ratchov <alex@caoua.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: April 19 2020 $
.Dt SIOCTL_OPEN 3
.Os
.Sh NAME
.Nm sioctl_open ,
.Nm sioctl_close ,
.Nm sioctl_ondesc ,
.Nm sioctl_onval ,
.Nm sioctl_setval ,
.Nm sioctl_nfds ,
.Nm sioctl_pollfd ,
.Nm sioctl_eof
.Nd interface to audio parameters
.Sh SYNOPSIS
.Fd #include <sndio.h>
.Ft "struct sioctl_hdl *"
.Fn "sioctl_open" "const char *name" "unsigned int mode" "int nbio_flag"
.Ft "void"
.Fn "sioctl_close" "struct sioctl_hdl *hdl"
.Ft "int"
.Fn "sioctl_ondesc" "struct sioctl_hdl *hdl" "void (*cb)(void *arg, struct sioctl_desc *desc, int val)" "void *arg"
.Ft "void"
.Fn "sioctl_onval" "struct sioctl_hdl *hdl" "void (*cb)(void *arg, unsigned int addr, unsigned int val)" "void *arg"
.Ft "int"
.Fn "sioctl_setval" "struct sioctl_hdl *hdl" "unsigned int addr" "unsigned int val"
.Ft "int"
.Fn "sioctl_nfds" "struct sioctl_hdl *hdl"
.Ft "int"
.Fn "sioctl_pollfd" "struct sioctl_hdl *hdl" "struct pollfd *pfd" "int events"
.Ft "int"
.Fn "sioctl_revents" "struct sioctl_hdl *hdl" "struct pollfd *pfd"
.Ft "int"
.Fn "sioctl_eof" "struct sioctl_hdl *hdl"
.Sh DESCRIPTION
Audio devices may expose a number of controls, like the playback volume control.
Each control has an integer
.Em address
and an integer
.Em value .
Depending on the control type, its integer value represents either a
continuous quantity or a boolean.
Any control may be changed by submitting
a new value to its address.
When values change, asynchronous notifications are sent.
.Pp
Controls descriptions are available, allowing them to be grouped and
represented in a human usable form.
.Sh Opening and closing the control device
First the application must call the
.Fn sioctl_open
function to obtain a handle
that will be passed as the
.Ar hdl
argument to other functions.
.Pp
The
.Ar name
parameter gives the device string discussed in
.Xr sndio 7 .
In most cases it should be set to SIO_DEVANY to allow
the user to select it using the
.Ev AUDIODEVICE
environment variable.
The
.Ar mode
parameter is a bitmap of the SIOCTL_READ and SIOCTL_WRITE constants
indicating whether control values can be read and
modified respectively.
.Pp
If the
.Ar nbio_flag
argument is 1, then the
.Fn sioctl_setval
function (see below) may fail instead of blocking and
the
.Fn sioctl_ondesc
function doesn't block.
.Pp
The
.Fn sioctl_close
function closes the control device and frees any allocated resources
associated with the handle.
.Sh Controls descriptions
The
.Fn sioctl_ondesc
function can be used to obtain the description of all available controls
and their initial values.
It registers a call-back that is immediately invoked for all
controls.
It's called once with a NULL argument to indicate that the full
description was sent and that the caller has a consistent
representation of the controls set.
.Pp
Then, whenever a control description changes, the call-back is
invoked with the updated information followed by a call with a NULL
argument.
.Pp
Controls are described by the
.Va sioctl_ondesc
structure as follows:
.Bd -literal
struct sioctl_node {
	char name[SIOCTL_NAMEMAX];	/* ex. "spkr" */
	int unit;			/* optional number or -1 */
};

struct sioctl_desc {
	unsigned int addr;		/* control address */
#define SIOCTL_NONE		0	/* deleted */
#define SIOCTL_NUM		2	/* integer in the 0..127 range */
#define SIOCTL_SW		3	/* on/off switch (0 or 1) */
#define SIOCTL_VEC		4	/* number, element of vector */
#define SIOCTL_LIST		5	/* switch, element of a list */
	unsigned int type;		/* one of above */
	char func[SIOCTL_NAMEMAX];	/* function name, ex. "level" */
	char group[SIOCTL_NAMEMAX];	/* group this control belongs to */
	struct sioctl_node node0;	/* affected node */
	struct sioctl_node node1;	/* dito for SIOCTL_{VEC,LIST} */
};
.Ed
.Pp
The
.Va addr
attribute is the control address, usable with
.Fn sioctl_setval
to set its value.
.Pp
The
.Va type
attribute indicates what the structure describes.
Possible types are:
.Bl -tag -width "SIOCTL_LIST"
.It SIOCTL_NONE
A previously valid control was deleted.
.It SIOCTL_NUM
A continuous control in the 0..SIOCTL_VALMAX range.
For instance the volume of the speaker.
.It SIOCTL_SW
A on/off switch control.
For instance the switch to mute the speaker.
.It SIOCTL_VEC
Element of an array of continuous controls.
For instance the knob to control the amount of signal flowing
from the line input to the speaker.
.It SIOCTL_LIST
An element of an array of on/off switches.
For instance the line-in position of the
speaker source selector.
.El
.Pp
The
.Va func
attribute is the name of the parameter being controlled.
There may be no parameters of different types with the same name.
.Pp
The
.Va node0
and
.Va node1
attributes indicate the names of the controlled nodes, typically
channels of audio streams.
.Va node1
is meaningful for
.Va SIOCTL_VEC
and
.Va SIOCTL_LIST
only.
.Pp
Names in the
.Va node0
and
.Va node1
attributes and
.Va func
are strings usable as unique identifiers within the the given
.Va group .
.Sh Changing and reading control values
Controls are changed with the
.Fn sioctl_setval
function, by giving the index of the control and the new value.
The
.Fn sioctl_onval
function can be used to register a call-back which will be invoked whenever
a control changes.
Continuous values are in the 0..127 range.
.Sh "Interface to" Xr poll 2
The
.Fn sioctl_pollfd
function fills the array
.Ar pfd
of
.Va pollfd
structures, used by
.Xr poll 2 ,
with
.Ar events ;
the latter is a bit-mask of
.Va POLLIN
and
.Va POLLOUT
constants.
.Fn sioctl_pollfd
returns the number of
.Va pollfd
structures filled.
The
.Fn sioctl_revents
function returns the bit-mask set by
.Xr poll 2
in the
.Va pfd
array of
.Va pollfd
structures.
If
.Va POLLOUT
is set,
.Fn sioctl_setval
can be called without blocking.
POLLHUP may be set if an error occurs, even if
it is not selected with
.Fn sioctl_pollfd .
POLLIN is not used yet.
.Pp
The
.Fn sioctl_nfds
function returns the number of
.Va pollfd
structures the caller must preallocate in order to be sure
that
.Fn sioctl_pollfd
will never overrun.
.Sh SEE ALSO
.Xr sndioctl 1 ,
.Xr poll 2 ,
.Xr sndio 7