The three virtues of a programmer: Laziness, Impatience, and Hubris. – Larry Wall

Difference between revisions of "UE2:TcpLink (UT2004)"

From Unreal Wiki, The Unreal Engine Documentation Site
Jump to: navigation, search
(unified class descriptions for all engine versions)
(added descriptions)
Line 17: Line 17:
 
}}
 
}}
 
}}
 
}}
{{autogenerated}}
 
 
TcpLink: An Internet TCP/IP connection.
 
TcpLink: An Internet TCP/IP connection.
 +
 +
See the parent class {{cl|InternetLink}} for additional members required to use this class.
  
 
==Properties==
 
==Properties==
Line 24: Line 25:
 
'''Type:''' [[class]]<{{cl|TcpLink}}>
 
'''Type:''' [[class]]<{{cl|TcpLink}}>
  
<!-- enter variable description -->
+
When in listening mode and this property specifies another TcpLink class, a new instance of that class is spawned with the listening instance as {{tl|Owner|Actor|internal variables}} whenever a connection is accepted.
  
 
====LinkState====
 
====LinkState====
 
'''Type:''' {{tl|ELinkState}}
 
'''Type:''' {{tl|ELinkState}}
  
<!-- enter variable description -->
+
The current link state of this TCP socket.
  
{{#ifeq:{{gamename}}|UT2003|
+
{{#ifeq:{{gamename}}|UT2003||{{#ifeq:{{NAMESPACE}}|UE1||
|{{#ifeq:{{NAMESPACE}}|UE1|
+
|
+
 
====RecvBuf====
 
====RecvBuf====
 
'''Type:''' [[string]]
 
'''Type:''' [[string]]
Line 39: Line 38:
 
'''[[Variables#Modifiers|Modifiers]]:''' const
 
'''[[Variables#Modifiers|Modifiers]]:''' const
  
<!-- enter variable description -->
+
An internal buffer for received string data that is used to store received text in line mode until a line ending was received.
 
}}}}
 
}}}}
 
 
====RemoteAddr====
 
====RemoteAddr====
 
'''Type:''' {{tl|IpAddr|InternetLink}}
 
'''Type:''' {{tl|IpAddr|InternetLink}}
  
<!-- enter variable description -->
+
The remote side's IP address and TCP port when this instance is connected. (Not applicable for listening sockets with an {{tl|AcceptClass}}.
  
 
====SendFIFO====
 
====SendFIFO====
Line 52: Line 50:
 
'''[[Variables#Modifiers|Modifiers]]:''' const
 
'''[[Variables#Modifiers|Modifiers]]:''' const
  
send fifo
+
An internal buffer for data to send. The TcpLink will try to flush any data to the underlying socket immediately, but if the socket can't handle all data, it may be stored here until the next attempt.
  
 
===Default values===
 
===Default values===
Line 85: Line 83:
 
==Enums==
 
==Enums==
 
====ELinkState====
 
====ELinkState====
<!-- enter enum description -->
+
This enumeration contains possible link states of the TCP socket.
; STATE_Initialized : Sockets is initialized
+
; STATE_Initialized : Sockets is initialized. This is the initial state when the TcpLink is spawned.
; STATE_Ready : Port bound, ready for activity
+
; STATE_Ready : Port bound, ready for activity. This state is set when the {{tl|BindPort}}() function returns successfully.
; STATE_Listening : Listening for connections
+
; STATE_Listening : Listening for connections. This state is set when the {{tl|Listen}}() function returns successfully.
; STATE_Connecting : Attempting to connect
+
; STATE_Connecting : Attempting to connect. This state indicates that a previous {{tl|Open}}() call was successful, but the connection is not yet established.
; STATE_Connected : Open and connected
+
; STATE_Connected : Open and connected. This state indicates that the background operations initiated by a previous {{tl|Open}}() call have successfully completed or a connection was accepted in listening state and the connection is now established.
; STATE_ListenClosePending : Socket in process of closing
+
; STATE_ListenClosePending : Socket in process of closing. This state is set after a {{tl|Close}}() call on a listening socket that had previously established a connection.
; STATE_ConnectClosePending : Socket in process of closing
+
; STATE_ConnectClosePending : Socket in process of closing. This state is set after a {{tl|Close}}() call on a non-listening socket (i.e. the connection was established via {{tl|Open}}() or by spawning a new TcpLink for an accepted connection) that had previously established a connection.
; STATE_ListenClosing : Socket in process of closing
+
; STATE_ListenClosing : Socket in process of closing. This state is set after a {{tl|Close}}() call on a listening socket without a connections.
; STATE_ConnectClosing : Socket in process of closing
+
; STATE_ConnectClosing : Socket in process of closing. This state is set when the close-pending connection was shut down.
  
 
==Functions==
 
==Functions==
Line 101: Line 99:
 
{{code|native function [[int]]&nbsp;'''BindPort''' (optional&nbsp;[[int]]&nbsp;'''Port''', optional&nbsp;[[bool]]&nbsp;'''bUseNextAvailable''')}}
 
{{code|native function [[int]]&nbsp;'''BindPort''' (optional&nbsp;[[int]]&nbsp;'''Port''', optional&nbsp;[[bool]]&nbsp;'''bUseNextAvailable''')}}
  
<!-- enter function description -->
+
Binds a local TCP port for this socket. This function must be called once before using {{tl|Open}}() or {{tl|Listen}}(). Specifying a port is recommended if you plan to listen for incoming connections. However, if you want to connect to a remote listening socket, specifying a port is actually counter-productive, since you usually don't care which local port is bound on the client side.
  
 
====Close====
 
====Close====
 
{{code|native function [[bool]]&nbsp;'''Close''' ()}}
 
{{code|native function [[bool]]&nbsp;'''Close''' ()}}
  
<!-- enter function description -->
+
Closes a connection or stops listening for connections.
  
 
====IsConnected====
 
====IsConnected====
 
{{code|native function [[bool]]&nbsp;'''IsConnected''' ()}}
 
{{code|native function [[bool]]&nbsp;'''IsConnected''' ()}}
  
<!-- enter function description -->
+
Returns whether the TCP socket is currently connected.
  
 
====Listen====
 
====Listen====
 
{{code|native function [[bool]]&nbsp;'''Listen''' ()}}
 
{{code|native function [[bool]]&nbsp;'''Listen''' ()}}
  
<!-- enter function description -->
+
Starts listening for incoming connection attempts on the previously bound port.
  
 
====Open====
 
====Open====
 
{{code|native function [[bool]]&nbsp;'''Open''' ({{tl|IpAddr|InternetLink}}&nbsp;'''Addr''')}}
 
{{code|native function [[bool]]&nbsp;'''Open''' ({{tl|IpAddr|InternetLink}}&nbsp;'''Addr''')}}
  
<!-- enter function description -->
+
Opens a connection to the specifies remote IP address and TCP port using the previously bound port as local port.
  
 
====ReadBinary====
 
====ReadBinary====
 
{{code|native function [[int]]&nbsp;'''ReadBinary''' ([[int]]&nbsp;'''Count''', out&nbsp;[[byte]]&nbsp;'''B'''[255])}}
 
{{code|native function [[int]]&nbsp;'''ReadBinary''' ([[int]]&nbsp;'''Count''', out&nbsp;[[byte]]&nbsp;'''B'''[255])}}
  
<!-- enter function description -->
+
Attempts to read the specified number of bytes into the provided buffer and returns the actual number of bytes read. (Don't specify a count greater than 255, unless you want to risk breaking things!)
 +
 
 +
You should not use this function when the TcpLink is in <code>{{tl|ReceiveMode|InternetLink}} = RMODE_Event</code>.
  
 
====ReadText====
 
====ReadText====
 
{{code|native function [[int]]&nbsp;'''ReadText''' (out&nbsp;[[string]]&nbsp;'''Str''')}}
 
{{code|native function [[int]]&nbsp;'''ReadText''' (out&nbsp;[[string]]&nbsp;'''Str''')}}
  
<!-- enter function description -->
+
Reads all pending received bytes and interprets them as Windows-1252 encoded string. If the receive buffer contains null bytes, the returned string will be truncated at the first such byte, but the receive buffer is emptied anyway, so part of the data may be lost. (Use {{tl|ReadBinary}}() if you expect binary data to be received.)
 +
 
 +
You should not use this function when the TcpLink is in <code>{{tl|ReceiveMode|InternetLink}} = RMODE_Event</code>.
  
 
====SendBinary====
 
====SendBinary====
 
{{code|native function [[int]]&nbsp;'''SendBinary''' ([[int]]&nbsp;'''Count''', [[byte]]&nbsp;'''B'''[255])}}
 
{{code|native function [[int]]&nbsp;'''SendBinary''' ([[int]]&nbsp;'''Count''', [[byte]]&nbsp;'''B'''[255])}}
  
<!-- enter function description -->
+
Sends the specified number of bytes from the provided buffer. (Like with {{tl|ReadBinary}}(), the count is not checked, so make sure it never exceeds 255!)
  
 
====SendText====
 
====SendText====
 
{{code|native function [[int]]&nbsp;'''SendText''' (coerce&nbsp;[[string]]&nbsp;'''Str''')}}
 
{{code|native function [[int]]&nbsp;'''SendText''' (coerce&nbsp;[[string]]&nbsp;'''Str''')}}
  
<!-- enter function description -->
+
Sends the specified string, assuming Windows-1252 encoding. That means if the string contains character codes greater than 255, those characters' high bytes will be lost!
  
 
===Events===
 
===Events===
Line 147: Line 149:
 
{{code|event '''Accepted''' ()}}
 
{{code|event '''Accepted''' ()}}
  
<!-- enter event description -->
+
This event is called on the {{tl|AcceptClass}} instance spawned when a connection is accepted by a listening socket.
  
 
====Closed====
 
====Closed====
 
{{code|event '''Closed''' ()}}
 
{{code|event '''Closed''' ()}}
  
<!-- enter event description -->
+
Called when a connection was closed.
  
 
====Opened====
 
====Opened====
 
{{code|event '''Opened''' ()}}
 
{{code|event '''Opened''' ()}}
  
<!-- enter event description -->
+
Called when a connection was opened.
  
 
====ReceivedBinary====
 
====ReceivedBinary====
 
{{code|event '''ReceivedBinary''' ([[int]]&nbsp;'''Count''', [[byte]]&nbsp;'''B'''[255])}}
 
{{code|event '''ReceivedBinary''' ([[int]]&nbsp;'''Count''', [[byte]]&nbsp;'''B'''[255])}}
  
<!-- enter event description -->
+
Called in <code>{{tl|ReceiveMode|InternetLink}} = RMODE_Event</code> when the {{tl|LinkMode|InternetLink}} is <code>MODE_Binary</code> and new data was received.
  
 
====ReceivedLine====
 
====ReceivedLine====
 
{{code|event '''ReceivedLine''' ([[string]]&nbsp;'''Line''')}}
 
{{code|event '''ReceivedLine''' ([[string]]&nbsp;'''Line''')}}
  
<!-- enter event description -->
+
Called in <code>{{tl|ReceiveMode|InternetLink}} = RMODE_Event</code> when the {{tl|LinkMode|InternetLink}} is <code>MODE_Line</code> and a new line was received. The end of the line type is defined by the {{tl|LineMode|InternetLink}} property.
  
 
====ReceivedText====
 
====ReceivedText====
 
{{code|event '''ReceivedText''' ([[string]]&nbsp;'''Text''')}}
 
{{code|event '''ReceivedText''' ([[string]]&nbsp;'''Text''')}}
  
<!-- enter event description -->
+
Called in <code>{{tl|ReceiveMode|InternetLink}} = RMODE_Event</code> when the {{tl|LinkMode|InternetLink}} is <code>MODE_Text</code> and new data was received.

Revision as of 10:15, 27 April 2014

UT2004 Object >> Actor >> Info >> InternetInfo >> InternetLink >> TcpLink
Package: 
IpDrv
Direct subclasses:
BufferedTcpLink, WebConnection, WebServer
This class in other games:
RTNP, U1, UT, U2, U2XMP, UE2Runtime, UT2003, UDK, UT3

TcpLink: An Internet TCP/IP connection.

See the parent class InternetLink for additional members required to use this class.

Properties

AcceptClass

Type: class<TcpLink>

When in listening mode and this property specifies another TcpLink class, a new instance of that class is spawned with the listening instance as Actor.Owner whenever a connection is accepted.

LinkState

Type: ELinkState

The current link state of this TCP socket.

RecvBuf

Type: string

Modifiers: const

An internal buffer for received string data that is used to store received text in line mode until a line ending was received.

RemoteAddr

Type: InternetLink.IpAddr

The remote side's IP address and TCP port when this instance is connected. (Not applicable for listening sockets with an AcceptClass.

SendFIFO

Type: array<byte>

Modifiers: const

An internal buffer for data to send. The TcpLink will try to flush any data to the underlying socket immediately, but if the socket can't handle all data, it may be stored here until the next attempt.

Default values

Property Value
bAlwaysTick True


Enums

ELinkState

This enumeration contains possible link states of the TCP socket.

STATE_Initialized 
Sockets is initialized. This is the initial state when the TcpLink is spawned.
STATE_Ready 
Port bound, ready for activity. This state is set when the BindPort() function returns successfully.
STATE_Listening 
Listening for connections. This state is set when the Listen() function returns successfully.
STATE_Connecting 
Attempting to connect. This state indicates that a previous Open() call was successful, but the connection is not yet established.
STATE_Connected 
Open and connected. This state indicates that the background operations initiated by a previous Open() call have successfully completed or a connection was accepted in listening state and the connection is now established.
STATE_ListenClosePending 
Socket in process of closing. This state is set after a Close() call on a listening socket that had previously established a connection.
STATE_ConnectClosePending 
Socket in process of closing. This state is set after a Close() call on a non-listening socket (i.e. the connection was established via Open() or by spawning a new TcpLink for an accepted connection) that had previously established a connection.
STATE_ListenClosing 
Socket in process of closing. This state is set after a Close() call on a listening socket without a connections.
STATE_ConnectClosing 
Socket in process of closing. This state is set when the close-pending connection was shut down.

Functions

Native functions

BindPort

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

Binds a local TCP port for this socket. This function must be called once before using Open() or Listen(). Specifying a port is recommended if you plan to listen for incoming connections. However, if you want to connect to a remote listening socket, specifying a port is actually counter-productive, since you usually don't care which local port is bound on the client side.

Close

native function bool Close ()

Closes a connection or stops listening for connections.

IsConnected

native function bool IsConnected ()

Returns whether the TCP socket is currently connected.

Listen

native function bool Listen ()

Starts listening for incoming connection attempts on the previously bound port.

Open

native function bool Open (InternetLink.IpAddr Addr)

Opens a connection to the specifies remote IP address and TCP port using the previously bound port as local port.

ReadBinary

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

Attempts to read the specified number of bytes into the provided buffer and returns the actual number of bytes read. (Don't specify a count greater than 255, unless you want to risk breaking things!)

You should not use this function when the TcpLink is in InternetLink.ReceiveMode = RMODE_Event.

ReadText

native function int ReadText (out string Str)

Reads all pending received bytes and interprets them as Windows-1252 encoded string. If the receive buffer contains null bytes, the returned string will be truncated at the first such byte, but the receive buffer is emptied anyway, so part of the data may be lost. (Use ReadBinary() if you expect binary data to be received.)

You should not use this function when the TcpLink is in InternetLink.ReceiveMode = RMODE_Event.

SendBinary

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

Sends the specified number of bytes from the provided buffer. (Like with ReadBinary(), the count is not checked, so make sure it never exceeds 255!)

SendText

native function int SendText (coerce string Str)

Sends the specified string, assuming Windows-1252 encoding. That means if the string contains character codes greater than 255, those characters' high bytes will be lost!

Events

Accepted

event Accepted ()

This event is called on the AcceptClass instance spawned when a connection is accepted by a listening socket.

Closed

event Closed ()

Called when a connection was closed.

Opened

event Opened ()

Called when a connection was opened.

ReceivedBinary

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

Called in InternetLink.ReceiveMode = RMODE_Event when the InternetLink.LinkMode is MODE_Binary and new data was received.

ReceivedLine

event ReceivedLine (string Line)

Called in InternetLink.ReceiveMode = RMODE_Event when the InternetLink.LinkMode is MODE_Line and a new line was received. The end of the line type is defined by the InternetLink.LineMode property.

ReceivedText

event ReceivedText (string Text)

Called in InternetLink.ReceiveMode = RMODE_Event when the InternetLink.LinkMode is MODE_Text and new data was received.