1 /*---------------------------------------------------------------------------* 2 Project: Horizon 3 File: fs_FileSystemBase.h 4 5 Copyright (C)2009 Nintendo Co., Ltd. All rights reserved. 6 7 These coded instructions, statements, and computer programs contain 8 proprietary information of Nintendo of America Inc. and/or Nintendo 9 Company Ltd., and are protected by Federal copyright law. They may 10 not be disclosed to third parties or copied or duplicated in any form, 11 in whole or in part, without the prior written consent of Nintendo. 12 13 $Rev: 37220 $ 14 *---------------------------------------------------------------------------*/ 15 16 #ifndef NN_FS_CTR_MPCORE_FS_FILESYSTEMBASE_H_ 17 #define NN_FS_CTR_MPCORE_FS_FILESYSTEMBASE_H_ 18 19 #include <nn/Handle.h> 20 #include <nn/fs/CTR/MPCore/fs_UserFileSystem.h> 21 22 namespace nn { namespace fs { namespace detail { 23 24 class FileSystemBaseImpl : public nn::fs::CTR::MPCore::detail::UserFileSystem 25 { 26 }; 27 28 }}} 29 30 namespace nn { namespace fs { 31 32 //---------------------------------------- 33 //! @name ROM アーカイブ 34 //@{ 35 36 /*! 37 @brief rom アーカイブのマウントに必要なメモリサイズを取得します。 38 39 ビルド時に生成される ROMFS を参照する rom アーカイブのマウントに必要なメモリサイズを計算して返します。@n 40 このサイズは、maxFile で指定される数のファイルと、maxDirectory で指定される数のディレクトリを同時に開くことがで 41 きるだけのメモリのサイズが返されます。@n 42 useCache を true に設定することで、ROMFS のメタデータをメモリにキャッシュするのに必要なメモリサイズも含まれるよ 43 うになります。 44 45 @param[in] maxFile 同時に開くファイルの最大数 46 @param[in] maxDirectory 同時に開くディレクトリの最大数 47 @param[in] useCache メタ情報をメモリにキャッシュするなら true、しないなら false 48 49 @return 計算したメモリサイズを返します。 50 */ 51 s32 GetRomRequiredMemorySize(size_t maxFile, size_t maxDirectory, bool useCache = true); 52 53 /*! 54 @brief rom アーカイブをマウントします。 55 56 ビルド時に生成される ROMFS を参照する rom アーカイブをマウントします。@n 57 rom アーカイブに対し、maxFile で指定された数のファイルを同時に開くことができ、maxDirectory で指定された数のディ 58 レクトリを同時に開けるようになります。@n 59 60 workingMemory で渡される領域は、@ref GetRomRequiredMemorySize 関数で計算されたサイズ以上である必要があります。@n 61 useCache を true に設定することで、ROMFS のメタデータをメモリにキャッシュします。これにより、ファイルを開いたり、 62 ディレクトリの走査をするのにかかる時間が短縮されます。但し、必要なメモリサイズは増加します。 63 64 @param[in] archiveName アーカイブ名を指定します(省略するオーバロードでは "rom:" が暗黙的に指定されます) 65 @param[in] maxFile 同時に開くファイルの最大数 66 @param[in] maxDirectory 同時に開くディレクトリの最大数 67 @param[in] workingMemory rom アーカイブの動作に使用するメモリ領域の先頭アドレス 68 @param[in] workingMemorySize rom アーカイブの動作に使用するメモリ領域のサイズ 69 @param[in] useCache メタ情報をメモリにキャッシュするなら true、しないなら false 70 71 @return 処理の結果を返します。 72 @retval 成功 処理に成功しました。戻り値の IsSuccess 関数が true を返す状態です。 73 @retval ResultNotFound ROMFS が存在しません。RSF ファイルが正しく記述されているか確かめてください。@n 74 製品では発生しないようにするべきエラーです。 75 @retval ResultAlreadyExists 指定したアーカイブ名は、既にマウントされています。@n 76 製品では発生しないようにするべきエラーです。 77 @retval ResultNotEnoughSpace workingMemory に指定したメモリのサイズが足りません。@n 78 製品では発生しないようにするべきエラーです。 79 @retval 上記以外 想定外のエラー、もしくは致命的なエラーが発生しました。 80 */ 81 Result MountRom(const char* archiveName, size_t maxFile, size_t maxDirectory, void* workingMemory, size_t workingMemorySize, bool useCache = true); 82 Result MountRom(size_t maxFile, size_t maxDirectory, void* workingMemory, size_t workingMemorySize, bool useCache = true); 83 84 //@} 85 86 //---------------------------------------- 87 //! @name セーブデータアーカイブ 88 //@{ 89 90 /*! 91 @brief セーブデータ領域をフォーマットします。 92 93 アプリケーション固有の領域であるセーブデータ領域をフォーマットします。この関数を呼ぶと、既存のセーブデータがあっ 94 た場合には消去されます。 95 96 フォーマットの際には、このセーブデータ領域が持つことのできるファイルの最大数と、ディレクトリの最大数を指定する 97 ことができます。この数を超えて、ファイルやディレクトリを作成することはできませんので注意してください。 98 99 isDuplicateAll を true にしてフォーマットした場合、セーブデータをアンマウントする前に必ず @ref CommitSaveData 100 を呼び出してください。 101 102 @param[in] maxFiles ファイルの最大数を指定します 103 @param[in] maxDirectories ディレクトリの最大数を指定します 104 @param[in] isDuplicateAll セーブデータ領域全体を二重化するかどうかを指定します 105 106 @return 処理の結果を返します。 107 @retval 成功 処理に成功しました。戻り値の IsSuccess 関数が true を返す状態です。 108 @retval ResultNotEnoughSpace セーブデータのサイズに対して、maxFiles, maxDirectories の値が大きすぎます。@n 109 製品では発生しないようにするべきエラーです。 110 @retval 上記以外 想定外のエラー、もしくは致命的なエラーが発生しました。 111 */ 112 Result FormatSaveData(size_t maxFiles, size_t maxDirectories, bool isDuplicateAll = false); 113 114 /*! 115 @brief セーブデータアーカイブをマウントします。 116 117 アプリケーション固有の領域であるセーブデータ領域を、指定されたアーカイブ名でマウントします。セーブデータ領域を 118 使用する前には、セーブデータ領域をフォーマットする必要があります。 119 120 この関数を呼んだ際には必ず戻り値の判定を行い、セーブデータ領域が不正な状態でないか判断をしてください。不正な状 121 態の場合は、@ref FormatSaveData を呼び出してセーブデータ領域の初期化をしてください。その後、もう一度この関数を 122 呼び出してマウントしてください。 123 124 @param[in] archiveName アーカイブ名を指定します(省略した際は "data:" が指定されます) 125 126 @return 処理の結果を返します。 127 @retval 成功 処理に成功しました。戻り値の IsSuccess 関数が true を返す状態です。 128 @retval ResultAlreadyExists 指定したアーカイブ名は、既にマウントされています。@n 129 製品では発生しないようにするべきエラーです。 130 @retval ResultOperationDenied セーブデータは現在マウント中のため、操作は拒否されました。@n 131 製品では発生しないようにするべきエラーです。 132 @retval ResultNotFormatted フォーマットされていません。@ref FormatSaveData を呼び出してフォーマットしてください。 133 @retval ResultBadFormat 不正なフォーマットです。@ref FormatSaveData を呼び出してフォーマットしてください。 134 @retval ResultVerificationFailed 検証に失敗、または改竄を検出しました。@ref FormatSaveData を呼び出してフォーマットしてください。 135 @retval 上記以外 アプリケーション側の不具合、もしくは想定外のエラーです。 136 */ 137 Result MountSaveData(const char* archiveName = "data:"); 138 139 /*! 140 @brief セーブデータの変更をコミットします。 141 142 指定のアーカイブ名でマウントされたセーブデータ領域をコミットし、セーブデータへの変更を確実なものとします。@n 143 この関数を呼ばずにアーカイブをアンマウントしたり、プログラムが停止した場合、前回のコミットからこれまでのセーブ 144 データへの変更は全て巻き戻されます。 145 146 この関数が正常に返ってきた場合、セーブデータへの変更が正しく行われたことが保障されます。この関数の実行中にプロ 147 グラムが中断した場合のセーブデータの状態は、「以前コミットが行われた状態か」もしくは「全ての変更が反映された状 148 態」のどちらかになります。破損したり、中途半端な状態になることはありません。 149 150 @param[in] archiveName アーカイブ名を指定します(省略した際は "data:" が指定されます) 151 152 @return 処理の結果を返します。 153 @retval 成功 処理に成功しました。戻り値の IsSuccess 関数が true を返す状態です。 154 @retval ResultNotFound 指定したアーカイブはマウントされていません。@n 155 製品では発生しないようにするべきエラーです。 156 @retval 上記以外 アプリケーション側の不具合、もしくは想定外のエラーです。 157 */ 158 Result CommitSaveData(const char* archiveName = "data:"); 159 160 //@} 161 162 //---------------------------------------- 163 //! @name 拡張セーブデータアーカイブ 164 //@{ 165 166 /*! 167 @brief 拡張セーブデータ領域を作成します。 168 169 この関数を呼ぶ前には必ず @ref MountExtSaveData を呼び出して、すでに同じ ID の領域が作成されていないか確認を行っ 170 てください。フォーマットを行う場合は、@ref DeleteExtSaveData を呼び出して削除を行なった後、この関数を呼び出して 171 ください。 172 173 アイコンデータには、ctr_makebunner32 により出力された icn ファイルを指定してください。 174 175 拡張セーブデータを作り直さない限り、ここで指定したディレクトリ数、ファイル数、データサイズを超えた書き込みは行 176 うことができません。拡張的な使用を行う場合は注意してください。 177 178 拡張セーブデータ上に作られるファイルは、サイズ変更が不可です。よって @ref FileStream::TryInitialize などでファ 179 イルを作成することができません。ファイルを作成するときは、サイズ指定が可能な @ref TryCreateFile を使用してくだ 180 さい。 181 182 @param[in] id 拡張セーブデータの ID を指定します。 183 @param[in] iconData アイコンデータを指定します。 184 @param[in] iconDataSize アイコンデータのサイズを指定します。 185 @param[in] entryDirectory この拡張セーブデータ領域に格納したいディレクトリ数を指定します。 186 @param[in] entryFile この拡張セーブデータ領域に格納したいファイル数を指定します。 187 188 @return 処理の結果を返します。 189 @retval 成功 処理に成功しました。戻り値の IsSuccess 関数が true を返す状態です。 190 @retval ResultMediaNotFound SD カードが見つからないか、もしくは認識できません。@n 191 @retval ResultNotEnoughSpace SD カードに必要な空き容量がありません。 192 @retval ResultWriteProtected SD カードが書き込み禁止になっています。 193 @retval ResultMediaAccessError 接触不良などの要因により、SD カードアクセス中にエラーが発生しました。 194 @retval ResultNotFormatted エラーにより、作成が中断されました。この状態でマウントを行うと同じエラーが返ります。 195 @retval ResultBadFormat SD カードのフォーマットが不正です。SD カードをフォーマットする必要があります。 196 @retval 上記以外 アプリケーション側の不具合、もしくは想定外のエラーです。 197 */ 198 Result CreateExtSaveData(nn::fs::ExtSaveDataId id, const void* iconData, size_t iconDataSize, u32 entryDirectory, u32 entryFile); 199 200 /*! 201 @brief 拡張セーブデータをマウントします。 202 203 指定した拡張セーブデータ ID の拡張セーブデータ領域を、アーカイブとしてマウントします。 204 205 この関数を呼んだ際には必ず戻り値の判定を行い、拡張セーブデータ領域が不正な状態でないか判断をしてください。不正 206 な状態の場合は、@ref DeleteExtSaveData を呼び出して削除を行なった後、@ref CreateExtSaveData 関数を呼び出して拡 207 張セーブデータ領域を作り直してください。その後、もう一度この関数を呼び出してマウントしてください。 208 209 この関数は、メタ情報と実データの間に食い違いが生じている場合に、内部で復旧処理を行うことがあります。このときに、 210 SD カードが書き込み禁止にされていた場合、エラーとして @ref ResultWriteProtected が返ります。また、SD カード上の 211 ファイル、もしくはディレクトリが、読み取り専用属性にされていた場合、エラーとして @ref ResultOperationDenied が 212 返ります。 213 214 @param[in] archiveName アーカイブ名を指定します。 215 @param[in] id 拡張セーブデータの ID を指定します。 216 217 @return 処理の結果を返します。 218 @retval 成功 処理に成功しました。戻り値の IsSuccess 関数が true を返す状態です。 219 @retval ResultNotFound 拡張セーブデータが見つかりません。@ref CreateExtSaveData を呼び出して作成してください。@n 220 開発中は、id の値が正しいか確認をしてください。 221 @retval ResultMediaNotFound SD カードが見つからないか、もしくは認識できません。 222 @retval ResultOperationDenied 操作が拒否されました。@n 223 このエラーは、内部で復旧処理が行われたときにのみ返ります。 224 @retval ResultWriteProtected SD カードが書き込み禁止になっています。@n 225 このエラーは、内部で復旧処理が行われたときにのみ返ります。 226 @retval ResultMediaAccessError 接触不良などの要因により、SD カードアクセス中にエラーが発生しました。 227 @retval ResultNotFormatted 作成中に失敗した状態です。一旦削除した後、@ref CreateExtSaveData を呼び出して作り直してください。 228 @retval ResultBadFormat 不正なフォーマットです。一旦削除した後、@ref CreateExtSaveData を呼び出して作り直してください。 229 解決しない場合は、SD カードのフォーマットが必要です。 230 @retval ResultVerificationFailed 検証に失敗、または改竄を検出しました。一旦削除した後、@ref CreateExtSaveData を呼び出して作り直してください。 231 @retval 上記以外 アプリケーション側の不具合、もしくは想定外のエラーです。 232 */ 233 Result MountExtSaveData(const char* archiveName, nn::fs::ExtSaveDataId id); 234 235 /*! 236 @brief 拡張セーブデータを削除します。 237 238 引数の拡張セーブデータ ID には、RSF で指定した拡張セーブデータ番号を指定してください。 239 240 @param[in] id 削除する拡張セーブデータの ID を指定します。 241 242 @return 処理の結果を返します。 243 @retval 成功 処理に成功しました。戻り値の IsSuccess 関数が true を返す状態です。 244 @retval ResultNotFound 拡張セーブデータが見つかりません。@ref CreateExtSaveData を呼び出して作成してください。@n 245 開発中は、ExtSaveDataId が正しいか確認をしてください。 246 @retval ResultMediaNotFound SD カードが見つからないか、もしくは認識できません。 247 @retval ResultOperationDenied 指定した拡張セーブデータは現在マウント中のため、操作は途中で失敗しました。 248 @retval ResultWriteProtected SD カードが書き込み禁止になっています。 249 @retval ResultMediaAccessError 接触不良などの要因により、SD カードアクセス中にエラーが発生しました。 250 @retval ResultBadFormat SD カードのフォーマットが不正です。SD カードをフォーマットする必要があります。 251 @retval 上記以外 アプリケーション側の不具合、もしくは想定外のエラーです。 252 */ 253 Result DeleteExtSaveData(ExtSaveDataId id); 254 255 256 //@} 257 258 /*! 259 @brief アーカイブをアンマウントします。 260 261 マウントしたアーカイブが必要なくなった場合は、この関数を呼び出して領域をアンマウントをしてください。 262 263 アンマウントを実行する前に、セーブデータを二重化している場合は @ref CommitSaveData の呼び出しを忘れずに行ってく 264 ださい。 265 266 アンマウントするアーカイブから開いているファイル・ディレクトリは、全て Finalize を呼び出してから アンマウントす 267 るようにしてください。Flush を行わずに書き込みを行ったファイルを閉じるときは、Flush を忘れずに行なうようにして 268 ください。 269 270 @param[in] archiveName アーカイブ名を指定します 271 272 @return 処理の結果を返します。 273 @retval 成功 処理に成功しました。戻り値の IsSuccess 関数が true を返す状態です。 274 @retval ResultNotFound 指定したアーカイブはマウントされていません。@n 275 製品では発生しないようにするべきエラーです。 276 @retval 上記以外 アプリケーション側の不具合、もしくは想定外のエラーです。 277 */ 278 Result Unmount(const char* archiveName); 279 280 281 //---------------------------------------- 282 //! @name デバッグ用 283 //@{ 284 285 /*! 286 @brief SD カードを直接参照するアーカイブをマウントします（デバッグ用）。 287 288 挿入されている SD カードを直接参照するアーカイブをマウントします。SD カードが挿入されていない場合や SD カードが 289 フォーマットされていない場合は失敗します。マウントしていた SD カードが抜かれ、再挿入された SD カードをマウント 290 する場合は、@ref nn::fs::Unmount 関数によりアンマウントした後、再度 @ref nn::fs::MountSdmc 関数を実行する必要が 291 あります。 292 293 基本的にデバッグ用途専用であり、製品版ではアクセスすることはできませんのでご注意ください。 294 295 @param[in] archiveName アーカイブ名を指定します(省略した際は "sdmc:" が指定されます) 296 297 @return 処理の結果を返します。 298 @retval 成功 処理に成功しました。戻り値の IsSuccess 関数が true を返す状態です。 299 @retval ResultMediaNotFound SD カードが見つからないか、もしくは認識できません。 300 @retval ResultAlreadyExists 指定したアーカイブ名は、既にマウントされています。@n 301 製品では発生しないようにするべきエラーです。 302 @retval ResultArchiveInvalidated マウント中に SD カードが抜かれた可能性があります。 303 @retval ResultMediaAccessError 接触不良などの要因により、SD カードアクセス中にエラーが発生しました。 304 @retval ResultBadFormat SD カードのフォーマットが不正です。SD カードをフォーマットする必要があります。 305 @retval 上記以外 アプリケーション側の不具合、もしくは想定外のエラーです。 306 */ 307 Result MountSdmc(const char* archiveName = "sdmc:"); 308 309 /*! 310 @brief 不揮発性メモリデバイスが劣化した際の動作を擬似的に再現させます（デバッグ用）。 311 312 ゲームカード、NAND、SDメモリカードへアクセスする際、劣化したデバイスで生じるウェイト時間を擬似的に再現させます。 313 （ウェイト時間は リード毎に 0～100ms、ライト毎に 0～380ms です） 314 315 このエミュレーション機能は debug ビルド、または development ビルドでは常に有効ですが、release ビルド時にはデフォ 316 ルトでは無効になるため、入念にデバッグする場合はこの関数で明示的に指定する必要があります。 317 318 なお、明示的にエミュレーション機能を OFF にするには、@ref nn::fs::ForceDisableLatencyEmulation 関数を使用します。 319 */ 320 void ForceEnableLatencyEmulation( void ); 321 322 /*! 323 @brief 不揮発性メモリデバイスが劣化した際の動作を擬似的に再現させないようにします（デバッグ用）。 324 325 ゲームカード、NAND、SDメモリカードへアクセスする際、劣化したデバイスで生じるウェイト時間を擬似的に再現させる機能 326 を明示的に OFF にします。 327 328 このエミュレーション機能は release ビルド時にはデフォルトでは無効ですが、debug ビルド、または development ビルド 329 では有効になっているため、この機能の影響を受けたくない場合にはこの関数で明示的に指定する必要があります。 330 331 なお、明示的にエミュレーション機能を ON にするには、@ref nn::fs::ForceEnableLatencyEmulation 関数を使用します。 332 */ 333 void ForceDisableLatencyEmulation( void ); 334 335 //@} 336 337 // TODO: その他細かいもの 338 339 340 /*! 341 @brief アーカイブの空き容量を取得します。 342 343 この関数は、セーブデータアーカイブに対してのみ使用できます。 344 345 セーブデータ領域は、512 バイトの固定サイズでデータの管理を行っています。よって、この関数が返す値は 512 バイトの 346 倍数になっています。@n 347 この関数が 1024 を返したとき、512 バイトのファイルを 2 つ作ることができますが、513 バイトのファイルを 1 つ作成 348 すると空き容量は 0 になります。 349 350 @param[out] pOut アーカイブの空き容量を返します。 351 @param[in] archiveName アーカイブ名を指定します。 352 353 @return 処理の結果を返します。 354 @retval 成功 処理に成功しました。戻り値の IsSuccess 関数が true を返す状態です。 355 @retval ResultNotFound 指定したアーカイブはマウントされていません。@n 356 製品では発生しないようにするべきエラーです。 357 @retval 上記以外 アプリケーション側の不具合、もしくは想定外のエラーです。 358 */ 359 Result GetArchiveFreeBytes(s64* pOut, const char* archiveName); 360 361 }} 362 363 364 namespace nn { namespace fs { 365 366 /*! @brief PC 上のファイルに直接アクセスするための関数を含んだ名前空間です（デバッグ用）。 367 368 @ref nn::fs::hio 名前空間内にある関数やクラスを使うためには、libnn_fshio をリンクした上で、予め @ref nn::hio::CTR::Initialize 369 を呼んでおく必要があります。 370 371 基本的にデバッグ用途専用であり、製品版ではアクセスすることはできませんのでご注意ください。 372 */ 373 namespace hio { 374 375 /*! 376 @brief hio アーカイブをマウントします。 377 378 hio アーカイブは hostPath で指定される PC 上の特定のディレクトリ以下を一つのアーカイブと見なすためのアーカイブ 379 で、デバッグ用途にのみ使用することができます。 380 381 この関数を使用するためには libnn_fshio をリンクした上で、あらかじめ @ref nn::hio::CTR::Initialize を呼んで HIO 382 を初期化しておく必要があります。HIO の初期化には連続メモリである DeviceMemory を使用してください。 383 384 @param[in] archiveName アーカイブ名を指定します。 385 @param[in] hostPath PC 上のルートディレクトリを指定します。 386 @param[in] maxFile 同時に開くファイルの最大数を指定します。 387 @param[in] maxDirectory 同時に開くディレクトリの最大数を指定します。 388 @param[in] workingMemory アーカイブの動作に使用するメモリ領域の先頭アドレスを指定します。 389 @param[in] workingMemorySize アーカイブの動作に使用するメモリ領域のサイズを指定します。 390 391 @return 処理の結果を返します。 392 */ 393 Result MountHioArchive(const char* archiveName, const wchar_t* hostPath, size_t maxFile, size_t maxDirectory, void* workingMemory, size_t workingMemorySize); 394 395 /*! 396 @brief hio アーカイブのマウントに必要なメモリサイズを取得します。 397 398 hio アーカイブのマウントに必要なメモリサイズを計算して返します。このサイズは、maxFile で指定される数のファイル 399 と、maxDirectory で指定される数のディレクトリを、同時に開くことができるだけのメモリのサイズも含まれます。 400 401 @param[in] maxFile 同時に開くファイルの最大数 402 @param[in] maxDirectory 同時に開くディレクトリの最大数 403 404 @return 計算したメモリサイズを返します。 405 */ 406 s32 GetHioRequiredMemorySize(size_t maxFile, size_t maxDirectory); 407 408 }}} 409 410 #endif 411