Search public documentation:
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.
The TcpLink class has a few modes which control how this class functions. These modes are described below.
- Event mode (
- Manual mode (
MODE_Textthe ReceivedText event is executed. The text argument contains all the text received since the last event. In
MODE_Linethe 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_Binarythe ReceivedBinary event is executed. The count argument tells how many bytes are in the byte buffer B.
MODE_Line, then newline terminators are appended to the text that is send using SendText. See line mode for the newline terminator used.
MODE_Line. The line mode is set independently for sending (OutLineMode) and receiving (InLineMode).
| || |
| || |
| || || Should not be used. It is incorrect, as old MacOS used just |
| || || For receiving this splits on |
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.
- The initial state of the TcpLink. It is ready for being bound. You can use BindPort.
- The TcpLink is bound to a port and is ready for establishing a connection. You can either use Open or Listen.
- The TcpLink is listening for incoming connections. This is usually the result of a call to Listen.
- A connection attempt is in process. This is the result of a call to Open. The TcpLink is not yet ready for I/O.
- A connection has beenestablished, and is ready for I/O.
- The listen socket is queued to be closed. This is the result of calling Close.
- The client socket is queued to be closed. This is the result of calling Close.
- The listen socket is currently closing it's connections. It can not be used for anything, yet.
- The client socket is currently closing it's connections. It can not be used for anything, yet.
The TcpLink class can be used in two different way, as client or as server.
- Set the appropiate modes.
IpAddrstructure: * Resove a hostname by using Resolve(...) * Convert an IP string using StringToIpAddr(..)
- Wait for Opened() event, or when LinkState is
STATE_Connected, or when IsConnected() returns true.
- Read and/or write data
TcpLinkClientclass in the package below for an example on how to use the TcpLink as a client.
- General listening class
- Connection accepting class
- Set the appropriate modes.
- Set the listen class
- [Optional] Respond to GainedChild(..) and LostChild(..) events.
- Wait for Accepted event
- Read and/or write data
- See Link mode
- InLineMode , OutLineMode
- See Line mode
- The local port
- See Receive mode
- See Link state
IpAddrstructure containing the information of the side
- Used in server mode as the class that will process the incoming connection
native function bool IsDataPending()Returns true if data is pending on the socket.
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.
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.
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
native function string IpAddrToString( IpAddr Arg )Converts an IpAddr structure to a string. For example:
native function bool StringToIpAddr( string Str, out IpAddr Addr )Parses an IPv4 address + port to an IpAddr structure. Returns true when successful.
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.
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.
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.
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.
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.
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.
native function int SendText( coerce string Str )Send a string to the remote host. If the link mode is
MODE_Linea 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.
native function int SendBinary( int Count, byte B )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.
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.
native function int ReadBinary( int Count, out byte B )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.
event Resolved( IpAddr Addr )Called when resolving a hostname successful.
event ResolveFailed()Called when the hostname could not be resolved.
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.
event Opened()Called for a TcpLink as the result of a successful open command.
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.
event ReceivedText( string Text )Called when the TcpLink receives text when the link mode is
MODE_Textand then the receive mode is
event ReceivedText( string Line )Called when the TcpLink receives text when the link mode is
MODE_Lineand 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.
event ReceivedBinary( int Count, byte B )Called when the TcpLink receives text when the link mode is
MODE_Binaryand then the receive mode is
RMODE_Event. The count argument defines how many bytes were written to the byte buffer.
Included in the zip file are a few example uses of the TcpLink class:
- A very simple HTTP client.
- A simple server which will echo every line it receives, this processing is actually handled by the
- The class that handles the connections that the
- TcpLinkExamples.zip: TcpLink Examples