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