Platform SDK: DirectX |
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 );
Can be one of the following values:
Returns DP_OK if successful, or one of the following error values otherwise:
DPERR_CANTADDPLAYER |
DPERR_CONNECTIONLOST |
DPERR_INVALIDFLAGS |
DPERR_INVALIDPARAMS |
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.
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.
DPNAME, DPMSG_CREATEPLAYERORGROUP, IDirectPlay4::AddGroupToGroup,IDirectPlay4::DestroyGroup, IDirectPlay4::EnumGroups, IDirectPlay4::EnumGroupPlayers, IDirectPlay4::Send, IDirectPlay4::SetGroupData, IDirectPlay4::SetGroupName, IDirectPlay4::CreateGroupInGroup, IDirectPlay4::GetGroupFlags