Index Topic Contents | |||
Previous Topic: IDirectPlay3::EnumGroupsInGroup Next Topic: IDirectPlay3::EnumSessions |
IDirectPlay3::EnumPlayers
IDirectPlay3 InterfaceEnumerates the players in the current 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 session that matches the criteria specified in dwFlags.
Within a lobby session, this method will always return DPERR_ACCESSDENIED.
HRESULT EnumPlayers(
LPGUID lpguidInstance,
LPDPENUMPLAYERSCALLBACK2 lpEnumPlayersCallback2,
LPVOID lpContext,
DWORD dwFlags
);Parameters
- lpguidInstance
- This parameter should be NULL to enumerate players in the currently open session. If there is no open session, this parameter can be a pointer to a GUID identifying the session to be enumerated. The GUID must be equal to one of the sessions enumerated by IDirectPlay3::EnumSessions. This parameter is ignored unless the DPENUMPLAYERS_SESSION flag is specified.
- lpEnumPlayersCallback2
- Pointer to the EnumPlayersCallback2 function that will be called for every player in the session 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. Default (dwFlags = 0) enumerates all players in the current active session. You should OR together 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 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_ALL
- Enumerates all players in this session.
- DPENUMPLAYERS_GROUP
- Includes groups in the enumeration of players.
- DPENUMPLAYERS_LOCAL
- Enumerates players created locally by this DirectPlay object.
- 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.
- DPENUMPLAYERS_SPECTATOR
- Enumerates players who are spectator players.
Return Values
Returns DP_OK if successful, or one of the following error values otherwise:
- DPERR_INVALIDPARAMS
- DPERR_NOSESSIONS
- DPERR_UNAVAILABLE
This method returns DPERR_INVALIDPARAMS if an invalid callback, an invalid guidInstance, or invalid flags were supplied. It returns DPERR_NOSESSIONS if there is no open session. It returns DPERR_UNAVAILABLE if the remote session could not be enumerated.
Remarks
By default, this method will enumerate players in the current open session. Groups can also be included in the enumeration by using the DPENUMPLAYERS_GROUP flag. 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. This method cannot be called from within an IDirectPlay3::EnumSessions enumeration. Furthermore, use of the DPENUMPLAYERS_SESSION flag with this method must occur after the IDirectPlay3::EnumSessions method has been called, and before any calls to the IDirectPlay3::Close or IDirectPlay3::Open methods.
See Also
IDirectPlay3::CreatePlayer, IDirectPlay3::DestroyPlayer, IDirectPlay3::EnumSessions
© 1998 Microsoft Corporation. All rights reserved. Terms of Use.