TcpLink

ドキュメント概要: TcpLink クラスの説明と API ドキュメンテーション。

ドキュメントの変更ログ: 初の作成。

概観

TcpLink クラスは、UnrealEngine 内から TCP ソケットを作成することを可能にします。このソケットを通して、インターネット上の他のサーバーに接続したり、単純なインターネット サービスを提供したりすることができます。

これは決してハイ パフォーマンスな機能ではないことに留意してください。これを使用すると、ゲーム パフォーマンスに重大な影響を与えることがあります。サービスを手供しているときは、パフォーマンスの影響はより大きくなります。なので、この機能を使用する際は、これを気に留めておいてください。

このページの下方には、TcpLink を使用するいくつかの例があります。

エンジンに含まれているのが、HTTP WebServer の実装です。このウェブサーバーは TcpLink の機能を活用します。

モード

TcpLink クラスには、このクラスが機能する方法をコントロールするようないくつかのモードがあります。これらのモードは以下で説明しています。

Receive mode (レシーブ モード)

TcpLink は、受信する際に以下の 2 つの異なるモードで機能します。

• Event mode (イベント モード) (RMODE_Event)
• Manual mode (手動モード) (RMODE_Manual)

Event mode (イベント モード)

イベント モードでは、TcpLink リンクの Native コードが、 リンク モード によって、イベントの 1 つをトリガします。

In MODE_Text では、 ReceivedText イベントが実行されます。 text 引数は、最後のイベント以降、受信したすべてのテキストを含んでいます。

In MODE_Line では、 ReceivedLine イベントが実行されます。 line 引数は、ライン ターミネータなしの 1 つのラインを含みます。他のイベントと異なり、これは tick ごとに 1 つ以上起きることが可能です。

In MODE_Binary では、 ReceivedBinary イベントが実行されます。 count 引数は、バイト バッファ B にどれぐらいのバイトがあるかを表します。

Manual mode (手動モード)

名前が示唆するように、手動モードでは、データを読み取るのは人間の役割になります。これは、tick イベント中、またはタイマーを使用して行うことができます。tick ごとに複数の読み取りを行うことはお勧めしません。というのは、これには時間がかかり、動作をブロックすることになるからです。

データの読み取りは、 ReadText または ReadBinary 関数を使用することで行うことができます。どちらの関数も、読み取られたバイト数を返します。 ReadBinary の count 引数は、読み取りたい最大バイト数を定義します。実際に読み取るバイト数は、戻り値を使用して決定します。

イベント モードと異なり、 リンク モード が何であるかは関係ありません。どちらの関数を使っても構いません。コストの少ない IsDataPending を使用して、データの読み取り自体が必要であるかどうかをチェックしてみてください。

Link mode (リンク モード)

TcpLink は、2 つの異なるモードで機能することができます。リンク モードは、TcpLink がレシーブ モード イベント モード で動作する際に、どのイベントが呼び出されるかを決定します。

また、リンク モードは SendText メソッドがどのように働くかに影響を与えます。リンク モードが MODE_Line に設定されていると、 SendText を使用して送信されるテキストに newline ターミネータが付け足されます。使用される newline ターミネータに関しては、 ライン モード を参照してください。

Line mode (ライン モード)

ライン モードは、テキストを受信する際に、新しいラインがどのように検知されるか、また SendText とともにどの新しいライン ターミネータが追加されるかをコントロールします。ライン モードは、 リンク モード が MODE_Line に設定される場合のみ使用されます。

ライン モードは、(OutLineMode) を送信するのと (InLineMode) を受信するのに、個別に設定されます。

リンク状態

TcpLink は、リンクの現在の状態をレポートする変数 LinkState を含みます。通常、特に TcpLink のイベントを使用している場合は、これを気にすることはありません。しかしながら、場合によっては、何が起きているかを知るのも興味深いかも知れません。

STATE_Initialized

TcpLink の初期状態です。バインドされる準備ができています。 BindPort を使用することができます。

STATE_Ready

TcpLink は、ポートにバインドされ、接続を確立する準備ができています。 Open (開く) か Listen (待ち受け) を使用することができます。

STATE_Listening

TcpLink は入ってくる接続を待ち受けしています。これは通常、 Listen の呼び出しの結果起こります。

STATE_Connecting

接続の試みが進行中です。これは通常、 Open の呼び出しの結果起こります。TcpLink は I/O の準備はまだできていません。

STATE_Connected

接続が確立され、I/O の準備ができました。

STATE_ListenClosePending

待ち受けソケットが閉じるキューをしています。これは、 Close の呼び出しの結果起こります。

STATE_ConnectClosePending

クライアント ソケットが閉じるキューをしています。これは、 Close の呼び出しの結果起こります。

STATE_ListenClosing

待ち受けソケットは、現在接続を閉じています。どのような用途でも使用することはできません。

STATE_ConnectClosing

クライアント ソケットは、現在接続を閉じています。どのような用途でも使用することはできません。

使用法

TcpLink クラスは、クライアント、またはサーバーとして、2 つの異なる方法で使用することができます。

クライアント

1. 適切な モード を設定します。
2. BindPort()
3. IpAddr 構造を作成します: * Resolve(...) を使用することにより、ホスト名を解決します。 * StringToIpAddr(..) を使用して IP 文字列を返還します。
4. Open(..)
5. Opened() イベントを待つか、 LinkState が STATE_Connected になるか、 IsConnected() が True を返すのを待ちます。
6. データの読み取り/書き込みをします。
7. Close(..)

クライアントは通常、ランダムな使用されていないポートを使用するので、 BindPort は引数なしで呼び出されるべきです。

TcpLink をクライアントとしてどのように使用するかの例は、以下のパッケージ内の TcpLinkClient クラスを参照してください。

サーバー

TcpLink のサーバーとしての使用は、もう少し複雑です。サーバーを以下の 2 つのクラスに分けることをお勧めします:

1. 一般的な待ち受け (listening) クラス
2. 接続待ち (accepting) クラス

一般的な待ち受けクラスは、単に接続の試みを待ち受け、接続が確立すると接続待ちクラスをスポーンします。接続待ちクラスは実際に接続をプロセスします。このロジックは TcpLink クラスにビルドされているので、 AcceptClass 変数を設定するだけで構いません。

待ち受けクラスのプロセスは以下のようになっています。

1. 適切な モード を設定します。
2. 待ち受けクラスを設定します。
3. BindPort(12345)
4. Listen()
5. [任意] GainedChild(..) と LostChild(..) イベントに応答します。

サーバーは特定のポートで待ち受けするべきです。そうでないと、クライアントがどのポートに接続すればよいかが分かりません。ポートが既に他のプロセスにバインドされているというこが起こり得ます。この場合、 BindPort(..) は 0 の値を返します。バインドされたポートがなかったということです。あるいは、2 つ目のパラメータを True に設定すると、次に利用可能になったポートにバインドすることができます。バインドされたポートは、 BindPort(..) 呼び出しにより返されます。バインドが成功すると、 Listen() を呼び出してサーバーを開始することができます。

AcceptClass を定義すると、新しい接続が作成された際に、イベント GainedChild(..) と LostChild(..) が呼び出されます。これを使用して、サーバーへの最大接続数を制限することができます。 新しい接続の受け入れを中止するには、 Close() を呼び出し、接続を再び受け入れ始めるには、 Listen() を再度呼び出せばよいだけです。

接続待ちクラスは、接続が確立された後のクライアント ソケットのような動作をします。

1. Accepted イベントを待ちます。
2. データの読み取り/書き込みをします。
3. Close(..)

AcceptClass がまったく設定されていないと、接続するクライアントすべてに対して、待ち受けクラスが Accepted イベントを受信することになります。

API