IDirectPlay4::EnumGroupPlayers
IDirectPlay4 Interface
Enumerates the players belonging to a specific group in the currently open session. If there is no open session, players in a remote session can be enumerated by specifying the DPENUMPLAYERS_session flag and the guidInstance of the session. Password-protected remote sessions cannot be enumerated.
A pointer to an application-implemented callback function must be supplied, and DirectPlay calls it once for each player in the group that matches the criteria specified in dwFlags.
You cannot use EnumGroupPlayers in a lobby session you are not connected to.
Syntax
HRESULT EnumGroupPlayers(
DPID idGroup,
LPGUID lpguidInstance,
LPDPENUMPLAYERSCALLBACK2 lpEnumPlayersCallback2,
LPVOID lpContext,
DWORD dwFlags
);
Parameters
- idGroup
- DPID of the group whose players are to be enumerated.
- lpguidInstance
- Pointer to a globally unique identifier (GUID) identifying the session to be enumerated. This parameter is ignored unless the DPENUMPLAYERS_SESSION flag is specified. The GUID must be equal to one of the sessions enumerated by IDirectPlay4::EnumSessions.
- lpEnumPlayersCallback2
- Pointer to the EnumPlayersCallback2 function that will be called for every player in the group that matches the criteria specified in dwFlags.
- lpContext
- Pointer to an application-defined context that is passed to each enumeration callback.
- dwFlags
- Flags specifying how the enumeration is to be done. The default (dwFlags = 0) enumerates players in a group in the current active session. You should use a logical OR operation to combine the flags that you want to specify. Only players that meet all the criteria of the combined flags will be enumerated. For example, if you specify (DPENUMPLAYERS_LOCAL | DPENUMPLAYERS_SPECTATOR) only players in the group that are local and are spectator players will be enumerated. If you specify (DPENUMPLAYERS_LOCAL | DPENUMPLAYERS_REMOTE), no players will be enumerated because no player can be both local and remote.
- Can be one or more of the following values:
- DPENUMPLAYERS_LOCAL
- Enumerates players created locally by this DirectPlay object.
- DPENUMPLAYERS_OWNER
- Enumerates only the player that is the owner of this group.
- DPENUMPLAYERS_REMOTE
- Enumerates players created by remote DirectPlay objects.
- DPENUMPLAYERS_SERVERPLAYER
- Enumerates the server player.
- DPENUMPLAYERS_SESSION
- Enumerates the players for the session identified by lpguidInstance. This flag can only be used if there is no current open session. This flag cannot be used in a lobby session.
- DPENUMPLAYERS_SPECTATOR
- Enumerates players who are spectator players.
Return Value
Returns DP_OK if successful, or one of the following error messages otherwise:
DPERR_ACCESSDENIED DPERR_CONNECTIONLOST DPERR_INVALIDPARAMS DPERR_INVALIDGROUP DPERR_NOSESSIONS DPERR_UNAVAILABLE This method returns DPERR_ACCESSDENIED if the session is a lobby session you are not connected to. It returns DPERR_INVALIDPARAMS if an invalid callback, an invalid guidInstance, or if invalid flags were supplied. It returns DPERR_NOSESSIONS if there is no active session. It returns DPERR_UNAVAILABLE if the session could not be enumerated.
Remarks
By default, this method will enumerate all players in the current session. The DPENUMPLAYERS_SESSION flag can be used, along with a session instance GUID, to request that a session's host provide its list for enumeration. Use of the DPENUMPLAYERS_SESSION flag with this method must occur after the IDirectPlay4::EnumSessions method has been called, and before any calls to the IDirectPlay4::Close or IDirectPlay4::Open methods.
The DPENUMPLAYERS_OWNER flag is returned in the callback, indicating which player is the owner of the group.
See Also
IDirectPlay4::CreatePlayer, IDirectPlay4::DestroyPlayer, IDirectPlay4::AddPlayerToGroup, IDirectPlay4::DeletePlayerFromGroup
Top of Page
© 1998 Microsoft Corporation. All rights reserved. Terms of Use.