DirectPlay Providers

This section describes the DirectPlay interface and the DirectPlay service providers and how they interact with each other. See:

• Service Providers
• Lobby Providers

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 IDirectPlay3 and IDirectPlay3A interfaces. The first uses Unicode strings in all the DirectPlay structures, while the second uses ANSI strings. IDirectPlay, IDirectPlay2, and IDirectPlay2A 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 machine through the IDirectPlayLobby2 and IDirectPlayLobby2A interfaces. The first interface uses Unicode strings while the second uses ANSI strings. The IDirectPlayLobby interface 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:

• TCP/IP
• IPX
• Modem-to-Modem
• Serial Link

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.

TCP/IP

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

When the IDirectPlay3::EnumSessions method is called, 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 IDirectPlay3::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.

Note: A Windows® 95 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. Most dial-up ISPs assign a dynamic IP address that changes each time the user logs on.

An application can call IDirectPlay3::InitializeConnection, or can call IDirectPlayLobby2::SetConnectionSettings followed by a call to Connect, to supply an IP address to the service provider in a DirectPlay Address. The 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.

The DirectPlay TCP/IP service provider does not generally work through firewalls.

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

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

Note: A Windows 95 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 checkbox 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. A single computer can host only one DirectPlay session using IPX.

IPX always uses a broadcast to find sessions on the network, so the IDirectPlay3::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

Modem-to-modem communication uses Telephony Application Programming Interface (TAPI) to communicate with another modem.

Creating a session (by using the IDirectPlay3::Open method) causes a dialog box to appear, asking the user which modem to wait for a call on. The IDirectPlay3::EnumSessions method will also display a dialog box asking the user what phone number to call and which modem to use. Once 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, dialogs are displayed to show the progress.

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

When calling 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 IDirectPlay3::GetPlayerAddress 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 may lose packets; for example, if you print a lot of debug information.

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

Serial Link

A serial link is used to communicate with another computer through the serial ports.

Creating a session (using the IDirectPlay3::Open method) causes a dialog box to appear asking the user to configure the serial port. The IDirectPlay3::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 your applications.

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

Top of Page