NetClient Class Reference

a network endpoint that can initiate a connection More...

Public Member Functions
	NetClient (object opts=null)
	constructor for NetClient, sets client options More...
NetClient	connect (object serverInfo, function callback, string clientKey="")
	establish a connection to a server More...
NetClient	onError (function callback)
	set the callback function that will handle errors More...

Public Attributes
boolean	connection
	reference to the NetConnection, or boolean false if not yet connected More...

Detailed Description

a network endpoint that can initiate a connection

Note

API Stability: 2 - Unstable. The API is in the process of settling, but has not yet had sufficient real-world testing to be considered stable. Backwards-compatibility will be maintained if reasonable.

NetClient is part of the PDG Engine's custom protocol for games. It handles protocol negotiation and optional connections. It establishes both a TCP connection (reliable transport with guaranteed delivery) and UDP communications (small and unreliable but fast) with the server.

NetClient doesn't actually handle network communication, it only establishes the connection. Once established, it creates NetConnection objects you can use to send and receive data.

Warning

NetClient, NetServer, and NetConnection all work together over a custom protocol. Do not attempt to use NetClient to connect to other kinds of servers, such as HTTP or raw TCP sockets. There are perfectly fine Net and HTTP modules built-in to Node.js (and thus to PDG) for that.

See Also

NetConnection

NetServer

Node.js Net module

Node.js HTTP module

Constructor & Destructor Documentation

NetClient

(

object

opts = null

)

constructor for NetClient, sets client options

Construct a new NetClient with particular options or using default values if no options are specified.

Available options are:

1. noDatagram - flag to indicate that we should not try to establish UDP communication with the server (defaults to false, allowing UDP)

Parameters

opts	a Javascript object with the options above

var myClient = new pdg.NetClient( {noDatagram = true} );

Member Function Documentation

connect	(	object	serverInfo,
		function	callback,
		string	clientKey = ""
	)

establish a connection to a server

Attempts to connect to the given server, and if it succeeds it invokes your callback with a new NetConnection object as the parameter. The If the connection fails, you'll get an error callback if you set one up using the onError() call.

An option key is passed in to do authentication if the server requires connection reservations. See NetServer.expectClient for more about client reservations.

Parameters

serverInfo	an object with host and port that tells us where to find the NetServer
callback	the connection established handler for this connection
clientKey	[optional] the reservation key to send to the server

// start trying to connect
var myConnection = false;
var myKey = '23dj3C340efp';
myClient.connect( { host: 208.122.0.12, port: 5000 }, function(connection) {
    myConnection = connection;
}, myKey);

// now wait for the connection to happen
var t = pdg.tm.onInterval( function() {
    if (myConnection) {
        console.log('Got connection to '+myConnection.remoteAddr);
        t.cancel();  // stop checking
    }
}, 100);  // check every 100 milleseconds

See Also

onError

NetConnection

NetServer.expectClient

onError

(

function

callback

)

set the callback function that will handle errors

This function will be called whenever a call to connect() fails. The function will be called with a single parameter, a string of the error message.

Parameters

callback

the error handling function for this connection

Returns

reference to itself for call chaining

myClient.onError( function(msg) {
    console.log("Connection failed: "+msg);
}

See Also

connect

Member Data Documentation

connection

reference to the NetConnection, or boolean false if not yet connected