Previous Next Table of Contents

3. Control Interface

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

3.1 Low-Level Layer

int snd_cards( void )

Returns the number of soundcards present in the system, if any. Otherwise it returns a negative value, which maps to an error code. This function will return 0 if no soundcards are detected.

unsigned int snd_cards_mask( void )

Returns the bitmap of soundcards present in the system, if any. Otherwise it returns a negative value, which maps to an error code. This function will return 0 if no soundcards are detected. First soundcard is represented with bit 0.

int snd_ctl_open( void **handle, int card )

Creates a new handle and opens communication with the kernel sound control interface for soundcard number card (0-N). The function also checks if protocol is compatible, so as to prevent the use of old programs with a new kernel API. Function returns zero if successful, otherwise an error code is returned.

int snd_ctl_close( void *handle )

Function frees all resources allocated with control handle and closes the kernel sound control interface. Function returns zero if successful, otherwise it returns an error code.

int snd_ctl_file_descriptor( void *handle )

Function returns file descriptor for the kernel sound control interface. This function should be used in very special cases. Function returns a negative error code if some error was encountered.

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

Fills the info structure with data about the sound hardware referenced by handle. Function returns zero if successful, otherwise it returns an error code.


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

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

  struct snd_ctl_hw_info {
    unsigned int type;            /* type of card - see SND_CARD_TYPE_XXXX */
    unsigned int gcaps;           /* see SND_CTL_GCAPS_XXXX */
    unsigned int lcaps;           /* see 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 use */
  };
  

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

Fills the *info structure with data about the PCM device. Function returns zero if successful, otherwise it returns an error code. Details about the snd_pcm_info_t structure are in the Digital Audio (PCM) Interface section. The argument dev selects the device number for the soundcard referenced by *handle. Its range is 0 to N where N is struct snd_ctl_hw_info -> pcmdevs - 1. This function will work if the selected PCM device is busy, too. It should be used to collect information about PCM devices without exclusive lock.

int snd_ctl_pcm_playback_info( void *handle, int dev, snd_pcm_playback_info_t *info )

Fills the *info structure with data about the PCM device and playback direction. Function returns zero if successful, otherwise it returns an error code. Details about the snd_pcm_playback_info_t structure are in the Digital Audio (PCM) Interface section. The argument dev selects the device number for the soundcard referenced by *handle. Its range is 0 to N where N is struct snd_ctl_hw_info -> pcmdevs - 1. This function will work if the selected PCM device is busy, too. It should be used to collect information about PCM devices without exclusive lock.

int snd_ctl_pcm_record_info( void *handle, int dev, snd_pcm_record_info_t *info )

Fills the *info structure with data about the PCM device and record direction. Function returns zero if successful, otherwise it returns an error code. Details about the snd_pcm_record_info_t structure are in the Digital Audio (PCM) Interface section. The argument dev selects the device number for the soundcard referenced by *handle. Its range is 0 to N where N is struct snd_ctl_hw_info -> pcmdevs - 1. This function will work if the 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 )

Fills the *info structure with data about the mixer device. Returns zero if successful, otherwise it returns an error code. Details about the snd_mixer_info_t structure are in the Mixer Interface section. The argument dev specifies the device number for the appropriate soundcard. Its range is 0 to N where N found from struct snd_ctl_hw_info -> mixerdevs - 1. It should be used to collect information about mixer devices.

3.2 Examples

The following example shows how all PCM devices can be detected for the 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