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

  Copyright (C)2010 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: 32947 $
 *---------------------------------------------------------------------------*/

#ifndef NN_SOCKET_SOCKET_COMMON_H_
#define NN_SOCKET_SOCKET_COMMON_H_

#include <nn/types.h>
#include <nn/os/os_Event.h>
#include <nn/fnd/fnd_Allocator.h>
#include <nn/socket/socket_Types.h>

namespace nn {
namespace socket {

    const char PORT_NAME_USER[]         = "soc:U";
    const char PORT_NAME_PRIVILEGED[]   = "soc:P";

    namespace detail{
        void* Allocate(size_t size, s32 alignment = sizeof(int));
        Result Allocate(void*& p, size_t size, s32 alignment = sizeof(int));
        void Free(void* p);
    }

    /*!
      @name         初期化・終了

      @{
     */

    /*!
      @brief        ソケットライブラリを初期化し、ソケット API を呼び出せるようにします。
                    
      @param[in]    bufferAddress
                                ソケットライブラリが使用するワーク領域のアドレスを指定します。
                                4096 バイト整合である必要があります。デバイスメモリは使用できません。

      @param[in]    bufferSize
                                ワーク領域のサイズを指定します。
                                <br/>
                                ワーク領域は最低でも @ref GetRequiredMemorySize で求めたサイズ以上の
                                大きさが必要です。
                                <br/>
                                通常の使用方法であれば、この値をそのまま使用して問題ありませんが、
                                @ref GetAddrInfo で多数の @ref AddrInfo を確保する場合はさらに大きいサイズを必要に応じて指定してください。

      @param[in]    bufferSizeForSockets
                                ワーク領域のうち、ソケットの送受信バッファの割り当てに使用するサイズを指定します。
                                <br/>
                                各ソケットの送受信バッファは @ref SetSockOpt にて指定できます。
                                デフォルトでは 1 ソケットあたり TCP では 16KB（送信 8KB・受信 8KB）、UDP では 32KB のメモリを割り当てます。
                                ソケットを 1 つだけ使う場合でも、最低 64KB 程度は確保するようにしてください。
                                <br/>
                                ※デフォルトのバッファサイズは今後変更される可能性があります。

      @param[in]    maxSessions ソケット API を扱うスレッド数を指定します。
                                <br/>
                                この値を超えるスレッドからブロックするソケット API を呼ぶことはできません。
                                厳密には同時にブロックする API を呼び出さなければ、
                                この値を超える数のスレッドからソケット API を呼び出すことができますが推奨しません。
                                <br/>
                                API の呼び出し中にセッション数が不足した場合、
                                同期・非同期に関わらず使用できるセッションが空くまでブロックします。
                                また、データの着信や送信の完了などブロックの解除条件が満たされても、セッションが空くまでブロックは解除されません。
                                非同期操作は同期的な挙動になるので特に注意してください。
                                <br/>
                                @ref Poll を使用すると、1 回の API 呼び出しで複数のソケットの状態を確認することができ、
                                ソケット API を扱うスレッド数を減らすことができます。
      
      @return       処理結果。
    */
    Result Initialize(uptr bufferAddress, size_t bufferSize, s32 bufferSizeForSockets, s32 maxSessions);


    /*!
      @brief        ソケットライブラリを初期化に最低限必要なワーク領域のサイズを求めます。

                    ワーク領域は @ref GetAddrInfo で返される @ref AddrInfo の確保に使用される他、API の呼び出し中に一時的に使用されます。
                    <br/>
                    ある程度余分にサイズを予約した上で値を計算していますので、通常はワーク領域がいつ使われているかを気にする必要はありません。
                    <br/>
                    ただし、@ref GetAddrInfo で取得した @ref AddrInfo を @ref FreeAddrInfo で解放せずに
                    連続して @ref GetAddrInfo を呼び出すような場合は、返された値よりもさらに大きなメモリが必要になる場合があります。
                    
      @param[in]    bufferSizeForSockets
                                @ref Initialize の同名引数に指定する数。

      @param[in]    maxSessions @ref Initialize の同名引数に指定する数。
      
      @return       必要なワーク領域のサイズ。
    */
    size_t GetRequiredMemorySize(size_t bufferSizeForSockets, s32 maxSessions);


    /*!
      @brief        ソケットライブラリを初期化し、ソケット API を呼び出せるようにします。

                    過去との互換性のために残されています。メモリの使用効率が悪いため、なるべく使用しないでください。                    
    */
    Result Initialize(nn::fnd::IAllocator& allocator, size_t bufferSize, s32 maxSessions) NN_ATTRIBUTE_DEPRECATED;

    /*!
      @brief        ソケットライブラリを初期化し、ソケット API を呼び出せるようにします。

                    パラメータを省略してすべてデフォルト値を指定します。
                    テスト用途のために用意されています。製品の開発には使用しないでください。
      
      @return       処理結果。
    */
    Result Initialize(void);


    /*!
      @brief        ソケットライブラリを終了し、使用していたリソースを解放します。

                    使用中のソケット記述子はすべて破棄され、ブロック中の API も全てキャンセルされエラーを返します。
                    
      @return       処理結果。
    */
    Result Finalize(void);


    /*!
      :private
      @brief        ソケットのシステム用 API を呼び出せるようにします。
                    Initialize とは別に呼び出す必要があります。

                    使用権限のない一般アプリケーションが呼び出すと常に失敗します。

      @param[in]    bUseSecondarySession    true にすると複数セッションが必要な操作
                                            (Startup 中の AbortStartup) が可能になります

      @return       処理結果。
    */                    
    Result InitializePrivilegedControl(bool bUseSecondarySession = false);


    /*!
      :private
      @brief        システム用 API の利用を終了し、使用していたリソースを解放します。
                     
      @return       処理結果。
    */  
    Result FinalizePrivilegedControl(void);

    /*!
      :private
      @brief        ソケットプロセスに動作の開始を指示します。
      
                    ソケットプロセスは動作を開始すると、IP アドレスの取得を試みます。
                    DHCP でアドレスを取得する設定になっている場合は、
                    取得処理が完了するまでブロックします。
                    
                    事前に InitializePrivilegedControl の呼び出しが必要です。

      @param[in]    config      ソケットの設定

      @return       処理結果。
    */  
    Result Startup(const Config& config);

    /*!
      :private
      @brief        ソケットプロセスに動作の停止を指示します。
                    
                    ソケットプロセスは動作を停止する際に IP アドレスの開放を試みます。
                    停止が完了すると IP アドレスは 0.0.0.0 となり一切の通信ができません。
      
                    事前に InitializePrivilegedControl の呼び出しが必要です。

      @return       処理結果。
    */  
    Result Cleanup(void);

    /*!
      :private
      @brief        @ref Startup を中断します。

      @return       処理結果。
    */  
    Result AbortStartup(void);

    /*!
      @}

      @name         そのほか

      @{
     */

    Result CloseAll(void);
    Result CloseAll(bit32 processId);

    Result SetMaxDescriptor(s32 number);
    Result AllowOtherProcess(s32 s);


    /*!
      :private
      @brief        ソケットプロセスの内部で発生したエラーを取得します。
      
                    事前に InitializePrivilegedControl の呼び出しが必要です。

      @param[out]   err     内部エラーコード

      @return       処理結果。
    */
    Result GetConfigError(s32* err);

    /*!
      :private
      @brief        ソケットプロセスの内部で発生したエラーを通知するイベントを取得します。

                    取得できるイベントは手動リセットイベントです。
                    一度エラーが発生すると再び Startup し直すまでずっとシグナル状態を維持します。
      
                    事前に InitializePrivilegedControl の呼び出しが必要です。

      @param[out]   event   通知のためのイベント。
                            未初期化のイベントを渡してください。

      @return       処理結果。
    */
    Result GetErrorReportEvent(nn::os::Event& event);

    /*!
      @}
     */
}
}

#endif  // ifndef NN_SOCKET_SOCKET_COMMON_H_