# 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.

## See Also

`NNS_SndArcSetup`
`NNS_SndArcGet*Symbol`
`NNS_SndArcSetCurrent`
`NNS_SndArcInitOnMemory`

## 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.

CONFIDENTIAL