mirror of https://github.com/ericonr/sndio.git
253 lines
6.7 KiB
Groff
253 lines
6.7 KiB
Groff
.\" $OpenBSD$
|
|
.\"
|
|
.\" 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$
|
|
.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
|