PDG engine v0.9.5
 All Classes Namespaces Functions Variables Groups Pages
Public Member Functions | Public Attributes | List of all members
NetConnection Class Reference

sends data between two network endpoints More...

Public Member Functions

 NetConnection (object socket)
 create a new net connection from a socket
 
 close (boolean kill)
 close a connection The remote endpoint of the connection will get an onClose() callback.
 
NetConnection onClose (function callback)
 set callback to handle connection closing
 
NetConnection onMessage (function callback)
 set callback to handle receipt of a network message
 
 send (string message)
 send a string to the remote endpoint
 
 send (MemBlock message)
 send a block of memory to the remote endpoint
 
 send (ISerializable message)
 send a serializable object to the remote endpoint
 
 send (object message)
 send a JavaScript object to the remote endpoint
 
 sendDgram (string message)
 send a string to the remote endpoint via UDP
 
 sendDgram (MemBlock message)
 send a block of memory to the remote endpoint via UDP
 
 sendDgram (ISerializable message)
 send a serializable object to the remote endpoint via UDP
 
 sendDgram (object message)
 send a JavaScript object to the remote endpoint via UDP
 

Public Attributes

boolean hasDgram
 true if the connection supports UDP/Datagram communications
 
string localAddr
 the ip address of the local end of the connection
 
number localPort
 the port that the local end of the connection is communicating over
 
string remoteAddr
 the ip address of the remote end of the connection
 
number remotePort
 the port that the remote end of the connection is communicating over
 

Detailed Description

sends data between two network endpoints

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.

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

NetConnection only represents an established connection created by NetClient or NetServer.

Warning
NetClient, NetServer, and NetConnection all work together over a custom protocol. Do not attempt to use NetConnection to communicate with other kinds of servers, such as HTTP or raw TCP sockets. All you'll do is get a bunch of error messages. There are perfectly fine Net and HTTP modules built-in to Node.js (and thus to PDG) for communicating with other kinds of servers.
See Also
NetClient
NetServer
Node.js Net module
Node.js HTTP module

Constructor & Destructor Documentation

NetConnection ( object  socket)

create a new net connection from a socket

Parameters
socketa Node.js net.Socket object
Note
you generally won't have to call this directly since NetClient and NetServer both create NetConnection objects for you.
See Also
NetClient
NetServer
Node.js net.Socket

Member Function Documentation

close ( boolean  kill)

close a connection The remote endpoint of the connection will get an onClose() callback.

close a connection

Parameters
killtrue if the connection should be abruptly dropped rather than cleanly disconnected. See AlsoNetConnection.onClose

The remote endpoint of the connection will get their onClose() callback.

Parameters
killtrue if the connection should be abruptly dropped rather than cleanly disconnected.
See Also
NetConnection.onClose
onClose ( function  callback)

set callback to handle connection closing

Whenever a network connection is dropped by the remote end (whether cleanly or abrubtly), you will get an onClose callback to the function specified.

Parameters
callbackthe function that should be called
Todo:
no parameters are passed to the onClose callback but we should probably indicate if it was an error and pass a reference to the connection object
onMessage ( function  callback)

set callback to handle receipt of a network message

Whenever the remote end sends a message, you will get an onMessage callback to the function specified with the message that was sent.

Parameters
callbackthe function that should be called when a message is received. The message is the first parameter passed to the callback function. Second parameter is the connection object. Third parameter is a string with the transport type (currently either 'upd' or 'tcp', where 'udp' means it was sent via sendDgram() and 'tcp' means it was sent via send() )
send ( string  message)

send a string to the remote endpoint

The string is sent guaranteed delivery (TCP), and will arrive in the order sent with other messages.

NetConnection handles packet framing for you, so the NetConnection on the remote endpoint will receive an onMessage callback with the string you sent. If the message cannot be sent, you will eventually get an onClose() callback to indicate that the connection has been lost.

Note
sending multiple strings in a row is fine, they will all be received as separate onMessage callbacks each with the string as sent. They will not be combined.
Parameters
messagethe string to send
Returns
itself (for call chaining)
send ( MemBlock  message)

send a block of memory to the remote endpoint

The block is sent guaranteed delivery (TCP), and will arrive in the order sent with other messages.

NetConnection handles packet framing for you, so the NetConnection on the remote endpoint will receive an onMessage callback with the string you sent. If the message cannot be sent, you will eventually get an onClose() callback to indicate that the connection has been lost.

Note
sending multiple MemBlock in a row is fine, they will all be received as separate onMessage callbacks each with the block as sent. They will not be combined.
Parameters
messagethe MemBlock to send
Returns
itself (for call chaining)
send ( ISerializable  message)

send a serializable object to the remote endpoint

The object is sent guaranteed delivery (TCP), and will arrive in the order sent with other messages.

NetConnection handles packet framing for you, so the NetConnection on the remote endpoint will receive an onMessage callback with the object you sent. If the message cannot be sent, you will eventually get an onClose() callback to indicate that the connection has been lost.

Parameters
messagethe serializable object to send
Returns
itself (for call chaining)
See Also
ISerializable
send ( object  message)

send a JavaScript object to the remote endpoint

The object is sent guaranteed delivery (TCP), and will arrive in the order sent with other messages.

NetConnection handles packet framing for you, so the NetConnection on the remote endpoint will receive an onMessage callback with the object you sent. If the message cannot be sent, you will eventually get an onClose() callback to indicate that the connection has been lost.

Note
the object is converted to JSON before being sent, then back again on the receiving side.
Parameters
messagethe object to send
Returns
itself (for call chaining)
Warning
Only use this for native JavaScript objects. No PDG objects can be sent over the network this way.
sendDgram ( string  message)

send a string to the remote endpoint via UDP

The string will be sent using UDP if it is available. Delivery is not guaranteed and neither is in-order deliver of messages. This is ideal for small bits of information that are frequently resent, such as position or status updates.

NetConnection handles packet framing for you, so if the packet arrives, the NetConnection on the remote endpoint will receive an onMessage callback with the string you sent. If the message cannot be sent you will not get any notification. It will simply disappear into the ether.

Note
sending multiple strings in a row is fine, they will all be received as separate onMessage callbacks each with the string as sent. They will not be combined.
Parameters
messagethe string to send
Returns
itself (for call chaining)
See Also
send(string)
Remarks
To guard against out-of-order delivery, you should always use a sequence number so you can drop older updates that arrive after newer ones.
Warning
Any string longer than MTU (generally 1500 bytes, but can be smaller) will always fail to send
sendDgram ( MemBlock  message)

send a block of memory to the remote endpoint via UDP

The block will be sent using UDP if it is available. Delivery is not guaranteed and neither is in-order deliver of messages. This is ideal for small bits of information that are frequently resent, such as position or status updates.

NetConnection handles packet framing for you, so if the packet arrives, the NetConnection on the remote endpoint will receive an onMessage callback with the object you sent. If the message cannot be sent you will not get any notification. It will simply disappear into the ether.

Note
sending multiple blocks in a row is fine, they will all be received as separate onMessage callbacks each with the string as sent. They will not be combined.
Parameters
messagethe MemBlock to send
Returns
itself (for call chaining)
See Also
send(MemBlock)
Remarks
To guard against out-of-order delivery, you should always use a sequence number so you can drop older updates that arrive after newer ones.
Warning
Any block longer than MTU (generally 1500 bytes, but can be smaller) will always fail to send.
sendDgram ( ISerializable  message)

send a serializable object to the remote endpoint via UDP

The object will be sent using UDP if it is available. Delivery is not guaranteed and neither is in-order deliver of messages. This is ideal for small bits of information that are frequently resent, such as position or status updates.

NetConnection handles packet framing for you, so if the packet arrives, the NetConnection on the remote endpoint will receive an onMessage callback with the object you sent. If the message cannot be sent you will not get any notification. It will simply disappear into the ether.

Parameters
messagethe serializable object to send
Returns
itself (for call chaining)
Remarks
To guard against out-of-order delivery, you should always use a sequence number so you can drop older updates that arrive after newer ones.
See Also
ISerializable
send(ISerializable)
sendDgram(object)
Warning
Any object with a serialized size greater than MTU (generally 1500 bytes, but can be smaller) will always fail to send
sendDgram ( object  message)

send a JavaScript object to the remote endpoint via UDP

The object will be sent using UDP if it is available. Delivery is not guaranteed and neither is in-order deliver of messages. This is ideal for small bits of information that are frequently resent, such as position or status updates.

NetConnection handles packet framing for you, so if the packet arrives, the NetConnection on the remote endpoint will receive an onMessage callback with the string you sent. If the message cannot be sent you will not get any notification. It will simply disappear into the ether.

Parameters
messagethe object to send
Returns
itself (for call chaining)
See Also
send(object)
sendDgram(ISerializable)
Remarks
To guard against out-of-order delivery, you should always use a sequence number so you can drop older updates that arrive after newer ones.
Warning
Any string longer than MTU (generally 1500 bytes, but can be smaller) will always fail to send
Only use this for native JavaScript objects. No PDG objects can be sent over the network this way.

Member Data Documentation

hasDgram

true if the connection supports UDP/Datagram communications

localAddr

the ip address of the local end of the connection

localPort

the port that the local end of the connection is communicating over

remoteAddr

the ip address of the remote end of the connection

remotePort

the port that the remote end of the connection is communicating over

User Comments