Previous Next Table of Contents

3. Control Interface

Control interface gives to application various informations about the currently installed sound driver in the system. Interface should be used to detect if another sound interface is present for selected soundcard or for example to create list of devices (MIXER, PCM etc) from which can user select.

3.1 Low-Level Layer

int snd_cards( void )

Function returns positive count of soundcards if are present in the system otherwise return value is negative and means error code. Zero value should never be returned.

int snd_ctl_open( void **handle, int card )

Function creates new handle and opens connection to kernel sound control interface to soundcard number card (0-N). Function also checks if protocol is compatible to prevent use old programs with new kernel API. Function returns zero if success otherwise it returns negative error code.

int snd_ctl_close( void *handle )

Function frees all resources allocated with control handle and closes connection to kernel sound control interface. Function returns zero if success otherwise it returns negative error code.

int snd_ctl_file_descriptor( void *handle )

Function returns file descriptor of connection to kernel sound control interface. This function should be used only with very special cases. Function returns negative error code if some error was occured.

int snd_ctl_hw_info( void *handle, struct snd_ctl_hw_info *info )

Function returns filled *info structure. Function returns zero if success otherwise it returns negative error code.


  #define SND_CTL_GCAPS_MIDI              0x0000001       /* driver have MIDI interface */

  #define SND_CTL_LCAPS_SYNTH             0x0000001       /* soundcard have synthesizer */
  #define SND_CTL_LCAPS_RAWFM             0x0000002       /* soundcard have RAW FM/OPL3 */

  struct snd_ctl_hw_info {
    unsigned int type;            /* type of card - look to SND_CARD_TYPE_XXXX */
    unsigned int gcaps;           /* look to SND_CTL_GCAPS_XXXX */
    unsigned int lcaps;           /* look to SND_CTL_LCAPS_XXXX */
    unsigned int pcmdevs;         /* count of PCM devices (0 to N) */
    unsigned int mixerdevs;       /* count of MIXER devices (0 to N) */
    unsigned int mididevs;        /* count of raw MIDI devices (0 to N) */
    char id[8];                   /* ID of card (user selectable) */
    char name[80];                /* name/info text about soundcard */
    unsigned char reserved[128];  /* reserved for future */
  };
  

int snd_ctl_pcm_info( void *handle, int dev, snd_pcm_info_t *info )

Function returns filled *info structure. Function returns zero if success otherwise it returns negative error code. Details about snd_pcm_info_t type are in Digital Audio (PCM) Interface section. Argument dev means device number for appropriate soundcard. Range is 0 to N where N is struct snd_ctl_hw_info -> pcmdevs - 1. This function works if selected PCM device is busy, too. It should be used to collect information about PCM devices without exclusive lock.

int snd_ctl_mixer_info( void *handle, int dev, snd_mixer_info_t *info )

Function returns filled *info structure. Function returns zero if success otherwise it returns negative error code. Details about snd_mixer_info_t type are in Mixer Interface section. Argument dev means device number for appropriate soundcard. Range is 0 to N where N is struct snd_ctl_hw_info -> mixerdevs - 1. This function works if selected PCM device is busy, too. It should be used to collect information about PCM devices without exclusive lock.

3.2 Examples

Bellow example shows how can be detected all PCM devices for first soundcard (#0) in the system.


int card = 0, err;
void *handle;
stuct snd_ctl_hw_info info;

if ( (err = snd_ctl_open( &handle, card )) < 0 ) {
  fprintf( stderr, "open failed: %s\n", snd_strerror( err ) );
  return;
}
if ( (err = snd_ctl_hw_info( handle, &info )) < 0 ) {
  fprintf( stderr, "hw info failed: %s\n", snd_strerror( err ) );
  snd_ctl_close( handle );
  return;
}
printf( "Installed PCM devices for card #i: %i\n", card + 1, info.pcmdevs );
snd_ctl_close( handle );


Previous Next Table of Contents