Network Connections
From PX Documentation
Contents |
Overview
Connections in NetDog manage all low-level network functionality - establishing all socket connections, routing, messaging, encryption and other low-level functions.
Connections are set with a connection role (server or client), local owner ID ("near end" of the connection) and remote address ID ("far end" of the connection). The connection role dictates what role the particular connection plays in the topology - whether it is a server a client or a localized server. Most important are the connection flags which set the configuration for the connection - including encryption, reliable UDP, etc.
Connection Basics
Connection State is the current status of the existing connection. A connection exists in one of the following states:
- connHandshaking - the connection was created but it is not yet ready for use
- connOpened - the connection is ready for use, but the session has not yet started
- connStarted - the connection is ready for use and the session has started
- connFinished - the connection is ready for use and the session has ended
- connClosed - the connection is closed and can no longer be used
Several functions exist allowing the user to determine the state of a connection. For example, the following function returns true if the connection is in the started state:
int NDConnIsStarted(int connID);
Connection Role indicates what role the connection is playing in the topology. Potential choices are:
- -1 for error
- 0 for unknown
- server
- client
- peer
NDRole::Type NDConnGetRole(int connID);
Connection Flags are used to set connection properties. These flags take the following defaults:
defaults = assignOwnerIDs | useKeepAlives
The following can be used depending on specific game needs:
- useEncryption to encrypt all traffic on the connection in question
- assignOwnerIDs to have server assign owner IDs to its clients (vs. pre-assigned IDs)
- reliable sets reliable UDP (i.e., data is resent over the network if receipt is not acknowledged)
- startImmediately to start game immediately (mutually exclusive with startAfterAllClientsReady and startManually)
- startAfterAllClientsReady to start game only when all clients are available (mutually exclusive with startImmediately and startManually)
- startManually to start game manually (mutually exclusive with startImmediately and startAfterAllClientsReady)
- useKeepAlives to keep infrequently-used connections alive, used primarily for situations where Netdog has punched-through a firewall and needs to keep connection available so as not to re-punch through
- culling to enable culling of network traffic, resulting in greatly improved performance in most scenarios (requires client call to NDSetCullingData())
- spontaneousUpdate to automatically send periodic updates for objects (server only)
- forceSocketReuse to allow the same socket to be bound twice in rapid succession (generally best left disabled)
- blockingConnect to cause NDCreateClientConn() to block until the conn enters the "started" state
- useTracker to transparently connect to a tracker when calling NDCreateServerConn
int NDConnGetFlags(int connID);
This function return value contains the status of all flags, which can be tested for as shown below:
int flags = NDConnGetFlags(EXAMPLE_CONNID);
if(flags & NDConnFlags::reliable)
//reliable UDP is set
The following function closes the connection with the specified connID:
void NDConnClose(int connID);
Connection IDs
Connection IDs provide references to network connections, (e.g., client-client, client-server, or server-server). Remote Owner ID is the ID of the computer the local computer is connecting to, whilst Local Owner ID is the ID for the local computer. These can be assigned dynamically.
The Connection Remote Owner ID is the ID(s) for the computer(s) to be connected to - whether client or server
int NDConnGetRemoteOwnerID(int connID);
The Local Owner ID identifies the local computer on the network. The following two functions get and subsequently set the local owner ID for the specified connection.
int NDConnGetLocalOwnerID(int connID);
void NDConnSetLocalOwnerID(int connID,
int ownerID);
The Connection Remote Address identifies the IP address the local computer is connected to.
const sockaddr_in* NDConnGetRemoteAddr(int connID);
Client and Server Connection Management
The client and server connections establish all low-level connections.
When creating a client connection, serverIP and serverPort are the IP address and Port for the server the particular client will connect to - this can be dynamically assigned in game. Flags are explained above. UserName and password are only used as authentication credentials when connecting to a tracker (Pro version only). ChannelID specifies the channel on which to create this conn, the default channel will be used by default (if haven't created multiple channels, you needn't worry about specifying this parameter).
int NDCreateClientConn(char* serverIP,
int serverPort,
int flags = NDConnFlags::defaults,
char* userName = NULL,
char* passwd = NULL,
int channelID = NDChannelID::defaultChannel);
For the Server connection - listenPort is the server's connection port to listen for clients. Flags are explained above. The authCB parameter allows for installation of an authorization callback which determines whether a connecting client has access to this server. The tracker IP/port and userName/password all specify how this server will connect to a tracker, if one is being used. The channelID specifies which channel to install this connection on (only relevant when multiple channels are being used).
int NDCreateServerConn(int listenPort = 0,
int flags = NDConnFlags::defaults,
NDAuthorizationCallback authCB = NULL,
char* trackerIP = NULL,
int trackerPort = -1,
char* userName = NULL,
char* passwd = NULL,
int channelID = NDChannelID::defaultChannel);
For a hands-on tutorial on how to set up connections go to Client Connection Tutorial
