---

IDirectPlay3::CreateGroup

IDirectPlay3 Interface

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 IDirectPlay3::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.

DPGROUP_STAGINGAREA – the group is created 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:

DPERR_CANTADDPLAYER

DPERR_INVALIDFLAGS

DPERR_INVALIDPARAMS

Remarks

This method will generate a DPMSG_CREATEPLAYERORGROUP system message that will be sent to all the other players. The application can use IDirectPlay3::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 IDirectPlay3::EnumGroups. In contrast, the IDirectPlay3::CreateGroupInGroup method creates a group that is a sub-group 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 IDirectPlay3::StartSession.

The player that 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 in the session can change the membership of the group or delete the group.

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

See Also

DPNAME, DPMSG_CREATEPLAYERORGROUP, IDirectPlay3::DestroyGroup, IDirectPlay3::EnumGroups, IDirectPlay3::EnumGroupPlayers, IDirectPlay3::Send, IDirectPlay3::SetGroupData, IDirectPlay3::SetGroupName, IDirectPlay3::CreateGroupInGroup, IDirectPlay3::GetGroupFlags

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Top of Page