# NNS_SndArcInit*

## 構文

      #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 );

## 引数

`arc` | サウンドアーカイブを管理する NNSSndArc構造体のポインタです。
`filePath` | サウンドアーカイブデータファイルのROMファイルシステム上のパスです。
`heap` | サウンドヒープハンドルです。
`symbolLoadFlag` | シンボルデータをロードするかどうかのフラグです。

## 返り値

`NNS_SndArcInit`関数は、返り値はありません。

`NNS_SndArcInitWithResult`関数は、初期化に成功したかどうかを返します。

## 説明

サウンドアーカイブ構造体を初期化します。 サウンドアーカイブ構造体は静的に確保することを推奨します。 動的に確保する場合は、後述の注意点に気をつけてください。

ROMファイルシステム上の、サウンドアーカイブデータファイル`filePath`を使って、 サウンドアーカイブ構造体を初期化します。 あらかじめ、ファイルシステムが有効になっていなければなりません。

サウンドヒープ`heap`上に、サウンドアーカイブ管理に必要なデータがロードされます。 この領域を開放すると、サウンドアーカイブが使えなくなります。 再度使用できるようにするためには、 `NNS_SndArcSetup`関数を呼びだします。

シンボルデータをロードするかどうかのフラグ`symbolLoadFlag`にTRUEを入れると、 `NNS_SndArcGet*Symbol`関数を使って、 シンボル名を取得できるようになりますが、より多く、サウンドヒープ`heap`を消費します。

初期化したサウンドアーカイブは、自動的にカレントサウンドアーカイブに設定されます。 カレントサウンドアーカイブを変更するには、 `NNS_SndArcSetCurrent`関数を使います。

`NNS_SndArcInit`関数は、初期化に失敗するとアサーションにひっかかりますが、 `NNS_SndArcInitWithResult`関数は、初期化に成功したかどうかを返り値で返します。

ファイルシステムを使わない場合や、全てのサウンドアーカイブデータをメモリ上に置く場合には、 これらの関数の代わりに、 `NNS_SndArcInitOnMemory`関数を使います。

### 注意

NANDアーカイブおよび、SDカードアーカイブ上のサウンドアーカイブデータファイルを使用することはできません。

サウンドアーカイブ構造体は、全てのサウンドヒープを解放した後で破棄することができます。 １つでもヒープ領域が残っていると、メモリ破壊を引き起こす可能性があります。 また、破棄するサウンドアーカイブ構造体のポインタが、 カレントサウンドアーカイブとして、セットされている可能性についても留意してください。

初期化に失敗する主な原因は、サウンドアーカイブデータファイルの読み込み失敗です。 ファイル読み込みに失敗する可能性がある状況では、`NNS_SndArcInitWithResult`関数を使って 返り値をチェックしてください。

## 参照

NNS_SndArcSetup, NNS_SndArcGet*Symbol, NNS_SndArcSetCurrent, NNS_SndArcInitOnMemory

## 履歴

2008/06/03 NANDアーカイブおよびSDカードアーカイブに関する注意書き追加
2005/08/18 NNS_SndArcInitWithResult関数の説明追加
2004/09/06 NNS_SndArc構造体の動的確保に関する注意書き追加
2004/09/02 NNS_SndArcSetup関数に関する説明追加
2004/06/01 初版