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