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: 33385 $ 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 カードが見つからないか、もしくは認識できません。@n 188 @retval ResultNotEnoughSpace SD カードに必要な空き容量がありません。 189 @retval ResultArchiveInvalidated 作成中に SD カードが抜かれた可能性があります。 190 @retval ResultWriteProtected SD カードが書き込み禁止になっています。 191 @retval ResultMediaAccessError 接触不良などの要因により、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 ResultWriteProtected SD カードが書き込み禁止になっています。 216 @retval ResultMediaAccessError 接触不良などの要因により、SD カードアクセス中にエラーが発生しました。 217 @retval ResultNotFormatted 作成中に失敗した状態です。一旦削除した後、@ref CreateExtSaveData を呼び出して作り直してください。 218 @retval ResultBadFormat 不正なフォーマットです。一旦削除した後、@ref CreateExtSaveData を呼び出して作り直してください。 219 解決しない場合は、SD カードのフォーマットが必要です。 220 @retval ResultVerificationFailed 検証に失敗、または改竄を検出しました。一旦削除した後、@ref CreateExtSaveData を呼び出して作り直してください。 221 @retval 上記以外 アプリケーション側の不具合、もしくは想定外のエラーです。 222 */ 223 Result MountExtSaveData(const char* archiveName, nn::fs::ExtSaveDataId id); 224 225 /*! 226 @brief 拡張セーブデータを削除します。 227 228 引数の拡張セーブデータ ID には、RSF で指定した拡張セーブデータ番号を指定してください。 229 230 @param[in] id 削除する拡張セーブデータの ID を指定します。 231 232 @return 処理の結果を返します。 233 @retval 成功 処理に成功しました。戻り値の IsSuccess 関数が true を返す状態です。 234 @retval ResultNotFound 拡張セーブデータが見つかりません。@ref CreateExtSaveData を呼び出して作成してください。@n 235 開発中は、ExtSaveDataId が正しいか確認をしてください。 236 @retval ResultMediaNotFound SD カードが見つからないか、もしくは認識できません。 237 @retval ResultArchiveInvalidated 削除中に SD カードが抜かれた可能性があります。 238 @retval ResultOperationDenied 指定した拡張セーブデータは現在マウント中のため、操作は途中で失敗しました。 239 @retval ResultWriteProtected SD カードが書き込み禁止になっています。 240 @retval ResultMediaAccessError 接触不良などの要因により、SD カードアクセス中にエラーが発生しました。 241 @retval ResultBadFormat SD カードのフォーマットが不正です。SD カードをフォーマットする必要があります。 242 @retval 上記以外 アプリケーション側の不具合、もしくは想定外のエラーです。 243 */ 244 Result DeleteExtSaveData(ExtSaveDataId id); 245 246 247 //@} 248 249 /*! 250 @brief アーカイブをアンマウントします。 251 252 マウントしたアーカイブが必要なくなった場合は、この関数を呼び出して領域をアンマウントをしてください。 253 254 アンマウントを実行する前に、セーブデータを二重化している場合は @ref CommitSaveData の呼び出しを忘れずに行ってく 255 ださい。 256 257 アンマウントするアーカイブから開いているファイル・ディレクトリは、全て Finalize を呼び出してから アンマウントす 258 るようにしてください。Flush を行わずに書き込みを行ったファイルを閉じるときは、Flush を忘れずに行なうようにして 259 ください。 260 261 @param[in] archiveName アーカイブ名を指定します 262 263 @return 処理の結果を返します。 264 @retval 成功 処理に成功しました。戻り値の IsSuccess 関数が true を返す状態です。 265 @retval ResultNotFound 指定したアーカイブはマウントされていません。@n 266 製品では発生しないようにするべきエラーです。 267 @retval 上記以外 アプリケーション側の不具合、もしくは想定外のエラーです。 268 */ 269 Result Unmount(const char* archiveName); 270 271 272 //---------------------------------------- 273 //! @name デバッグ用 274 //@{ 275 276 /*! 277 @brief SD カードを直接参照するアーカイブをマウントします（デバッグ用）。 278 279 挿入されている SD カードを直接参照するアーカイブをマウントします。SD カードが挿入されていない場合や SD カードが 280 フォーマットされていない場合は失敗します。マウントしていた SD カードが抜かれ、再挿入された SD カードをマウント 281 する場合は、@ref nn::fs::Unmount 関数によりアンマウントした後、再度 @ref nn::fs::MountSdmc 関数を実行する必要が 282 あります。 283 284 基本的にデバッグ用途専用であり、製品版ではアクセスすることはできませんのでご注意ください。 285 286 @param[in] archiveName アーカイブ名を指定します(省略した際は "sdmc:" が指定されます) 287 288 @return 処理の結果を返します。 289 @retval 成功 処理に成功しました。戻り値の IsSuccess 関数が true を返す状態です。 290 @retval ResultMediaNotFound SD カードが見つからないか、もしくは認識できません。 291 @retval ResultArchiveInvalidated マウント中に SD カードが抜かれた可能性があります。 292 @retval ResultMediaAccessError 接触不良などの要因により、SD カードアクセス中にエラーが発生しました。 293 @retval ResultBadFormat SD カードのフォーマットが不正です。SD カードをフォーマットする必要があります。 294 @retval 上記以外 アプリケーション側の不具合、もしくは想定外のエラーです。 295 */ 296 Result MountSdmc(const char* archiveName = "sdmc:"); 297 298 /*! 299 @brief 不揮発性メモリデバイスが劣化した際の動作を擬似的に再現させます（デバッグ用）。 300 301 ゲームカード、NAND、SDメモリカードへアクセスする際、劣化したデバイスで生じるウェイト時間を擬似的に再現させます。 302 （ウェイト時間は リード毎に 0～100ms、ライト毎に 0～380ms です） 303 304 このエミュレーション機能は debug ビルド、または development ビルドでは常に有効ですが、release ビルド時にはデフォ 305 ルトでは無効になるため、入念にデバッグする場合はこの関数で明示的に指定する必要があります。 306 307 なお、明示的にエミュレーション機能を OFF にするには、@ref nn::fs::ForceDisableLatencyEmulation 関数を使用します。 308 */ 309 void ForceEnableLatencyEmulation( void ); 310 311 /*! 312 @brief 不揮発性メモリデバイスが劣化した際の動作を擬似的に再現させないようにします（デバッグ用）。 313 314 ゲームカード、NAND、SDメモリカードへアクセスする際、劣化したデバイスで生じるウェイト時間を擬似的に再現させる機能 315 を明示的に OFF にします。 316 317 このエミュレーション機能は release ビルド時にはデフォルトでは無効ですが、debug ビルド、または development ビルド 318 では有効になっているため、この機能の影響を受けたくない場合にはこの関数で明示的に指定する必要があります。 319 320 なお、明示的にエミュレーション機能を ON にするには、@ref nn::fs::ForceEnableLatencyEmulation 関数を使用します。 321 */ 322 void ForceDisableLatencyEmulation( void ); 323 324 //@} 325 326 // TODO: その他細かいもの 327 328 329 /*! 330 @brief アーカイブの空き容量を取得します。 331 332 この関数は、セーブデータアーカイブに対してのみ使用できます。 333 334 セーブデータ領域は、512 バイトの固定サイズでデータの管理を行っています。よって、この関数が返す値は 512 バイトの 335 倍数になっています。@n 336 この関数が 1024 を返したとき、512 バイトのファイルを 2 つ作ることができますが、513 バイトのファイルを 1 つ作成 337 すると空き容量は 0 になります。 338 339 @param[out] pOut アーカイブの空き容量を返します。 340 @param[in] archiveName アーカイブ名を指定します。 341 342 @return 処理の結果を返します。 343 @retval 成功 処理に成功しました。戻り値の IsSuccess 関数が true を返す状態です。 344 @retval ResultNotFound 指定したアーカイブはマウントされていません。@n 345 製品では発生しないようにするべきエラーです。 346 @retval 上記以外 アプリケーション側の不具合、もしくは想定外のエラーです。 347 */ 348 Result GetArchiveFreeBytes(s64* pOut, const char* archiveName); 349 350 }} 351 352 353 namespace nn { namespace fs { 354 355 /*! @brief PC 上のファイルに直接アクセスするための関数を含んだ名前空間です（デバッグ用）。 356 357 @ref nn::fs::hio 名前空間内にある関数やクラスを使うためには、libnn_fshio をリンクした上で、予め @ref nn::hio::CTR::Initialize 358 を呼んでおく必要があります。 359 360 基本的にデバッグ用途専用であり、製品版ではアクセスすることはできませんのでご注意ください。 361 */ 362 namespace hio { 363 364 /*! 365 @brief hio アーカイブをマウントします。 366 367 hio アーカイブは hostPath で指定される PC 上の特定のディレクトリ以下を一つのアーカイブと見なすためのアーカイブ 368 で、デバッグ用途にのみ使用することができます。 369 370 この関数を使用するためには libnn_fshio をリンクした上で、あらかじめ @ref nn::hio::CTR::Initialize を呼んで HIO 371 を初期化しておく必要があります。HIO の初期化には連続メモリである DeviceMemory を使用してください。 372 373 @param[in] archiveName アーカイブ名を指定します。 374 @param[in] hostPath PC 上のルートディレクトリを指定します。 375 @param[in] maxFile 同時に開くファイルの最大数を指定します。 376 @param[in] maxDirectory 同時に開くディレクトリの最大数を指定します。 377 @param[in] workingMemory アーカイブの動作に使用するメモリ領域の先頭アドレスを指定します。 378 @param[in] workingMemorySize アーカイブの動作に使用するメモリ領域のサイズを指定します。 379 380 @return 処理の結果を返します。 381 */ 382 Result MountHioArchive(const char* archiveName, const wchar_t* hostPath, size_t maxFile, size_t maxDirectory, void* workingMemory, size_t workingMemorySize); 383 384 /*! 385 @brief hio アーカイブのマウントに必要なメモリサイズを取得します。 386 387 hio アーカイブのマウントに必要なメモリサイズを計算して返します。このサイズは、maxFile で指定される数のファイル 388 と、maxDirectory で指定される数のディレクトリを、同時に開くことができるだけのメモリのサイズも含まれます。 389 390 @param[in] maxFile 同時に開くファイルの最大数 391 @param[in] maxDirectory 同時に開くディレクトリの最大数 392 393 @return 計算したメモリサイズを返します。 394 */ 395 s32 GetHioRequiredMemorySize(size_t maxFile, size_t maxDirectory); 396 397 }}} 398 399 #endif 400