DirectPlay Providers

This section describes the DirectPlay interface and the DirectPlay service providers and how they interact with each other. For more information, see:

The DirectPlay interface is a common interface to the application for simple send and receive type messaging, as well as higher-level services like player management, groups for multicast, data management and propagation, and lobby services for locating other players on a network.

The service providers furnish network-specific communications services as requested by DirectPlay. Online services and network operators can supply service providers to use specialized hardware, protocols, communications media, and network resources. A service provider can simply be a layer between DirectPlay and an existing transport like Winsock, or it can use specialized resources on an online service such as multicast servers, enhanced quality of service, or billing services. Microsoft includes four generic service providers with DirectPlay: head-to-head modem (TAPI), serial connection, Internet TCP/IP (using Winsock), and IPX (also using Winsock).

The DirectPlay interface hides the complexities and unique tasks required to establish an arbitrary communications link inside the DirectPlay provider implementation. An application using DirectPlay need only concern itself with the performance and capabilities of the virtual network presented by DirectPlay. It need not know whether a modem, network card, or online service is providing the medium.

DirectPlay will dynamically bind to any DirectPlay provider installed on the user's system. The application interacts with the DirectPlay object. The DirectPlay object interacts with one of the available DirectPlay service providers, and the selected service provider interacts with the transport, protocol, and other network resources.

The DirectPlay API is exposed to the application through several Component Object Model (COM) interfaces. (See DirectPlay Interfaces for a discussion of COM and DirectPlay.) Application sessions can talk to someone else on the network through the IDirectPlay4 and IDirectPlay4A interfaces. The first uses Unicode strings in all the DirectPlay structures, while the second uses ANSI strings. IDirectPlay, IDirectPlay2, IDirectPlay2A, IDirectPlay3, and IDirectPlay3A still exist for backward compatibility with applications written to a previous version of the DirectPlay Software Development Kit (SDK).

Lobby clients can talk to another application on the same computer through the IDirectPlayLobby3 and IDirectPlayLobby3A interfaces. The first interface uses Unicode strings while the second uses ANSI strings. The IDirectPlayLobby, IDirectPlayLobby2, and IDirectPlayLobby2A interfaces still exists for backward compatibility.

Service Providers

The service provider furnishes network-specific communication services as requested by DirectPlay. Online services and network operators can supply service providers for specialized hardware and communications media. Microsoft includes the following service providers with DirectPlay:

Individual service providers are identified using a globally unique identifier (GUID). GUIDs for the standard service providers are listed in the header file Dplay.h. Third-party service providers will have their own GUIDs.

This section outlines what to expect from the default service providers that Microsoft provides. To obtain information about the behavior of third-party service providers, contact the network operator.

You can ask the service provider to optimize for bandwidth or for latency. The DPSESSION_OPTIMIZELATENCY flag asks the service provider to optimize for latency (which turns off nagling in TCP/IP). The default is to optimize for bandwidth.

TCP/IP

The Transmission Control Protocol/Internet Protocol (TCP/IP) service provider uses Winsock to communicate over the Internet or local area network (LAN) using the TCP/IP protocol. It uses User Datagram Protocol (UDP) packets for nonguaranteed messaging and TCP for guaranteed messaging. A single computer can host multiple DirectPlay sessions using TCP/IP.

When the IDirectPlay4::EnumSessions method is used, TCP/IP displays a dialog box asking the user for the session's IP address. The user must enter the IP address of the computer hosting the session to be joined. If the computer has a name (such as microsoft.com), the name can be used instead of the IP address, and DirectPlay will use Domain Name System (DNS) lookup to find it. The IDirectPlay4::EnumSessions method will return the sessions that the computer is hosting. The user can also leave the address blank and select OK. In this case, DirectPlay will broadcast a message looking for sessions. This will generally only work on a LAN and only on the same subnet.

If you're hosting a session, the application can use IDirectPlay4::GetPlayerAddress to obtain the local IP address.

An application can use the IDirectPlay4::InitializeConnection method, or the IDirectPlayLobby3::SetConnectionSettings method followed by a call to IDirectPlayLobby3::Connect, to supply an IP address to the service provider in a DirectPlay Address. The IP address must be a null-terminated ANSI or Unicode string (each has a different data type GUID). If a broadcast enumeration of sessions is desired, the address must be a zero-length string; that is, a string only consisting of the null terminator.

Note: A Windows® 9x user can determine his or her IP address by choosing Run from the Start menu and typing WINIPCFG as the program to run. A Windows® NT® user can determine his or her IP address by running IPConfig from the command line. If the user is connected to both a LAN and a dial-up Internet service provider (ISP), the computer can have two IP addresses, and the correct one must be selected for that connection. Most dial-up ISPs assign a dynamic IP address that changes each time the user logs on.

The TCP/IP service provider uses port 47624 to send and receive enumeration requests. Communications are sent on the port range 2300-2400. To work through a firewall, all computers must be using DirectPlay 6.0 and the ports 47624, and the range 2300-2400 must be open for both inbound and outbound TCP and UDP traffic. Note: DirectPlay starts assigning ports at 2300 and works its way up, sequentially. It is possible to open a smaller range starting at 2300.

An application can select a specific port to use. To do so, it must initialize the TCP/IP service provider with a DirectPlay Address that includes the data chunk DPAID_INetPort. See DirectPlay Address and DirectPlay Address Data Types for more information. If an application selects a specific port to use, all communication is sent through that port, and it is only necessary to open that one port (for both inbound and outbound using TCP and UDP).

Adding DirectPlay lobby support can eliminate the need for users to enter an IP address if they start the game from a lobby server.

The TCP/IP service provider can be identified using the symbol definition DPSPGUID_TCPIP.

Note: A Windows 9x user can configure his or her computer connections to display or not display a dialog box requesting connection information when DirectPlay tries to initiate a TCP/IP connection. To suppress the display of this dialog box, follow these steps:

  1. Open Control Panel.
  2. Double-click the Internet icon.
  3. Choose the Connection tab.
  4. Clear the check box next to Connect to the Internet as needed.

IPX

The IPX service provider uses Winsock to communicate over a local area network (LAN) using the Internet Packet Exchange (IPX) protocol. The service provider only supports nonguaranteed messaging. You can use the DirectPlay Protocol for guaranteed messaging on IPX. A single computer can host only one DirectPlay session using IPX.

IPX always uses a broadcast to find sessions on the network, so the IDirectPlay4::EnumSessions method will not display a dialog box requesting IP addresses.

IPX will not enumerate sessions on another subnet.

Once a session is established, packets are sent directly between computers (they are not broadcast).

This service provider can be identified using the symbol definition DPSPGUID_IPX.

Modem-to-Modem

A modem-to-modem service provider uses Telephony API (TAPI) to communicate with another modem. The service provider only supports nonguaranteed messaging. You can use the DirectPlay Protocol for guaranteed messaging for modem sessions.

Creating a session (by using the IDirectPlay4::Open method) causes a dialog box to appear, asking the user which modem to wait for a call on. The IDirectPlay4::EnumSessions method will also display a dialog box asking the user what phone number to call and which modem to use. After the information is entered, DirectPlay will dial the modem and try to find sessions hosted by the computer on the other end. In both cases, dialog boxes are displayed to show the progress.

To enumerate the modem sessions, use EnumSessions in a loop with the DPENUMSESSIONS_RETURNSTATUS flag set on the modem service provider, and wait for DP_OK to be returned. The application should then use EnumSessions one more time to obtain the sessions.

To enumerate the modem sessions without any dialog boxes, use IDirectPlay4::EnumSessions in a loop with the DPENUMSESSIONS_RETURNSTATUS flag (see EnumSessions for more details). When DP_OK is returned, the application should then use EnumSessions one more time to obtain the actual list of sessions.

When using EnumSessions in a loop like this, the application must implement a windows message loop as follows: 


while (lpDPLAY->EnumSessions(lpsd, 0, lpEnumSessionsCallback, lpContext, DPENUMSESSIONS_RETURNSTATUS) == DPERR_CONNECTING)
{
	MSG	msg;

	if (PeekMessage(&msg, 0, 0, 0, PM_REMOVE))
	{
		TranslateMessage(&msg);
		DispatchMessage(&msg);
	}

	Sleep(500);
}

The current list of available modems can be obtained from the service provider by initializing it and calling the IDirectPlay4::GetPlayerAddress method with a player ID of zero. The DirectPlay Address returned will contain a data chunk with the ANSI modem names (DPAID_Modem) and the Unicode modem names (DPAID_ModemW). The list of modems is a series of NULL-terminated strings with a zero-length string at the end of the list.

If you insert too many delays into the message processing, you can lose packets; for example, if you print a lot of debug information.

The modem-to-modem service provider can be identified by using the symbol definition DPSPGUID_MODEM.

Serial Link

A serial link is used to communicate with another computer through the serial ports. The service provider only supports nonguaranteed messaging. You can use the DirectPlay Protocol for guaranteed messaging on serial links.

Creating a session (using the IDirectPlay4::Open method) causes a dialog box to appear asking the user to configure the serial port. The IDirectPlay4::EnumSessions method will also display a dialog box asking the user to configure the serial port. You must configure the serial port the same way on both computers.

If you insert too many delays into the message processing, you may lose packets; for example, if you print a lot of debug information.

This service provider can be identified using the symbol definition DPSPGUID_SERIAL.

Lobby Providers

The lobby provider is a client component dynamic-link library (DLL) supplied by the developer of a lobby server. It implements communications functions with the lobby server as requested by DirectPlay. A lobby client written using the DirectPlay API can interoperate with any lobby server for which a lobby provider DLL is present on the system.

The DirectX® SDK installs a lobby provider for use with the test lobby server (LSERVER.EXE) included with the SDK. This lobby provider is used by the BELLHOP sample lobby client, and together they can be used to test the lobby-aware functions of your applications.

Firewall Support in DirectPlay 6.0

Applications do not need to be rewritten to take advantage of DirectPlay's new firewall support. The default behavior is to use a dynamically allocated port from DirectPlay's range. This provides backward compatibility with existing applications, as well as the ability to use multiple DirectPlay applications on a single computer.

Additionally, applications can be written to take advantage of DirectPlay's new fixed-port feature. You can choose a port number specifically for the application, and a firewall administrator need only open that particular port. See the section on selecting a specific port in the TCP/IP topic.

Compatibility

DirectX 6.0 users can still communicate with DirectX 5.0 users as long as no firewall is involved. This means that if even one computer is behind a firewall, peer-to-peer games with DirectX 5.0 computers will not work. Client/server games are allowed, as long as the host is DirectX 6.0, and in each case where the line of communication between the host and a client will pass through a firewall, that client is DirectX 6.0, as well.

Proxy Setup

Because of proxy architecture, you are limited to using a single computer. However, multiple applications (each using the dynamic DirectPlay range or unique application-defined ports) on the computer are still allowed.

For more information about using DirectPlay's firewall support, please see the following topics.

Setup for Client Firewall Support Using the DirectPlay Dynamic Range

To join a game through a firewall, the client must be using DirectX 6.0 and communicating with a DirectX 6.0 host. To support applications using the DirectPlay dynamic range, a firewall administrator needs to allow an initial outbound TCP connection on port 47624, with subsequent connections of inbound TCP ports 2300-2400, outbound TCP ports 2300-2400, inbound UDP ports 2300-2400, and outbound UDP ports 2300-2400. For a chart highlighting these requirements, see the Dynamic Range Port Reference Chart.

Note: It is sufficient to open only a subset of these ports starting at 2300, for example, 2300-2310. The first DirectPlay application on a particular computer will use port 2300, the next will use 2301, and so on.

Example of a Microsoft Proxy Server 2.0 Configuration:

Setup for Host Firewall Support Using the DirectPlay Dynamic Range

To host a game through a firewall, the host must be using DirectX 6.0, and the clients beyond the firewall must be using DirectX 6.0, as well. To support applications using the DirectPlay dynamic range, a firewall administrator needs to allow an initial inbound TCP connection on port 47624, with subsequent connections of inbound TCP ports 2300-2400, outbound TCP ports 2300-2400, inbound UDP ports 2300-2400, and outbound UDP ports 2300-2400. For a chart highlighting these requirements, see the Dynamic Range Port Reference Chart.

Note: It is sufficient to open only a subset of these ports starting at 2300. For example 2300-2310. The first DirectPlay application on a particular computer will use port 2300, the next will use 2301, and so on.

Theoretical Microsoft Proxy Server 2.0 configuration:

Unfortunately, some firewall solutions, including Microsoft Proxy Server 2.0, won't recognize additional inbound connections as subsequent connections. The workaround for this is that each port in the range (2300, 2301, 2302, and so on) must get its own protocol definition, as if it were an application-specified fixed port. For more information, see Setup for Host Firewall Support Using an Application-Specified Fixed Port. Practically, only as many ports as active DirectPlay applications need to be opened, that is, to run both the applications "SuperDuperGame" and "WackyFunGame" at the same time, only ports 2300 and 2301 will be used.

Using an Application-Specified Fixed Port

An application can choose to use a fixed port rather than the DirectPlay default ports. If this is done, only the one port needs to be opened to allow that application (and only that application) to operate through a firewall.

To specify a fixed port, the application must create a DirectPlay Address that contains the data chunk for DPAID_InetPort (defined in dplobby.h). The application can append the chunk to the lpAddress returned by EnumConnections before passing it to InitializeConnection. Alternatively, the application can create the DirectPlay Address completely (specifying the service provider, IP address and port number) and pass that to InitializeConnection.

Setup for Client Firewall Support Using an Application-Specified Fixed Port

To join a game through a firewall, the client must be using DirectX 6.0 and communicating with a DirectX 6.0 host. To support applications using an application-specified fixed port n, a firewall administrator needs to allow an initial outbound TCP connection on port n, with subsequent connections of inbound TCP port n, inbound UDP port n, and outbound UDP port n.

Example of a Microsoft Proxy Server 2.0 configuration, where the application "SuperDuperGame" (superdg.exe) specifies the port as 12345:

Setup for Host Firewall Support Using an Application-Specified Fixed Port

To host a game through a firewall, the host must be using DirectX 6.0, and the clients beyond the firewall must be DirectX 6.0, as well. To support applications using an application-specified fixed port n, a firewall administrator needs to allow an initial inbound TCP connection on port n, with subsequent connections of outbound TCP port n, inbound UDP port n, and outbound UDP port n.

Example of a Microsoft Proxy Server 2.0 configuration, where the application "SuperDuperGame" (superdg.exe) specifies the port as 12345.

Dynamic Range Port Reference Chart

The following chart shows which ports an administrator needs to open for a given desired style of play for applications using DirectPlay's dynamic range.

ConnectionClient configuration Host configuration
Initial TCP Connection 47624 Outbound 47624 Inbound
Subsequent Inbound TCP Connections 2300-2400 2300-2400
Subsequent Outbound TCP Connections 2300-2400 2300-2400
Subsequent Inbound UDP Connections 2300-2400 2300-2400
Subsequent Outbound UDP Connections 2300-2400 2300-2400

DirectX 5.0-DirectX 6.0 Cross-Compatibility Reference Chart

The following chart shows which versions work with each other, assuming there are only two computers, and the firewall referred to is physically the same firewall for both (that is, both the client and host are behind the same firewall):

Internet DirectX 5.0 Host DirectX 5.0 Host Behind Firewall Internet DirectX 6.0 Host DirectX 6.0 Host Behind Firewall
Internet DirectX 5.0 Client yes no yes no
DirectX 5.0 Client behind firewall no yes no yes
Internet DirectX 6.0 Client yes no yes yes
DirectX 6.0 Client behind firewall no yes yes yes

The chart still holds true for more than two computers if the session is client/server. If there are more than two computers, the session is peer-to-peer, and there is a firewall involved anywhere, then all computers must be using DirectX 6.0.

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