/*---------------------------------------------------------------------------* 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: 26639 $ *---------------------------------------------------------------------------*/ #ifndef INCLUDE_NN_UDS_CTR_UDS_API_H_ #define INCLUDE_NN_UDS_CTR_UDS_API_H_ /*! @file @brief UDS ライブラリの API 群です。 */ #include #include #include namespace nn { namespace uds { namespace CTR { /*! @name 初期化/終了処理関連 @{ */ /*! @brief UDS ライブラリを初期化します。他の通信機能を使用中には成功しません。 なお、バックグラウンドでの通信処理を終了させ、 @ref Finalize を実行するまで UDS ライブラリが通信デバイスを 占有するための処理を行うため、長時間ブロックする可能性があります。 @param[out] pStatusUpdateEvent 接続状態の更新通知用イベントです。ライブラリ内で自動リセットイベントとして Initialize されます。 @param[in] receiveBuffer UDS ライブラリが使用する受信バッファの先頭を指すポインタです。UDS ライブラリは内部で、実際に無線通信による データ受信をしてからアプリが取得するまで受信したデータを格納しておくバッファを必要とします。 4096 バイト整合されたバッファを指定してください。デバイスメモリは使用できません。 @param[in] bufferSize 受信バッファのサイズです。4096 の倍数を指定してください。 @return 関数の実行結果を返します。 */ nn::Result Initialize( nn::os::Event* pStatusUpdateEvent, void* receiveBuffer, const size_t bufferSize ); /*! @brief UDS ライブラリを終了します。 @ref Initialize で指定した受信バッファは本 API が完了するまで UDS ライブラリが使用します。 また、 @ref Initialize で受け取る接続状態の更新通知用イベントはここで Finalize されます。 @return 無し */ void Finalize (); /*! @} */ /*! @name ネットワークの構築/破棄、およびネットワークの接続/切断 @{ */ /*! @brief 業務部から割り当てられた 20bit のユニーク ID から UDS 通信で使用する 32bit 値 (ローカル通信 ID) を生成します。 @param[in] id 業務部から割り当てられた 20bit の ユニークID です。複数タイトル間で通信したい場合はどちらか片方のユニーク ID を指定してください。 @param[in] isTrial ユニークID が製品版と体験版で共通であるための対応です。製品版-体験版間での通信を行いたくない場合に true を指定してください。 */ bit32 CreateLocalCommunicationId( bit32 uniqueId, bool isTrial = false); /*! @brief 新規にローカルネットワークを構築します。 @param[in] subId 通信モード識別用 ID です。アプリが自由に設定可能です。 @param[in] maxEntry ネットワークに接続できるノードの最大数です。自身を含み、最大 12 まで指定可能です。 @param[in] localId ローカル通信 ID です。 @ref CreateLocalCommunicationId で生成した値を指定してください。 @param[in] passphrase 無線レイヤの暗号化に使用する暗号鍵の種となる文字列です。 UDS では uniqueId と passphrase が一致する場合にのみ通信が成立します。 @param[in] passphraseLength passphrase の長さです。255(暫定) 未満を指定してください。 @param[in] channel 通信に使用するチャンネルです。0(自動), 1,6,11ch のいずれかを指定してください。製品実機で実行した場合は常にチャンネルを自動で選択します。 @return 関数の実行結果を返します。成功した場合、ネットワークが構築されます。 */ nn::Result CreateNetwork( u8 subId, u8 maxEntry, bit32 localId, const char passphrase[], size_t passphraseLength, u8 channel = 0 ); /*! @brief 周囲のネットワークを探索します。 @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 関数の実行結果を返します。 */ nn::Result Scan( void* pBuffer, size_t bufferSize, u8 subId, bit32 localId, u8 channel = 0, u16 scanTime = 0 ); /*! @brief 既存のネットワークに接続します。 @param[in] networkDescription ネットワーク情報です。スキャン結果から取得します。 @param[in] type 接続タイプです。 @param[in] passphrase 無線レイヤの暗号化に使用する暗号鍵です。 UDS では uniqueId と passphrase が一致する場合にのみ通信が成立します。 @param[in] passphraseLength passphrase の長さです。255(暫定) 未満を指定してください。 @return 関数の実行結果を返します。成功した場合、ネットワークに接続されます。 */ 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 関数の実行結果を返します。 */ nn::Result EjectClient ( u16 nodeId ); /*! @brief 接続している全ての Spectator をネットワークから追放します。 本 API を実行後は新規に Spectator が接続することは出来ない状態になります。 再度 Spectator の接続を許可したい場合は @ref AllowToSpectate を実行してください。 Master のみ実行可能です。 @return 関数の実行結果を返します。 */ nn::Result EjectSpectator ( void ); inline nn::Result EjectAudience ( void ){ return EjectSpectator(); } /*! @brief Spectator のネットワークへの接続を許可します。 デフォルトでは許可された状態になっているため、 @ref EjectSpectator を使用後に 再度 Spectator をネットワークに接続させたい場合にご使用下さい。 Master のみ実行可能です。 @return 関数の実行結果を返します。 */ nn::Result AllowToSpectate(); /*! @brief 接続中の Client 全てを追放してローカルネットワークを終了します。 Master のみ実行可能です。 @return 関数の実行結果を返します。 */ nn::Result DestroyNetwork ( void ); /*! @brief 接続中のネットワークから離脱します。意図しない切断が発生した場合も、再接続前に実行することが望ましいです。 Client および Spectator のみ実行可能です。 @return 関数の実行結果を返します。 */ nn::Result DisconnectNetwork ( void ); /*! @} */ /*! @name データ送受信関連 @{ */ /*! @brief ネットワークの端点 (endpoint) を生成し、対応する descriptor を返します。 [暫定仕様] endpoint は現在 16 個生成可能です。 @param[out] pEndpointDesc 生成する endpoint を示す descriptor です。 @return 関数の実行結果を返します。 */ nn::Result CreateEndpoint( EndpointDescriptor* pEndpointDesc ); /*! @brief 指定した相手の指定したポートにデータを送信します。 送信処理が完了するまでブロックします。 @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 送信オプションです。 @ref NO_WAIT を指定すると UDS 内部の送信バッファに貯めずに即時無線送信を行います。 @return 関数の実行結果を返します。 */ nn::Result SendTo ( const EndpointDescriptor& endpointDesc, const void* data, size_t dataSize, u16 destNodeId, u8 port, bit8 option = 0x00 ); /*! @brief descriptor とポート、ノードID を結びつけます。その際システムは受信用バッファを作成し、以降データを受信できるようになります。 @param[in] pEndpointDesc 使用する Endpoint を示す descriptor です。 @param[in] srcNodeId 結びつけるノード ID です。BROADCAST_NODE_ID を指定すると全てのノードと結びつけられます。 @param[in] port 結びつけるポート番号です。ポート番号0x00はシステム側で予約されているため使用できません。 @param[in] receiveBufferSize 確保する受信バッファのサイズです。@ref Initialize で確保したメモリブロックから確保されますので、受信バッファの合計が 確保したメモリブロックのサイズよりも大きくならないよう注意してください。 デフォルトでは @ref UDS_PACKET_PAYLOAD_MAX_SIZE のデータの8倍を確保します。 データサイズを指定する場合は内部で32バイト毎にメモリを確保しているため、32の倍数を指定すると効率的です。 @return 関数の実行結果を返します。 */ nn::Result Attach ( EndpointDescriptor* pEndpointDesc, u16 srcNodeId, u8 port, size_t receiveBufferSize =(UDS_PACKET_PAYLOAD_MAX_SIZE*8) ); /*! @brief データを受信します。(送信元アドレス取得機能なし) @param[in] endpointDesc 使用する endpoint を示す descriptor です。 事前に Attach() により、ポート、送信元が結びつけて置く必要があります。 @param[out] pBuffer 受信データの格納先です。4 バイト整合されたバッファを指定してください。 @param[out] pReceivedSize 受信したデータのサイズです。UDS の最大受信データサイズは @ref UDS_PACKET_PAYLOAD_MAX_SIZE Byteです。 @param[in] bufferSize 受信バッファ (pBuffer) のサイズです。 @param[in] option 受信オプションです。 @ref NO_WAIT を指定するとデータを受信していない場合でも即時終了します。 指定しないとデータを受信、もしくはエラーが発生するまで終了しません。 @return 関数の実行結果を返します。 */ nn::Result Receive ( const EndpointDescriptor& endpointDesc, void* pBuffer, size_t* pReceivedSize, size_t bufferSize, bit8 option = 0x00 ); /*! @brief データを受信します。(送信元アドレス取得機能付き) @param[in] endpointDesc 使用する endpoint を示す descriptor です。 事前に Attach() により、ポート、送信元が結びつけて置く必要があります。 @param[out] pBuffer 受信データの格納先です。4 バイト整合されたバッファを指定してください。 @param[out] pReceivedSize 受信したデータのサイズです。UDS の最大受信データサイズは @ref UDS_PACKET_PAYLOAD_MAX_SIZE Byteです。 @param[out] pSrcNodeId 送信元ノードIDです。 @param[in] bufferSize 受信バッファ (pBuffer) のサイズです。 @param[in] option 受信オプションです。 @ref NO_WAIT を指定するとデータを受信していない場合でも即時終了します。 指定しないとデータを受信、もしくはエラーが発生するまで終了しません。 @return 関数の実行結果を返します。 */ nn::Result ReceiveFrom ( const EndpointDescriptor& endpointDesc, void* pBuffer, size_t* pReceivedSize, u16* pSrcNodeId, size_t bufferSize, bit8 option = 0x00 ); /*! @brief endpoint を破棄します。同時に @ref Attach で作成した受信用バッファを解放します。 @param[in] pEndpoint endpoint を示す descriptor です。 @return 関数の実行結果を返します。 */ nn::Result DestroyEndpoint( EndpointDescriptor* pEndpointDesc ); /*! @} */ /*! @brief 自身の MAC アドレスを取得します。 @param[out] pMacAddress 自身の MAC アドレスです。 @return 関数の実行結果を返します。 */ nn::Result GetMacAddress( bit8 pMacAddress[MAC_ADDRESS_SIZE] ); /*! @brief 現在の接続状態を返します。 @param[out] pStatus 現在の接続状態です。 @return 関数の実行結果を返します。 */ nn::Result GetConnectionStatus( ConnectionStatus* pStatus ); /*! @brief 現在のリンクレベルを取得します。 @param[out] pLinkLevel 現在のリンクレベルです。 @return 関数の実行結果を返します。 */ nn::Result GetLinkLevel( LinkLevel* pLinkLevel ); /*! @brief 現在のリンクレベルを取得します。 @return 現在のリンクレベルです。 */ LinkLevel GetLinkLevel(); /*! @brief 指定したノードの情報を取得します。 @param[out] pNodeInfo ノードの情報です。将来、格納するデータに対応した構造体を用意する予定です。 @param[in] nodeId 対象となるノードのノードIDです。 @return 関数の実行結果を返します。 */ nn::Result GetNodeInformation ( NodeInformation* pNodeInfo, u16 nodeId ); /*! @brief 省電力モードを変更します。(通信開始前、もしくは通信中に変更することが出来ます) この設定は Master でのみ変更可能で、Client / Spectator は Master の設定に従います。 現在未実装で、実行すると必ず失敗します。 @param[in] mode 省電力モードです。省電力モードを有効にすると若干接続性が悪くなる場合があります。 @return 関数の実行結果を返します。 */ nn::Result SetPowerSaveMode(PowerSaveMode mode); /*! @brief ネットワークの属性を変更します。 現在未実装で、実行すると必ず失敗します。 @param[in] flag ネットワークの属性です。複数の属性を OR で指定します。 @return 関数の実行結果を返します。 */ nn::Result SetNetworkAttribute( bit16 flag ); /*! @brief ビーコンに任意データ (最大 @ref NET_DESC_APPDATA_SIZE_MAX Byte) をセットします。Master でのみ実行可能です。 このデータは他の機器が Scan した際、 Client/Spectator として接続中に取得可能です。 @param[in] pData セットしたいデータのポインタです。 @param[in] dataSize セットしたいデータのサイズです。@ref NET_DESC_APPDATA_SIZE_MAX 未満の数値を指定してください。 @return 関数の実行結果を返します。 */ nn::Result SetApplicationDataToBeacon ( const void* pData, size_t dataSize ); /*! @brief ビーコンにセットされたデータ (最大 @ref NET_DESC_APPDATA_SIZE_MAX Byte) を取得します。 ネットワークに接続中にのみ実行可能です。 Client/Spectator として通信中にデータが更新されてもアプリには 通知されませんのでご注意下さい。 @param[out] pBuffer データの格納先です。 @param[out] pDataSize データのサイズです。 @param[in] bufferSize バッファの大きさです。受け取るデータのサイズは送信側が自由に変更できますので、基本的には @ref NET_DESC_APPDATA_SIZE_MAX Byte を指定してください。 @return 関数の実行結果を返します。 */ nn::Result GetApplicationDataFromBeacon ( void* pBuffer, size_t* pDataSize, size_t bufferSize ); namespace detail{ /*! :private @brief endpoint を破棄します。同時に @ref Attach で作成した受信用バッファを解放します。 ( 無線による受信は成功したものの、UDS の受信バッファ溢れによってロストしたパケットについての情報を取得できるデバッグ用 API です) @param[in] pEndpoint endpoint を示す descriptor です。 @param[out] pReport 破棄した Endpoint に到達したパケットに関する情報です。 @return 関数の実行結果を返します。 */ nn::Result DestroyEndpoint( EndpointDescriptor* pEndpointDesc, ReceiveReport* pReport ); /*! :private @brief システムプロセス用 Initialize() */ nn::Result InitializeCore( nn::os::Event* pStatusUpdateEvent, void* receiveBuffer, const size_t bufferSize ); /*! :private @brief システムプロセス用 Finalize() */ void FinalizeCore(); } // 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_