IDirectPlay4::CreateGroup
IDirectPlay4 Interface
Creates a group in the current session. A group is a logical collection of players or other groups.
Syntax
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 Value
Returns DP_OK if successful, or one of the following error values otherwise:
DPERR_CANTADDPLAYER DPERR_CONNECTIONLOST DPERR_INVALIDFLAGS DPERR_INVALIDPARAMS
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 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 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.
See Also
DPNAME, DPMSG_CREATEPLAYERORGROUP, IDirectPlay4::AddGroupToGroup,IDirectPlay4::DestroyGroup, IDirectPlay4::EnumGroups, IDirectPlay4::EnumGroupPlayers, IDirectPlay4::Send, IDirectPlay4::SetGroupData, IDirectPlay4::SetGroupName, IDirectPlay4::CreateGroupInGroup, IDirectPlay4::GetGroupFlags
Top of Page
© 1998 Microsoft Corporation. All rights reserved. Terms of Use.