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
中国翻译
한국어
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. InMODE_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 toMODE_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 toeMODE_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
- Set the appropiate modes.
- BindPort()
- Create
IpAddr
structure: * Resove a hostname by using Resolve(...) * Convert an IP string using StringToIpAddr(..) - Open(..)
- Wait for Opened() event, or when LinkState is
STATE_Connected
, or when IsConnected() returns true. - Read and/or write data
- Close(..)
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:- General listening class
- Connection accepting class
- Set the appropriate modes.
- Set the listen class
- BindPort(12345)
- Listen()
- [Optional] Respond to GainedChild(..) and LostChild(..) events.
- Wait for Accepted event
- Read and/or write data
- Close(..)
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
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.
- TcpLinkExamples.zip: TcpLink Examples