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: 32914 $ 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 計算したメモリサイズを返します。rom アーカイブをマウントすることができない状態の場合、0 を返します。 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 ResultNotEnoughSpace workingMemory に指定したメモリのサイズが足りません。@n 76 製品では発生しないようにするべきエラーです。 77 @retval 上記以外 想定外のエラー、もしくは致命的なエラーが発生しました。 78 */ 79 Result MountRom(const char* archiveName, size_t maxFile, size_t maxDirectory, void* workingMemory, size_t workingMemorySize, bool useCache = true); 80 Result MountRom(size_t maxFile, size_t maxDirectory, void* workingMemory, size_t workingMemorySize, bool useCache = true); 81 82 //@} 83 84 //---------------------------------------- 85 //! @name セーブデータアーカイブ 86 //@{ 87 88 /*! 89 @brief セーブデータ領域をフォーマットします。 90 91 アプリケーション固有の領域であるセーブデータ領域をフォーマットします。この関数を呼ぶと、既存のセーブデータがあっ 92 た場合には消去されます。 93 94 フォーマットの際には、このセーブデータ領域が持つことのできるファイルの最大数と、ディレクトリの最大数を指定する 95 ことができます。この数を超えて、ファイルやディレクトリを作成することはできませんので注意してください。 96 97 isDuplicateAll を true にしてフォーマットした場合、セーブデータをアンマウントする前に必ず @ref CommitSaveData 98 を呼び出してください。 99 100 @param[in] maxFiles ファイルの最大数を指定します 101 @param[in] maxDirectories ディレクトリの最大数を指定します 102 @param[in] isDuplicateAll セーブデータ領域全体を二重化するかどうかを指定します 103 104 @return 処理の結果を返します。 105 @retval 成功 処理に成功しました。戻り値の IsSuccess 関数が true を返す状態です。 106 @retval ResultNotEnoughSpace セーブデータのサイズに対して、maxFiles,maxDirectories の値が大きすぎます。@n 107 製品では発生しないようにするべきエラーです。 108 @retval 上記以外 想定外のエラー、もしくは致命的なエラーが発生しました。 109 */ 110 Result FormatSaveData(size_t maxFiles, size_t maxDirectories, bool isDuplicateAll = false); 111 112 /*! 113 @brief セーブデータアーカイブをマウントします。 114 115 アプリケーション固有の領域であるセーブデータ領域を、指定されたアーカイブ名でマウントします。セーブデータ領域を 116 使用する前には、セーブデータ領域をフォーマットする必要があります。 117 118 この関数を呼んだ際には必ず戻り値の判定を行い、セーブデータ領域が不正な状態でないか判断をしてください。不正な状 119 態の場合は、@ref FormatSaveData を呼び出してセーブデータ領域の初期化をしてください。その後、もう一度この関数を 120 呼び出してマウントしてください。 121 122 @param[in] archiveName アーカイブ名を指定します(省略した際は "data:" が指定されます) 123 124 @return 処理の結果を返します。 125 @retval 成功 処理に成功しました。戻り値の IsSuccess 関数が true を返す状態です。 126 @retval ResultNotFormatted フォーマットされていません。@ref FormatSaveData を呼び出してフォーマットしてください。 127 @retval ResultBadFormat 不正なフォーマットです。@ref FormatSaveData を呼び出してフォーマットしてください。 128 @retval ResultVerificationFailed 検証に失敗、または改竄を検出しました。@ref FormatSaveData を呼び出してフォーマットしてください。 129 @retval 上記以外 アプリケーション側の不具合、もしくは想定外のエラーです。 130 */ 131 Result MountSaveData(const char* archiveName = "data:"); 132 133 /*! 134 @brief セーブデータの変更をコミットします。 135 136 指定のアーカイブ名でマウントされたセーブデータ領域をコミットし、書き込んだデータを確実なものとします。@n 137 この関数を呼ばずにアーカイブをアンマウントしたり、プログラムが停止した場合、前回のコミットからこれまでのセーブ 138 データへの変更は全て巻き戻されます。 139 140 この関数が正常に返ってきた場合、セーブデータへの変更が正しく行われたことが保障されます。この関数の実行中にプロ 141 グラムが中断した場合のセーブデータの状態は、「以前コミットが行われた状態か」もしくは「全ての変更が反映された状 142 態」のどちらかになります。破損したり、中途半端な状態になることはありません。 143 144 @param[in] archiveName アーカイブ名を指定します(省略した際は "data:" が指定されます) 145 146 @return 処理の結果を返します。 147 @retval 成功 処理に成功しました。戻り値の IsSuccess 関数が true を返す状態です。 148 @retval ResultNotFound 指定したアーカイブはマウントされていません。@n 149 製品では発生しないようにするべきエラーです。 150 @retval 上記以外 アプリケーション側の不具合、もしくは想定外のエラーです。 151 */ 152 Result CommitSaveData(const char* archiveName = "data:"); 153 154 //@} 155 156 //---------------------------------------- 157 //! @name 拡張セーブデータアーカイブ 158 //@{ 159 160 /*! 161 @brief 拡張セーブデータ領域を作成します。 162 163 id に対応した拡張セーブデータ領域を作成します。引数の拡張セーブデータ ID には、RSF で指定した拡張セーブデータ番 164 号を指定してください。 165 166 この関数を呼ぶ前には必ず @ref MountExtSaveData を呼び出して、すでに同じ ID の領域が作成されていないか確認を行っ 167 てください。フォーマットを行う場合は、@ref DeleteExtSaveData を呼び出して削除を行なった後、この関数を呼び出して 168 ください。 169 170 アイコンデータには、ctr_makebunner32 により出力された icn ファイルを指定してください。 171 172 拡張セーブデータを作り直さない限り、ここで指定したディレクトリ数、ファイル数、データサイズを超えた書き込みは行 173 うことができません。拡張的な使用を行う場合は注意してください。 174 175 拡張セーブデータ上に作られるファイルは、サイズ変更が不可です。よって @ref FileStream::TryInitialize などでファ 176 イルを作成することができません。ファイルを作成するときは、サイズ指定が可能な @ref TryCreateFile を使用してくだ 177 さい。 178 179 @param[in] id 拡張セーブデータの ID を指定します。 180 @param[in] iconData アイコンデータを指定します。 181 @param[in] iconDataSize アイコンデータのサイズを指定します。 182 @param[in] entryDirectory この拡張セーブデータ領域に格納したいディレクトリ数を指定します。 183 @param[in] entryFile この拡張セーブデータ領域に格納したいファイル数を指定します。 184 185 @return 処理の結果を返します。 186 @retval 成功 処理に成功しました。戻り値の IsSuccess 関数が true を返す状態です。 187 @retval ResultMediaNotFound SD カードが見つからないか、もしくは認識できません。 188 @retval ResultNotEnoughSpace SD カードに必要な空き容量がありません。 189 @retval ResultArchiveInvalidated 作成中に SD カードが抜かれた可能性があります。 190 @retval ResultWriteProtected SD カードが書き込み禁止になっています。 191 @retval ResultMediaAccessError 挿さっているのが SD カードではないか、もしくは SD カードが壊れています。 192 @retval ResultNotFormatted エラーにより、作成が中断されました。この状態でマウントを行うと同じエラーが返ります。 193 @retval ResultBadFormat SD カードのフォーマットが不正です。SD カードをフォーマットする必要があります。 194 @retval 上記以外 アプリケーション側の不具合、もしくは想定外のエラーです。 195 */ 196 Result CreateExtSaveData(nn::fs::ExtSaveDataId id, const void* iconData, size_t iconDataSize, u32 entryDirectory, u32 entryFile); 197 198 /*! 199 @brief 拡張セーブデータをマウントします。 200 201 指定した拡張セーブデータ ID の拡張セーブデータ領域を、アーカイブとしてマウントします。 202 203 この関数を呼んだ際には必ず戻り値の判定を行い、拡張セーブデータ領域が不正な状態でないか判断をしてください。不正 204 な状態の場合は、@ref DeleteExtSaveData を呼び出して削除を行なった後、@ref CreateExtSaveData 関数を呼び出して拡 205 張セーブデータ領域を作り直してください。その後、もう一度この関数を呼び出してマウントしてください。 206 207 @param[in] archiveName アーカイブ名を指定します。 208 @param[in] id 拡張セーブデータの ID を指定します。 209 210 @return 処理の結果を返します。 211 @retval 成功 処理に成功しました。戻り値の IsSuccess 関数が true を返す状態です。 212 @retval ResultNotFound 拡張セーブデータが見つかりません。@ref CreateExtSaveData を呼び出して作成してください。@n 213 開発中は、id の値が正しいか確認をしてください。 214 @retval ResultMediaNotFound SD カードが見つからないか、もしくは認識できません。 215 @retval ResultArchiveInvalidated マウント中に SD カードが抜かれた可能性があります。 216 @retval ResultWriteProtected SD カードが書き込み禁止になっています。 217 @retval ResultMediaAccessError 挿さっているのが SD カードではないか、もしくは SD カードが壊れています。 218 @retval ResultNotFormatted 作成中に失敗した状態です。一旦削除した後、@ref CreateExtSaveData を呼び出して作り直してください。 219 @retval ResultBadFormat 不正なフォーマットです。一旦削除した後、@ref CreateExtSaveData を呼び出して作り直してください。 220 解決しない場合は、SD カードのフォーマットが必要です。 221 @retval ResultVerificationFailed 検証に失敗、または改竄を検出しました。一旦削除した後、@ref CreateExtSaveData を呼び出して作り直してください。 222 @retval 上記以外 アプリケーション側の不具合、もしくは想定外のエラーです。 223 */ 224 Result MountExtSaveData(const char* archiveName, nn::fs::ExtSaveDataId id); 225 226 /*! 227 @brief 拡張セーブデータを削除します。 228 229 引数の拡張セーブデータ ID には、RSF で指定した拡張セーブデータ番号を指定してください。 230 231 @param[in] id 削除する拡張セーブデータの ID を指定します。 232 233 @return 処理の結果を返します。 234 @retval 成功 処理に成功しました。戻り値の IsSuccess 関数が true を返す状態です。 235 @retval ResultNotFound 拡張セーブデータが見つかりません。@ref CreateExtSaveData を呼び出して作成してください。@n 236 開発中は、ExtSaveDataId が正しいか確認をしてください。 237 @retval ResultMediaNotFound SD カードが見つからないか、もしくは認識できません。 238 @retval ResultArchiveInvalidated 削除中に SD カードが抜かれた可能性があります。 239 @retval ResultOperationDenied 指定した拡張セーブデータは現在マウント中のため、操作は途中で失敗しました。 240 @retval ResultWriteProtected SD カードが書き込み禁止になっています。 241 @retval ResultMediaAccessError 挿さっているのが SD カードではないか、もしくは SD カードが壊れています。 242 @retval ResultBadFormat SD カードのフォーマットが不正です。SD カードをフォーマットする必要があります。 243 @retval 上記以外 アプリケーション側の不具合、もしくは想定外のエラーです。 244 */ 245 Result DeleteExtSaveData(ExtSaveDataId id); 246 247 248 //@} 249 250 /*! 251 @brief アーカイブをアンマウントします。 252 253 マウントしたアーカイブが必要なくなった場合は、この関数を呼び出して領域をアンマウントをしてください。 254 255 アンマウントを実行する前に、セーブデータを二重化している場合は @ref CommitSaveData の呼び出しを忘れずに行ってく 256 ださい。 257 258 アンマウントするアーカイブから開いているファイル・ディレクトリは、全て Finalize を呼び出してから アンマウントす 259 るようにしてください。Flush を行わずに書き込みを行ったファイルを閉じるときは、Flush を忘れずに行なうようにして 260 ください。 261 262 @param[in] archiveName アーカイブ名を指定します 263 264 @return 処理の結果を返します。 265 @retval 成功 処理に成功しました。戻り値の IsSuccess 関数が true を返す状態です。 266 @retval ResultNotFound 指定したアーカイブはマウントされていません。@n 267 製品では発生しないようにするべきエラーです。 268 @retval 上記以外 アプリケーション側の不具合、もしくは想定外のエラーです。 269 */ 270 Result Unmount(const char* archiveName); 271 272 273 //---------------------------------------- 274 //! @name デバッグ用 275 //@{ 276 277 /*! 278 @brief SD カードを直接参照するアーカイブをマウントします（デバッグ用）。 279 280 挿入されている SD カードを直接参照するアーカイブをマウントします。SD カードが挿入されていない場合や SD カードが 281 フォーマットされていない場合は失敗します。マウントしていた SD カードが抜かれ、再挿入された SD カードをマウント 282 する場合は、@ref nn::fs::Unmount 関数によりアンマウントした後、再度 @ref nn::fs::MountSdmc 関数を実行する必要が 283 あります。 284 285 基本的にデバッグ用途専用であり、製品版ではアクセスすることはできませんのでご注意ください。 286 287 @param[in] archiveName アーカイブ名を指定します(省略するオーバロードでは "sdmc:" が暗黙的に指定されます) 288 289 @return 処理の結果を返します。 290 @retval 成功 処理に成功しました。戻り値の IsSuccess 関数が true を返す状態です。 291 @retval ResultMediaNotFound SD カードが見つからないか、もしくは認識できません。 292 @retval ResultArchiveInvalidated マウント中に SD カードが抜かれた可能性があります。 293 @retval ResultMediaAccessError 挿さっているのが SD カードではないか、もしくは SD カードが壊れています。 294 @retval ResultBadFormat SD カードのフォーマットが不正です。SD カードをフォーマットする必要があります。 295 @retval 上記以外 アプリケーション側の不具合、もしくは想定外のエラーです。 296 */ 297 Result MountSdmc(const char* archiveName = "sdmc:"); 298 299 /*! 300 @brief 不揮発性メモリデバイスが劣化した際の動作を擬似的に再現させます（デバッグ用）。 301 302 ゲームカード、NAND、SDメモリカードへアクセスする際、劣化したデバイスで生じるウェイト時間を擬似的に再現させます。 303 （ウェイト時間は リード毎に 0～100ms、ライト毎に 0～380ms です） 304 305 このエミュレーション機能は debug ビルド または development ビルド では常に有効ですが、release ビルド時 にはデフォ 306 ルトでは無効になるため、入念にデバッグする場合はこの関数で明示的に指定する必要があります。 307 308 なお、明示的にエミュレーション機能を OFF にするには、@ref nn::fs::ForceDisableLatencyEmulation 関数を使用します。 309 */ 310 void ForceEnableLatencyEmulation( void ); 311 312 /*! 313 @brief 不揮発性メモリデバイスが劣化した際の動作を擬似的に再現させないようにします（デバッグ用）。 314 315 ゲームカード、NAND、SDメモリカードへアクセスする際、劣化したデバイスで生じるウェイト時間を擬似的に再現させる機能 316 を明示的に OFF にします。 317 318 このエミュレーション機能は release ビルド時 にはデフォルトでは無効ですが、debug ビルド または development ビルド 319 では有効になっているため、この機能の影響を受けたくない場合にはこの関数で明示的に指定する必要があります。 320 321 なお、明示的にエミュレーション機能を ON にするには、@ref nn::fs::ForceEnableLatencyEmulation 関数を使用します。 322 */ 323 void ForceDisableLatencyEmulation( void ); 324 325 //@} 326 327 // TODO: その他細かいもの 328 329 330 /*! 331 @brief アーカイブの空き容量を取得します。 332 333 この関数は、セーブデータアーカイブに対してのみ使用できます。 334 335 セーブデータ領域は、512 バイトの固定サイズでデータの管理を行っています。よって、この関数が返す値は 512 バイトの 336 倍数になっています。@n 337 この関数が 1024 を返したとき、512 バイトのファイルを 2 つ作ることができますが、513 バイトのファイルを 1 つ作成 338 すると空き容量は 0 になります。 339 340 @param[out] pOut アーカイブの空き容量を返します。 341 @param[in] archiveName アーカイブ名を指定します。 342 343 @return 処理の結果を返します。 344 @retval 成功 処理に成功しました。戻り値の IsSuccess 関数が true を返す状態です。 345 @retval ResultNotFound 指定したアーカイブはマウントされていません。@n 346 製品では発生しないようにするべきエラーです。 347 @retval 上記以外 アプリケーション側の不具合、もしくは想定外のエラーです。 348 */ 349 Result GetArchiveFreeBytes(s64* pOut, const char* archiveName); 350 351 }} 352 353 354 namespace nn { namespace fs { 355 356 /*! @brief PC 上のファイルに直接アクセスするための関数を含んだ名前空間です（デバッグ用）。 357 358 @ref nn::fs::hio 名前空間内にある関数やクラスを使うためには、libnn_fshio をリンクした上で、予め @ref nn::hio::CTR::Initialize 359 を呼んでおく必要があります。 360 361 基本的にデバッグ用途専用であり、製品版ではアクセスすることはできませんのでご注意ください。 362 */ 363 namespace hio { 364 365 /*! 366 @brief hio アーカイブをマウントします。 367 368 hio アーカイブは hostPath で指定される PC 上の特定のディレクトリ以下を一つのアーカイブと見なすためのアーカイブ 369 で、デバッグ用途にのみ使用することができます。 370 371 この関数を使用するためには libnn_fshio をリンクした上で、あらかじめ @ref nn::hio::CTR::Initialize を呼んで HIO 372 を初期化しておく必要があります。HIO の初期化には連続メモリである DeviceMemory を使用してください。 373 374 @param[in] archiveName アーカイブ名を指定します。 375 @param[in] hostPath PC 上のルートディレクトリを指定します。 376 @param[in] maxFile 同時に開くファイルの最大数を指定します。 377 @param[in] maxDirectory 同時に開くディレクトリの最大数を指定します。 378 @param[in] workingMemory アーカイブの動作に使用するメモリ領域の先頭アドレスを指定します。 379 @param[in] workingMemorySize アーカイブの動作に使用するメモリ領域のサイズを指定します。 380 381 @return 処理の結果を返します。 382 */ 383 Result MountHioArchive(const char* archiveName, const wchar_t* hostPath, size_t maxFile, size_t maxDirectory, void* workingMemory, size_t workingMemorySize); 384 385 /*! 386 @brief hio アーカイブのマウントに必要なメモリサイズを取得します。 387 388 hio アーカイブのマウントに必要なメモリサイズを計算して返します。このサイズは、maxFile で指定される数のファイル 389 と、maxDirectory で指定される数のディレクトリを、同時に開くことができるだけのメモリのサイズも含まれます。 390 391 @param[in] maxFile 同時に開くファイルの最大数 392 @param[in] maxDirectory 同時に開くディレクトリの最大数 393 394 @return 計算したメモリサイズを返します。 395 */ 396 s32 GetHioRequiredMemorySize(size_t maxFile, size_t maxDirectory); 397 398 }}} 399 400 #endif 401