CTR NEX API Reference
nn::nex::VSocket クラス

VSocket は UDP によるソケット通信に似たインターフェースを提供する低レベルな通信ライブラリです。 [詳解]

#include <OnlineCore/src/Transport/Interface/VSocket.h>

+ nn::nex::VSocket の継承関係図

クラス

class  InetAddress
 IP アドレスとポート番号を保持するクラスです。 このクラスは常にホストバイトオーダーで表現されます。 [詳解]
 

公開型

enum  Result {
  Success,
  Error,
  WouldBlock,
  PacketBufferFull
}
 結果を表す列挙子です。 [詳解]
 

公開メンバ関数

 VSocket (size_t maxRecvPackets=DEFAULT_MAX_RECV_PACKTES)
 コンストラクタです。 [詳解]
 
virtual ~VSocket ()
 デストラクタです。
 
qBool Bind (qUnsignedInt8 uiVPort)
 VSocket を指定した仮想ポートに紐づけます。 [詳解]
 
void Close ()
 VSocket をクローズします。 [詳解]
 
qBool Open ()
 VSocket をオープンします。 [詳解]
 
Result RecvFrom (qByte *pBuffer, size_t uiBufferSize, VSocket::InetAddress *pSourceAddress, size_t *puiNbBytesRecvd)
 データを受信します。 [詳解]
 
Result SendTo (const qByte *pBuffer, size_t uiBufferSize, const VSocket::InetAddress &oDestinationAddress, size_t *puiNbBytesSent)
 データを送信します。 [詳解]
 

静的公開メンバ関数

static qBool ProbeStations (CallContext *pContext, StationProbeList *preflstStationProbe, qUnsignedInt32 ui32Timeout=0, qBool bWaitForAllResult=false)
 NAT トラバーサルを行います。 [詳解]
 

静的公開変数類

static const size_t DEFAULT_MAX_RECV_PACKTES = 128
 デフォルトの受信パケットキューサイズです。
 
static const size_t MAX_DATA_SIZE = 1250
 一度に送信可能な最大サイズ (byte)。
 

詳解

VSocket は UDP によるソケット通信に似たインターフェースを提供する低レベルな通信ライブラリです。

VSocket を使うと NEX のサーバー機能や NAT トラバーサル機能や暗号化・改ざん検知機能を利用しつつ クライアント同士の P2P 通信に任意のサードパーティー製のネットワークエンジンを利用できるようになります。 サードパーティー製のネットワークエンジンからソケット API を呼び出している箇所を VSocket の API を呼び出すように変更して使用されることを想定しています。

VSocket はソケットの UDP と同様にコネクションレスなプロトコルであり、信頼性や順序性を保証しません。 一般に端末は NAT デバイスの配下に置かれている事が多いため、VSocket による通信を行う前に NAT トラバーサルを行う必要があります。 通信経路上の NAT デバイスの NAT テーブルを維持するため、アプリケーション側でキープアライブを行う必要があります。

列挙型メンバ詳解

結果を表す列挙子です。

列挙値
Success 

呼び出しは成功で完了した。

Error 

呼び出しはエラーで完了した。

WouldBlock 

呼び出しはブロックするためまだ完了していない。

PacketBufferFull 

パケットバッファの不足により呼び出しは失敗した。PacketBufferManager を参照してください。

構築子と解体子

nn::nex::VSocket::VSocket ( size_t  maxRecvPackets = DEFAULT_MAX_RECV_PACKTES)

コンストラクタです。

maxRecvPackets は RecvFrom() で受信するまでにライブラリ内部に貯めておけるパケットの数です。 この値より多くのパケットを受信した場合は破棄されます。 送信頻度を高くしたい場合はこの値を増やしてください。

引数
[in]maxRecvPackets受信パケットキューサイズです。

関数詳解

qBool nn::nex::VSocket::Open ( )

VSocket をオープンします。

事前に VSocket::StartNATSession() の呼び出しが必要です。 マッチメイクし、新しい P2P セッションを構築する度に VSocket::StartNATSession() 及び VSocket::StopNATSession() を呼び出す必要があります。 事前に NGS から取得した鍵を Network::SetP2PDataPacketSessionSignatureKey() でセットする必要があります。

参照
MatchmakeSession::GetSessionKey() VSocket::Close() VSocket::StartNATSession()


戻り値一覧:

true 成功。

false 事前に VSocket::StartNATSession() を呼び出していない。 もしくは事前に Network::SetP2PDataPacketSessionSignatureKey() を呼び出していない。

void nn::nex::VSocket::Close ( )

VSocket をクローズします。

参照
VSocket::Open()
qBool nn::nex::VSocket::Bind ( qUnsignedInt8  uiVPort)

VSocket を指定した仮想ポートに紐づけます。

複数の VSocket オブジェクトを生成し、それぞれ異なる仮想ポートを紐づけた場合、内部的には同一の UDP ソケットが使用されます。 ただし、送受信データは仮想ポート番号に応じて多重化(マルチプレックス)、多重分離(デマルチプレックス)されます。 一つのアプリケーションで最大 16 個の仮想ポートを使用することができます。

引数
[in]uiVPort送受信に使用する仮想ポート。0 から 15 までの任意の数を指定してください。
Result nn::nex::VSocket::RecvFrom ( qByte pBuffer,
size_t  uiBufferSize,
VSocket::InetAddress pSourceAddress,
size_t *  puiNbBytesRecvd 
)

データを受信します。

本関数はノンブロッキングで実行されます。

引数
[out]pBuffer受信データを書き込むバッファ。
[in]uiBufferSizepBuffer のサイズ。最大の受信サイズは VSocket::MAX_DATA_SIZE です。
[out]pSourceAddress送信元のアドレス情報。
[out]puiNbBytesRecvdpBuffer に書き込まれたサイズ。 VSocket::SendTo() で送信されたサイズと同じサイズで受信します。一つの送信データが分割されて受信する事はありません。 NULL を指定した場合は書き込まれません。


戻り値一覧:

VSocket::Success 受信に成功した。pSourceAddress と puiNbBytesReceived が更新されます。

VSocket::Error uiBufferSize が 0。 VSocket::Open() が呼び出されていない。VSocket::Bind() が呼び出されていない。

VSocket::WouldBlock 受信するデータが存在しない。

参照
VSocket::SendTo()
Result nn::nex::VSocket::SendTo ( const qByte pBuffer,
size_t  uiBufferSize,
const VSocket::InetAddress oDestinationAddress,
size_t *  puiNbBytesSent 
)

データを送信します。

本関数はノンブロッキングで実行されます。

引数
[in]pBuffer送信データ。
[in]uiBufferSizepBuffer のサイズ。1 以上 VSocket::MAX_DATA_SIZE 以下の数値を指定できます。
[in]oDestinationAddress宛先のアドレス情報。NAT トラバーサル済みの IP アドレスとポート番号、及び VSocket の仮想ポート番号を指定する必要があります。
[out]puiNbBytesSent送信されたサイズ。 VSocket::Success が返されたときは uiBufferSize と同じサイズ、それ以外の場合は 0 が書き込まれます。 中途半端なサイズで送信されることはありません。NULL を指定した場合は書き込まれません。


戻り値一覧:

VSocket::Success 送信に成功した。puiNbBytesSent が更新されます。

VSocket::Error uiBufferSize が 0 もしくは VSocket::MAX_DATA_SIZE を超えている。 VSocket::Open() が呼び出されていない。VSocket::Bind() が呼び出されていない。

VSocket::PacketBufferFull 送受信バッファが不足していて送信できない。

参照
VSocket::RecvFrom() PacketBufferManager
static qBool nn::nex::VSocket::ProbeStations ( CallContext pContext,
StationProbeList preflstStationProbe,
qUnsignedInt32  ui32Timeout = 0,
qBool  bWaitForAllResult = false 
)
static

NAT トラバーサルを行います。

本関数を呼び出す前に ConnectivityManager::StartNATSession() の呼び出しが必要です。 本関数呼び出し時に preflstStationProbe に保存されている前回試行した NAT トラバーサルの結果 (PingTime (RTT) 情報や接続情報) はクリアされます。 本関数では、CallContext::SetTimeout()CallContext::Cancel() で非同期処理をコントロールしないでください。 タイムアウト時間は内部で自動的に設定されます。 非同期処理に成功した場合は、指定した全ての相手と NAT トラバーサルが成功したことを示します。 非同期処理の結果、以下の Result が返ることがあります。

  • QERROR(Core, InvalidSequence) : 事前に ConnectivityManager::StartNatSession() を呼び出していない。
  • QERROR(Transport, NatTraversalError) : 少なくとも一人の相手と NAT トラバーサルに失敗した。(タイムアウトによる失敗を含む) bWaitForAllResult に true を指定した場合は preflstStationProbe を参照する事でどの端末と失敗したかを調べる事ができます。
引数
[in,out]pContext呼び出し情報。
[in,out]preflstStationProbeNAT トラバーサルを行う相手の情報を指定します。 非同期処理が完了すると それぞれの相手ごとの NAT トラバーサルの成否、PingTime (RTT)、接続情報が書き込まれます。
[in]ui32Timeout指定した値は無視されます。0 を指定してください。タイムアウト時間は内部で自動的に設定されます。
[in]bWaitForAllResultfalse を指定すると、NAT トラバーサル対象のうち一つでも NAT トラバーサルに失敗した時に即座に非同期処理を完了します。 true を指定すると全ての NAT トラバーサル対象との成否が確定するまで非同期処理が完了しません。 全ての相手と NAT トラバーサルをする必要があり、一つでも失敗してはいけないケースでは false を指定してください。 これはフルメッシュ型もしくはサーバークライアント(スター)型のネットワークトポロジを構成する場合に該当します。 NAT トラバーサルが成功した相手とのみ通信したいケースでは true を指定してください。 これは NAT トラバーサルに失敗した相手とは他の端末を中継して通信するなどの特殊なネットワークトポロジを採用する場合に該当します。


戻り値一覧:

true 非同期処理の開始に成功。

false 指定した pContext の状態が CallContext::CallInProgress となっており非同期処理を開始出来ない。 これは他の非同期処理で使用中であることを示します。 プログラミングエラーであるため、このケースはリリースビルド以外では内部で Assert により停止します。