| Platform SDK: DirectX |
DirectPlay supports groups within a session. A group is a logical collection of players. An application can send a message to a group, and all the players in the group will receive the message. Like players, groups are identified by unique numbers that are not reused in the course of a session.
Groups can be used to organize players in a session—for example, in teams. A player can belong to more than one group. When a group is destroyed, all member players are removed from the group, but the players themselves are not destroyed.
Groups can also contain subgroups and shortcuts to groups. When a group is created by using the CreateGroup method, it is a top-level group (call it A). A shortcut to that group can then be added to another group (call it B) by using the AddGroupToGroup method. When group B is destroyed, the shortcut to A is also destroyed, but A continues to exist as a top-level group. On the other hand, if A is created within B by using the CreateGroupInGroup method, then A is not a top-level group and ceases to exist when B is destroyed.
A message sent to a group is delivered to all players who are part of that group, whether directly or indirectly. Suppose, for example, a player called Quarterback is added to a group called BlueOffense. The BlueOffense group is then added to the BlueTeam group. Quarterback has not been added directly to BlueTeam, but nonetheless receives all messages addressed to BlueTeam as well as those addressed to BlueOffense.
It is a good idea to take advantage of the group management methods of DirectPlay rather than implementing your own system for player groups. DirectPlay is able to take advantage of any multicasting capabilities of the service provider in order to send group messages, thus reducing message traffic. For more information, see Peer-to-Peer Session.
DirectPlay provides the following essential methods for administering groups and their membership:
IDirectPlay4::AddPlayerToGroup adds a player to a group.
IDirectPlay4::CreateGroup creates a new top-level group.
IDirectPlay4::DeletePlayerFromGroup removes a player from a group.
IDirectPlay4::DestroyGroup destroys a group.
IDirectPlay4::EnumGroupPlayers enumerates the players in a group.
IDirectPlay4::EnumGroups enumerates all the groups in the session.
DirectPlay provides these additional methods for managing groups and group information:
IDirectPlay4::AddGroupToGroup adds a group shortcut to an already existing group.
IDirectPlay4::CreateGroupInGroup creates a group within an existing group.
IDirectPlay4::DeleteGroupFromGroup removes a group previously added to another group by using AddGroupToGroup, but doesn't destroy the deleted group.
IDirectPlay4::EnumGroupsInGroup enumerates all the groups within another group.
IDirectPlay4::GetGroupConnectionSettings retrieves a group's connection settings.
IDirectPlay4::GetGroupData gets the application-specific data associated with a group.
IDirectPlay4::GetGroupFlags gets additional information about how a group was created.
IDirectPlay4::GetGroupName gets the group's name.
IDirectPlay4::GetGroupOwner gets the owner of a group.
IDirectPlay4::GetGroupParent gets the ID of the parent of a subgroup created by using CreateGroupInGroup.
IDirectPlay4::SetGroupConnectionSettings sets a group's connection settings.
IDirectPlay4::SetGroupData changes the application-specific data associated with a group created by this computer.
IDirectPlay4::SetGroupName changes the name of a group created by this computer.
IDirectPlay4::SetGroupOwner changes the owner of a group.
DirectPlay provides the following essential methods for administering groups and their membership:
DirectPlay4.AddPlayerToGroup adds a player to a group.
DirectPlay4.CreateGroup creates a new top-level group.
DirectPlay4.DeletePlayerFromGroup removes a player from a group.
DirectPlay4.DestroyGroup destroys a group.
DirectPlay4.GetDPEnumGroupPlayers enumerates the players in a group.
DirectPlay4.GetDPEnumGroups enumerates all the groups in the session.
DirectPlay provides these additional methods for managing groups and group information:
DirectPlay4.AddGroupToGroup adds a group shortcut to an existing group.
DirectPlay4.CreateGroupInGroup creates a group within an existing group.
DirectPlay4.DeleteGroupFromGroup removes a group previously added to another group by using AddGroupToGroup, but doesn't destroy the deleted group.
DirectPlay4.GetDPEnumGroupsInGroup enumerates all the groups within another group.
DirectPlay4.GetGroupData gets the application-specific data associated with a group.
DirectPlay4.GetGroupFlags gets additonal information about how a group was created.
DirectPlay4.GetGroupLongName gets the group's long or formal name.
DirectPlay4.GetGroupOwner gets the owner of a group.
DirectPlay4.GetGroupParent gets the ID of the parent of a subgroup created by using CreateGroupInGroup.
DirectPlay4.GetGroupShortName gets the group's short or friendly name.
DirectPlay4.SetGroupConnectionSettings sets a group's connection settings in a lobby session.
DirectPlay4.SetGroupData changes the application-specific data associated with a group created by this computer.
DirectPlay4.SetGroupName changes the long and short name of a group.
DirectPlay4.SetGroupOwner changes the owner of a group.