/*---------------------------------------------------------------------------*
  Project:  Horizon
  File:     hio_SerialChannel.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: 25970 $
 *---------------------------------------------------------------------------*/

#ifndef NN_HIO_CTR_HIO_SERIALCHANNEL_H_
#define NN_HIO_CTR_HIO_SERIALCHANNEL_H_
#ifdef  NN_SWITCH_ENABLE_HOST_IO

/*! @file
    @brief      SerialChannel クラスを定義します。
  
    :include nn/hio.h
*/

#include <nn/types.h>

namespace nn {
namespace hio {
namespace CTR {

    /*!
    @brief      シリアル通信を行うためのチャンネルを表すクラスです。

                PC側でも同一のチャンネルのシリアル通信を開くことでPCと通信することができます。

                接続を作る側が @ref Connect を呼び、接続を待つ側が @ref WaitHost を呼びます。
                例えば、CTR側が Connect を呼んだ場合は、PC側は WaitHost を呼ぶ必要があります。
    */
    class SerialChannel
    {
    public:
        /*!
        @brief  送受信属性を表す列挙体です。
        */
        enum Attribute
        {
            ATTRIBUTE_NONE      = 0,            //!<    属性がないことを示します。
            ATTRIBUTE_NO_WAIT   = (1u << 0),    //!<    データが存在しない場合にブロックしないことを示します。
            ATTRIBUTE_IN_PC     = (1u << 1)     //!<    バッファ状態の取得に PC 側の状態を含めます。
        };

    private:
        s32     m_Ch;

    public:
        /*!
        @brief  コンストラクタです。別途 @ref Open によって、チャンネルを開く必要があります。
        */
        SerialChannel() : m_Ch(-1) {}

        /*!
        @brief  デストラクタです。チャンネルがオープンされている場合は閉じます。
        */
        ~SerialChannel()
        {
            if( m_Ch >= 0 )
            {
                Close();
            }
        }

        /*!
        @brief                  チャンネルを開きます。

        @param[in]  ch          使用するチャンネル番号。
        @param[in]  pWorkMemory ライブラリが使用するワークメモリを指定します。ワークメモリは デバイス用のメモリ である必要があり、サイズは @ref WORKMEMORY_SIZE です。

        @return                 処理の結果を返します。

        */
        Result Open(s32 ch, void* pWorkMemory);


        /*!
        @brief                  チャンネルを閉じます。

        @return                 処理の結果を返します。

        */
        Result Close();

        /*!
        @brief                  ホストに接続します。
                                ホスト側で Wait が呼び出されるまでブロックします。

        @return                 処理の結果を返します。
        */
        Result Connect();


        /*!
        @brief                  ホストからの接続を待ちます。

        @param[in]  attr        接続時の属性。<br>
                                ATTRIBUTE_NONE が指定されている場合は、ホスト側から接続されるまでブロックします。<br>
                                ATTRIBUTE_NO_WAIT が指定されている場合は、ホスト側からの接続を待たずに処理結果を返します。
                                
        @return                 処理の結果を返します。

        接続に成功したときは、@ref ResultConnected と同じResult値が返ります。

        @ref ATTRIBUTE_NO_WAIT を指定していて、まだ接続されていないときは、@ref ResultNoConnected と同じResult値が返ります。

        */
        Result WaitHost(bit32 attr=ATTRIBUTE_NONE);


        /*!
        @brief                  ホストとの接続を切断します。

        @return                 処理の結果を返します。

        */
        Result Disconnect();

        /*!
        @brief                  送信バッファが空になるまで待ちます。
                                ホスト側の受信バッファの状態には関与しません。

        @return                 処理の結果を返します。
        */
        Result Flush();


        /*!
        :overload               withresult

        @brief                  バッファからの読み込み可能サイズを取得し、処理結果を返します。
                                
        @param[out] pSize       データサイズの格納先。
        @param[in]  attr        受信属性。<br>
                                ATTRIBUTE_NONE が指定されている場合、CTR 側のバッファからの読み込み可能サイズを取得します。<br>
                                ATTRIBUTE_IN_PC が指定されている場合、CTR 側と PC 側それぞれのバッファの読み込み可能サイズの合計を取得します。

        @return                 処理結果を返します。
        */
        Result GetReadableSize(size_t* pSize, bit32 attr=ATTRIBUTE_NONE);


        /*!
        :overload               withresult

        @brief                  ホスト側からデータを受信し、処理結果を返します。
                                
        @param[out] pReadSize   実際に受信したバイト数の格納先。
        @param[out] buf         データ受信先のバッファ。
        @param[in]  size        最大受信サイズ。
        @param[in]  attr        受信属性。<br>
                                ATTRIBUTE_NONE が指定されている場合、size で指定したサイズを受信できるか、チャンネルを閉じるまでブロックします。<br>
                                ATTRIBUTE_NO_WAIT が指定されている場合、受信データが亡くなった時点でリターンします。

        @return                 処理結果を返します。
        */
        Result Read(size_t* pReadSize, void* buf, size_t size, bit32 attr=ATTRIBUTE_NONE);

        /*!
        :overload               noresult

        @brief                  ホスト側からデータを受信します。
                                
        @param[out] buf         データ受信先のバッファ。
        @param[in]  size        最大受信サイズ。
        @param[in]  attr        受信属性。<br>
                                ATTRIBUTE_NONE が指定されている場合、size で指定したサイズを受信できるか、チャンネルを閉じるまでブロックします。<br>
                                ATTRIBUTE_NO_WAIT が指定されている場合、受信データが亡くなった時点でリターンします。

        @return                 実際に受信したバイト数を返します。エラーが発生した場合は -1 を返します。
        */
        s32 Read(void* buf, size_t size, bit32 attr=ATTRIBUTE_NONE)
        {
            size_t read;
            return Read(&read, buf, size, attr).IsFailure() ? -1: static_cast<s32>(read);
        }

        /*!
        :overload               withresult

        @brief                  バッファへの書き込み可能サイズを取得し、処理結果を返します。
                                
        @param[out] pSize       データサイズの格納先。
        @param[in]  attr        受信属性。<br>
                                ATTRIBUTE_NONE が指定されている場合、CTR 側のバッファの書き込み可能サイズのみを取得します。<br>
                                ATTRIBUTE_IN_PC が指定されている場合、CTR 側と PC 側それぞれのバッファの書き込み可能サイズの合計を取得します。

        @return                 処理結果を返します。
        */
        Result GetWritableSize(size_t* pSize, bit32 attr=ATTRIBUTE_NONE);

        /*!
        :overload               withresult

        @brief                  ホスト側へデータを送信し、処理結果を返します。
                                
        @param[out] pWrittenSize    実際に送信したバイト数の格納先。
        @param[in]  buf             データ送信元のバッファ。
        @param[in]  size            最大送信サイズ。
        @param[in]  attr            送信属性。<br>
                                    ATTRIBUTE_NONE が指定されている場合、size で指定したサイズを送信するまでブロックします。<br>
                                    ATTRIBUTE_NO_WAIT が指定されている場合、送信バッファがいっぱいになった時点でリターンします。

        @return                     処理結果を返します。
        */
        Result Write(size_t* pWrittenSize, const void* buf, size_t size, bit32 attr=ATTRIBUTE_NONE);

        /*!
        :overload               noresult

        @brief                  ホスト側へデータを送信します。                                
                                
        @param[in]  buf         データ送信元のバッファ。
        @param[in]  size        最大送信サイズ。
        @param[in]  attr        送信属性。<br>
                                ATTRIBUTE_NONE が指定されている場合、size で指定したサイズを送信するまでブロックします。<br>
                                ATTRIBUTE_NO_WAIT が指定されている場合、送信バッファがいっぱいになった時点でリターンします。

        @return                 実際に送信したバイト数を返します。エラーが発生した場合は -1 を返します。
        */
        s32 Write(const void* buf, size_t size, bit32 attr=ATTRIBUTE_NONE)
        {
            size_t written;
            return Write(&written, buf, size,  attr).IsFailure() ? -1: static_cast<s32>(written);
        }
    };

    /*!
        @brief  接続されていないことを表すResultを返します。
        @return Result オブジェクトを返します。
    */
    nn::Result ResultNoConnected();

    /*!
        @brief  接続されたことを表すResultを返します。
        @return Result オブジェクトを返します。
    */
    nn::Result ResultConnected();

    inline nn::Result ResultNoConnected()
    {
        return nn::Result(nn::Result::LEVEL_SUCCESS, nn::Result::SUMMARY_SUCCESS, nn::Result::MODULE_COMMON, 0);
    }

    inline nn::Result ResultConnected()
    {
        return nn::Result(nn::Result::LEVEL_SUCCESS, nn::Result::SUMMARY_SUCCESS, nn::Result::MODULE_COMMON, 1);
    }

}
}
}


#endif  // ifdef NN_SWITCH_ENABLE_HOST_IO
#endif  // ifndef NN_HIO_CTR_HIO_SERIALCHANNEL_H_