Getting DirectPlay Data

Many times during a Microsoft® DirectPlay® session, your application needs to get information from DirectPlay. This can be to enumerate all the hosts available or to get a new player's data. The DirectPlay programming model for retrieving data usually involves passing a buffer to DirectPlay to be filled. However, the buffer size needed is usually unknown. Allocating a large enough block of memory to hold any conceivable array will work, but is inefficient. Therefore, to use these methods that return data, you should first call the method with a null buffer. The method will return to you the required size of the buffer. Then you can call the method again using the required buffer size. This system of getting data is used to:

• Get address information (IDirectPlay8Address::GetComponentByIndex, IDirectPlay8Address::GetComponentByName, IDirectPlay8Address::GetURLA, IDirectPlay8Address::GetURLW, IDirectPlay8Address::GetUserData).
• Enumerate session hosts (IDirectPlay8Peer::EnumHosts, IDirectPlay8Client::EnumHosts).
• Enumerate service providers (IDirectPlay8Peer::EnumServiceProviders, IDirectPlay8Client::EnumServiceProviders, IDirectPlay8Server::EnumServiceProviders).
• Get application descriptions (IDirectPlay8Client::GetApplicationDesc, IDirectPlay8Server::GetApplicationDesc, IDirectPlay8Peer::GetApplicationDesc).
• Fill structures (Structures).
• Enumerate devices (IDirectPlay8NATResolver::EnumDevices).
• Enumerate players and groups(IDirectPlay8Peer::EnumPlayersAndGroups, IDirectPlay8Server::EnumPlayersAndGroups).
• Enumerate group members (IDirectPlay8Peer::EnumGroupMembers, IDirectPlay8Server::EnumGroupMembers).
• Enumerate local programs (IDirectPlay8LobbyClient::EnumLocalPrograms).

The following procedure outlines how to enumerate the members of a group in a peer-to-peer game as an example. The same general procedure is followed by all other types of data retrieval, except for host enumerations. Because enumerations are often used to obtain a snapshot of information that might be changing, you should perform enumerations in a loop until you are successful.

1. Call IDirectPlay8Peer::EnumGroupMembers. This method returns an integer array in the prgdpnid parameter that contains the identifier (ID) of each player in the group. The pcdpnid parameter is used to indicate the number of elements in the array. Set the pcdpnid parameter to 0 to request the appropriate value. Set prgdpnid to NULL.
2. When the method returns, pcdpnid will point to the number of elements that will be in the array.
3. Allocate your array using the returned pcdpnid value, and assign the array to the prgdpnid parameter.
4. Set pcdpnid to the value that was returned in the first method call.
5. Call IDirectPlay8Peer::EnumGroupMembers again.
6. When the method returns the second time, check the return value. If successful, the method will return S_OK, and the array will contain the player's IDs.
7. If the method returns DPNERR_BUFFERTOOSMALL again, the number of players has increased since the previous method call. Return to step three and use the new pcdpnid value to increase the array size. Be careful not to leak memory.

In some cases, the method returns an array of structures. In that case, you follow the same procedure, but the value returned from the first method call gives you the size of the array in bytes, instead of the number of elements in the array. Refer to the individual method references for details.

For more information, see Enumerating Hosts.