IDirectPlay4::EnumGroups
IDirectPlay4 Interface
Enumerates all the top-level groups in the current session. Top-level groups are groups that were created with the IDirectPlay4::CreateGroup method. If there is no open session, groups in a remote session can be enumerated by specifying the DPENUMGROUPS_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 group in the session that matches the criteria specified in dwFlags.
You cannot use EnumGroups in a lobby session you are not connected to.
Syntax
HRESULT EnumGroups(
LPGUID lpguidInstance,
LPDPENUMPLAYERSCALLBACK2 lpEnumPlayersCallback2,
LPVOID lpContext,
DWORD dwFlags
);
Parameters
- lpguidInstance
- This parameter should be NULL to enumerate groups in the currently open session. If there is no open session, this parameter can be a pointer to a globally unique identifier (GUID) identifying the session to be enumerated. The GUID must be equal to one of the sessions enumerated by IDirectPlay4::EnumSessions. This parameter is ignored unless the DPENUMGROUPS_SESSION flag is specified.
- lpEnumPlayersCallback2
- Pointer to the EnumPlayersCallback2 function that will be called for every group 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 groups in the current active session. You should use a logical OR operation to combine the flags that you want to specify. Only groups that meet all the criteria of the combined flags will be enumerated. For example, if you specify (DPENUMGROUPS_LOCAL | DPENUMGROUPS_STAGINGAREA) only groups that are local and are staging areas will be enumerated. If you specify (DPENUMGROUPS_LOCAL | DPENUMGROUPS_REMOTE), no groups will be enumerated because no group can be both local and remote.
- Can be one or more of the following values:
- DPENUMGROUPS_ALL
- Enumerates all groups in this session.
- DPENUMGROUPS_HIDDEN
- Enumerates only hidden groups that are currently available.
- DPENUMGROUPS_LOCAL
- Enumerates groups created locally by this DirectPlay object.
- DPENUMGROUPS_REMOTE
- Enumerates groups created by remote DirectPlay objects.
- DPENUMGROUPS_SESSION
- Performs enumeration in the session identified by the lpguidInstance parameter. This flag can only be used if there is no current active session. You cannot use this flag in a lobby session.
- DPENUMGROUPS_STAGINGAREA
- Enumerates groups that are staging areas. (Staging areas are used to marshal players together in order to launch a new session.)
Return Value
Returns DP_OK if successful, or one of the following error messages otherwise:
DPERR_CONNECTIONLOST 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
To enumerate the subgroups in a group, use IDirectPlay4::EnumGroupsInGroup.
See Also
EnumPlayersCallback2, IDirectPlay4::CreateGroup, IDirectPlay4::DestroyGroup, IDirectPlay4::EnumSessions
Top of Page
© 1998 Microsoft Corporation. All rights reserved. Terms of Use.