NetConnection Class Reference

sends data between two network endpoints More...

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

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

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

socket

a 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

kill	true 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

kill	true 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

callback

the 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

callback

the 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

message

the 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

message

the 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

message

the 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

message

the 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

message

the 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

message

the 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

message

the 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

message

the 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