/*---------------------------------------------------------------------------*
  Project:  Horizon
  File:     fs_FileOutputStream.h

  Copyright (C)2009 Nintendo Co., Ltd.  All rights reserved.

  These coded instructions, statements, and computer programs contain
  proprietary information of Nintendo of America Inc. and/or Nintendo
  Company Ltd., and are protected by Federal copyright law.  They may
  not be disclosed to third parties or copied or duplicated in any form,
  in whole or in part, without the prior written consent of Nintendo.

  $Rev: 31495 $
 *---------------------------------------------------------------------------*/

#ifndef NN_FS_FS_FILEOUTPUTSTREAM_H_
#define NN_FS_FS_FILEOUTPUTSTREAM_H_

#include <nn/fs/fs_IOutputStream.h>
#include <nn/fs/fs_FileBase.h>
#include <nn/fnd/fnd_Storage.h>

namespace nn { namespace fs {

/*!
    :category ファイル・ディレクトリ操作
    @brief ファイルを書き込むためのクラスです。

           パス名で指定されたファイルを開き、データを書き込むことができます。@n
           パス名の指定には、ワイド文字列とマルチバイト文字列の両方が使えますが、
           特別な理由が無い限りは、ワイド文字列を使うようにしてください。

           拡張セーブデータの場合、このクラスを使用してファイルを新規に作成することはできません。
           サイズ指定のある @ref TryCreateFile 関数を使用してください。
*/
class FileOutputStream : public IOutputStream, public detail::FileBase, private nn::util::NonCopyable<FileOutputStream>
{
public:

    /*!
        @brief コンストラクタです。

               引数の無いオーバロードでは、ファイルは開きません。ファイルを操作するためには、別途 @ref TryInitialize を呼ぶ必要があります。

               パス名を指定したオーバロードでは、指定されたパスのファイルを書き込み専用で開き、書き込める状態にします。

    */
    FileOutputStream() {}

    /*!
        @brief オブジェクトを構築し、指定されたファイルを開くコンストラクタです。

               指定されたパスのファイルを書き込み専用で開き、書き込める状態にします。@n
               createIfNotExist 引数に true を指定しておくと、指定されたパスにファイル
               が存在しない場合に、ファイルを作成してから書き込み専用で開きます。

               なお、拡張セーブデータの場合、本関数を呼ぶ前に明示的に @ref nn::fs::TryCreateFile で
               ファイルを作成しておく必要があります。

               この関数は、処理の結果を返さないためエラーハンドリングを行なうことができません。
               基本的に @ref TryInitialize を使うようにしてください。

        @param[in] pathName 開くファイルのパス
        @param[in] createIfNotExist 指定されたパスにファイルが存在しない場合にファイルを作成するかを指定
    */
    FileOutputStream(const wchar_t* pathName, bool createIfNotExist) :
        detail::FileBase(pathName, OPEN_MODE_WRITE | (createIfNotExist ? OPEN_MODE_CREATE : 0)) {}

    /*!
        @brief オブジェクトを構築し、指定されたファイルを開くコンストラクタです。

               指定されたパスのファイルを書き込み専用で開き、書き込める状態にします。@n
               createIfNotExist 引数に true を指定しておくと、指定されたパスにファイル
               が存在しない場合に、ファイルを作成してから書き込み専用で開きます。@n
               この関数では、内部でパス名をマルチバイト文字列からワイド文字列に変換するために、
               大きくスタック上にバッファを取るので、スタックの大きさには注意してください。

               なお、拡張セーブデータの場合、本関数を呼ぶ前に明示的に @ref nn::fs::TryCreateFile で
               ファイルを作成しておく必要があります。

               この関数は、処理の結果を返さないためエラーハンドリングを行なうことができません。
               基本的に @ref TryInitialize を使うようにしてください。

        @param[in] pathName 開くファイルのパス
    */
    FileOutputStream(const char* pathName, bool createIfNotExist) :
        detail::FileBase(pathName, OPEN_MODE_WRITE | (createIfNotExist ? OPEN_MODE_CREATE : 0)) {}

    /*!
        @brief 指定されたファイルを開きます。

               指定されたパスのファイルを書き込み専用で開き、書き込める状態にします。@n
               createIfNotExist 引数に true を指定しておくと、指定されたパスにファイル
               が存在しない場合に、ファイルを作成してから書き込み専用で開きます。
               既にこのオブジェクトでファイルを開いている場合に呼ぶことはできません。

               なお、拡張セーブデータの場合、本関数を呼ぶ前に明示的に @ref nn::fs::TryCreateFile で
               ファイルを作成しておく必要があります。

               この関数は、処理の結果を返さないためエラーハンドリングを行なうことができません。
               基本的に @ref TryInitialize を使うようにしてください。

        @param[in] pathName 開くファイルのパス
    */
    void Initialize(const wchar_t* pathName, bool createIfNotExist)
    { detail::FileBase::Initialize(pathName,  OPEN_MODE_WRITE | (createIfNotExist ? OPEN_MODE_CREATE : 0)); }

    /*!
        @brief 指定されたファイルを開きます。

               指定されたパスのファイルを書き込み専用で開き、書き込める状態にします。@n
               createIfNotExist 引数に true を指定しておくと、指定されたパスにファイル
               が存在しない場合に、ファイルを作成してから書き込み専用で開きます。
               既にこのオブジェクトでファイルを開いている場合に呼ぶことはできません。@n
               この関数では、内部でパス名をマルチバイト文字列からワイド文字列に変換するために、
               大きくスタック上にバッファを取るので、スタックの大きさには注意してください。

               なお、拡張セーブデータの場合、本関数を呼ぶ前に明示的に @ref nn::fs::TryCreateFile で
               ファイルを作成しておく必要があります。

               この関数は、処理の結果を返さないためエラーハンドリングを行なうことができません。
               基本的に @ref TryInitialize を使うようにしてください。

        @param[in] pathName 開くファイルのパス
    */
    void Initialize(const char* pathName, bool createIfNotExist)
    { detail::FileBase::Initialize(pathName,  OPEN_MODE_WRITE | (createIfNotExist ? OPEN_MODE_CREATE : 0)); }

    /*!
        @brief 指定されたファイルを開きます。

               指定されたパスのファイルを書き込み専用で開き、書き込める状態にします。@n
               createIfNotExist 引数に true を指定しておくと、指定されたパスにファイル
               が存在しない場合に、ファイルを作成してから書き込み専用で開きます。
               ファイルを開く途中でエラーが発生した場合は、そのエラーを返します。
               既にこのオブジェクトでファイルを開いている場合に呼ぶことはできません。

               なお、拡張セーブデータの場合、本関数を呼ぶ前に明示的に @ref nn::fs::TryCreateFile で
               ファイルを作成しておく必要があります。

        @param[in] pathName 開くファイルのパス
    */
    nn::Result TryInitialize(const wchar_t* pathName, bool createIfNotExist)
    { return detail::FileBase::TryInitialize(pathName,  OPEN_MODE_WRITE | (createIfNotExist ? OPEN_MODE_CREATE : 0)); }

    /*!
        @brief 指定されたファイルを開きます。

               指定されたパスのファイルを書き込み専用で開き、書き込める状態にします。@n
               createIfNotExist 引数に true を指定しておくと、指定されたパスにファイル
               が存在しない場合に、ファイルを作成してから書き込み専用で開きます。
               ファイルを開く途中でエラーが発生した場合は、そのエラーを返します。@n
               この関数では、内部でパス名をマルチバイト文字列からワイド文字列に変換するために、
               大きくスタック上にバッファを取るので、スタックの大きさには注意してください。

               なお、拡張セーブデータの場合、本関数を呼ぶ前に明示的に @ref nn::fs::TryCreateFile で
               ファイルを作成しておく必要があります。

        @param[in] pathName 開くファイルのパス
    */
    nn::Result TryInitialize(const char* pathName, bool createIfNotExist)
    { return detail::FileBase::TryInitialize(pathName,  OPEN_MODE_WRITE | (createIfNotExist ? OPEN_MODE_CREATE : 0)); }
    /*!
        @brief ファイルを閉じます。

               ファイルを閉じます。ファイルが開かれていなかった場合は何もしません。
    */
    void Finalize() { detail::FileBase::Finalize(); }

    /*!
        @brief デストラクタです。

               ファイルが開かれていればファイルを閉じます。
    */
    virtual ~FileOutputStream() {}

    /*!
        @brief バッファから指定サイズをファイルに書き込みます。

               buffer で指定されたアドレスの領域にから、
               最大 size バイトをファイルに書き込みます。

               引数の flush に false を指定したときは、インスタンスを破棄する前に必ず
               @ref TryFlush 関数を呼び出してください。

               この関数は、処理の結果を返さないためエラーハンドリングを行なうことができません。
               基本的に @ref TryWrite を使うようにしてください。

         @param[in] buffer 書き込むデータが含まれているバッファへのポインタ
         @param[in] size ファイルに書き込む最大バイト数
         @param[in] flush デバイスへの書き戻しを行なうか指定します。

         @return 実際に書き込んだバイト数を返します。
    */
    virtual s32 Write(const void* buffer, size_t size, bool flush=true) { return detail::FileBase::Write(buffer, size, flush); }

    /*!
        @brief バッファから指定サイズをファイルに書き込みます。

               buffer で指定されたアドレスの領域にから、
               最大 size バイトをファイルに書き込みます。

               引数の flush に false を指定したときは、インスタンスを破棄する前に必ず
               @ref TryFlush 関数を呼び出してください。

         @param[out] pOut 実際に書き込んだバイト数が格納されます。
         @param[in] buffer 書き込むデータが含まれているバッファへのポインタ
         @param[in] size ファイルに書き込む最大バイト数
         @param[in] flush デバイスへの書き戻しを行なうか指定します。

         @return 処理の結果を返します。
    */
    virtual Result TryWrite(s32* pOut, const void* buffer, size_t size, bool flush=true) { return detail::FileBase::TryWrite(pOut, buffer, size, flush); }

    /*!
        @brief ファイルの書き込み位置を変更します。

               base で指定された位置から position 離れた場所に書き込み位置を設定します。

               この関数は、処理の結果を返さないためエラーハンドリングを行なうことができません。
               基本的に @ref TrySeek を使うようにしてください。

        @param[in] base 書き込み位置の変更する基準を指定します。
        @param[in] position 書き込み位置の変更する位置を指定します。
    */
    virtual void Seek(s64 position, PositionBase base) { detail::FileBase::Seek(position, base); }
    
    /*!
        @brief ファイルの読み出し位置を変更します。
        
               base で指定された位置から position 離れた場所に読み出し位置を設定します。
               
        @param[in] base 読み出し位置の変更する基準を指定します。
        @param[in] position 読み出し位置の変更する位置を指定します。
        
        @return 処理の結果を返します。
    */
    virtual Result TrySeek(s64 position, PositionBase base) { return detail::FileBase::TrySeek(position, base); }

    /*!
        @brief ファイル先頭から数えた現在の読み出し位置を取得します。
        
               この関数は、処理の結果を返さないためエラーハンドリングを行なうことができません。
               基本的に @ref TryGetPosition を使うようにしてください。

        @return 現在の位置を返します。
    */
    virtual s64 GetPosition() const { return detail::FileBase::GetPosition(); }
    
    /*!
        @brief ファイル先頭から数えた現在の読み出し位置を取得します。
        
        @param[out] pOut 現在の位置が格納されます。
        
        @return 処理の結果を返します。
    */
    virtual Result TryGetPosition(s64* pOut) const { return detail::FileBase::TryGetPosition(pOut); }

    /*!
        @brief ファイル先頭から数えた現在の読み出し位置を設定します。
        
               この関数は、処理の結果を返さないためエラーハンドリングを行なうことができません。
               基本的に @ref TrySetPosition を使うようにしてください。

        @param[in] position 読み出し位置を指定します。
    */
    virtual void SetPosition(s64 position) { detail::FileBase::SetPosition(position); }
    
    /*!
        @brief ファイル先頭から数えた現在の読み出し位置を設定します。
        
        @param[in] position 読み出し位置を指定します。
        
        @return 処理の結果を返します。
    */
    virtual Result TrySetPosition(s64 position) { return detail::FileBase::TrySetPosition(position); }

    /*!
        @brief ファイルサイズを取得します。
        
               この関数は、処理の結果を返さないためエラーハンドリングを行なうことができません。
               基本的に @ref TryGetSize を使うようにしてください。

        @return ファイルサイズを返します。
    */
    virtual s64 GetSize() const { return detail::FileBase::GetSize(); }
    
    /*!
        @brief ファイルサイズを取得します。
        
        @param[out] pOut ファイルサイズが格納されます。
        
        @return 処理の結果を返します。
    */
    virtual Result TryGetSize(s64* pOut) const { return detail::FileBase::TryGetSize(pOut); }

    /*!
        @brief ファイルサイズを設定します。
        
               この関数は、処理の結果を返さないためエラーハンドリングを行なうことができません。
               基本的に @ref TrySize を使うようにしてください。

        @param[in] size ファイルサイズを指定します。
     */
    virtual void SetSize(s64 size) { detail::FileBase::SetSize(size); }

    /*!
        @brief ファイルサイズを設定します。
        
        @param[in] size ファイルサイズを指定します。
        
        @return 処理の結果を返します。
     */
    virtual Result TrySetSize(s64 size) { return detail::FileBase::TrySetSize(size); }

    /*!
        @brief ファイルキャッシュをデバイスに書き戻します。

               この関数は、処理の結果を返さないためエラーハンドリングを行なうことができません。
               基本的に @ref TryFlush を使うようにしてください。
     */
    virtual void Flush() { detail::FileBase::Flush(); }

    /*!
        @brief ファイルキャッシュをデバイスに書き戻します。
        
        @return 処理の結果を返します。
     */
    virtual Result TryFlush() { return detail::FileBase::TryFlush(); }
};

}}

#endif