1 /*---------------------------------------------------------------------------*
2   Project:  Horizon
3   File:     fs_FileStream.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: 32512 $
14  *---------------------------------------------------------------------------*/
15 
16 #ifndef NN_FS_FS_FILESTREAM_H_
17 #define NN_FS_FS_FILESTREAM_H_
18 
19 #include <nn/fs/fs_IStream.h>
20 #include <nn/fs/fs_FileBase.h>
21 #include <nn/fnd/fnd_Storage.h>
22 
23 namespace nn { namespace fs {
24 
25 /*!
26     :category ファイル・ディレクトリ操作
27 
28     @brief ファイルを読み書きするためのクラスです。
29 
30            パス名で指定されたファイルを開き、データを読み書きできます。@n
31            パス名の指定には、ワイド文字列とマルチバイト文字列の両方が使えますが、
32            特別な理由が無い限りは、ワイド文字列を使うようにしてください。
33 
34            拡張セーブデータの場合、このクラスを使用してファイルを新規に作成することはできません。
35            サイズ指定のある @ref TryCreateFile 関数を使用してください。
36 
37 */
38 class FileStream : public IStream, public detail::FileBase, private nn::util::NonCopyable<FileStream>
39 {
40 public:
41 
42     /*!
43         :overload   noparam
44 
45         @brief コンストラクタです。
46 
47                引数の無いオーバロードでは、ファイルは開きません。ファイルを操作するためには、別途 @ref TryInitialize を呼ぶ必要があります。
48     */
FileStream()49     FileStream() {}
50 
51     /*!
52         :overload   wcharparam
53 
54         @brief オブジェクトを構築し、指定されたファイルを開くコンストラクタです。
55 
56                指定されたパスのファイルを指定された OpenMode で開きます。
57 
58                なお、拡張セーブデータの場合、本関数を呼ぶ前に明示的に @ref nn::fs::TryCreateFile で
59                ファイルを作成しておく必要があります。
60 
61                openMode 引数の詳細については、@ref OpenMode を参照してください。
62                拡張セーブデータに対して OPEN_MODE_CREATE を指定するとエラーになる点に注意してください。
63 
64                この関数は処理の結果を返さないため、アプリケーション側でエラーハンドリングを行なうことができません。
65                rom アーカイブ以外では @ref TryInitialize を使用してください。
66 
67         @param[in] pathName 開くファイルのパス
68         @param[in] openMode ファイルを開くモード
69     */
FileStream(const wchar_t * pathName,bit32 openMode)70     FileStream(const wchar_t* pathName, bit32 openMode) : detail::FileBase(pathName, openMode) {}
71 
72     /*!
73         :overload   charparam
74 
75         @brief オブジェクトを構築し、指定されたファイルを開くコンストラクタです。
76 
77                指定されたパスのファイルを指定された OpenMode で開きます。@n
78                この関数では、内部でパス名をマルチバイト文字列からワイド文字列に変換するために、
79                大きくスタック上にバッファを取るので、スタックの大きさには注意してください。
80 
81                なお、拡張セーブデータの場合、本関数を呼ぶ前に明示的に @ref nn::fs::TryCreateFile で
82                ファイルを作成しておく必要があります。
83 
84                openMode 引数の詳細については、@ref OpenMode を参照してください。
85                拡張セーブデータに対して OPEN_MODE_CREATE を指定するとエラーになる点に注意してください。
86 
87                この関数は処理の結果を返さないため、アプリケーション側でエラーハンドリングを行なうことができません。
88                rom アーカイブ以外では @ref TryInitialize を使用してください。
89 
90         @param[in] pathName 開くファイルのパス
91         @param[in] openMode ファイルを開くモード
92     */
FileStream(const char * pathName,bit32 openMode)93     FileStream(const char* pathName, bit32 openMode) : detail::FileBase(pathName, openMode) {}
94 
95     /*!
96         :overload   wcharparam
97 
98         @brief 指定されたファイルを開きます。
99 
100                指定されたパスのファイルを指定された OpenMode で開きます。@n
101                指定されたパスにファイルが存在しない場合は、ファイルを作成してから書き込み専用で開きます。
102                既にこのオブジェクトでファイルを開いている場合に呼ぶことはできません。
103 
104                なお、拡張セーブデータの場合、本関数を呼ぶ前に明示的に @ref nn::fs::TryCreateFile で
105                ファイルを作成しておく必要があります。
106 
107                openMode 引数の詳細については、@ref OpenMode を参照してください。
108                拡張セーブデータに対して OPEN_MODE_CREATE を指定するとエラーになる点に注意してください。
109 
110                この関数は処理の結果を返さないため、アプリケーション側でエラーハンドリングを行なうことができません。
111                rom アーカイブ以外では @ref TryInitialize を使用してください。
112 
113         @param[in] pathName 開くファイルのパス
114         @param[in] openMode ファイルを開くモード
115     */
Initialize(const wchar_t * pathName,bit32 openMode)116     void Initialize(const wchar_t* pathName, bit32 openMode) { detail::FileBase::Initialize(pathName, openMode); }
117 
118     /*!
119         :overload   charparam
120 
121         @brief 指定されたファイルを開きます。
122 
123                指定されたパスのファイルを指定された OpenMode で開きます。@n
124                指定されたパスにファイルが存在しない場合は、ファイルを作成してから書き込み専用で開きます。
125                既にこのオブジェクトでファイルを開いている場合に呼ぶことはできません。@n
126                この関数では、内部でパス名をマルチバイト文字列からワイド文字列に変換するために、
127                大きくスタック上にバッファを取るので、スタックの大きさには注意してください。
128 
129                なお、拡張セーブデータの場合、本関数を呼ぶ前に明示的に @ref nn::fs::TryCreateFile で
130                ファイルを作成しておく必要があります。
131 
132                openMode 引数の詳細については、@ref OpenMode を参照してください。
133                拡張セーブデータに対して OPEN_MODE_CREATE を指定するとエラーになる点に注意してください。
134 
135                この関数は処理の結果を返さないため、アプリケーション側でエラーハンドリングを行なうことができません。
136                rom アーカイブ以外では @ref TryInitialize を使用してください。
137 
138         @param[in] pathName 開くファイルのパス
139         @param[in] openMode ファイルを開くモード
140     */
Initialize(const char * pathName,bit32 openMode)141     void Initialize(const char* pathName, bit32 openMode) { detail::FileBase::Initialize(pathName, openMode); }
142 
143     /*!
144         :overload   wcharparam
145 
146         @brief 指定されたファイルを開きます。
147 
148                指定されたパスのファイルを指定された OpenMode で開きます。@n
149                指定されたパスにファイルが存在しない場合は、ファイルを作成してから書き込み専用で開きます。
150                ファイルを開く途中でエラーが発生した場合は、そのエラーを返します。
151                既にこのオブジェクトでファイルを開いている場合に呼ぶことはできません。
152 
153                なお、拡張セーブデータの場合、本関数を呼ぶ前に明示的に @ref nn::fs::TryCreateFile で
154                ファイルを作成しておく必要があります。
155 
156                openMode 引数の詳細については、@ref OpenMode を参照してください。
157                拡張セーブデータに対して OPEN_MODE_CREATE を指定するとエラーになる点に注意してください。
158 
159         @param[in] pathName 開くファイルのパス
160         @param[in] openMode ファイルを開くモード
161 
162         @return 処理の結果を返します。
163     */
TryInitialize(const wchar_t * pathName,bit32 openMode)164     nn::Result TryInitialize(const wchar_t* pathName, bit32 openMode) { return detail::FileBase::TryInitialize(pathName, openMode); }
165 
166     /*!
167         :overload   charparam
168 
169         @brief 指定されたファイルを開きます。
170 
171                指定されたパスのファイルを指定された OpenMode で開きます。@n
172                指定されたパスにファイルが存在しない場合は、ファイルを作成してから書き込み専用で開きます。
173                ファイルを開く途中でエラーが発生した場合は、そのエラーを返します。@n
174                この関数では、内部でパス名をマルチバイト文字列からワイド文字列に変換するために、
175                大きくスタック上にバッファを取るので、スタックの大きさには注意してください。
176 
177                なお、拡張セーブデータの場合、本関数を呼ぶ前に明示的に @ref nn::fs::TryCreateFile で
178                ファイルを作成しておく必要があります。
179 
180                openMode 引数の詳細については、@ref OpenMode を参照してください。
181                拡張セーブデータに対して OPEN_MODE_CREATE を指定するとエラーになる点に注意してください。
182 
183         @param[in] pathName 開くファイルのパス
184         @param[in] openMode ファイルを開くモード
185 
186         @return 処理の結果を返します。
187     */
TryInitialize(const char * pathName,bit32 openMode)188     nn::Result TryInitialize(const char* pathName, bit32 openMode) { return detail::FileBase::TryInitialize(pathName, openMode); }
189 
190     /*!
191         @brief ファイルを閉じます。
192 
193                ファイルを閉じます。ファイルが開かれていなかった場合は何もしません。
194     */
Finalize()195     void Finalize() { detail::FileBase::Finalize(); }
196 
197     /*!
198         @brief デストラクタです。
199 
200                ファイルが開かれていればファイルを閉じます。
201     */
~FileStream()202     virtual ~FileStream() {}
203 
204     /*!
205         @brief ファイルから指定サイズをバッファに読み込みます。
206 
207                ファイルの現在位置から最大 size バイトデータを読み込み、
208                buffer で指定されたアドレスの領域にコピーします。
209 
210                この関数は処理の結果を返さないため、アプリケーション側でエラーハンドリングを行なうことができません。
211                rom アーカイブ以外では @ref TryRead を使用してください。
212 
213          @param[in] buffer コピー先のバッファへのポインタ
214          @param[in] size コピーする最大バイト数
215 
216          @return 実際にコピーしたバイト数を返します。ファイルの終端に達したときは 0 を返します。
217     */
Read(void * buffer,size_t size)218     virtual s32 Read(void* buffer, size_t size) { return detail::FileBase::Read(buffer, size); }
219 
220     /*!
221         @brief ファイルから指定サイズをバッファに読み込みます。
222 
223                ファイルの現在位置から最大 size バイトデータを読み込み、
224                buffer で指定されたアドレスの領域にコピーします。
225 
226          @param[out] pOut 実際にコピーしたバイト数が格納されます。ファイルの終端に達したときは 0 が格納されます。
227          @param[in] buffer コピー先のバッファへのポインタ
228          @param[in] size コピーする最大バイト数
229 
230          @return 処理の結果を返します。
231     */
TryRead(s32 * pOut,void * buffer,size_t size)232     virtual Result TryRead(s32* pOut, void* buffer, size_t size) { return detail::FileBase::TryRead(pOut, buffer, size); }
233 
234     /*!
235         @brief バッファから指定サイズをファイルに書き込みます。
236 
237                buffer で指定されたアドレスの領域にから、
238                最大 size バイトをファイルに書き込みます。
239 
240                引数の flush に false を指定したときは、@ref Finalize を呼び出すまでに flush を true にしてこの関数を呼び出すか、
241                @ref TryFlush 関数を呼び出してください。
242 
243                この関数は処理の結果を返さないため、アプリケーション側でエラーハンドリングを行なうことができません。
244                rom アーカイブ以外では @ref TryWrite を使用してください。
245 
246          @param[in] buffer 書き込むデータが含まれているバッファへのポインタ
247          @param[in] size ファイルに書き込む最大バイト数
248          @param[in] flush デバイスへの書き戻しを行なうか指定します。
249 
250          @return 実際に書き込んだバイト数を返します。
251     */
252     virtual s32 Write(const void* buffer, size_t size, bool flush=true) { return detail::FileBase::Write(buffer, size, flush); }
253 
254     /*!
255         @brief バッファから指定サイズをファイルに書き込みます。
256 
257                buffer で指定されたアドレスの領域にから、
258                最大 size バイトをファイルに書き込みます。
259 
260                引数の flush に false を指定したときは、@ref Finalize を呼び出すまでに flush を true にしてこの関数を呼び出すか、
261                @ref TryFlush 関数を呼び出してください。
262 
263          @param[out] pOut 実際に書き込んだバイト数が格納されます。
264          @param[in] buffer 書き込むデータが含まれているバッファへのポインタ
265          @param[in] size ファイルに書き込む最大バイト数
266          @param[in] flush デバイスへの書き戻しを行なうか指定します。
267 
268          @return 処理の結果を返します。
269     */
270     virtual Result TryWrite(s32* pOut, const void* buffer, size_t size, bool flush=true) { return detail::FileBase::TryWrite(pOut, buffer, size, flush); }
271 
272     /*!
273         @brief ファイルの読み込み・書き込み位置を変更します。
274 
275                base で指定された位置から position 離れた場所に読み込み・書き込み位置を設定します。
276 
277                この関数は処理の結果を返さないため、アプリケーション側でエラーハンドリングを行なうことができません。
278                rom アーカイブ以外では @ref TrySeek を使用してください。
279 
280         @param[in] base 読み込み・書き込み位置の変更する基準を指定します。
281         @param[in] position 読み込み・書き込み位置の変更する位置を指定します。
282     */
Seek(s64 position,PositionBase base)283     virtual void Seek(s64 position, PositionBase base) { detail::FileBase::Seek(position, base); }
284 
285     /*!
286         @brief ファイルの読み出し位置を変更します。
287 
288                base で指定された位置から position 離れた場所に読み出し位置を設定します。
289 
290         @param[in] base 読み出し位置の変更する基準を指定します。
291         @param[in] position 読み出し位置の変更する位置を指定します。
292 
293         @return 処理の結果を返します。
294     */
TrySeek(s64 position,PositionBase base)295     virtual Result TrySeek(s64 position, PositionBase base) { return detail::FileBase::TrySeek(position, base); }
296 
297     /*!
298         @brief ファイル先頭から数えた現在の読み出し位置を取得します。
299 
300                この関数は処理の結果を返さないため、アプリケーション側でエラーハンドリングを行なうことができません。
301                rom アーカイブ以外では @ref TryGetPosition を使用してください。
302 
303         @return 現在の位置を返します。
304     */
GetPosition()305     virtual s64 GetPosition() const { return detail::FileBase::GetPosition(); }
306 
307     /*!
308         @brief ファイル先頭から数えた現在の読み出し位置を取得します。
309 
310         @param[out] pOut 現在の位置が格納されます。
311 
312         @return 処理の結果を返します。
313     */
TryGetPosition(s64 * pOut)314     virtual Result TryGetPosition(s64* pOut) const { return detail::FileBase::TryGetPosition(pOut); }
315 
316     /*!
317         @brief ファイル先頭から数えた現在の読み出し位置を設定します。
318 
319                この関数は処理の結果を返さないため、アプリケーション側でエラーハンドリングを行なうことができません。
320                rom アーカイブ以外では @ref TrySetPosition を使用してください。
321 
322         @param[in] position 読み出し位置を指定します。
323     */
SetPosition(s64 position)324     virtual void SetPosition(s64 position) { detail::FileBase::SetPosition(position); }
325 
326     /*!
327         @brief ファイル先頭から数えた現在の読み出し位置を設定します。
328 
329         @param[in] position 読み出し位置を指定します。
330 
331         @return 処理の結果を返します。
332     */
TrySetPosition(s64 position)333     virtual Result TrySetPosition(s64 position) { return detail::FileBase::TrySetPosition(position); }
334 
335     /*!
336         @brief ファイルサイズを取得します。
337 
338                この関数は処理の結果を返さないため、アプリケーション側でエラーハンドリングを行なうことができません。
339                rom アーカイブ以外では @ref TryGetSize を使用してください。
340 
341         @return ファイルサイズを返します。
342     */
GetSize()343     virtual s64 GetSize() const { return detail::FileBase::GetSize(); }
344 
345     /*!
346         @brief ファイルサイズを取得します。
347 
348         @param[out] pOut ファイルサイズが格納されます。
349 
350         @return 処理の結果を返します。
351     */
TryGetSize(s64 * pOut)352     virtual Result TryGetSize(s64* pOut) const { return detail::FileBase::TryGetSize(pOut); }
353 
354     /*!
355         @brief ファイルサイズを設定します。
356 
357                この関数は処理の結果を返さないため、アプリケーション側でエラーハンドリングを行なうことができません。
358                rom アーカイブ以外では @ref TrySetSize を使用してください。
359 
360         @param[in] size ファイルサイズを指定します。
361      */
SetSize(s64 size)362     virtual void SetSize(s64 size) { detail::FileBase::SetSize(size); }
363 
364     /*!
365         @brief ファイルサイズを設定します。
366 
367         @param[in] size ファイルサイズを指定します。
368 
369         @return 処理の結果を返します。
370      */
TrySetSize(s64 size)371     virtual Result TrySetSize(s64 size) { return detail::FileBase::TrySetSize(size); }
372 
373     /*!
374         @brief ファイルキャッシュをデバイスに書き戻します。
375 
376                この関数は処理の結果を返さないため、アプリケーション側でエラーハンドリングを行なうことができません。
377                rom アーカイブ以外では @ref TryFlush を使用してください。
378      */
Flush()379     virtual void Flush() { detail::FileBase::Flush(); }
380 
381     /*!
382         @brief ファイルキャッシュをデバイスに書き戻します。
383 
384         @return 処理の結果を返します。
385      */
TryFlush()386     virtual Result TryFlush() { return detail::FileBase::TryFlush(); }
387 };
388 
389 }}
390 
391 #endif
392