UDN
Search public documentation:

TcpLink
日本語訳
中国翻译
한국어

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

UE3 Home > Input / Output > TcpLink

TcpLink


Overview


The TcpLink class allows you to create a TCP socket from within the UnrealEngine. Through this socket you can connect with other servers on the internet, or you can provide a simple internet service.

A word of caution, this is not a high performance feature. Using it can have a serious impact on the game performance. The performance impact is higher when providing a service. So keep this in mind when using this functionality.

At the bottom of this page you will find a few examples that use the TcpLink.

Included with the engine is an implementation of a HTTP WebServer. This webserver makes use of the TcpLink functionality.

Modes


The TcpLink class has a few modes which control how this class functions. These modes are described below.

Receive mode

TcpLink can operate in two different modes when receiving:

  • Event mode (RMODE_Event)
  • Manual mode (RMODE_Manual)

Event mode

In event mode the native code of TcpLink link will trigger one of the events depending on the Link mode.

In MODE_Text the ReceivedText event is executed. The text argument contains all the text received since the last event.

In MODE_Line the ReceivedLine event is executed. The line argument contains a single line, without the line terminator. Unlike the other events this one can happen more than once per tick.

In MODE_Binary the ReceivedBinary event is executed. The count argument tells how many bytes are in the byte buffer B.

Manual mode

As the name suggests, in manual mode you are responsible for reading the data. This could be done during a tick event or using a timer. It is strongly discouraged to perform multiple reads per tick, as this is a slow and blocking operation.

Reading data can be done using either the ReadText or ReadBinary functions. Both functions return the number of bytes read. The count argument of ReadBinary defines the maximum number of bytes you want to read. Use the the return value to determine the actual number of read bytes.

Unlike in the event mode it does not matter what the link mode is. You can use either function. Use the lightweight IsDataPending function so see if you should even bother reading data.

Link mode

There are two different modes in which the TcpLink can operate. The link mode determines which events will be called when the TcpLink operates in receive mode event mode.

Link mode also affects how the SendText method works. When the link mode is set to MODE_Line, then newline terminators are appended to the text that is send using SendText. See line mode for the newline terminator used.

Line mode

The line mode controls how new lines are detected when receiving text, and what new line terminators are added with SendText. The line mode is only used when the link mode is set toe MODE_Line.

The line mode is set independently for sending (OutLineMode) and receiving (InLineMode).

Mode Terminator  
LMODE_DOS \n\r  
LMODE_UNIX \n  
LMODE_MAC \r\n Should not be used. It is incorrect, as old MacOS used just \r.
LMODE_AUTO \n\r For receiving this splits on \n and removes any leading or trailing \r.

Link state


The TcpLink contains a variable which reports the current status of the link: LinkState. Usually you won't need to bother with this, especially not when you're using the events of TcpLink. But in some cases it might be interesting to know what is happening.

STATE_Initialized
The initial state of the TcpLink. It is ready for being bound. You can use BindPort.
STATE_Ready
The TcpLink is bound to a port and is ready for establishing a connection. You can either use Open or Listen.
STATE_Listening
The TcpLink is listening for incoming connections. This is usually the result of a call to Listen.
STATE_Connecting
A connection attempt is in process. This is the result of a call to Open. The TcpLink is not yet ready for I/O.
STATE_Connected
A connection has beenestablished, and is ready for I/O.
STATE_ListenClosePending
The listen socket is queued to be closed. This is the result of calling Close.
STATE_ConnectClosePending
The client socket is queued to be closed. This is the result of calling Close.
STATE_ListenClosing
The listen socket is currently closing it's connections. It can not be used for anything, yet.
STATE_ConnectClosing
The client socket is currently closing it's connections. It can not be used for anything, yet.

Usage


The TcpLink class can be used in two different way, as client or as server.

Client

  1. Set the appropiate modes.
  2. BindPort()
  3. Create IpAddr structure: * Resove a hostname by using Resolve(...) * Convert an IP string using StringToIpAddr(..)
  4. Open(..)
  5. Wait for Opened() event, or when LinkState is STATE_Connected, or when IsConnected() returns true.
  6. Read and/or write data
  7. Close(..)

Clients usually use a random free port, thus BindPort should be called without any arguments.

See the TcpLinkClient class in the package below for an example on how to use the TcpLink as a client.

Server

Using the TcpLink for a server is a little bit more complicated. It is strongly advised to divide the server into two classes:

  1. General listening class
  2. Connection accepting class

The general listening class will simply listen for connection attempts and spawn a connection-accepting class when a connection is made. The connection-accepting class will actually process the connection. This logic is built into the TcpLink class, all you have to do is set the AcceptClass variable.

The process for the listening class is as follows:

  1. Set the appropriate modes.
  2. Set the listen class
  3. BindPort(12345)
  4. Listen()
  5. [Optional] Respond to GainedChild(..) and LostChild(..) events.

A server should listen on a specific port, otherwise the clients do not know to what port they should connect to. It could happen that the port is already bound some an other process. In that case BindPort(..) will return the value 0, meaning that no port was bound. Alternatively you can set the second parameter to true, and it will bind the next available port. The bound port will be returned by the BindPort(..) call. After binding is succesful you can call Listen() to start the server.

When defined a AcceptClass the events GainedChild(..) and LostChild(..) will be called when a new connection is created. You can use this to limit the maximum number of connections to the server. To stop accepting new connections you simply call Close(), and to restart accepting connections simply call Listen() again.

The connection accepting class work pretty much like the client socket right after the connection was established:

  1. Wait for Accepted event
  2. Read and/or write data
  3. Close(..)

When no AcceptClass is set the listening class will receive the Accepted event for every client that connects.

API


Structures

IpAddr

This is a composite of the IP address (IPv4) and port number.

Variables

LinkMode
See Link mode
InLineMode , OutLineMode
See Line mode
Port
The local port
ReceiveMode
See Receive mode
LinkState
See Link state
RemoteAddr
An IpAddr structure containing the information of the side
AcceptClass
Used in server mode as the class that will process the incoming connection

There are other variables besides the ones listed here, but those are used internally and should be left alone.

Functions

IsDataPending

native function bool IsDataPending()

Returns true if data is pending on the socket.

ParseURL

native function bool ParseURL(coerce string URL, out string Addr, out int PortNum, out string LevelName, out string EntryName)

Parses an Unreal URL. Returns true for valid urls. An Unreal URL is not like a URL you are used with in browsers. It might not be very useful.

Resolve

native function Resolve( coerce string Domain )

Resolve the hostname provided as first argument. Hostname resolving is a slow process, therefor the result of function is returned through an event.

In case of a successful resolve the Resolved is called. Otherwise the ResolveFailed event is called.

GetLastError

native function int GetLastError()

Returns the last error code. A return value of 0 means that there was no error. What the other values mean depends on the underlaying subsystem. For MS Windows the error codes are equals to the WinSock API

IpAddrToString

native function string IpAddrToString( IpAddr Arg )

Converts an IpAddr structure to a string. For example: 123.123.123.123:45678

StringToIpAddr

native function bool StringToIpAddr( string Str, out IpAddr Addr )

Parses an IPv4 address + port to an IpAddr structure. Returns true when successful.

GetLocalIP

native function GetLocalIP(out IpAddr Arg )

Get the local IP address. This is the first IP address as returned by the underlaying subsystem, and it might not be a routable address. So use it with caution.

BindPort

native function int BindPort( optional int PortNum, optional bool bUseNextAvailable )

Bind a port for this TcpLink instance. If no port number is given a random free port is allocated. If the second argument is true the next available free port will be bound if the prefered port is already used. If it is false the binding will simply fail.

The return value is the bound port, or 0 if binding failed.

Listen

native function bool Listen()

Set the TcpLink to listen mode. Returns true if successful. In listen mode the TcpLink will wait incomming connections. See server mode for more information.

Open

native function bool Open( IpAddr Addr )

Open a connection to a remote host. Either use StringToIpAddr or Resolve to get a valid IpAddr structure.

Returns false if there was an issue initiating the connection. After calling this function the socket is not yet ready for communication. Wait for the Opened event or when IsConnected becomes true.

Close

native function bool Close()

Close the current connection. Use this to stop the TcpLink for listening incoming connections, or to close the connection to the remote host. After closing the connection you can reopen is with Open or Close.

IsConnected

native function bool IsConnected()

Returns true when the TcpLink is connected to a remote host. In client mode it returns true when a valid connection has been establish to the remote host. In server mode it will only return true when a client is connected.

SendText

native function int SendText( coerce string Str )

Send a string to the remote host. If the link mode is MODE_Line a line terminator is appended. See line mode for more information.

It will return the number of bytes send to the remote host, this might not be the same as the string length.

SendBinary

native function int SendBinary( int Count, byte B[255] )

Send a number of bytes to the remote host. The count argument defines the number of bytes in the buffer (the second argument) to send to the remote host. You can send a maximum of 255 bytes at the time.

It will return the number of bytes send to the remote host.

ReadText

native function int ReadText( out string Str )

Read text from the remote host. This is a blocking operation, it will not return until data has been read. This function should only be used in manual transfer mode.

It returns the number of bytes read, this does not have to be equal to the string length.

ReadBinary

native function int ReadBinary( int Count, out byte B[255] )

Read up to count bytes from the remote host. You can read up to 255 bytes at the time. This function should only be used in manual transfer mode.

It returns the number of bytes read. This can be less that the value provided in count.

Events

Resolved

event Resolved( IpAddr Addr )

Called when resolving a hostname successful.

ResolveFailed

event ResolveFailed()

Called when the hostname could not be resolved.

Accepted

event Accepted()

Called when a client connects to a TcpLink in listen mode, or on a TcpLink which was spawned by a TcpLink in listen mode.

Opened

event Opened()

Called for a TcpLink as the result of a successful open command.

Closed

event Closed()

Called when the connection of a TcpLink is closed. This could be the result of either called close or when the remote host closes the connection.

ReceivedText

event ReceivedText( string Text )

Called when the TcpLink receives text when the link mode is MODE_Text and then the receive mode is RMODE_Event.

ReceivedLine

event ReceivedText( string Line )

Called when the TcpLink receives text when the link mode is MODE_Line and then the receive mode is RMODE_Event. The text has been stripped from newlines according to the line mode. This event can be called multiple times per tick.

ReceivedText

event ReceivedBinary( int Count, byte B[255] )

Called when the TcpLink receives text when the link mode is MODE_Binary and then the receive mode is RMODE_Event. The count argument defines how many bytes were written to the byte buffer.

Downloads


Included in the zip file are a few example uses of the TcpLink class:

TcpLinkClient
A very simple HTTP client.
TcpLinkServer
A simple server which will echo every line it receives, this processing is actually handled by the TcpLinkServerAcceptor class.
TcpLinkServerAcceptor
The class that handles the connections that the TcpLinkServer receives.