Inside Macintosh: Sound /

Chapter 2 - Sound Manager / Sound Manager Reference

Sound Manager Routines / Playing From Disk

SndStartFilePlay

You can call the SndStartFilePlay function to initiate a play from disk.

FUNCTION SndStartFilePlay (chan: SndChannelPtr; fRefNum: Integer;
                           resNum: Integer; bufferSize: LongInt;
                           theBuffer: Ptr; 
                           theSelection: AudioSelectionPtr; 
                           theCompletion: ProcPtr; 
                           async: Boolean): OSErr;

chan

A pointer to a valid sound channel. You can pass NIL instead of a pointer to a sound channel if you want the Sound Manager to internally allocate a sound channel in your application's heap zone.

fRefNum

The file reference number of the AIFF or AIFF-C file to play. To play a sound resource rather than a sound file, this field should be 0.

resNum

The resource ID number of a sound resource to play. To play a sound file rather than a sound resource, this field should be 0.

bufferSize

The number of bytes of memory that the Sound Manager is to use for input buffering while reading in sound data. For SndStartFilePlay to execute successfully on the slowest Macintosh computers, use a buffer of at least 20,480 bytes. You can pass the value 0 to instruct the Sound Manager to allocate a buffer of the default size.

theBuffer

A pointer to a buffer that the Sound Manager should use for input buffering while reading in sound data. If this parameter is NIL, the Sound Manager allocates two buffers, each half the size of the value specified in the bufferSize parameter. If this parameter is not NIL, the buffer should be a nonrelocatable block of size bufferSize.

theSelection

A pointer to an audio selection record that specifies which portion of a sound should be played. You can pass NIL to specify that the Sound Manager should play the entire sound.

theCompletion

A pointer to a completion routine that the Sound Manager calls when the sound is finished playing. You can pass NIL to specify that the Sound Manager should not execute a completion routine. This field is useful only for asynchronous play.

async

A Boolean value that indicates whether the sound should be played asynchronously (TRUE) or synchronously (FALSE). You can play sound asynchronously only if you allocate your own sound channel (using SndNewChannel). If you pass NIL in the chan parameter and TRUE for this parameter, the SndStartFilePlay function returns the badChannel result code.

DESCRIPTION

The SndStartFilePlay function begins a continuous play from disk on a sound channel. The chan parameter is a pointer to the sound channel. If chan is not NIL, it is used as a valid channel. If chan is NIL, an internally allocated sound channel is used for play from disk. This internally allocated sound channel is not passed back to you. Because SndPauseFilePlay and SndStopFilePlay require a sound-channel pointer, you must allocate your own channel if you wish to use those routines.

The sounds you wish to play can be stored either in a file or in an 'snd ' resource. If you are playing a file, then fRefNum should be the file reference number of the file to be played and the parameter resNum should be set to 0. If you are playing an 'snd ' resource, then fRefNum should be set to 0 and resNum should be the resource ID number (not the file reference number) of the resource to play.

WARNING

The SndStartFilePlay function might not play 'snd ' resources from disk correctly. In particular, the function will not execute correctly if any resource in the resource file containing the 'snd ' resource you wish to play has been changed through a call to the WriteResource procedure and you have not updated the resource file using the UpdateResFile procedure. To avoid this and other problems, you should use the SndStartFilePlay function to play only sound files.

SPECIAL CONSIDERATIONS

Because the SndStartFilePlay function moves memory, you should not call it at interrupt time.

ASSEMBLY-LANGUAGE INFORMATION

The trap macro and routine selector for the SndStartFilePlay function are

Trap macro	Selector
_SoundDispatch	$0D000008

RESULT CODES

noErr	0	No error
notEnoughHardwareErr	-201	Insufficient hardware available
queueFull	-203	No room in the queue
badChannel	-205	Channel is corrupt or unusable
badFormat	-206	Resource is corrupt or unusable
notEnoughBufferSpace	-207	Insufficient memory available
badFileFormat	-208	File is corrupt or unusable, or not AIFF or AIFF-C
channelBusy	-209	Channel is busy
buffersTooSmall	-210	Buffer is too small
siInvalidCompression	-223	Invalid compression type

SEE ALSO

For an example of how to play a sound file, see the chapter "Introduction to Sound on the Macintosh" in this book.

For information on the format of a completion routine, see "Completion Routines" on page 2-151.