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