Inside Macintosh: Sound /

Chapter 1 - Introduction to Sound on the Macintosh / Sound Reference

Routines / Playing Sounds

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 (described in the chapter "Sound Manager") 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.

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
resProblem	-204	Problem loading the resource
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 using the SndStartFilePlay function, see "Playing a Sound File" on page 1-26. For information on completion routines, see the chapter "Sound Manager" in this book.