Inside Macintosh: Sound /

Chapter 5 - Sound Components / Sound Components Reference

Sound Component-Defined Routines / Getting and Setting Sound Component Information

SoundComponentGetInfo

A sound component must implement the SoundComponentGetInfo function. The Sound Manager calls this function to get information about the capabilities of your component.

pascal ComponentResult SoundComponentGetInfo 
                           (ComponentInstance ti, 
                              SoundSource sourceID,
                              OSType selector, void *infoPtr);

ti

A component instance that identifies your sound component.

sourceID

A source ID for a source component chain.

selector

A sound component information selector. See "Sound Component Information Selectors" beginning on page 5-22 for a description of the available selectors.

infoPtr

On output, a pointer to the information requested by the caller.

DESCRIPTION

Your SoundComponentGetInfo function returns information about your sound component. The sourceID parameter specifies the sound source to return information about, and the selector parameter specifies the kind of information to be returned. If the information occupies 4 or fewer bytes, it should be returned in the location pointed to by the infoPtr parameter. If the information is larger than 4 bytes, the infoPtr parameter is a pointer to a component information list, a 6-byte structure of type SoundInfoList:

typedef struct {
   short          count;
   Handle         handle;
} SoundInfoList, *SoundInfoListPtr;

This structure consists of a count and a handle to a variable-sized array. The count field specifies the number of elements in the array to which handle is a handle. It is your component's responsibility to allocate the block of data referenced by that handle, but it is the caller's responsibility to dispose of that handle once it is finished with it.

The data type of the array elements depends on the kind of information being returned. For example, the selector siSampleSizeAvailable indicates that you should return a list of the sample sizes your component can support. You return the information by passing back, in the infoPtr parameter, a pointer to an integer followed by a handle to an array of integers.

If your component cannot provide the information specified by the selector parameter, it should pass the selector to its source component.

SPECIAL CONSIDERATIONS

Your SoundComponentGetInfo function is not called at interrupt time if it is passed a selector that might cause it to allocate memory for the handle in the component information list.

RESULT CODES

Your SoundComponentGetInfo function should return noErr if successful or an appropriate result code otherwise.

SEE ALSO

See "Finding and Changing Component Capabilities" on page 5-18 for a sample SoundComponentGetInfo function.