Channels

From PX Documentation

Contents 1 Overview 2 Creating New Channels 3 Managing Channels 3.1 Channel Roles 3.2 Channel Flags 3.3 Default Channels 3.4 Channel Description 3.5 Channel Sessions 3.6 Other Channels Functions 4 Channel Connections

Overview

While the majority of games will not require it, Netdog provides a multichannel option for managing game objects and events. Different channels can be customized to point to different ports, for easier processing and managing of different and distinct data/event types.

Creating New Channels

Channels are created in the program declarations by assigning the channel role, port and any associated flags to the specific channel, then providing a string channel description.

  int NDCreateChannel(NDRole::Type role, 
                      int port = 0, 
                      int flags = NDChannelFlags::defaults, 
                      char *desc = NULL);

Managing Channels

Channel Roles

The following two functions retrieve and set the channel role.

  void NDChannelSetRole(NDRole::Type role, 
                        int channelID = -1);

  NDRole::Type NDChannelGetRole(int channelID = -1);

Channel Role indicates what role the channel connection is playing in the topology. Potential choices are:

• -1 for error
• 0 for unknown
• server
• client

Channel Flags

Flags identify the current operating conditions for specified channels. The following three functions set, unset and get the current flag status for channels by channelID

  void NDChannelSetFlags(int flags, 
                         int channelID = -1);

  int NDChannelGetFlags(int channelID = -1);

  void NDChannelClearFlags(int flags,
                           int channelID = -1);

Channels take similar flags to connections, including the following:

• useSnapshots to create event queue snapshots to correct for missing state updates
• allowUnexpectedConnections allows unexpected connections (vs. for every connection a server initiates, only pre-specified IP addresses are allowed)
• assignOwnerIDs to set specific owner IDs (vs. pre-assigned IDs)
• immediate to have events executed immediately upon receipt (vs. executed according to a pre-set schedule)
• 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)
• useClockSync to clock-synch across clients initially and ensures they remain synched for the duration of the session

Default Channels

Netdog uses -1 as the default channel for the two functions below, which get and set the default channels for specific actions and activities, respectively.

  int NDGetDefaultChannel(void);

  int NDSetDefaultChannel(int channelID);

Channel Description

The following two functions get and set the character description of specified channels (accessed by channelID), respectively.

  const char *NDChannelGetDescription(int channelID = -1);

  void NDChannelSetDescription(char *desc, 
                               int channelID = -1);

Channel Sessions

Sessions are used to start episodic event sequences, such as starting a new game. This functionality is relevant in smaller games (e.g., tournament play) where you want to wait until all players are connected before starting the game. Only used when connection flag startManually has been set.

  void NDStartSession(int channelID = -1);

  void NDEndSession(int channelID = -1);

Other Channels Functions

The following functions are used to retrieve channel information - the first retrieves channel information for all channels associated with a specific connection ID. The second retrieves all channels associated with a specified Owner ID.

  int NDGetChannelByConnID(int connID);

  int NDChannelGetOwnerID(int channelID = -1);

NDChannelSetOwnerID sets/changes the owner ID for the channel to that ID specified by id

  void NDChannelSetOwnerID(int id, 
                           int channelID = -1);

The following function retrieves the socket address for a specified channel, using channel ID

  int NDChannelGetAddr(sockaddr_in *a, 
                       int channelID = -1);

NDChannelExists checks whether the specified channel exists within the existing network topology, returning false if it does not.

  int NDChannelExists(int channelID = -1);

NDChannelToChannelMessage sends data from one channel to another. It takes user-defined data and passes it to other channels. The default channel is set as the default fromChannelID.

  int NDChannelToChannelMessage(void *usr, 
                                int usrLen, 
                                int toChannelID, 
                                int fromChannelID = -1);

Channel Connections

Channel connections are groupings of connections across multiple clients - the various tools beneath are used for both game maintenance and game play for managing the connections across existing channels.

The following function closes all existing connections within a particular channel.

  void NDCloseAllConns(int channelID = -1);

The following functions perform basic status reporting on the connections within a particular channel, retrieving the number and IDs of connections, clients and servers within the topology.

  int NDGetNumConns(int channelID = -1);

  int NDGetNumClients(int channelID = -1);

  int NDGetNumServers(int channelID = -1);

  int NDGetConnByOwnerID(int ownerIDRemote, 
                                int channelID = -1);

  int NDGetClientConnByOwnerID(int ownerIDRemote, 
                                      int channelID = -1);

  int NDGetServerConnByOwnerID(int ownerIDRemote, 
                                      int channelID = -1);