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