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