Implementing a DirectPlay Enumeration

Most Microsoft?DirectPlay?enumerations follow a standard pattern: call the appropriate enumeration method, and examine the returned data array. The exception to this pattern is host enumerations, which are discussed separately.

Before you can call the method to obtain the data, you must allocate enough memory to contain the returned data block. However, you typically do not know, in advance, how large that array will be. Allocating a large enough block of memory to hold any conceivable array will work, but is inefficient. Instead DirectPlay is allows you query for the required array size, and then repeat the query to obtain the structure itself.

The following procedure outlines how to enumerate the members of a group in a peer-to-peer game. The same general procedure is followed by all other types of enumeration, 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.