DirectPlay Overview

This section contains general information about the DirectPlay® component. The following topics are discussed:

• Architecture
• Session Management
• Player Management
• Message Management
• Group Management
• Overview of DirectPlay Communications

Architecture

The DirectPlay API is a network abstraction and distributed object system that applications can be written to. The API defines the functionality of the abstract DirectPlay network, and all the functionality is available to your application regardless of whether the actual underlying network supports it. In cases where the underlying network does not support a method, DirectPlay contains all the code necessary to emulate it. Examples include group messaging and guaranteed messaging.

DirectPlay's service-provider architecture insulates the application from the underlying network it is running on. The application can query DirectPlay for specific capabilities of the underlying network, such as latency and bandwidth, and adjust its communications accordingly.

The following diagram illustrates the DirectPlay service-provider architecture.

The first step in using DirectPlay is to select which service provider to use. The service provider determines what type of network or protocol will be used for communications. The protocol can range from TCP/IP over the Internet, to an IPX local area network, to a serial cable connection between two computers.

Use the service provider to make a connection to a point on the network. The user may need to provide additional information to make a connection, or the application can specify the connection parameters.

Connection Management Methods

DirectPlay provides two useful connection management methods:

• IDirectPlay4::EnumConnections enumerates all the connections that are available to the application.
• IDirectPlay4::InitializeConnection initializes a specific connection.

Session Management

A DirectPlay session is a communications channel between several computers. Before an application can start communicating with other computers, it must be part of a session. An application can do this in one of two ways: It can enumerate all the existing sessions on a network and join one of them, or it can create a new session and wait for other computers to join it. Once the application is part of a session, it can create a player and exchange messages with all the other players in the session.

Each session has one computer that is designated as the host. The host is the owner of the session and is the only computer that can change the session's properties.

The following diagram illustrates the DirectPlay session model:

Session Management Methods

DirectPlay provides several session management methods:

• IDirectPlay4::EnumSessions enumerates all the available sessions.
• IDirectPlay4::Open joins one of the enumerated sessions or creates a new session.
• IDirectPlay4::SecureOpen performs the same function as IDirectPlay4::Open, but enables the application to alter the default opening behavior.
• IDirectPlay4::Close leaves the currently open session.
• IDirectPlay4::GetSessionDesc gets the properties of the current session.
• IDirectPlay4::SetSessionDesc changes the properties of the current session.
• IDirectPlay4::GetCaps gets the communications capabilities of the underlying network.

Player Management

The most basic entity within a DirectPlay session is a player. A player represents a logical object within the session that can send and receive messages. DirectPlay does not have any representation of a physical computer in the session. Each player is identified as being either a local player (one that exists on your computer) or a remote player (one that exists on another computer). Each computer must have at least one local player before it can start sending and receiving messages. Individual computers can have more than one local player.

When an application sends a message, it is always directed to another player - not another computer. The destination player can be another local player (in which case the message will not go out over the network) or a remote player. Similarly, when an application receives messages, they are always addressed to a specific (local) player and marked as being from some other player (except system messages, which are always marked as being from DPID_SYSMSG).

DirectPlay provides some additional player management methods that an application can use. These methods can save the application from having to implement a list of players and data associated with each one. You do not need these methods to use DirectPlay successfully. They enable an application to associate a name with a player and automatically propagate that name to all the computers in the session. Similarly, the application can associate some arbitrary data with a player that will be propagated to all the other computers in the session. The application can also associate private local data with a player that is available only to the local computer.

Basic Player Management Methods

DirectPlay provides several basic player management methods:

• IDirectPlay4::EnumPlayers enumerates all the players in the sessions.
• IDirectPlay4::CreatePlayer creates a local player.
• IDirectPlay4::DestroyPlayer destroys a local player.

Additional Player Management Methods

DirectPlay provides these additional methods to manage player information:

• IDirectPlay4::GetPlayerCaps gets a player's communications capabilities.
• IDirectPlay4::GetPlayerName gets a player's name.
• IDirectPlay4::SetPlayerName changes a player's name.
• IDirectPlay4::GetPlayerData gets the application-specific data associated with a player.
• IDirectPlay4::SetPlayerData changes the application-specific data associated with a player.
• IDirectPlay4::GetPlayerAddress gets a player's network-specific address.
• IDirectPlay4::GetPlayerAccount gets a player's account information.
• IDirectPlay4::GetPlayerFlags gets a player's flag settings.

Message Management

Once an application has created a player within a session, it can start exchanging messages with other players in the session. DirectPlay imposes no message format or extra bytes on the message. A message can be sent to an individual player, to all the players in the sessions, or to a subset of players that have been defined as a group (see Group Management). When sending a message, it must also be marked as being from a specific local player.

All the messages received by an application are put into a receive queue. The application must retrieve individual messages from the queue and act on them as appropriate. The application can either poll the receive queue for messages or use a separate thread that waits on a synchronization event for notification that a new message has arrived.

There are two types of messages. Player messages are messages that another player in the session sent. This type of message is directed to a specific player and is marked as being from the sending player. System messages are sent to all the players in a session, and are all marked as being from the system (DPID_SYSMSG). DirectPlay generates system messages to notify the application of some change in state of the session; for example, when a new player has been created. See Using system messages for more information.

Basic Message Management Methods

DirectPlay provides several message management methods:

• IDirectPlay4::SendEx sends a message from a local player to another player in the session. This is an enhanced version of Send that supports guaranteed and nonguaranteed messages, asychronous messages, and setting the timeout and priority of a message.
• IDirectPlay4::Send sends a message from a local player to another player in the session.
• IDirectPlay4::SendChatMessage enables players to chat with other players using standardized messages.
• IDirectPlay4::Receive retrieves a message from the incoming message queue.
• IDirectPlay4::CancelMessage cancels a specific message (or all messages) that is still in the send queue.
• IDirectPlay4::CancelPriority cancels all messages of a particular priority or range of priorities that are still in the send queue.
• IDirectPlay4::GetMessageCount gets the number of messages currently in the incoming message queue.
• IDirectPlay4::GetMessageQueue determines how many messages are in the send or receive queue.

Group Management

DirectPlay supports groups within a session. A group is a logical collection of players. By creating a group of players, an application can send a single message to the group, and all the players in the group will receive the message. A group is the means by which a network's multicast capabilities are exposed to the application.

Groups can also be used as a general means to organize players in a session. A player can belong to more than one group. DirectPlay provides methods for administering groups and their membership. Additional methods associate names and data with individual groups as a convenience, but you don't need them to use groups.

The following diagram shows a logical representation of the contents of a DirectPlay session:

Basic Group Management Methods

DirectPlay provides several group management methods:

• IDirectPlay4::EnumGroups enumerates all the groups in the session.
• IDirectPlay4::CreateGroup creates a new group.
• IDirectPlay4::DestroyGroup destroys a group.
• IDirectPlay4::EnumGroupPlayers enumerates the players that are in a group.
• IDirectPlay4::AddPlayerToGroup adds a player to a group.
• IDirectPlay4::DeletePlayerFromGroup removes a player from a group.

Additional Group Management Methods

DirectPlay provides these additional methods to manage groups and group information:

• IDirectPlay4::GetGroupName gets the group's name.
• IDirectPlay4::SetGroupName changes the name of a group created by this computer.
• IDirectPlay4::GetGroupData gets the application-specific data associated with a group.
• IDirectPlay4::SetGroupData changes the application-specific data associated with a group created by this computer.
• IDirectPlay4::GetGroupFlags gets the flags describing a group.
• IDirectPlay4::GetGroupParent gets the DPID of the parent of the group.
• IDirectPlay4::CreateGroupInGroup creates a group within an existing group.
• IDirectPlay4::EnumGroupsInGroup enumerates all the groups within another group.
• IDirectPlay4::AddGroupToGroup adds a shortcut from a group to an already existing group.
• IDirectPlay4::DeleteGroupFromGroup removes a group previously added to another group with AddGroupToGroup, but doesn't destroy the deleted group.
• IDirectPlay4::GetGroupConnectionSettings retrieves a group's connection settings.
• IDirectPlay4::SetGroupConnectionSettings sets a group's connection settings.
• IDirectPlay4::SetGroupOwner changes the owner of a group.
• IDirectPlay4::GetGroupOwner gets the owner of a group.

Overview of DirectPlay Communications

DirectPlay's default mode of communications is peer-to-peer. In this model, the session's complete state is replicated on all the computers in the session. This means that the session description data, the list of players and groups, and the names and remote data associated with each session are duplicated on every computer. When one computer changes something, it is immediately propagated to all the other computers.

DirectPlay's alternative mode of communications is client/server. In this model, only the server stores the session's complete state, and each client has only a subset of the session's state. Each client has only the information that is relevant to that computer and receives that information from the server. When one computer changes something, it propagates the change to the server. The server then determines which clients it must inform of the change.

An application can manage its own data using either a client/server model or peer-to-peer model, but this will not change how the underlying DirectPlay session state is managed.

The following sections discuss the two modes of communications within DirectPlay sessions:

• Peer-to-Peer Session
• Client/Server Session

Peer-to-Peer Session

In a peer-to-peer DirectPlay session, one computer is designated the name server. This computer responds to enumeration requests, regulates computers trying to join the session, downloads the session's state to new computers that have joined, and generates ID numbers as players and groups are created. Beyond that, the name server is just another peer in the session and runs the same application as all the other peers. Messages are not routed through the name server, and the name server does not generate all the system messages.

DirectPlay automatically performs the name server functions, which are not exposed to the application in any way. The DirectPlay application running on the name server is also the session's host. Only the host application can change the session description data. Each peer application in the session has access to the complete list of players and groups in the session (see Session Management) and can send and receive messages from any other player in the session or send a message to any group in the session. See Session Management for more details.

The session's network address corresponds to the name server's network address. When a computer needs to join the session, it sends the join request to the name server. In response, the name server downloads the session's state to the new computer. If the name server leaves the session, a new computer is elected name server. When the name server migrates, the session's network address also changes.

The following diagram illustrates joining a session. To join a session, a machine sends the join request to the name server of the session.

Peer-to-peer sessions generally have a limitation on the number of computers that can participate. Every change in state on every computer (such as player movements) must be broadcast to all the other computers in the session. Because of the limit on the amount of data a computer can receive (especially if connected through a phone line), there is a limit on how many computers can generate data. Minimizing the quantity and frequency of data exchanged can help increase the number of computers that can be in a session before performance degrades.

Computers in a peer-to-peer DirectPlay session communicate directly with each other. That is, messages are not sent through an intermediate computer to reach their destination (although they can go through a router). When DirectPlay needs to send the same message to a set of computers, it attempts to use any multicast capabilities in the service provider. If multicast is not supported, then individual unicast messages are sent to each destination computer.

The following diagram illustrates group messaging without multicast. To broadcast a message, individual messages are sent to each machine.

This can be a source of inefficiency in sessions with a large number of players (more than four). Adding a multicast server to the session can alleviate this. A multicast server is a computer that will forward a single message to multiple destinations. A computer needing to broadcast a message to all the other computers in the session can send one message to the multicast server, which in turn sends individual messages to all the other computers. This is more efficient because the multicast server is connected to the network through a high-speed link and can therefore pump out unicast messages faster than any individual computer. The assumption is that the server has a high-speed link to the network (such as a T1 line), while the other computers have slow-speed links (such as phone lines).

The following diagram illustrates group messaging using a multicast server. Player-to-player messages are sent directly to the destination machine. Group messages are sent to the multicast server, which forwards them to all the destination machines.

DirectPlay supports the creation of a multicast server in a session. If the name server is on a sufficiently high-speed link, it can choose to be a multicast server for the session as well. Adding a multicast server to a session only changes how group messages (including broadcast) are routed - the application's behavior does not change. Unicast player-to-player messages are still sent directly to the destination computers.

Client/Server Session

In a DirectPlay client/server session, one computer is designated the server. Like the peer-to-peer name server, this computer responds to enumeration requests, regulates computers trying to join the session, downloads the session's state to new computers that have joined, and generates ID numbers as players and groups are created. Unlike the peer-to-peer name server, all messages in the session are routed through the server.

The server computer runs a special version of the application (the application server) that can maintain the master state of the game, updating that state according to actions that the client computers take, and notifying individual clients of relevant events. The application server creates a special player called the server player. Any client computer can send a message directly to the server player or receive a message from the server player. When the server player receives a message, it can send messages to other client players to inform them of a change in state.

The following diagram illustrates client\server communications. Each machine communicates directly with the server only. The server can forward messages to other clients.

The client computers run client versions of the application that can maintain the local state, updating the state in response to messages from the server, and sending messages to the server when local action occurs.

You can implement a client/server application in two ways. One mode is a hybrid peer-to-peer and client/server session, where every client application has the complete player and group list available to it (including the server player). Any client player can send a message directly to any player in the session, and each player or group can have data associated with it (such as name or remote data) that will be updated on all the computers whenever it changes. All the benefits of peer-to-peer state propagation are available, and, in addition, a server player is available. However, you cannot control the propagation of the player-to-player data. Depending on the frequency with which players and groups are created and destroyed or their data changes, client computers could be overloaded with in-coming messages. This type of a session is not scalable beyond about 16 players. It is not very different from a peer-to-peer session, except: it has a server player; all messages are routed through the server; and the server player will receive a copy of all the messages that pass through the server.

The second mode is pure client/server. Each client application sees only the server player and its own local players in the session. A client player can send messages only to the server player and receive messages from only the server player. The application server can see all the players on all clients. When the server receives a message from a client, it can intelligently decide how to update the master application state and inform the clients that need to be notified of this update. In this mode, the client application must manage the player list and the data associated with each player.

The following diagram shows a logical representation of the contents of a DirectPlay client/server session.

Like a peer-to-peer session, the session's network address corresponds to the server's network address. When a computer needs to join the session, it sends the join request to the server. In response, the server downloads the session's state to the new computers. If the server leaves the session, the session is terminated.

Because all messages are routed through the server, it automatically behaves as a multicast server.

Security

Using DirectPlay security features, an application running on a server can create secure sessions. DirectPlay implements security through the Security Support Provider Interface (SSPI) on Windows. Key features supported by DirectPlay in a secure session are:

• Authentication to verify the identity of the user. Once a user has been authenticated, communications between the client and server can be done securely either by digitally signing or encrypting the messages.
• Digitally signed system messages to verify the identity of the sender.
• Encryption of sensitive system messages.

For more information, including how to set up a secure server, start a secure session, and specify security packages, see Security and Authentication.

---

 Top of Page
© 1998 Microsoft Corporation. All rights reserved. Terms of Use.