DirectX SDK

IDirectPlay4::CreateGroup

The IDirectPlay4::CreateGroup method creates a group in the current session. A group is a logical collection of players or other groups.

HRESULT CreateGroup(
  LPDPID lpidGroup,
  LPDPNAME lpGroupName,
  LPVOID lpData,
  DWORD dwDataSize,
  DWORD dwFlags
);

Parameters

lpidGroup

Pointer to a variable that will be filled with the DirectPlay group ID. This value is defined by DirectPlay.

lpGroupName

Pointer to a DPNAME structure that holds the name of the group. NULL indicates that the group has no initial name. The name in lpGroupName is provided for human use only; it is not used internally and need not be unique.

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 IDirectPlay4::SetGroupData were called.

dwDataSize

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

dwFlags

Flag indicating what type of group to create. By default (dwFlags = 0), ownership of the group will migrate to the host when the owner leaves the session, and the group persists until it is explicitly destroyed.

Can be one of the following values:

DPGROUP_HIDDEN: Creates the group with the hidden flag. When the group is enumerated, the hidden flag is set. In a lobby session, hidden groups are only available through shortcuts created with IDirectPlay4::AddGroupToGroup. This flag works much like the DPPLAYER_SPECTATOR flag for players.
DPGROUP_STAGINGAREA: Creates the group as a staging area. A staging area is used to marshal players together in order to launch a new session.

Return Values

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

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, CreateGroup will generate a DPMSG_CREATEPLAYERORGROUP system message that will be sent to all the other players. The application can then use IDirectPlay4::Send to send a message to all the players in a group by sending one message to the group ID. DirectPlay will either use multicast to send the message (if the service provider supports it) or send individual messages to each player in the group.

The group ID returned to the application should be used to identify the group for message passing and data association. Player and group IDs assigned by DirectPlay will always be unique within the session.

Groups created with CreateGroup are top-level groups in the session. They are enumerated with IDirectPlay4::EnumGroups. In contrast, the IDirectPlay4::CreateGroupInGroup method creates a group that is a subgroup of a parent group.

Groups can also be used by the application for general organization. In a lobby session, a staging area is used as the mechanism for collecting players for the purpose of starting a new application session using IDirectPlay4::StartSession.

The player who creates a group is the default owner of it. Only the owner can change group properties such as the name and remote data. If the owner leaves the session, ownership is transferred to the host of the session.

Any player aware of a group in a session can change the membership of the group or delete the group.

Groups will persist in the session until they are explicitly destroyed.

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.

IDirectPlay4::CreateGroup

Parameters

Return Values

Remarks

Requirements

See Also