NAT P2P Interface

ユーザーが互いにデータを送受信するインターフェースと関連するネットワーク機能です。

15 分で読めます

P2P インターフェース により Epic Online Systems (EOS) SDK を実装するゲームで、ユーザー間の ピアツーピア (P2P) 接続 を設定して管理できるようになります。これにより、ユーザーが相互に直接データを送受信できるようになります。これは、通常マルチ プレイヤー ゲームで使用します。EOS P2P インターフェースで行う接続は、認証済みユーザー間でのみ確立され、デフォルトで DTLS を使用して保護されます。これには、わかりやすいメリットが 2 つあります。1つめ目は、EOS 認証で接続を再ネゴシエートする必要性が大幅に減ることから、P2P 接続処理が大幅に高速化します。2 つ目は、SDK のユーザーにとって接続を安全に処理するプロセス自体がとてもシンプルになることです。ネットワーク ソケットを細かく管理する必要性が抽象化され、どのデータを誰に送信すべきかに多くの機能が集約されます。

P2P インターフェースを利用する

EOS P2P インターフェースの関数を使用するには、最初に Platform (プラットフォーム) インターフェース 関数である EOS_Platform_GetP2PInterface から有効な EOS_HP2P ハンドルを取得する必要があり、このハンドルをすべての P2P インターフェース関数で使用します。Platform インターフェースと、この関数の詳細は「EOS Platform インターフェース」のページを参照してください。

P2P 接続を管理する

P2P インターフェースは、ピア間接続で使用するタイトル指定の識別子として EOS_P2P_SocketId 構造体を使用します。接続に関連する P2P 関数の多くが EOS_P2P_SocketId を必要とし、接続リクエストに関連付けたり、接続リクエストを返して受信した接続リクエストが関連付けられた接続を指定します。EOS_P2P_SocketId は次のパラメータで構成します。

パラメータ説明
ApiVersionバージョン フィールド。これは EOS_P2P_SOCKETID_API_LATEST に設定する必要があります。
SocketNameマルチ プレイヤー ゲームで不明なピアからの受信接続をすべて検証するために使用する値。SocketName は 1 から 32 文字の英数字を含む null で終わる文字列を指定します。

この SocketName フィールドは、すべての接続に共通の値を使用することも、マルチプレイヤー セッションで特定のプレイヤーだけが知っている秘密の値にすることもできます。承認された P2P 接続は、ユーザーの IP アドレスを接続先のピアに公開します。そのため接続リクエストを無闇に承認しないことが重要となります。

また通常、有効な EOS_ProductUserId は両方のユーザーに必要で、データの送信で自分が誰かを示し、またデータの送信先のユーザーを指定します。

明示的にオプションであることがマークされていない限り、P2P インターフェースの関数パラメータと関連する値はすべて必須です。これは、非同期関数やイベント応答のデータ出力によく使用する P2P インターフェースの出力パラメータも同様です。関数の戻り値の型が EOS_EResult で、その戻り値が EOS_Success でない場合、この関数が提供する出力パラメータに特に指定がない限りは設定されないことに注意が必要です。

接続をリクエストする

ローカル ユーザーが EOS_P2P_SendPacket 関数などでリモート ユーザーに情報を送信する場合、P2P インターフェースはこの 2 人のユーザー間の接続開始リクエストを自動で行い、その際に EOS_P2P_SocketId はこの接続の識別子として機能します。情報を送信するユーザーは SocketId に対して自分のリクエストを自動で承認しますが、情報を受信するユーザーはそれを承認する必要があり、通常は受信接続リクエストをリッスンして EOS_P2P_AcceptConnection 関数を使用します。

P2P 接続がまだ開始されていない場合、P2P 接続の開始に必要なすべての操作が P2P 接続のリクエストと承認の両方に使用できます。例えば、ローカル ユーザーが情報の送信に使用するソケット ID に対して既に作成済みの場合、リモート ユーザーと P2P 接続をリクエストする際に EOS_P2P_AcceptConnection を使用して、リモート ユーザーの P2P 接続要求を承認する際に EOS_P2P_SendPacket を使用できます。これは事実上、EOS_P2P_AcceptConnection を使用して、特定の SocketId で行われた次の接続リクエストを事前に承認できることを意味します。

特定のユーザーと複数の接続が開始している場合は、最初の接続のみをネゴシエートする必要があります。するとその後の接続リクエストでデータの受信速度が大幅に向上します。

接続リクエスト通知を受信する

ユーザーが接続リクエストを受信すると、バインド済みのすべての Peer Connection Request Handler (ピア接続リクエスト ハンドラ) に対して通知イベントが発生します。

新しいピア接続リクエスト ハンドラで接続リクエストをリッスンするには、EOS_P2P_AddNotifyPeerConnectionRequest を使用して受信接続リクエストの応答に使用する関数をバインドします。EOS_P2P_AddNotifyPeerConnectionRequest 関数が取るパラメータを以下に示します。

パラメータ説明
HandlePlatform インターフェースから受信した有効な EOS_HP2P ハンドル。
OptionsEOS_P2P_AddNotifyPeerConnectionRequestOptions 構造体へのポインタ。
ClientData (オプション)イベント発生時に呼び出し元に返すデータへのポインタ。
ConnectionRequestHandlerピア接続リクエスト ハンドラーとして機能して受信接続リクエストに応答する関数。この関数にはパラメータとして EOS_P2P_OnIncomingConnectionRequestInfo 構造体へのポインタを必ず渡します。

EOS_P2P_AddNotifyPeerConnectionRequestOptions 構造体は以下のパラメータで構成されています。

パラメータ説明
ApiVersionバージョン フィールド。EOS_P2P_ADDNOTIFYPEERCONNECTIONREQUEST_API_LATEST に設定します。
LocalUserId受信接続リクエストをリッスンしているローカル ユーザーの ID に設定します。
SocketId (オプション)接続リクエストのフィルターに使用する有効な EOS_P2P_SocketId 構造体へのポインタ。

EOS_P2P_AddNotifyPeerConnectionRequest 関数は、成功すると有効な EOS_NotificationId を返し、失敗すると値 EOS_INVALID_NOTIFICATIONID を返します。

以下のパラメータを渡して EOS_P2P_RemoveNotifyPeerConnectionRequest 関数を使用し、ピア接続リクエスト ハンドラを削除できます。

パラメータ説明
HandlePlatform インターフェースから受信した有効な EOS_HP2P ハンドル。
NotificationIdEOS_P2P_AddNotifyPeerConnectionRequest が返す有効な EOS_NotificationId で、削除するピア接続リクエスト ハンドラの特定に使用します。

接続を承認する

EOS_P2P_AcceptConnection 関数を使用してリクエストされた接続を承認したり、新しい接続リクエストを開始したりできます。接続を確立してデータ送信に使用する前に、双方のユーザーが必要な SocketId の接続を承認する必要があります。接続を開始するユーザーは、情報が送信された EOS_P2P_SocketId の接続を自動で承認します。一方、接続リクエストを受信したユーザーは、自分の接続リクエストを開くか、EOS_P2P_AcceptConnection でそれを承認する必要があります。

EOS_P2P_AcceptConnection 関数の呼び出しには以下のパラメータを指定する必要があります。

パラメータ説明
HandlePlatform インターフェースから受信した有効な EOS_HP2P ハンドル。
OptionsEOS_P2P_AcceptConnectionOptions 構造体へのポインタ。

EOS_P2P_AcceptConnectionOptions 構造体は以下のパラメータを含みます。

パラメータ説明
ApiVersionEOS_P2P_ACCEPTCONNECTION_API_LATEST に設定します。
LocalUserId接続を承認するローカル ユーザーの EOS_ProductUserId に設定します。
RemoteUserIdローカル ユーザーが接続する先の、リモート ユーザーの EOS_ProductUserId に設定します。
SocketId接続を承認する対象の、有効な EOS_P2P_SocketId 構造体へのポインタ。

指定した入力に無効なものがあると、EOS_P2P_AcceptConnection 関数は EOS_InvalidParameters の値を返します。提供した情報が有効な場合は EOS_Success を返して接続がローカルで承認されたことを通知し、リモート ユーザーが接続を承認するとデータを送信できるようになります。接続終了イベントが発生する前に、何度も EOS_P2P_AcceptConnection を呼び出しても効果はありません。

接続を終了する

EOS_P2P_CloseConnection 関数を使用して、リクエストされた接続を拒否したり、以前に特定のユーザーで承認済みの接続を終了したりできます。特定のユーザーとの接続をすべて閉じると、バッキング ソケット接続もすぐに破棄されます。この EOS_P2P_CloseConnection 関数には以下のパラメータが必要です。

パラメータ説明
HandlePlatform インターフェースから受信した有効な EOS_HP2P ハンドル。
OptionsEOS_P2P_CloseConnectionOptions 構造体へのポインタ。

EOS_P2P_CloseConnectionOptions 構造体は以下のパラメータを含みます。

パラメータ説明
ApiVersionEOS_P2P_CLOSECONNECTION_API_LATEST に設定します。
LocalUserId接続を終了する、もしくは拒否するローカル ユーザーの EOS_ProductUserId に設定します。
RemoteUserId接続を終了されている、もしくは拒否されているリモート ユーザーの EOS_ProductUserId に設定します。
SocketId接続を終了する、もしくは拒否する、有効な EOS_P2P_SocketId 構造体へのポインタ。

EOS_P2P_CloseConnection 関数は、指定した関数の入力が無効なことを示す EOS_InvalidParameters の値を返すか、もしくは指定した入力が有効で接続が終了したか、接続リクエストがサイレントで拒否されたことを示す EOS_Success の値を返します。

EOS_P2P_CloseConnections 関数を使用すると、特定のユーザーからの接続ではなく、特定の SocketId 上の接続をすべて終了したり拒否したりできます。これはセッションの終了時に、そのセッションに関連する接続をすべて破棄する場合に使用できます。この EOS_P2P_CloseConnections 関数には以下のパラメータが必要です。

パラメータ説明
HandlePlatform インターフェースから受信した有効な EOS_HP2P ハンドル。
OptionsEOS_P2P_CloseConnectionsOptions 構造体へのポインタ。

EOS_P2P_CloseConnectionsOptions 構造体は以下のパラメータを含みます。

パラメータ説明
ApiVersionEOS_P2P_CLOSECONNECTIONS_API_LATEST に設定します。
LocalUserIdリクエストの SocketId との接続をすべて終了するローカル ユーザーの EOS_ProductUserId に設定します。
SocketId (オプション)接続リクエストのフィルターに使用する有効な EOS_P2P_SocketId 構造体へのポインタ。

指定した入力に無効なものがあると、この関数は EOS_InvalidParameters の結果を返します。または提供した情報が有効で、指定した SocketId との接続がすべて正常に終了した場合は EOS_Success を返します。

接続終了通知を受信する

開始した接続や保留中の接続が終了すると Connection Closed Event (接続終了イベント) が発生して、アプリケーションに通知して応答を許可します。接続終了イベントのハンドラを作成するには、以下のパラメータを設定して EOS_P2P_AddNotifyPeerConnectionClosed 関数を使用します。

パラメータ説明
HandlePlatform インターフェースから受信した有効な EOS_HP2P ハンドル。
OptionsEOS_P2P_AddNotifyPeerConnectionClosedOptions 構造体へのポインタ。
ClientData (オプション)イベント発生時に呼び出し元に返すデータへのポインタ。
ConnectionClosedHandler接続終了イベントの発生時に呼び出す関数。この関数は、パラメータとして渡す EOS_P2P_OnRemoteConnectionClosedInfo 構造体へのポインタを受け取る必要がある。

EOS_P2P_AddNotifyPeerConnectionClosedOptions 構造体は以下のパラメータを含みます。

パラメータ説明
ApiVersionEOS_P2P_ADDNOTIFYPEERCONNECTIONCLOSED_API_LATEST に設定します。
LocalUserId接続の終了をリッスンしているローカル ユーザーの EOS_ProductUserId に設定します。
SocketId (オプション)接続終了イベントをフィルターする対象の、有効な EOS_P2P_SocketId 構造体へのポインタ。

この EOS_P2P_AddNotifyPeerConnectionClosed 関数は、接続終了イベント ハンドラの特定に使用する EOS_NotificationId を返します。

以下のパラメータを使用して関数 EOS_P2P_RemoveNotifyPeerConnectionClosed を呼び出すと、接続終了イベント ハンドラを削除できます。

パラメータ説明
HandlePlatform インターフェースから受信した有効な EOS_HP2P ハンドル。
NotificationIdEOS_P2P_AddNotifyPeerConnectionClosed が返す有効な EOS_NotificationId

P2P 接続を介してデータを送受信する