/*---------------------------------------------------------------------------* Project: Horizon File: fs_FileSystemBase.h Copyright (C)2009 Nintendo Co., Ltd. All rights reserved. These coded instructions, statements, and computer programs contain proprietary information of Nintendo of America Inc. and/or Nintendo Company Ltd., and are protected by Federal copyright law. They may not be disclosed to third parties or copied or duplicated in any form, in whole or in part, without the prior written consent of Nintendo. $Rev: 32914 $ *---------------------------------------------------------------------------*/ #ifndef NN_FS_CTR_MPCORE_FS_FILESYSTEMBASE_H_ #define NN_FS_CTR_MPCORE_FS_FILESYSTEMBASE_H_ #include #include namespace nn { namespace fs { namespace detail { class FileSystemBaseImpl : public nn::fs::CTR::MPCore::detail::UserFileSystem { }; }}} namespace nn { namespace fs { //---------------------------------------- //! @name ROM アーカイブ //@{ /*! @brief rom アーカイブのマウントに必要なメモリサイズを取得します。 ビルド時に生成される ROMFS を参照する rom アーカイブのマウントに必要なメモリサイズを計算して返します。@n このサイズは、maxFile で指定される数のファイルと、maxDirectory で指定される数のディレクトリを同時に開くことがで きるだけのメモリのサイズが返されます。@n useCache を true に設定することで、ROMFS のメタデータをメモリにキャッシュするのに必要なメモリサイズも含まれるよ うになります。 @param[in] maxFile 同時に開くファイルの最大数 @param[in] maxDirectory 同時に開くディレクトリの最大数 @param[in] useCache メタ情報をメモリにキャッシュするなら true、しないなら false @return 計算したメモリサイズを返します。rom アーカイブをマウントすることができない状態の場合、0 を返します。 */ s32 GetRomRequiredMemorySize(size_t maxFile, size_t maxDirectory, bool useCache = true); /*! @brief rom アーカイブをマウントします。 ビルド時に生成される ROMFS を参照する rom アーカイブをマウントします。@n rom アーカイブに対し、maxFile で指定された数のファイルを同時に開くことができ、maxDirectory で指定された数のディ レクトリを同時に開けるようになります。@n workingMemory で渡される領域は、@ref GetRomRequiredMemorySize 関数で計算されたサイズ以上である必要があります。@n useCache を true に設定することで、ROMFS のメタデータをメモリにキャッシュします。これにより、ファイルを開いたり、 ディレクトリの走査をするのにかかる時間が短縮されます。但し、必要なメモリサイズは増加します。 @param[in] archiveName アーカイブ名を指定します(省略するオーバロードでは "rom:" が暗黙的に指定されます) @param[in] maxFile 同時に開くファイルの最大数 @param[in] maxDirectory 同時に開くディレクトリの最大数 @param[in] workingMemory rom アーカイブの動作に使用するメモリ領域の先頭アドレス @param[in] workingMemorySize rom アーカイブの動作に使用するメモリ領域のサイズ @param[in] useCache メタ情報をメモリにキャッシュするなら true、しないなら false @return 処理の結果を返します。 @retval 成功 処理に成功しました。戻り値の IsSuccess 関数が true を返す状態です。 @retval ResultNotFound ROMFS が存在しません。RSF ファイルが正しく記述されているか確かめてください。@n 製品では発生しないようにするべきエラーです。 @retval ResultNotEnoughSpace workingMemory に指定したメモリのサイズが足りません。@n 製品では発生しないようにするべきエラーです。 @retval 上記以外 想定外のエラー、もしくは致命的なエラーが発生しました。 */ Result MountRom(const char* archiveName, size_t maxFile, size_t maxDirectory, void* workingMemory, size_t workingMemorySize, bool useCache = true); Result MountRom(size_t maxFile, size_t maxDirectory, void* workingMemory, size_t workingMemorySize, bool useCache = true); //@} //---------------------------------------- //! @name セーブデータアーカイブ //@{ /*! @brief セーブデータ領域をフォーマットします。 アプリケーション固有の領域であるセーブデータ領域をフォーマットします。この関数を呼ぶと、既存のセーブデータがあっ た場合には消去されます。 フォーマットの際には、このセーブデータ領域が持つことのできるファイルの最大数と、ディレクトリの最大数を指定する ことができます。この数を超えて、ファイルやディレクトリを作成することはできませんので注意してください。 isDuplicateAll を true にしてフォーマットした場合、セーブデータをアンマウントする前に必ず @ref CommitSaveData を呼び出してください。 @param[in] maxFiles ファイルの最大数を指定します @param[in] maxDirectories ディレクトリの最大数を指定します @param[in] isDuplicateAll セーブデータ領域全体を二重化するかどうかを指定します @return 処理の結果を返します。 @retval 成功 処理に成功しました。戻り値の IsSuccess 関数が true を返す状態です。 @retval ResultNotEnoughSpace セーブデータのサイズに対して、maxFiles,maxDirectories の値が大きすぎます。@n 製品では発生しないようにするべきエラーです。 @retval 上記以外 想定外のエラー、もしくは致命的なエラーが発生しました。 */ Result FormatSaveData(size_t maxFiles, size_t maxDirectories, bool isDuplicateAll = false); /*! @brief セーブデータアーカイブをマウントします。 アプリケーション固有の領域であるセーブデータ領域を、指定されたアーカイブ名でマウントします。セーブデータ領域を 使用する前には、セーブデータ領域をフォーマットする必要があります。 この関数を呼んだ際には必ず戻り値の判定を行い、セーブデータ領域が不正な状態でないか判断をしてください。不正な状 態の場合は、@ref FormatSaveData を呼び出してセーブデータ領域の初期化をしてください。その後、もう一度この関数を 呼び出してマウントしてください。 @param[in] archiveName アーカイブ名を指定します(省略した際は "data:" が指定されます) @return 処理の結果を返します。 @retval 成功 処理に成功しました。戻り値の IsSuccess 関数が true を返す状態です。 @retval ResultNotFormatted フォーマットされていません。@ref FormatSaveData を呼び出してフォーマットしてください。 @retval ResultBadFormat 不正なフォーマットです。@ref FormatSaveData を呼び出してフォーマットしてください。 @retval ResultVerificationFailed 検証に失敗、または改竄を検出しました。@ref FormatSaveData を呼び出してフォーマットしてください。 @retval 上記以外 アプリケーション側の不具合、もしくは想定外のエラーです。 */ Result MountSaveData(const char* archiveName = "data:"); /*! @brief セーブデータの変更をコミットします。 指定のアーカイブ名でマウントされたセーブデータ領域をコミットし、書き込んだデータを確実なものとします。@n この関数を呼ばずにアーカイブをアンマウントしたり、プログラムが停止した場合、前回のコミットからこれまでのセーブ データへの変更は全て巻き戻されます。 この関数が正常に返ってきた場合、セーブデータへの変更が正しく行われたことが保障されます。この関数の実行中にプロ グラムが中断した場合のセーブデータの状態は、「以前コミットが行われた状態か」もしくは「全ての変更が反映された状 態」のどちらかになります。破損したり、中途半端な状態になることはありません。 @param[in] archiveName アーカイブ名を指定します(省略した際は "data:" が指定されます) @return 処理の結果を返します。 @retval 成功 処理に成功しました。戻り値の IsSuccess 関数が true を返す状態です。 @retval ResultNotFound 指定したアーカイブはマウントされていません。@n 製品では発生しないようにするべきエラーです。 @retval 上記以外 アプリケーション側の不具合、もしくは想定外のエラーです。 */ Result CommitSaveData(const char* archiveName = "data:"); //@} //---------------------------------------- //! @name 拡張セーブデータアーカイブ //@{ /*! @brief 拡張セーブデータ領域を作成します。 id に対応した拡張セーブデータ領域を作成します。引数の拡張セーブデータ ID には、RSF で指定した拡張セーブデータ番 号を指定してください。 この関数を呼ぶ前には必ず @ref MountExtSaveData を呼び出して、すでに同じ ID の領域が作成されていないか確認を行っ てください。フォーマットを行う場合は、@ref DeleteExtSaveData を呼び出して削除を行なった後、この関数を呼び出して ください。 アイコンデータには、ctr_makebunner32 により出力された icn ファイルを指定してください。 拡張セーブデータを作り直さない限り、ここで指定したディレクトリ数、ファイル数、データサイズを超えた書き込みは行 うことができません。拡張的な使用を行う場合は注意してください。 拡張セーブデータ上に作られるファイルは、サイズ変更が不可です。よって @ref FileStream::TryInitialize などでファ イルを作成することができません。ファイルを作成するときは、サイズ指定が可能な @ref TryCreateFile を使用してくだ さい。 @param[in] id 拡張セーブデータの ID を指定します。 @param[in] iconData アイコンデータを指定します。 @param[in] iconDataSize アイコンデータのサイズを指定します。 @param[in] entryDirectory この拡張セーブデータ領域に格納したいディレクトリ数を指定します。 @param[in] entryFile この拡張セーブデータ領域に格納したいファイル数を指定します。 @return 処理の結果を返します。 @retval 成功 処理に成功しました。戻り値の IsSuccess 関数が true を返す状態です。 @retval ResultMediaNotFound SD カードが見つからないか、もしくは認識できません。 @retval ResultNotEnoughSpace SD カードに必要な空き容量がありません。 @retval ResultArchiveInvalidated 作成中に SD カードが抜かれた可能性があります。 @retval ResultWriteProtected SD カードが書き込み禁止になっています。 @retval ResultMediaAccessError 挿さっているのが SD カードではないか、もしくは SD カードが壊れています。 @retval ResultNotFormatted エラーにより、作成が中断されました。この状態でマウントを行うと同じエラーが返ります。 @retval ResultBadFormat SD カードのフォーマットが不正です。SD カードをフォーマットする必要があります。 @retval 上記以外 アプリケーション側の不具合、もしくは想定外のエラーです。 */ Result CreateExtSaveData(nn::fs::ExtSaveDataId id, const void* iconData, size_t iconDataSize, u32 entryDirectory, u32 entryFile); /*! @brief 拡張セーブデータをマウントします。 指定した拡張セーブデータ ID の拡張セーブデータ領域を、アーカイブとしてマウントします。 この関数を呼んだ際には必ず戻り値の判定を行い、拡張セーブデータ領域が不正な状態でないか判断をしてください。不正 な状態の場合は、@ref DeleteExtSaveData を呼び出して削除を行なった後、@ref CreateExtSaveData 関数を呼び出して拡 張セーブデータ領域を作り直してください。その後、もう一度この関数を呼び出してマウントしてください。 @param[in] archiveName アーカイブ名を指定します。 @param[in] id 拡張セーブデータの ID を指定します。 @return 処理の結果を返します。 @retval 成功 処理に成功しました。戻り値の IsSuccess 関数が true を返す状態です。 @retval ResultNotFound 拡張セーブデータが見つかりません。@ref CreateExtSaveData を呼び出して作成してください。@n 開発中は、id の値が正しいか確認をしてください。 @retval ResultMediaNotFound SD カードが見つからないか、もしくは認識できません。 @retval ResultArchiveInvalidated マウント中に SD カードが抜かれた可能性があります。 @retval ResultWriteProtected SD カードが書き込み禁止になっています。 @retval ResultMediaAccessError 挿さっているのが SD カードではないか、もしくは SD カードが壊れています。 @retval ResultNotFormatted 作成中に失敗した状態です。一旦削除した後、@ref CreateExtSaveData を呼び出して作り直してください。 @retval ResultBadFormat 不正なフォーマットです。一旦削除した後、@ref CreateExtSaveData を呼び出して作り直してください。 解決しない場合は、SD カードのフォーマットが必要です。 @retval ResultVerificationFailed 検証に失敗、または改竄を検出しました。一旦削除した後、@ref CreateExtSaveData を呼び出して作り直してください。 @retval 上記以外 アプリケーション側の不具合、もしくは想定外のエラーです。 */ Result MountExtSaveData(const char* archiveName, nn::fs::ExtSaveDataId id); /*! @brief 拡張セーブデータを削除します。 引数の拡張セーブデータ ID には、RSF で指定した拡張セーブデータ番号を指定してください。 @param[in] id 削除する拡張セーブデータの ID を指定します。 @return 処理の結果を返します。 @retval 成功 処理に成功しました。戻り値の IsSuccess 関数が true を返す状態です。 @retval ResultNotFound 拡張セーブデータが見つかりません。@ref CreateExtSaveData を呼び出して作成してください。@n 開発中は、ExtSaveDataId が正しいか確認をしてください。 @retval ResultMediaNotFound SD カードが見つからないか、もしくは認識できません。 @retval ResultArchiveInvalidated 削除中に SD カードが抜かれた可能性があります。 @retval ResultOperationDenied 指定した拡張セーブデータは現在マウント中のため、操作は途中で失敗しました。 @retval ResultWriteProtected SD カードが書き込み禁止になっています。 @retval ResultMediaAccessError 挿さっているのが SD カードではないか、もしくは SD カードが壊れています。 @retval ResultBadFormat SD カードのフォーマットが不正です。SD カードをフォーマットする必要があります。 @retval 上記以外 アプリケーション側の不具合、もしくは想定外のエラーです。 */ Result DeleteExtSaveData(ExtSaveDataId id); //@} /*! @brief アーカイブをアンマウントします。 マウントしたアーカイブが必要なくなった場合は、この関数を呼び出して領域をアンマウントをしてください。 アンマウントを実行する前に、セーブデータを二重化している場合は @ref CommitSaveData の呼び出しを忘れずに行ってく ださい。 アンマウントするアーカイブから開いているファイル・ディレクトリは、全て Finalize を呼び出してから アンマウントす るようにしてください。Flush を行わずに書き込みを行ったファイルを閉じるときは、Flush を忘れずに行なうようにして ください。 @param[in] archiveName アーカイブ名を指定します @return 処理の結果を返します。 @retval 成功 処理に成功しました。戻り値の IsSuccess 関数が true を返す状態です。 @retval ResultNotFound 指定したアーカイブはマウントされていません。@n 製品では発生しないようにするべきエラーです。 @retval 上記以外 アプリケーション側の不具合、もしくは想定外のエラーです。 */ Result Unmount(const char* archiveName); //---------------------------------------- //! @name デバッグ用 //@{ /*! @brief SD カードを直接参照するアーカイブをマウントします（デバッグ用）。 挿入されている SD カードを直接参照するアーカイブをマウントします。SD カードが挿入されていない場合や SD カードが フォーマットされていない場合は失敗します。マウントしていた SD カードが抜かれ、再挿入された SD カードをマウント する場合は、@ref nn::fs::Unmount 関数によりアンマウントした後、再度 @ref nn::fs::MountSdmc 関数を実行する必要が あります。 基本的にデバッグ用途専用であり、製品版ではアクセスすることはできませんのでご注意ください。 @param[in] archiveName アーカイブ名を指定します(省略するオーバロードでは "sdmc:" が暗黙的に指定されます) @return 処理の結果を返します。 @retval 成功 処理に成功しました。戻り値の IsSuccess 関数が true を返す状態です。 @retval ResultMediaNotFound SD カードが見つからないか、もしくは認識できません。 @retval ResultArchiveInvalidated マウント中に SD カードが抜かれた可能性があります。 @retval ResultMediaAccessError 挿さっているのが SD カードではないか、もしくは SD カードが壊れています。 @retval ResultBadFormat SD カードのフォーマットが不正です。SD カードをフォーマットする必要があります。 @retval 上記以外 アプリケーション側の不具合、もしくは想定外のエラーです。 */ Result MountSdmc(const char* archiveName = "sdmc:"); /*! @brief 不揮発性メモリデバイスが劣化した際の動作を擬似的に再現させます（デバッグ用）。 ゲームカード、NAND、SDメモリカードへアクセスする際、劣化したデバイスで生じるウェイト時間を擬似的に再現させます。 （ウェイト時間は リード毎に 0～100ms、ライト毎に 0～380ms です） このエミュレーション機能は debug ビルド または development ビルド では常に有効ですが、release ビルド時 にはデフォ ルトでは無効になるため、入念にデバッグする場合はこの関数で明示的に指定する必要があります。 なお、明示的にエミュレーション機能を OFF にするには、@ref nn::fs::ForceDisableLatencyEmulation 関数を使用します。 */ void ForceEnableLatencyEmulation( void ); /*! @brief 不揮発性メモリデバイスが劣化した際の動作を擬似的に再現させないようにします（デバッグ用）。 ゲームカード、NAND、SDメモリカードへアクセスする際、劣化したデバイスで生じるウェイト時間を擬似的に再現させる機能 を明示的に OFF にします。 このエミュレーション機能は release ビルド時 にはデフォルトでは無効ですが、debug ビルド または development ビルド では有効になっているため、この機能の影響を受けたくない場合にはこの関数で明示的に指定する必要があります。 なお、明示的にエミュレーション機能を ON にするには、@ref nn::fs::ForceEnableLatencyEmulation 関数を使用します。 */ void ForceDisableLatencyEmulation( void ); //@} // TODO: その他細かいもの /*! @brief アーカイブの空き容量を取得します。 この関数は、セーブデータアーカイブに対してのみ使用できます。 セーブデータ領域は、512 バイトの固定サイズでデータの管理を行っています。よって、この関数が返す値は 512 バイトの 倍数になっています。@n この関数が 1024 を返したとき、512 バイトのファイルを 2 つ作ることができますが、513 バイトのファイルを 1 つ作成 すると空き容量は 0 になります。 @param[out] pOut アーカイブの空き容量を返します。 @param[in] archiveName アーカイブ名を指定します。 @return 処理の結果を返します。 @retval 成功 処理に成功しました。戻り値の IsSuccess 関数が true を返す状態です。 @retval ResultNotFound 指定したアーカイブはマウントされていません。@n 製品では発生しないようにするべきエラーです。 @retval 上記以外 アプリケーション側の不具合、もしくは想定外のエラーです。 */ Result GetArchiveFreeBytes(s64* pOut, const char* archiveName); }} namespace nn { namespace fs { /*! @brief PC 上のファイルに直接アクセスするための関数を含んだ名前空間です（デバッグ用）。 @ref nn::fs::hio 名前空間内にある関数やクラスを使うためには、libnn_fshio をリンクした上で、予め @ref nn::hio::CTR::Initialize を呼んでおく必要があります。 基本的にデバッグ用途専用であり、製品版ではアクセスすることはできませんのでご注意ください。 */ namespace hio { /*! @brief hio アーカイブをマウントします。 hio アーカイブは hostPath で指定される PC 上の特定のディレクトリ以下を一つのアーカイブと見なすためのアーカイブ で、デバッグ用途にのみ使用することができます。 この関数を使用するためには libnn_fshio をリンクした上で、あらかじめ @ref nn::hio::CTR::Initialize を呼んで HIO を初期化しておく必要があります。HIO の初期化には連続メモリである DeviceMemory を使用してください。 @param[in] archiveName アーカイブ名を指定します。 @param[in] hostPath PC 上のルートディレクトリを指定します。 @param[in] maxFile 同時に開くファイルの最大数を指定します。 @param[in] maxDirectory 同時に開くディレクトリの最大数を指定します。 @param[in] workingMemory アーカイブの動作に使用するメモリ領域の先頭アドレスを指定します。 @param[in] workingMemorySize アーカイブの動作に使用するメモリ領域のサイズを指定します。 @return 処理の結果を返します。 */ Result MountHioArchive(const char* archiveName, const wchar_t* hostPath, size_t maxFile, size_t maxDirectory, void* workingMemory, size_t workingMemorySize); /*! @brief hio アーカイブのマウントに必要なメモリサイズを取得します。 hio アーカイブのマウントに必要なメモリサイズを計算して返します。このサイズは、maxFile で指定される数のファイル と、maxDirectory で指定される数のディレクトリを、同時に開くことができるだけのメモリのサイズも含まれます。 @param[in] maxFile 同時に開くファイルの最大数 @param[in] maxDirectory 同時に開くディレクトリの最大数 @return 計算したメモリサイズを返します。 */ s32 GetHioRequiredMemorySize(size_t maxFile, size_t maxDirectory); }}} #endif