IDirectPlay4::CreateGroupInGroup

The IDirectPlay4::CreateGroupInGroup method creates a group within an existing group. A group created within another group can only be enumerated using the IDirectPlay4::EnumGroupsInGroup method. A group created this way can be destroyed by calling the IDirectPlay4::DestroyGroup method.

HRESULT CreateGroupInGroup(
  DPID idParentGroup,
  LPDPID lpidGroup,
  LPDPNAME lpGroupName,
  LPVOID lpData,
  DWORD dwDataSize,
  DWORD dwFlags
);

Parameters

idParentGroup

ID of the group within which a group will be created. Must be an already existing group.

lpidGroup

Address of a variable to receive the DirectPlay group ID of the created group.

lpGroupName

Pointer to a DPNAME structure that holds the name of the group to be created. NULL indicates that the group has no initial name.

lpData

Pointer to a block of application-defined remote data to associate initially with the group ID. NULL indicates that the group has no initial data. The data specified here is assumed to be remote data that will be propagated to all the other applications in the session as if the IDirectPlay4::SetGroupData method had been called.

dwDataSize

Size, in bytes, of the data block that the lpData parameter points to.

dwFlags

Flag indicating what type of group to create. Default (dwFlags = 0) is a normal group.

DPGROUP_HIDDEN

Creates the group with the hidden flag. When the group is enumerated, the hiddle flag is set. In a lobby session, hidden groups are only available through shortcuts created with IDirectPlay4::AddGroupToGroup.

DPGROUP_STAGINGAREA

Creates the group as a staging area. A staging area can be used to launch DirectPlay sessions using the IDirectPlay4::StartSession method.

Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

This method returns DPERR_CANTADDPLAYER if the group could not be created. It returns DPERR_INVALIDGROUP if the parent group ID is invalid.

Remarks

If the group is created in a client/server session, no group notification messages are sent. Groups are only visible on the machine that created them, regardless of whether the machine is the client or the host.

If the group is created in a peer-to-peer session, CreateGroupInGroup will generate a DPMSG_CREATEPLAYERORGROUP system message generated to inform players of this change.

If you destroy a top-level group, any member groups it contains are destroyed as well, and the appropriate destruction messages are sent.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
  Header: Declared in dplay.h.
  Import Library: Use dplayx.lib.

See Also

IDirectPlay4::DestroyGroup, IDirectPlay4::EnumGroupsInGroup, DPMSG_CREATEPLAYERORGROUP