Inside Macintosh: Sound /

Chapter 3 - Sound Input Manager / Using the Sound Input Manager

Getting and Setting Sound Input Device Information

You can get information about a specific sound input device and alter a sound input device's settings by calling the functions SPBGetDeviceInfo and SPBSetDeviceInfo. These functions accept sound input device information selectors that determine which information you need or want to change. The selectors currently available are defined by constants of type OSType.

Here is a list of the selectors that all sound input device drivers must support. For complete details on all the selectors described in this section, see "Sound Input Device Information Selectors" beginning on page 3-18.

CONST
   siAsync                 = 'asyn';   {asynchronous capability}
   siChannelAvailable      = 'chav';   {number of channels available}
   siCompressionAvailable  = 'cmav';   {compression types available}
   siCompressionFactor     = 'cmfa';   {current compression factor}
   siCompressionType       = 'comp';   {compression type}
   siContinuous            = 'cont';   {continuous recording}
   siDeviceBufferInfo      = 'dbin';   {size of interrupt buffer}
   siDeviceConnected       = 'dcon';   {input device connection status}
   siDeviceIcon            = 'icon';   {input device icon}
   siDeviceName            = 'name';   {input device name}
   siLevelMeterOnOff       = 'lmet';   {level meter state}
   siNumberChannels        = 'chan';   {current number of channels}
   siRecordingQuality      = 'qual';   {recording quality}
   siSampleRate            = 'srat';   {current sample rate}
   siSampleRateAvailable   = 'srav';   {sample rates available}
   siSampleSizeAvailable   = 'ssav';   {sample sizes available}
   siSampleSize            = 'ssiz';   {current sample size}
   siTwosComplementOnOff   = 'twos';   {two's complement state}

The Sound Input Manager defines several selectors that specifically help it interact with sound input device drivers. Your application should not use any of these selectors, but if you are implementing a sound input device driver, you need to support these selectors. They are:

CONST
   siCloseDriver           = 'clos';   {release driver}
   siInitializeDriver      = 'init';   {initialize driver}
   siPauseRecording        = 'paus';   {pause recording}
   siUserInterruptProc     = 'user';   {set sound input interrupt routine}

Finally, there are a number of sound input device information selectors that sound input device drivers can optionally support. If you are writing an application, you can use these selectors to interact with a sound input device driver, but you should be aware that some drivers might not support all of them. To determine if a driver supports one of these selectors, you can use the SPBGetDeviceInfo function. If no errors are returned, then the selector is supported when using the SPBGetDeviceInfo and the SPBSetDeviceInfo functions.

CONST
   siActiveChannels        = 'chac';   {channels active}
   siActiveLevels          = 'lmac';   {levels active}
   siAGCOnOff              = 'agc ';   {automatic gain control state}
   siCompressionHeader     = 'cmhd';   {get compression header}
   siCompressionNames      = 'cnam';   {return compression type names}
   siInputGain             = 'gain';   {input gain level}
   siInputSource           = 'sour';   {input source selector}
   siInputSourceNames      = 'snam';   {input source names}
   siOptionsDialog         = 'optd';   {display options dialog box}
   siPlayThruOnOff         = 'plth';   {play-through state}
   siStereoInputGain       = 'sgai';   {stereo input gain level}
   siVoxRecordInfo         = 'voxr';   {VOX record parameters}
   siVoxStopInfo           = 'voxs';   {VOX stop parameters}

The format of the relevant data (either returned by the Sound Input Manager or provided by you) depends on the selector you provide. For example, if you want to determine the name of some sound input device, you can pass to the SPBGetDeviceInfo function the siDeviceName selector and a pointer to a 256-byte buffer. If the SPBGetDeviceInfo function can get the information, it fills that buffer with the name of the specified sound input device. Listing 3-2 illustrates one way you can determine the name of a particular sound input device.

Listing 3-2 Determining the name of a sound input device

FUNCTION MyGetDeviceName (myRefNum: LongInt; VAR dName: Str255): OSErr;
BEGIN
   MyGetDeviceName := SPBGetDeviceInfo(myRefNum, siDeviceName, Ptr(@dName));
END;

Note

You can get the name and icon of all connected sound input devices without using sound input information selectors by using the SPBGetIndexedDevice function, which is described on page 3-49.

Some selectors cause the SPBGetDeviceInfo function to return data of other types. Listing 3-3 illustrates how to determine the number of channels, the sample rate, the sample size, and the compression type currently in use by a given sound input device. (The procedure defined in Listing 3-3 is called in the procedure defined in Listing 3-1.)

Listing 3-3 Determining some sound input device settings

PROCEDURE MyGetDeviceSettings (myRefNum: LongInt; 
                                 VAR numChannels: Integer; 
                                 VAR sampleRate: Fixed; 
                                 VAR sampleSize: Integer; 
                                 VAR compressionType: OSType);
VAR
   myErr:      OSErr;
BEGIN
   {Get number of active channels.}
   myErr := SPBGetDeviceInfo (myRefNum, siNumberChannels, Ptr(@numChannels));
   {Get sample rate.}
   myErr := SPBGetDeviceInfo(myRefNum, siSampleRate, Ptr(@sampleRate));
   {Get sample size.}
   myErr := SPBGetDeviceInfo(myRefNum, siSampleSize, Ptr(@sampleSize));
   {Get compression type.}
   myErr := SPBGetDeviceInfo(myRefNum, siCompressionType, 
                                                   Ptr(@compressionType));
END;

All of the selectors that return a handle allocate the memory for that handle in the current heap zone; you are responsible for disposing of that handle when you are done with it, and you should verify that there is enough memory for such a handle before calling the selector.