Legacy:TcpLink

From Unreal Wiki, The Unreal Engine Documentation Site
Jump to navigation Jump to search
UT :: Actor (UT) >> Info (UT) >> InternetInfo >> InternetLink (UT) >> TcpLink (Package: IpDrv)
UT2003 :: Actor >> Info >> InternetInfo >> InternetLink >> TcpLink (Package: IpDrv)

A socket class for the Wikipedia:Transmission Control Protocol. This class is almost identical in UT, UT2003 and UT2004. The only change is the added RecvBuf string property in UT200x.

Note: Like any InternetLink, TcpLink subclass ignore their default value for the LinkMode and ReceiveMode properties. Make sure you set them to the desired value before opening a connection unless you are happy with the default MODE_Text and RMORE_Event values. If you only want to listen for connections and use AcceptClass to spawn new TcpLinks for the accepted connections you don't need to set the LinkMode and ReceiveMode for the listening TcpLink.

Enums

See InternetLink for other relevant enums.

ELinkState enum

Enumeration of the possible socket states. These are not the TCP socket states, but they are similar to them.

STATE_Initialized 
The socket is initialized. It is ready to resolve addresses and bind a port.
STATE_Ready 
A port has been bound and the socket is ready to open a connection or listen for incoming connections.
STATE_Listening 
The socket is either listening for incoming connections or has accepted an incoming connection without spawning a child TcpLink.
STATE_Connecting 
The socket attempts to open a connection.
STATE_Connected 
The socket is connected, either as a result of a successful Open() or because it was spawned as the AcceptClass of a listening socket.
STATE_ListenClosePending 
A connected listen socket marked for closing.
STATE_ConnectClosePending 
A connected socket marked for closing.
STATE_ListenClosing 
An listen socket in process of closing.
STATE_ConnectClosing 
A socket in process of closing.

Properties

ELinkState LinkState 
The current state of the socket. (see above) This isn't declared as const, but you shouldn't modify this anyway.
InternetLink.IpAddr RemoteAddr 
Contains the address of the remote socket when accepting an incoming connection while listening. The value is valid as soon as the Accept() event is called. This value is not used by the connection and is not set at all when Open()ing a connection.
class<TcpLink> AcceptClass 
Set this to a valid TcpLink subclass if you want to listen for multiple simultaneous incoming connections. A TcpLink of the specified class is spawned whenever the listening socket accepts a connection. If this is set to None, the listening socket itself will open the connection and stop listening.
array<byte> SendFIFO (const) 
The buffer for data to be sent. Data fed into the various Send*() methods is buffered here until the data is actually sent, which happens once per tick.
(This is a dynamic array, so it's not accessible from UnrealScript in the Unreal Engine 1.)
string RecvBuf (const) 
The buffer for received data in MODE_Line LinkMode. Received data is temporarily stored here until the next line terminator is received. (This property does not exist in UT.)

Methods

Native Functions

Connection Methods

int BindPort(optional int Port, optional bool bUseNextAvailable) 
Attempts to bind a port for this socket. This function must be called once before using the Listen() or Open() methods. Leaving out the port or passing the value 0 means BindPort should attempt to bind a random port. If bUseNextAvailable is True, BindPort will increment the port number until it finds a port that is still available. This parameter should be set to True if a random port should be bound to increase the chance of finding a valid port number.
BindPort will return the actually bound port number on success or 0 on failure. Note that you can only call BindPort once before opening a connection or starting to listen. As soon as BindPort was successful, further BindPort calls will fail.
bool Listen() 
Start listening for connections. Returns true on success or fals if the socket could not be placed in listen mode.
When listening for connection and using AcceptClass up to five incoming connections can be queued, but only one of them will be accepted per tick. The others remain in the connection queue and the next one will be processed in the next tick. If the connection queue is full, additional connection attempts are rejected until there's room in the queue again.
bool Open(IpAddr Addr) 
Attempts to open a connection to the specified remote host. Returns false if the connection attempt results in an immediate error, otherwise returns true. The LinkState is set to STATE_Connecting if an actual connection attempt is made. Later the Opened() event is called if the connection attempt succeeds.
Note: There is no event signalling a failure of the connection attempt at a later time.
bool Close() 
Closes the current connection, if any. Always returns true.
bool IsConnected() 
Returns true if connected, false otherwise.

Send Methods

int SendText(coerce string Str) 
Sends the string. In LinkMode MODE_Line a line separator is appended depending on the OutLineMode. (See InternetLink.ELineMode enum for details.) Returns actual number of bytes sent, including the potentially appended line separator.
int SendBinary(int Count, byte B[255]) 
Sends the specified number of bytes from the array. Make sure the Count parameter is a value in the range of 0 to 255. Returns the number of bytes sent, which is identical to the Count parameter.

Manual Read Methods

These methods are only relevant if the ReceiveMode is RMODE_Manual. Use the InternetLink.IsDataPending() method to find out if data has been received.

int ReadText(out string Str) 
Reads pending data as a text string. The InLineMode is ignored. Returns actual number of bytes read, but if the buffer contains a zero byte, the string will be truncated and its length will not match the return value. The data beyond the first null byte is lost. The method returns 0 if no data is available or an error occured.
int ReadBinary(int Count, out byte B[255]) 
Reads up to Count pending bytes of data into the byte array and returns the actual number of bytes read. Make sure the Count value is in the range of 0 to 255.

Events

Connection Events

Accepted() 
Called when a listen socket accepted an incoming connection. If a new TcpLink was spawned to handle the connection, this event is called on the new TcpLink after the listen socket received a GainedChild() event with the new TcpLink as parameter. The RemoteAddr property of the accepting TcpLink will be set to the remote address and port.
Opened() 
Called when the Open() method succeeds to establish a connection.
Closed() 
Called when the connection is closed by the remote host or as a result of the Close() method.

Receive Events

These events are only called if ReceiveMode is RMODE_Event, which is the default. Appearantly in UT only LinkMode MODE_Text works as advertised.

ReceivedText(string Text) 
Called once per tick if data is received and the LinkMode is MODE_Text. The Text parameter will contain the entire input buffer. Note that the string is truncated prematurely if a null byte was received. In that case all buffered text following the null byte is lost.
ReceivedLine(string Line) 
Called whenever a line separator matching the InLineMode is received and LinkMode is MODE_Line. The actually received text is stored in the RecvBuf property and broken up into lines as specified by the InLineMode. For every line the line separator is removed and a ReceivedLine event is generated. Remaining text stays in the buffer until more line separators are received.
This event seems to be broken in UT, it doesn't actually break lines but behaves like ReceivedText.
ReceivedBinary(int Count, byte B[255]) 
Called once per tick if data is received and the LinkMode is MODE_Binary. The Count will contain a value in the range of 1 to 255, signalling the actual number of bytes read into the array.
Note: In the latest release of the IpDrv package for UT, this function is broken. It simply will repeat the same (and incorrect) byte array constantly, with a Count that is greater than 255 (often 999).
Note: This event is also broken in UT3. It receives some garbage before the actual data. Use manual mode instead.

Samples

Known Subclasses (UT)

Known Subclasses (UT200x)