TCPObject Class Reference
[Networking]

Allows communications between the game and a server using TCP/IP protocols. More...

Inheritance diagram for TCPObject:

[legend]

List of all members.

Public Member Functions
void	connect (string address)
	Connect to the given address.
void	disconnect ()
	Disconnect from whatever this TCPObject is currently connected to, if anything.
void	listen (int port)
	Start listening on the specified port for connections.
void	send (string data)
	Transmits the data string to the connected computer.
Callbacks
void	onConnected ()
	Called whenever a connection is established with a server.
void	onConnectFailed ()
	Called whenever a connection has failed to be established with a server.
void	onConnectionRequest (string address, string ID)
	Called whenever a connection request is made.
void	onDisconnect ()
	Called whenever the TCPObject disconnects from whatever it is currently connected to.
void	onDNSFailed ()
	Called whenever the DNS has failed to resolve.
void	onDNSResolved ()
	Called whenever the DNS has been resolved.
void	onLine (string line)
	Called whenever a line of data is sent to this TCPObject.

---

Detailed Description

Allows communications between the game and a server using TCP/IP protocols.

To use TCPObject you set up a connection to a server, send data to the server, and handle each line of the server's response using a callback. Once you are done communicating with the server, you disconnect.

TCPObject is intended to be used with text based protocols which means you'll need to delineate the server's response with an end-of-line character. i.e. the newline character \n. You may optionally include the carriage return character \r prior to the newline and TCPObject will strip it out before sending the line to the callback. If a newline character is not included in the server's output, the received data will not be processed until you disconnect from the server (which flushes the internal buffer).

TCPObject may also be set up to listen to a specific port, making Torque into a TCP server. When used in this manner, a callback is received when a client connection is made. Following the outside connection, text may be sent and lines are processed in the usual manner.

If you want to work with HTTP you may wish to use HTTPObject instead as it handles all of the HTTP header setup and parsing.

Example:

// In this example we'll retrieve the new forum threads RSS
// feed from garagegames.com.  As we're using TCPObject, the
// raw text response will be received from the server, including
// the HTTP header.

// Define callbacks for our specific TCPObject using our instance's
// name (RSSFeed) as the namespace.

// Handle an issue with resolving the server's name
function RSSFeed::onDNSFailed(%this)
{
   // Store this state
   %this.lastState = "DNSFailed";

   // Handle DNS failure
}

function RSSFeed::onConnectFailed(%this)
{
   // Store this state
   %this.lastState = "ConnectFailed";

   // Handle connection failure
}

function RSSFeed::onDNSResolved(%this)
{
   // Store this state
   %this.lastState = "DNSResolved";

}

function RSSFeed::onConnected(%this)
{
   // Store this state
   %this.lastState = "Connected";

}

function RSSFeed::onDisconnect(%this)
{
   // Store this state
   %this.lastState = "Disconnected";

}

// Handle a line from the server
function RSSFeed::onLine(%this, %line)
{
   // Print the line to the console
   echo( %line );
}

// Create the TCPObject
%rss = new TCPObject(RSSFeed);

// Define a dynamic field to store the last connection state
%rss.lastState = "None";

// Connect to the server
%rss.connect("www.garagegames.com:80");

// Send the RSS feed request to the server.  Response will be
// handled in onLine() callback above
%rss.send("GET /feeds/rss/threads HTTP/1.1\r\nHost: www.garagegames.com\r\n\r\n");

See also:

HTTPObject

---

Member Function Documentation

void TCPObject::connect

(

string

address

)

Connect to the given address.

Parameters:

address

Server address (including port) to connect to.

Example:

// Set the address.
%address = "www.garagegames.com:80";

// Inform this TCPObject to connect to the specified address.
%thisTCPObj.connect(%address);

void TCPObject::disconnect

(

)

Disconnect from whatever this TCPObject is currently connected to, if anything.

Example:

// Inform this TCPObject to disconnect from anything it is currently connected to.
%thisTCPObj.disconnect();

void TCPObject::listen

(

int

port

)

Start listening on the specified port for connections.

This method starts a listener which looks for incoming TCP connections to a port. You must overload the onConnectionRequest callback to create a new TCPObject to read, write, or reject the new connection.

Parameters:

port

Port for this TCPObject to start listening for connections on.

Example:

// Create a listener on port 8080.
new TCPObject( TCPListener );
TCPListener.listen( 8080 );

function TCPListener::onConnectionRequest( %this, %address, %id )
{
   // Create a new object to manage the connection.
   new TCPObject( TCPClient, %id );
}

function TCPClient::onLine( %this, %line )
{
   // Print the line of text from client.
   echo( %line );
}

void TCPObject::onConnected

(

)

Called whenever a connection is established with a server.

void TCPObject::onConnectFailed

(

)

Called whenever a connection has failed to be established with a server.

void TCPObject::onConnectionRequest	(	string	address,
		string	ID
	)

Called whenever a connection request is made.

This callback is used when the TCPObject is listening to a port and a client is attempting to connect.

Parameters:

	address	Server address connecting from.
	ID	Connection ID

See also:

listen()

void TCPObject::onDisconnect

(

)

Called whenever the TCPObject disconnects from whatever it is currently connected to.

void TCPObject::onDNSFailed

(

)

Called whenever the DNS has failed to resolve.

void TCPObject::onDNSResolved

(

)

Called whenever the DNS has been resolved.

void TCPObject::onLine

(

string

line

)

Called whenever a line of data is sent to this TCPObject.

This callback is called when the received data contains a newline \n character, or the connection has been disconnected and the TCPObject's buffer is flushed.

Parameters:

line

Data sent from the server.

void TCPObject::send

(

string

data

)

Transmits the data string to the connected computer.

This method is used to send text data to the connected computer regardless if we initiated the connection using connect(), or listening to a port using listen().

Parameters:

data

The data string to send.

Example:

// Set the command data
%data = "GET " @ $RSSFeed::serverURL @ " HTTP/1.0\r\n";
%data = %data @ "Host: " @ $RSSFeed::serverName @ "\r\n";
%data = %data @ "User-Agent: " @ $RSSFeed::userAgent @ "\r\n\r\n"

// Send the command to the connected server.
%thisTCPObj.send(%data);