audio_support(7I)

NAME

     audio_support - audio driver support routines and interface

SYNOPSIS

     #include <sys/audio.h>

DESCRIPTION

     The audio support  module supports audio  drivers  that  use
     the  new audio driver  architecture. It also provides a lim-
     ited number of ioctl(2) functions for  application  program-
     mers.

DATA STRUCTURES

     The following data structures are defined to manage the dif-
     ferent audio device types and  channels.

  Device Types
     The following enumeration lists a number of  generic  device
     types.

          typedef enum {
               UNDEFINED, AUDIO, AUDIOCTL, USER1, USER2, USER3
          } audio_device_type_e;

     Currently, the Solaris audio mixer implements only the AUDIO
     and  AUDIOCTL  audio  device types. See the mixer(7I) manual
     page for details. The USER1, USER2 and  USER3  device  types
     allow  third  parties  to write audio personality modules of
     their own.

  Channel Structure
     This structure is used to get and set state  information  on
     individual channels.

          struct audio_channel {
               pid_t                         pid;           /* application's process ID */
               uint_t                        ch_number;     /* device channel */
               audio_device_type_e dev_type;      /* device type */
               uint_t                        info_size;     /* size of channel's */
                                                                 /* info structure */
               void                     *info;              /* channel state information */
          ;
          typedef struct audio_channel audio_channel_t;

     The ch_number must specify the specific  channel  number  to
     get  or  set. When the ioctl() returns, the pid contains the
     process ID of the process that has  that  channel  open  and
     dev_type  will  contain the device type. If pid is 0 (zero),
     then the channel is not open. The pointer *info  must  point
     to  a  buffer  large  enough  to hold whatever audio device-
     related state structure that may  be  returned.   Currently,
     only  the  audio_info_t  structure  is  returned.   See  the
     audio(7I) and mixer(7I) man pages for more information.

IOCTLS

     The audio support  driver provides the following ioctls():

     AUDIO_GET_CH_NUMBER
           This ioctl() returns the channel number pointed to  by
           the  file  descriptor.  It  is returned in the integer
           pointer of the ioctl() argument.

     AUDIO_GET_CH_TYPE
           This ioctl() returns the type of channel  the  process
           has  open.  It  is returned in the audio_device_type_e
           enumeration pointer of the ioctl() argument.

     AUDIO_GET_NUM_CHS
           This ioctl() returns the number of channels the device
           supports. It is returned in the integer pointer of the
           ioctl() argument.

MACROS

     The following macro can be used to  initialize  data  struc-
     tures.   The   established  convention  is  that  the  state
     corresponding to a field set to -1 will not be modified.

          AUDIO_INIT(I, S)

     Where I is a pointer to an info structure and S is the  size
     of that structure.

     The following code segment  demonstrates  how  to  use  this
     macro:

          audio_info_t    info;

          AUDIO_INIT(&info, sizeof(info));
          info.play.port = AUDIO_HEADPHONE;
          err = ioctl(audio_fd, AUDIO_SETINFO, &info);

ERRORS

     EINVAL
           The ioctl() is invalid for this file descriptor.   The
           audio_channel_t  structure's  info  pointer  does  not
           point to a buffer, or the ch_number is bad.

     ENOMEM
           The ioctl() failed due to lack of memory.

FILES

     /usr/share/audio/samples
            Audio sample files

ATTRIBUTES

     See attributes(5) for a description of the following  attri-
     butes:

     _____________________________________________________________
    |       ATTRIBUTE TYPE        |        ATTRIBUTE VALUE       |
    | Architecture                | SPARC, x86                   |
    | Availability                | SUNWaudd, SUNWauddx, SUNWaudh|
    | Stability Level             | Evolving                     |
    |_____________________________|______________________________|

SEE ALSO

     ioctl(2), attributes(5), audio(7I), mixer(7I), streamio(7I)

FUTURE DIRECTIONS

     Over time, additional  audio  personality  modules  will  be
     added.  Audio  application  programmers  are  encouraged  to
     review this man page with each Solaris release for new audio
     personality modules.