PDG engine v0.9.5
 All Classes Namespaces Functions Variables Groups Pages
Public Member Functions | Public Attributes | List of all members
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
 
NetClient connect (object serverInfo, function callback, string clientKey="")
 establish a connection to a server
 
NetClient onError (function callback)
 set the callback function that will handle errors
 

Public Attributes

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

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
optsa 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
serverInfoan object with host and port that tells us where to find the NetServer
callbackthe 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
callbackthe 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

User Comments