NNS_SndArcInit*

Syntax

#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`	Pointer to the `NNSSndArc` structure that manages the sound archive.
`filePath`	Path in the ROM file system of the sound archive data.
`heap`	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 deallocated, 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 consumes 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, but 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 data files in NAND and SD Card archives cannot be used.

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.

Revision History

2008/06/03 Added note about NAND and SD Card archives.
2005/08/18 Added explanation of the NNS_SndArcInitWithResult function.
2004/09/06 Added note about dynamically allocating the NNS_SndArc structure.
2004/09/02 Added explanation of the NNS_SndArcSetup function.
2004/06/01 Initial version.