NNS_SndArcInit*

C Specification

#include <nnsys/snd.h>
void NNS_SndArcInit(
        NNSSndArc* arc,
        const char* filePath,
        NNSSndHeapHandle heap,
        BOOL symbolLoadFlag );
BOOL NNS_SndArcInitWithResult( NNSSndArc* arc, const char* filePath, NNSSndHeapHandle heap, BOOL symbolLoadFlag );

Arguments

arc The pointer to the NNSSndArc structure that manages the sound archive.
filePath The path in the ROM file system of the sound archive data
heap The sound heap handle
symbolLoadFlag Flag that determines whether to load symbol data.

Return Values

The NNS_SndArcInit function does not have a return value.

The NNS_SndArcInitWithResult function returns whether or not initialization was successful.

Description

Initializes the sound archive structure. We recommend that you allocate the sound archive structure statically. If you choose to allocate dynamically, be aware of the following.

This function initializes the sound archive structure using the sound archive data file filePath in the ROM file system. The file system must be validated in advance.

The data necessary for the management of the sound archive is loaded into the sound heap heap. If this region is de-allocated, the sound archive becomes unusable. To make it usable again, call the NNS_SndArcSetup function.

If you set the symbol load flag symbolLoadFlag to TRUE, this function can use the NNS_SndArcGet*Symbol function to acquire symbol names. However, this requires more of the sound heap.

The initialized sound archive is automatically set to the current sound archive. Use NNS_SndArcSetCurrent to modify the current sound archive.

With the NNS_SndArcInit function assertion fails when initialization fails, whereas the NNS_SndArcInitWithResult function returns whether or not initialization was successful as a return value.

When not using the file system or when placing all of the sound archive data in memory, use the NNS_SndArcInitOnMemory function instead of these functions.

Note

The sound archive structure can be discarded after releasing all sound heaps. Memory may be damaged if even a single heap region remains. Note that the pointer to the discarded sound archive structure may be set as the current sound archive.

The primary reason that initialization fails is when the sound archive data fails to load. In situations when file loading may fail, use NNS_SndArcInitWithResult and check the return value.

See Also

NNS_SndArcSetup,
NNS_SndArcGet*Symbol,
NNS_SndArcSetCurrent,
NNS_SndArcInitOnMemory

Revision History

2005/08/18 Added an explanation about the NNS_SndArcInitWithResult function.

2004/09/06 Added notes about static allocation of the NNS_SndArc structure to the description.

2004/09/02 Added explanation about the NNS_SndArcSetup function.

2004/06/01 Initial version.


CONFIDENTIAL