UDN
Search public documentation:
TcpLinkJP
English Translation
中国翻译
한국어
Interested in the Unreal Engine?
Visit the Unreal Technology site.
Looking for jobs and company info?
Check out the Epic games site.
Questions about support via UDN?
Contact the UDN Staff
中国翻译
한국어
Interested in the Unreal Engine?
Visit the Unreal Technology site.
Looking for jobs and company info?
Check out the Epic games site.
Questions about support via UDN?
Contact the UDN Staff
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 つをトリガします。 InMODE_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) を受信するのに、個別に設定されます。
モード | ターミネータ | |
---|---|---|
LMODE_DOS | \n\r | |
LMODE_UNIX | \n | |
LMODE_MAC | \r\n | 使用されるべきではありません。古い MacOS は \r のみを使用していたので、これは間違いです。 |
LMODE_auto | \n\r | 受信で、これは \n で分割し、 \r の手前も後ろも削除します。 |
リンク状態
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 つの異なる方法で使用することができます。クライアント
- 適切な モード を設定します。
- BindPort()
-
IpAddr
構造を作成します: * Resolve(...) を使用することにより、ホスト名を解決します。 * StringToIpAddr(..) を使用して IP 文字列を返還します。 - Open(..)
- Opened() イベントを待つか、 LinkState が
STATE_Connected
になるか、 IsConnected() が True を返すのを待ちます。 - データの読み取り/書き込みをします。
- Close(..)
TcpLinkClient
クラスを参照してください。
サーバー
TcpLink のサーバーとしての使用は、もう少し複雑です。サーバーを以下の 2 つのクラスに分けることをお勧めします:- 一般的な待ち受け (listening) クラス
- 接続待ち (accepting) クラス
- 適切な モード を設定します。
- 待ち受けクラスを設定します。
- BindPort(12345)
- Listen()
- [任意] GainedChild(..) と LostChild(..) イベントに応答します。
- Accepted イベントを待ちます。
- データの読み取り/書き込みをします。
- Close(..)
API
構造
IpAddr
これは、IP アドレス (IPv4) とポート番号の組み合わせです。変数
- LinkMode
- リンク モード を参照してください。
- InLineMode , OutLineMode
- ライン モード を参照してください。
- Port
- ローカル ポートです。
- ReceiveMode
- レシーブ モード を参照してください。
- LinkState
- リンク状態 を参照してください。
- RemoteAddr
- そのサイドの情報を含む
IpAddr
構造です。 - AcceptClass
- サーバー モード で、入ってくる接続をプロセスするクラスとして使用されます。
関数
IsDataPending
native function bool IsDataPending()
ソケットでデータが未解決な場合、True を返します。
ParseURL
native function bool ParseURL(coerce string URL, out string Addr, out int PortNum, out string LevelName, out string EntryName)
Unreal URL を分析します。有効な URL に関して True を返します。
Unreal URL は、ブラウザ内で慣れ親しんでいる URL とは異なります。あまり便利ではないかも知れません。
Resolve
native function Resolve( coerce string Domain )
提供されたホスト名を最初の引数として解決します。ホスト名の解決は時間のかかるプロセスなので、関数の結果はイベントを通して返されます。
解決が成功した場合、 Resolved が呼び出されます。そうでない場合、 ResolveFailed イベントが呼び出されます。
GetLastError
native function int GetLastError()
最後のエラー コードを返します。0 の戻り値は、エラーがなかったということを意味します。他の値が何を意味するかは、下にあるサブシステムによります。
MS Windows の場合、エラー コードは WinSock API と同様です。
IpAddrToString
native function string IpAddrToString( IpAddr Arg )
IpAddr 構造を文字列に変換します。例: 123.123.123.123:45678
StringToIpAddr
native function bool StringToIpAddr( string Str, out IpAddr Addr )
IPv4 アドレスとポートを IpAddr 構造に解析します。成功すると True を返します。
GetLocalIP
native function GetLocalIP(out IpAddr Arg )
ローカル IP アドレスを取得します。これは、下にあるサブシステムによって返される最初の IP アドレスであり、ルーティング可能なアドレスでない場合があります。従って、気をつけて使用してください。
BindPort
native function int BindPort( optional int PortNum, optional bool bUseNextAvailable )
この TcpLink インスタンスのポートをバインドします。ポート番号が与えられていない場合、ランダムな使用されていないポートが割り当てられます。2 つ目の引数が True であれば、既に望ましいポートが使用されている場合に、次に利用可能な未使用のポートがバインドされます。False の場合、バインドは単純に失敗します。
戻り値はバインドされたポート、またはバインドが失敗した場合は 0 になります。
Listen
native function bool Listen()
TcpLink を待ち受けモードに設定します。成功すると True を返します。待ち受けモードでは、TcpLink は入ってくる接続を待ちます。詳細は サーバー モード を参照してください。
Open
native function bool Open( IpAddr Addr )
リモート ホストへの接続を開きます。 StringToIpAddr または Resolve を使用して、有効な IpAddr 構造を取得します。
接続の開始に問題があった場合は、False を返します。この関数を呼び出した後、ソケットはまだ通信の準備ができていません。 Opened イベントを待つか、 IsConnected が True になるのを待ちます。
Close
native function bool Close()
現在の接続を閉じます。TcpLink が入ってくる接続を待ち受けするのを中止する、またはリモート ホストへの接続を閉じるには、これを使用します。接続を閉じた後は、 Open または Close で再度開くことができます。
IsConnected
native function bool IsConnected()
TcpLink がリモート ホストに接続されていると True を返します。クライアント モードでは、有効な接続がリモート ホストに確立されると True を返します。サーバー モードでは、クライアントが接続されている場合のみ True を返します。
SendText
native function int SendText( coerce string Str )
リモート ホストに文字列を送信します。 リンク モード が MODE_Line
の場合、ライン ターミネータが追加されます。詳細は ライン モード を参照してください。
リモート ホストに送られたバイト数を返します。これは、文字列の長さ同じでない場合があります。
SendBinary
native function int SendBinary( int Count, byte B[255] )
リモート ホストにバイト数を送信します。 count 引数は、リモート ホストに送るようなバッファ内にあるバイト数 (2 つ目の引数) を定義します。一度に送ることのできる最大バイト数は 255 バイトです。
リモート ホストへ送られるバイト数を返します。
ReadText
native function int ReadText( out string Str )
リモート ホストからのテキストを読み取ります。これはブロックする操作なので、データが読み取られるまで戻りません。この関数は、 手動転送モード でのみ使用されるべきです。
読み取られるバイト数を返します。これは、文字列の長さと等しくある必要はありません。
ReadBinary
native function int ReadBinary( int Count, out byte B[255] )
リモート ホストからの count バイトまでを読み取ります。一度に読み取ることのできるバイト数は 255 バイトまでです。この関数は、 手動転送モード でのみ使用されるべきです。
読み取られたバイト数を返します。これは、 count で提供された値よりも少ないことがあります。
イベント
Resolved
event Resolved( IpAddr Addr )
ホスト名の解決が成功した場合に呼び出されます。
ResolveFailed
event ResolveFailed()
ホスト名が解決されなかった場合に呼び出されます。
Accepted
event Accepted()
クライアントが待ち受けモードで TcpLink に接続をする、または待ち受けモードで TcpLink によってスポーンされた TcpLink 上で呼び出されます。
Opened
event Opened()
成功した open コマンドの結果として TcpLink のために呼び出されます。
Closed
event Closed()
TcpLink の接続が閉じられると呼び出されます。これは、呼び出された close の結果、またはリモート ホストが接続を閉じた結果です。
ReceivedText
event ReceivedText( string Text )
リンク モード が MODE_Text
で、 レシーブ モード が RMODE_Event
の場合に、TcpLink がテキストを受信すると呼び出されます。
ReceivedLine
event ReceivedText( string Line )
リンク モード が MODE_Line
で、 レシーブ モード が RMODE_Event
の場合に、TcpLink がテキストを受信すると呼び出されます。
ライン モード に従って、テキストは newlines から取り除かれています。このイベントは、tick ごとに複数回呼び出されることが可能です。
ReceivedText
event ReceivedBinary( int Count, byte B[255] )
リンク モード が MODE_Line
で、 レシーブ モード が MODE_Binary
の場合に、TcpLink がテキストを受信すると呼び出されます。 count 引数は、バイト バッファに何バイト書き込まれたかを定義します。
実例
zip ファイルに含まれているのは、TcpLink クラスのいくつかの使用例です。-
TcpLinkClient
- 非常にシンプルな HTTP クライアントです。
-
TcpLinkServer
- 受信するラインすべてをエコーするシンプルなサーバーです。このプロセスは、実際
TcpLinkServerAcceptor
クラスによって処理されます。 -
TcpLinkServerAcceptor
-
TcpLinkServer
が受信する接続を処理するクラスです。
- TcpLinkExamples.zip: TcpLink の使用例