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

#ifndef INCLUDE_NN_UDS_CTR_UDS_API_H_
#define INCLUDE_NN_UDS_CTR_UDS_API_H_

/*! @file
    @brief      UDS ライブラリの API 群です。
*/

#include <nn/uds/CTR/uds_Type.h>
#include <nn/uds/CTR/uds_Result.h>
#include <nn/uds/CTR/uds_NetworkDescription.h>

namespace nn {
namespace uds {
namespace CTR {

/*!
  @name     初期化/終了処理関連
  @{
*/

/*!
  @brief        UDS ライブラリを初期化します。他の通信機能を使用中には成功しません。
  
                バックグラウンドでの通信処理を終了させ、 @ref Finalize を実行するまで UDS ライブラリが通信デバイスを
                占有する処理を行うため、長時間ブロックする可能性があります。

  @param[out]   pStatusUpdateEvent  接続状態の更新通知用イベントです。ライブラリ内で自動リセットイベントとして Initialize されます。
  @param[in]    receiveBuffer       UDS ライブラリが使用する受信バッファの先頭を指すポインタです。
                                    4096 Byte整合されたバッファを指定してください。デバイスメモリは使用できません。
                                    バッファに指定したメモリ領域は @ref Finalize が実行完了するまでアクセスが禁止されます。
  @param[in]    bufferSize          受信バッファのサイズです。4096 の倍数を指定してください。
  @return       関数の実行結果を返します。以下に挙げる Result を返します。
  @retval       ResultSuccess                       初期化に成功しました。
  @retval       ResultAlreadyOccupiedWirelessDevice 既に別の通信が行われていて、新規に UDS 通信を開始できない状態です。
  @retval       ResultOutOfResource                 システムリソースが足りません。
  @retval       ResultWirelessOff                   無線 OFF モードです。
*/
nn::Result Initialize( nn::os::Event* pStatusUpdateEvent, void* receiveBuffer, const size_t bufferSize);

/*!
  @brief        UDS ライブラリを終了します。実行後、他の通信機能を利用可能になります。

                @ref Initialize で指定した受信バッファは本 API が実行完了した以降はアプリからアクセス可能になります。

                @ref Initialize で受け取る接続状態の更新通知用イベントはここで Finalize されます。
  @return       無し
*/
void Finalize  ();

/*!
  @}
*/
/*!
  @name     ネットワークの構築/破棄、およびネットワークの接続/切断
  @{
*/

/*!
  @brief        ユニーク ID からローカル通信 ID を生成します。
  
                業務部から割り当てられた 20bit のユニーク ID から UDS 通信で使用する 32bit 値 (ローカル通信 ID) を生成します。

  @param[in]    uniqueId      	ユニークID です。複数タイトル間で通信したい場合はどちらか片方のユニーク ID を指定してください。
  @param[in]    isTrial 		ユニークID が製品版と体験版で共通だった場合の対処用フラグです。製品版-体験版間での通信を行いたくない場合、
								体験版側を true を指定してください。製品版は常に false が指定されるようご注意下さい。
  @return       ローカル通信 IDです。
*/
bit32 CreateLocalCommunicationId( bit32 uniqueId, bool isTrial = false);

/*!
  @brief        新規にネットワークを構築します。

                チャンネルの自動選択などを行うため完了するまでに 800ms 程度を要します。

  @param[in]    subId             通信モード識別用 ID です。アプリが自由に設定可能です。
  @param[in]    maxEntry          ネットワークに接続できるノードの最大数です。自身を含み、最大 @ref NODE_MAX まで指定可能です。
  @param[in]    localId           ローカル通信 ID です。 @ref CreateLocalCommunicationId で生成した値を指定してください。
  @param[in]    passphrase        無線レイヤの暗号化に使用する暗号鍵の種となる文字列です。
                                  UDS では uniqueId と passphrase が一致する場合にのみ通信が成立します。
  @param[in]    passphraseLength  passphrase の長さです。 @ref UDS_PASSPHRASE_LENGTH_MIN 以上、 @ref UDS_PASSPHRASE_LENGTH_MAX 以下の値を指定してください。

  @return       関数の実行結果を返します。以下に挙げる Result を返します。
  @retval       ResultSuccess       ローカル通信の構築に成功し Master として動作を開始しました。
  @retval       ResultNotInitialized  ライブラリが初期化されていません。 nn::uds::Initialize 関数を実行してください。
  @retval       ResultInvalidState  実行可能なステートではありません。STATE_DISCONNECTED 以外で実行した場合に返ります。
  @retval       ResultOutOfRange    指定した引数が指定できる範囲内ではありません。引数の値を適切にして再度実行することで成功する可能性があります。
  @retval       ResultWirelessOff   無線 OFF モードに遷移しました。再初期化が必要です。
  @retval       上記以外            上記以外の理由で失敗しました。
*/
nn::Result CreateNetwork(
        u8 subId,
        u8 maxEntry,
        bit32 localId,
        const char passphrase[],
        size_t passphraseLength ); 

/*!
  @brief        新規にネットワークを構築します。 本関数は、開発時に無線通信に使用するチャンネルを指定したい場合を考慮して用意されたデバッグ用関数です。
                製品実機では channel 引数は無視される点に注意してご利用下さい。

                チャンネルの自動選択などを行うため完了するまでに 800ms 程度を要します。


  @param[in]    subId             通信モード識別用 ID です。アプリが自由に設定可能です。
  @param[in]    maxEntry          ネットワークに接続できるノードの最大数です。自身を含み、最大 @ref NODE_MAX まで指定可能です。
  @param[in]    localId           ローカル通信 ID です。 @ref CreateLocalCommunicationId で生成した値を指定してください。
  @param[in]    passphrase        無線レイヤの暗号化に使用する暗号鍵の種となる文字列です。
                                  UDS では uniqueId と passphrase が一致する場合にのみ通信が成立します。
  @param[in]    passphraseLength  passphrase の長さです。 @ref UDS_PASSPHRASE_LENGTH_MIN 以上、 @ref UDS_PASSPHRASE_LENGTH_MAX 以下の値を指定してください。
  @param[in]    channel           通信に使用するチャンネルです。0(自動), 1,6,11ch のいずれかを指定してください。製品実機で実行した場合は常にチャンネルを自動で選択します。

  @return       関数の実行結果を返します。以下に挙げる Result を返します。
  @retval       ResultSuccess       ローカル通信の構築に成功し Master として動作を開始しました。
  @retval       ResultNotInitialized  ライブラリが初期化されていません。 nn::uds::Initialize 関数を実行してください。
  @retval       ResultInvalidState  実行可能なステートではありません。STATE_DISCONNECTED 以外で実行した場合に返ります。
  @retval       ResultOutOfRange    指定した引数が指定できる範囲内ではありません。引数の値を適切にして再度実行することで成功する可能性があります。
  @retval       ResultWirelessOff   無線 OFF モードに遷移しました。再初期化が必要です。
  @retval       上記以外            上記以外の理由で失敗しました。
*/
nn::Result CreateNetwork(
        u8 subId,
        u8 maxEntry,
        bit32 localId,
        const char passphrase[],
        size_t passphraseLength,
        u8 channel ); 

/*!
  @brief        周囲のネットワークを探索します。

                完了するまでにデフォルトで 330ms を要します。

  @param[out]   pBuffer     発見したネットワークの情報の格納先です。
  @param[in]    bufferSize  バッファの大きさです。ネットワーク 1つあたり 1KB 程度とお見積もりください。
  @param[in]    subId       アプリが自由に設定可能な通信モード識別用 ID です。0xff を指定するとあらゆる SubID を検索します。
  @param[in]    localId     ローカル通信 ID です。 @ref CreateLocalCommunicationId で生成した値を指定してください。
  
  @return       関数の実行結果を返します。以下に挙げる Result を返します。
  @retval       ResultSuccess       ローカル通信の構築に成功し バッファに見つかったネットワークの情報が格納されます。
  @retval       ResultNotInitialized  ライブラリが初期化されていません。 nn::uds::Initialize 関数を実行してください。
  @retval       ResultInvalidState  実行可能なステートではありません。STATE_DISCONNECTED 以外で実行した場合に返ります。
  @retval       ResultOutOfRange    指定した引数が指定できる範囲内ではありません。引数の値を適切にして再度実行することで成功する可能性があります。
  @retval       ResultWirelessOff   無線 OFF モードに遷移しました。再初期化が必要です。
  @retval       上記以外            上記以外の理由で失敗しました。
*/
nn::Result Scan( void* pBuffer, size_t bufferSize, u8 subId, bit32 localId );

/*!
  :private
  @brief        周囲のネットワークを探索します。 スキャンチャンネルを指定しなければならない場合などの特殊な場合にのみ使用する機能です。

                完了するまでにデフォルトで 330ms を要します。

  @param[out]   pBuffer     発見したネットワークの情報の格納先です。
  @param[in]    bufferSize  バッファの大きさです。ネットワーク 1つあたり 1KB 程度とお見積もりください。
  @param[in]    subId       アプリが自由に設定可能な通信モード識別用 ID です。0xff を指定するとあらゆる SubID を検索します。
  @param[in]    localId     ローカル通信 ID です。 @ref CreateLocalCommunicationId で生成した値を指定してください。
  @param[in]    channel     UDS が使用する全てのチャンネルをスキャンします。特定のチャンネルのみスキャンしたい場合にのみセットしてください。
                            (0: UDS が使用する全チャンネル (1,6,11ch) をスキャン) 
  @param[in]    scanTime    1チャンネルあたりのスキャン時間です。通常指定する必要はありません(0: 110ミリ秒) 
  
  @return       関数の実行結果を返します。以下に挙げる Result を返します。
  @retval       ResultSuccess       ローカル通信の構築に成功し バッファに見つかったネットワークの情報が格納されます。
  @retval       ResultNotInitialized  ライブラリが初期化されていません。 nn::uds::Initialize 関数を実行してください。
  @retval       ResultInvalidState  実行可能なステートではありません。STATE_DISCONNECTED 以外で実行した場合に返ります。
  @retval       ResultOutOfRange    指定した引数が指定できる範囲内ではありません。引数の値を適切にして再度実行することで成功する可能性があります。
  @retval       ResultWirelessOff   無線 OFF モードに遷移しました。再初期化が必要です。
  @retval       上記以外            上記以外の理由で失敗しました。
*/
nn::Result Scan( void* pBuffer, size_t bufferSize, u8 subId, bit32 localId, u8 channel, u16 scanTime = 0 );

/*!
  @brief        既存のネットワークに接続します。

                電波状況が悪いほど時間がかかり、完了するまでに最大 800ms 程度を要します。

  @param[in]    networkDescription        ネットワーク情報です。スキャン結果から取得します。
  @param[in]    type                      接続タイプです。
  @param[in]    passphrase                無線レイヤの暗号化に使用する暗号鍵です。
                                          UDS では uniqueId と passphrase が一致する場合にのみ通信が成立します。
  @param[in]    passphraseLength          passphrase の長さです。 @ref UDS_PASSPHRASE_LENGTH_MIN 以上、 @ref UDS_PASSPHRASE_LENGTH_MAX 以下の値を指定してください。
  
  @return       関数の実行結果を返します。以下に挙げる Result を返します。
  @retval       ResultSuccess               接続に成功し、指定した接続タイプとして動作を開始しました。
  @retval       ResultNotInitialized  ライブラリが初期化されていません。 nn::uds::Initialize 関数を実行してください。
  @retval       ResultNotFoundNetwork       接続対象のネットワークが見つかりませんでした。ネットワークが既に破棄されている、もしくは通信範囲から外れた場合に返ります。
  @retval       ResultAlreadyNetworkIsFull  既にネットワークのノード数が最大接続数に達していました。ノード数が減少しない限り接続できません。
  @retval       ResultDeniedFromMaster      Master に接続を拒否されました。Master が接続を拒否している場合に返ります。passphrase が間違っている場合も返ります。
  @retval       ResultConnectionTimeout     一定時間以内に接続が成立しませんでした。電波状況が悪い場合や、Master に過度の通信負荷がかかっている場合に返ります。
  @retval       ResultInvalidState          実行可能なステートではありません。STATE_DISCONNECTED 以外で実行した場合に返ります。
  @retval       ResultOutOfRange            指定した引数が指定できる範囲内ではありません。引数の値を適切にして再度実行することで成功する可能性があります。
  @retval       ResultWirelessOff           無線 OFF モードに遷移しました。再初期化が必要です。
  @retval       上記以外                    上記以外の理由で失敗しました。
*/
nn::Result ConnectNetwork(
        const NetworkDescription& networkDescription,
        ConnectType type,
        const char passphrase[],
        size_t passphraseLength );

/*!
  @brief        指定したノードをネットワークから追放します。 Master のみ実行可能です。

  @param[in]    nodeId  追放したいノードID です。BROADCAST_NODE_ID を指定した場合、接続中の全ての Client を追放します。
  
  @return       関数の実行結果を返します。以下に挙げる Result を返します。
  @retval       ResultSuccess       対象の Client はネットワークから追放されました。
  @retval       ResultNotInitialized  ライブラリが初期化されていません。 nn::uds::Initialize 関数を実行してください。
  @retval       ResultInvalidState  実行可能なステートではありません。Master 状態以外で実行した場合に返ります。
  @retval       ResultWirelessOff   無線 OFF モードに遷移しました。再初期化が必要です。
  @retval       上記以外            上記以外の理由で失敗しました。
*/
nn::Result EjectClient ( u16 nodeId );

/*!
  @brief        Client のネットワークへの接続を不許可にします。現在接続中の Client には影響しません。
                
                通信対戦中は新規に Client が接続することを拒否したい、と言うような用途を想定した接続拒否機能です。
                再び接続を許可したい場合は @ref AllowToConnect を実行してください。
                Master のみ実行可能です。

  @param[in]    isDisallowToReconnect false の場合、一度 Master に接続したことのある Client の再接続が可能になります。
  
  @return       関数の実行結果を返します。以下に挙げる Result を返します。
  @retval       ResultSuccess       処理に成功しました。
  @retval       ResultNotInitialized  ライブラリが初期化されていません。 nn::uds::Initialize 関数を実行してください。
  @retval       ResultInvalidState  実行可能なステートではありません。Master 状態以外で実行した場合に返ります。
  @retval       ResultWirelessOff   無線 OFF モードに遷移しました。再初期化が必要です。
  @retval       上記以外            上記以外の理由で失敗しました。
*/
nn::Result DisallowToConnect(bool isDisallowToReconnect = false);

/*!
  @brief        Client のネットワークへの接続を許可します。
  
                @ref DisallowToConnect で拒否した、Client の接続を再開するための関数です。
                この関数では @ref EjectSpectator による Spectator の接続拒否状態は解除されません。
                Master のみ実行可能です。

  @return       関数の実行結果を返します。以下に挙げる Result を返します。
  @retval       ResultSuccess       処理に成功しました。
  @retval       ResultNotInitialized  ライブラリが初期化されていません。 nn::uds::Initialize 関数を実行してください。
  @retval       ResultInvalidState  実行可能なステートではありません。Master 状態以外で実行した場合に返ります。
  @retval       ResultWirelessOff   無線 OFF モードに遷移しました。再初期化が必要です。
  @retval       上記以外            上記以外の理由で失敗しました。
*/
nn::Result AllowToConnect();

/*!
  @brief        接続している全ての Spectator をネットワークから追放します。
  
                実行後は新規に Spectator が接続することは出来ない状態になります。
                再度 Spectator の接続を許可したい場合は @ref AllowToSpectate を実行してください。
                Master のみ実行可能です。

  @return       関数の実行結果を返します。以下に挙げる Result を返します。
  @retval       ResultSuccess       処理に成功しました。
  @retval       ResultNotInitialized  ライブラリが初期化されていません。 nn::uds::Initialize 関数を実行してください。
  @retval       ResultInvalidState  実行可能なステートではありません。Master 状態以外で実行した場合に返ります。
  @retval       ResultWirelessOff   無線 OFF モードに遷移しました。再初期化が必要です。
  @retval       上記以外            上記以外の理由で失敗しました。
*/
nn::Result EjectSpectator  ( void );
inline nn::Result EjectAudience  ( void ){ return EjectSpectator(); }

/*!
  @brief        Spectator のネットワークへの接続を許可します。
  
                @ref EjectSpectator 実行後に再度 Spectator をネットワークに接続させたい場合にご使用下さい。
                Master のみ実行可能です。

  @return       関数の実行結果を返します。以下に挙げる Result を返します。
  @retval       ResultSuccess       処理に成功しました。
  @retval       ResultNotInitialized  ライブラリが初期化されていません。 nn::uds::Initialize 関数を実行してください。
  @retval       ResultInvalidState  実行可能なステートではありません。Master 状態以外で実行した場合に返ります。
  @retval       ResultWirelessOff   無線 OFF モードに遷移しました。再初期化が必要です。
  @retval       上記以外            上記以外の理由で失敗しました。
*/
nn::Result AllowToSpectate();

/*!
  @brief        ネットワークを破棄します。
  
                接続中の全ての Client、Spectator を追放し、ネットワークを破棄します。
                Master のみ実行可能です。

  @return       関数の実行結果を返します。以下に挙げる Result を返します。
  @retval       ResultSuccess       ネットワークを破棄し、STATE_DISCONNECTED ステートに遷移しました。
  @retval       ResultNotInitialized  ライブラリが初期化されていません。 nn::uds::Initialize 関数を実行してください。
  @retval       ResultInvalidState  実行可能なステートではありません。Master 状態以外で実行した場合に返ります。
  @retval       ResultWirelessOff   無線 OFF モードに遷移しました。再初期化が必要です。
  @retval       上記以外            上記以外の理由で失敗しました。
*/
nn::Result DestroyNetwork ( void );

/*!
  @brief        接続中のネットワークから離脱します。
  
                Client および Spectator のみ実行可能です。
                披切断 (外的要因でネットワークから切断された) を考慮し、ネットワークに接続していない状態でも成功します。

  @return       関数の実行結果を返します。以下に挙げる Result を返します。
  @retval       ResultSuccess       ネットワークを破棄し、STATE_DISCONNECTED ステートに遷移しました。
  @retval       ResultNotInitialized  ライブラリが初期化されていません。 nn::uds::Initialize 関数を実行してください。
  @retval       ResultInvalidState  実行可能なステートではありません。Master 状態以外で実行した場合に返ります。
  @retval       ResultWirelessOff   無線 OFF モードに遷移しました。再初期化が必要です。
  @retval       上記以外            上記以外の理由で失敗しました。
*/
nn::Result DisconnectNetwork  ( void );

/*!
  @}
*/
/*!
  @name     データ送受信関連
  @{
*/

/*!
  @brief        ネットワークの端点 (endpoint) を生成し、対応する descriptor を返します。
  
                [暫定仕様] endpoint は現在 16 個生成可能です。

  @param[out]   pEndpointDesc   生成する endpoint を示す descriptor です。

  @return       関数の実行結果を返します。以下に挙げる Result を返します。
  @retval       ResultSuccess         処理に成功しました。
  @retval       ResultNotInitialized  ライブラリが初期化されていません。 nn::uds::Initialize 関数を実行してください。
  @retval       ResultOutOfResource   既に規定数以上の endpoint が生成されています。既存の endpoint を破棄してください。
  @retval       ResultWirelessOff     無線 OFF モードに遷移しました。再初期化が必要です。
  @retval       上記以外              上記以外の理由で失敗しました。
*/
nn::Result CreateEndpoint( EndpointDescriptor* pEndpointDesc );

/*!
  @brief       最大送信遅延時間を指定します。
  
               システムは物理レイヤの効率を良くするために、サイズの小さなパケットはまとめて送信するようにしています。
               そのため、最大で @ref SendTo で送信したデータは最大で、この関数でセットした期間送信を待つ可能性があります。
               回線効率よりもレイテンシを重視したい場合は @ref SendTo で @ref NO_WAIT を指定することで、この送信遅延を回避する事が出来ます。

               ネットワークに接続していない状態でのみ実行可能です。
  
  @param[in]   maxDelay  最大送信遅延時間です。5ミリ秒～100ミリ秒の範囲で指定してください。デフォルトでは 10 ミリ秒となっています。

  @return       関数の実行結果を返します。以下に挙げる Result を返します。
  @retval       ResultSuccess       処理に成功しました。
  @retval       ResultNotInitialized  ライブラリが初期化されていません。 nn::uds::Initialize 関数を実行してください。
  @retval       ResultInvalidState  実行可能なステートではありません。通信中に実行した場合に返ります。
  @retval       ResultWirelessOff   無線 OFF モードに遷移しました。再初期化が必要です。
  @retval       上記以外            上記以外の理由で失敗しました。
*/
nn::Result SetMaxSendDelay ( nn::fnd::TimeSpan maxDelay );

/*!
  @brief       指定した相手の指定したポートにデータを送信します。
  
               送信処理が完了するまでブロックします。
               option に @ref NO_WAIT , @ref FORCE_DIRECT_BC , @ref FORCE_UNICAST を指定することで、送信方法を指定できます。
               複数のオプションを指定したい場合には OR による複数指定を行ってください。

  @param[in]   endpointDesc 使用する endpoint を示す descriptor です。
  @param[in]   data         送信するデータのポインタです。
  @param[in]   dataSize     送信するデータのサイズです。最大送信サイズは @ref UDS_PACKET_PAYLOAD_MAX_SIZE Byte です。
  @param[in]   destNodeId   送信先です。 BROADCAST_NODE_ID を指定するとデータはブロードキャストされます。
  @param[in]   port         使用するポートです。ポート番号0x00はシステム側で予約されているため使用できません。
  @param[in]   option       送信オプションです。

  @return       関数の実行結果を返します。以下に挙げる Result を返します。
  @retval       ResultSuccess       処理に成功しました。
  @retval       ResultNotInitialized  ライブラリが初期化されていません。 nn::uds::Initialize 関数を実行してください。
  @retval       ResultInvalidState  実行可能なステートではありません。Master もしくは Client 状態以外で実行した場合に返ります。
  @retval       ResultInvalidNode   対象のノードはネットワーク上に存在しません。切断されている可能性があります。
  @retval       ResultTooLarge      dataSize が nn::uds::UDS_PACKET_PAYLOAD_MAX_SIZE を超えています。
  @retval       ResultOutOfRange    指定した引数が指定できる範囲内ではありません。引数の値を適切にして再度実行することで成功する可能性があります。
  @retval       ResultBufferIsFull  NO_WAIT オプションを指定している場合に、無線デバイス内の送信処理能力を超えるパケット送信をした場合に発生します。電波状況が悪い場合には発生頻度が上がります。
  @retval       ResultWirelessOff   無線 OFF モードに遷移しました。再初期化が必要です。
  @retval       上記以外            上記以外の理由で失敗しました。
*/
nn::Result SendTo  ( const EndpointDescriptor& endpointDesc, const void* data, size_t dataSize, u16 destNodeId, u8 port, bit8 option = 0x00 );


/*!
  @brief       endpoint とパケット受信可能な状態にします。
  
               endpoint とポート、ノードID を結びつけます。
               システムは受信用バッファを作成し、以降指定したポートへ送信されたパケットを受信できるようになります。

  @param[in]   pEndpointDesc        使用する Endpoint を示す descriptor です。
  @param[in]   srcNodeId            結びつけるノード ID です。BROADCAST_NODE_ID を指定すると全てのノードと結びつけられます。
  @param[in]   port                 結びつけるポート番号です。ポート番号0x00はシステム側で予約されているため使用できません。
  @param[in]   receiveBufferSize    確保する受信バッファのサイズです。@ref Initialize で確保したメモリブロックから確保されますので、受信バッファの合計が
                                    確保したメモリブロックのサイズよりも大きくならないよう注意してください。
                                    @ref ATTACH_BUFFER_SIZE_MIN Byte以上を指定する必要があり、デフォルトでは @ref ATTACH_BUFFER_SIZE_DEFAULT Byteを確保します。
                                    データサイズを指定する場合は内部で32Byte毎にメモリを確保しているため、32の倍数を指定すると効率的です。

  @return       関数の実行結果を返します。以下に挙げる Result を返します。
  @retval       ResultSuccess         処理に成功しました。
  @retval       ResultNotInitialized  ライブラリが初期化されていません。 nn::uds::Initialize 関数を実行してください。
  @retval       ResultInvalidState    実行可能なステートではありません。
  @retval       ResultOutOfResource   システムリソースが不足している場合、nn::uds::Initialize 関数で指定したバッファから受信バッファが足りなくなった場合に返ります。
  @retval       ResultOutOfRange      指定した引数が指定できる範囲内ではありません。引数の値を適切にして再度実行することで成功する可能性があります。
  @retval       ResultWirelessOff     無線 OFF モードに遷移しました。再初期化が必要です。
  @retval       上記以外              上記以外の理由で失敗しました。
*/
nn::Result Attach  ( EndpointDescriptor* pEndpointDesc, u16 srcNodeId, u8 port, size_t receiveBufferSize = ATTACH_BUFFER_SIZE_DEFAULT );

/*!
  @brief       データを受信します。(送信元アドレス取得機能なし)
  
               引数以外は @ref ReceiveFrom と同機能です。詳細は @ref ReceiveFrom のリファレンスを参照下さい。

  @param[in]   endpointDesc  使用する endpoint を示す descriptor です。 事前に Attach() により、ポート、送信元が結びつけて置く必要があります。
  @param[out]  pBuffer       受信データの格納先です。4 Byte整合されたバッファを指定してください。
  @param[out]  pReceivedSize 受信したデータのサイズです。UDS の最大受信データサイズは @ref UDS_PACKET_PAYLOAD_MAX_SIZE Byteです。
  @param[in]   bufferSize     受信バッファ (pBuffer) のサイズです。
  @param[in]   option        受信オプションです。 @ref NO_WAIT を指定するとデータを受信していない場合でも即時終了します。
                             指定しないとデータを受信、もしくはエラーが発生するまで終了しません。
                             
  @return       関数の実行結果を返します。以下に挙げる Result を返します。
  @retval       ResultSuccess         処理に成功しました。
  @retval       ResultNotInitialized  ライブラリが初期化されていない場合、指定した endpoint が存在しない場合に返ります。
  @retval       ResultInvalidState    実行可能なステートではありません。ネットワークに接続されていない状態で実行すると返ります。
  @retval       ResultNotAuthorized   Attach していない endpoint を指定した場合に返ります。
  @retval       ResultTooLarge        受信したデータよりも bufferSize が小さい場合に返ります。サイズは nn::uds::UDS_PACKET_PAYLOAD_MAX_SIZE であることが望まれます。
  @retval       ResultOutOfRange      指定した引数が指定できる範囲内ではありません。引数の値を適切にして再度実行することで成功する可能性があります。
  @retval       ResultWirelessOff     無線 OFF モードに遷移しました。再初期化が必要です。
  @retval       上記以外              上記以外の理由で失敗しました。
*/
nn::Result Receive     ( const EndpointDescriptor& endpointDesc, void* pBuffer, size_t* pReceivedSize, size_t bufferSize, bit8 option = 0x00 );

/*!
  @brief       データを受信します。
  
               @ref Attach を実行済みの endpoint に送信されたパケットを受信します。
               受信すべきパケットがない場合、関数はブロックします。(エラー発生時を除く)
               option に @ref NO_WAIT を指定した場合には、パケットを受信していない場合でも完了します。

  @param[in]   endpointDesc  使用する endpoint を示す descriptor です。 事前に Attach() により、ポート、送信元が結びつけて置く必要があります。
  @param[out]  pBuffer       受信データの格納先です。4 Byte整合されたバッファを指定してください。
  @param[out]  pReceivedSize 受信したデータのサイズです。UDS の最大受信データサイズは @ref UDS_PACKET_PAYLOAD_MAX_SIZE Byteです。
  @param[out]  pSrcNodeId    送信元ノードIDです。
  @param[in]   bufferSize    受信バッファ (pBuffer) のサイズです。
  @param[in]   option        受信オプションです。 
                             
  @return       関数の実行結果を返します。以下に挙げる Result を返します。
  @retval       ResultSuccess         処理に成功しました。
  @retval       ResultNotInitialized  ライブラリが初期化されていない場合、指定した endpoint が存在しない場合に返ります。
  @retval       ResultInvalidState    実行可能なステートではありません。ネットワークに接続されていない状態で実行すると返ります。
  @retval       ResultNotAuthorized   Attach していない endpoint を指定した場合に返ります。
  @retval       ResultTooLarge        受信したデータよりも bufferSize が小さい場合に返ります。サイズは nn::uds::UDS_PACKET_PAYLOAD_MAX_SIZE であることが望まれます。
  @retval       ResultOutOfRange      指定した引数が指定できる範囲内ではありません。引数の値を適切にして再度実行することで成功する可能性があります。
  @retval       ResultWirelessOff     無線 OFF モードに遷移しました。再初期化が必要です。
  @retval       上記以外              上記以外の理由で失敗しました。
*/
nn::Result ReceiveFrom ( const EndpointDescriptor& endpointDesc, void* pBuffer, size_t* pReceivedSize, u16* pSrcNodeId, size_t bufferSize, bit8 option = 0x00 );

/*!
  @brief       endpoint を破棄します。
  
               @ref Attach を実行済みの endpoint を指定した場合には、受信用バッファを解放します。
               解放された受信バッファは、再度 @ref Attach で利用できますが、アプリケーションがアクセスできるのは @ref Finalize 実行後であることに注意してください。

  @param[in]   pEndpointDesc      endpoint を示す descriptor です。

  @return       関数の実行結果を返します。以下に挙げる Result を返します。
  @retval       ResultSuccess         処理に成功しました。
  @retval       ResultNotInitialized  ライブラリが初期化されていません。 nn::uds::Initialize 関数を実行してください。
  @retval       ResultNotAuthorized   無効な EndpointDescriptor を指定した場合に返ります。
  @retval       上記以外              上記以外の理由で失敗しました。
*/
nn::Result DestroyEndpoint( EndpointDescriptor* pEndpointDesc );

/*!
  @}
*/

/*!
  @brief       自身の MAC アドレスを取得します。(デバッグ用)

               通信機能のデバッグを行う際に、実行中のデバイスの MAC アドレスを調査、取得するための API です。

               MAC アドレスは本体ごとにユニークな値ですが、修理などによって変更されてる可能性があります。
               本体の特定を行いたい場合は @ref nn::cfg::GetTransferableId 関数を使用してください。

  @param[out]   pMacAddress 自身の MAC アドレスです。
  
  @return       関数の実行結果を返します。以下に挙げる Result を返します。
  @retval       ResultSuccess         処理に成功しました。
  @retval       ResultNotAuthorized   MAC アドレスを取得できない状態です。ライブラリ未初期化でも返ります。
  @retval       上記以外              上記以外の理由で失敗しました。
*/
nn::Result GetMacAddress( bit8 pMacAddress[MAC_ADDRESS_SIZE] );

/*!
  @brief        現在の接続状態を返します。

                Initialize 関数で得た状態変化通知イベントがシグナルされたときの呼び出しのみで充分です。

  @param[out]   pStatus  現在の接続状態です。

  @return       関数の実行結果を返します。以下に挙げる Result を返します。
  @retval       ResultSuccess         処理に成功しました。
  @retval       ResultNotInitialized  ライブラリが初期化されていません。 nn::uds::Initialize 関数を実行してください。
  @retval       上記以外              上記以外の理由で失敗しました。
*/
nn::Result GetConnectionStatus( ConnectionStatus* pStatus );

/*!
  @brief        現在のリンクレベルを取得します。

  @param[out]   pLinkLevel  現在のリンクレベルです。
  
  @return       関数の実行結果を返します。以下に挙げる Result を返します。
  @retval       ResultSuccess         処理に成功しました。
  @retval       上記以外              上記以外の理由で失敗しました。
*/
nn::Result GetLinkLevel( LinkLevel* pLinkLevel );

/*!
  @brief        現在のリンクレベルを取得します。

  @return       現在のリンクレベルです。
*/
LinkLevel GetLinkLevel();

/*!
  @brief        指定したノードの情報を取得します。

  @param[out]   pNodeInfo ノードの情報です。将来、格納するデータに対応した構造体を用意する予定です。
  @param[in]    nodeId    対象となるノードのノードIDです。

  @return       関数の実行結果を返します。以下に挙げる Result を返します。
  @retval       ResultSuccess         処理に成功しました。
  @retval       ResultNotInitialized  ライブラリが初期化されていません。 nn::uds::Initialize 関数を実行してください。
  @retval       ResultInvalidNode     対象のノードはネットワーク上に存在しません。切断されている可能性があります。
  @retval       ResultWirelessOff     無線 OFF モードに遷移しました。再初期化が必要です。
  @retval       上記以外              上記以外の理由で失敗しました。
  
*/
nn::Result GetNodeInformation ( NodeInformation* pNodeInfo, u16 nodeId );

/*!
  @brief        省電力モードを変更します。(現在未実装)
  
                この設定は Master でのみ変更可能で、Client / Spectator は Master の設定に従います。
                現在未実装で、実行すると必ず失敗します。
                機能実装後は、通信中に動的に省電力モードを変更することが可能になる予定ですが、高頻度 (数秒未満の間隔) にモードを切り替えないで下さい。

  @param[in]    mode 省電力モードです。省電力モードを有効にすると若干接続性が悪くなる場合があります。
  
  @return       関数の実行結果を返します。以下に挙げる Result を返します。
  @retval       ResultNotImplemented  まだ実装されていません。

*/
nn::Result SetPowerSaveMode(PowerSaveMode mode);

/*!
  @brief        ビーコンに任意データをセットします。

                最大 @ref NET_DESC_APPDATA_SIZE_MAX Byte の任意のデータをセットします。
                暗号化されていませんので PC などの一般機器で収集可能である点にご注意下さい。
                このデータは他の機器が @ref Scan した際と @ref Client/Spectator として接続中に取得可能です。
                Master でのみ実行可能です。

  @param[in]    pData   セットしたいデータのポインタです。
  @param[in]    dataSize セットしたいデータのサイズです。 @ref NET_DESC_APPDATA_SIZE_MAX 以下の数値を指定してください。
  
  @return       関数の実行結果を返します。以下に挙げる Result を返します。
  @retval       ResultSuccess       処理に成功しました。
  @retval       ResultNotInitialized  ライブラリが初期化されていません。 nn::uds::Initialize 関数を実行してください。
  @retval       ResultInvalidState  実行可能なステートではありません。Master 状態以外で実行した場合に返ります。
  @retval       ResultTooLarge      dataSize が nn::uds::NET_DESC_APPDATA_SIZE_MAX を超えています。
  @retval       ResultWirelessOff   無線 OFF モードに遷移しました。再初期化が必要です。
  @retval       上記以外            上記以外の理由で失敗しました。
*/
nn::Result SetApplicationDataToBeacon   ( const void* pData, size_t dataSize );

/*!
  @brief        ビーコンにセットされたデータを取得します。
  
                Master が @ref SetApplicationDataToBeacon でセットしたデータを取得します。
                ネットワークに接続中にのみ実行可能です。 
                データが更新されても通知されませんのでご注意下さい。

  @param[out]   pBuffer     データの格納先です。
  @param[out]   pDataSize   データのサイズです。
  @param[in]    bufferSize  バッファの大きさです。受け取るデータのサイズは送信側が自由に変更できますので、基本的には @ref NET_DESC_APPDATA_SIZE_MAX Byte を指定してください。
  
  @return       関数の実行結果を返します。以下に挙げる Result を返します。
  @retval       ResultSuccess         処理に成功しました。
  @retval       ResultNotInitialized  ライブラリが初期化されていません。 nn::uds::Initialize 関数を実行してください。
  @retval       ResultInvalidState    実行可能なステートではありません。ネットワークに接続されていない状態で実行すると返ります。
  @retval       ResultTooLarge        受信したデータよりも bufferSize が小さい場合に返ります。サイズは nn::uds::NET_DESC_APPDATA_SIZE_MAX であることが望まれます。
  @retval       ResultWirelessOff     無線 OFF モードに遷移しました。再初期化が必要です。
  @retval       上記以外              上記以外の理由で失敗しました。
*/
nn::Result GetApplicationDataFromBeacon ( void* pBuffer, size_t* pDataSize, size_t bufferSize );

namespace detail{

/*!
  :private
  @brief        詳細な電波強度を取得します。
  
                この関数は開発機でのみ実行可能な開発支援のための関数ですので製品では利用しないでください。
                呼び出し間隔が短いと通信に影響を及ぼしますので、1秒程度の間隔を空けて実行するようてください。

  @param[out]   info 電波強度情報です。関数が成功した場合にデータが格納されます。

  @return       関数の実行結果を返します。成功したら info にデータが格納され、ResultSuccess を返します。
*/
nn::Result GetRadioStrengthInfo(RadioStrengthInfo* info);

/*!
  :private
  @brief       endpoint を破棄します。
  
                同時に @ref Attach で作成した受信用バッファを解放します。
                無線による受信は成功したものの、UDS の受信バッファ溢れによってロストしたパケットについての情報を取得できるデバッグ用 API です。

  @param[in]    pEndpoint      endpoint を示す descriptor です。
  @param[out]   pReport        破棄した Endpoint に到達したパケットに関する情報です。

  @return       関数の実行結果を返します。以下に挙げる Result を返します。
  @retval       ResultSuccess         処理に成功しました。
  @retval       ResultNotInitialized  ライブラリが初期化されていません。 nn::uds::Initialize 関数を実行してください。
  @retval       ResultNotAuthorized   無効な EndpointDescriptor を指定した場合に返ります。
  @retval       上記以外              上記以外の理由で失敗しました。
*/
nn::Result DestroyEndpoint( EndpointDescriptor* pEndpointDesc, ReceiveReport* pReport );

} // end of namespace detail

} // end of namespace CTR
} // end of namespace uds
} // end of namespace nn



#endif  // ifndef INCLUDE_NN_UDS_CTR_UDS_API_H_