DirectPlay4.CreateGroup

The DirectPlay4.CreateGroup method creates a group in the current session.

object.CreateGroup(friendlyName As String, _
    formalName As String, _
    flags As CONST_DPGROUPFLAGS) As Long

Parameters

object

Object expression that resolves to a DirectPlay4 object.

friendlyName

Handle that can be used to identify and access the created group. This token identifier should differ from formalName.

formalName

Handle that can be used to identify and access the created group. This token identifier should differ from friendlyName.

flags

Flag from the CONST_DPGROUPFLAGS enumeration indicating what type of group to create. Can be one of DPGROUP_DEFAULT, DPGROUP_HIDDEN, or DPGROUP_STAGINGAREA.

Return Values

The method returns the group ID.

Error Codes

If the method fails, an error is raised and Err.Number may be set to one of the following values:

Remarks

If the group is created in a client/server session, no group notification messages are sent. Groups are only visible on the computer that created them, regardless of whether the computer is the client or the host.

If the group is created in a peer-to-peer session, CreateGroup will generate a DPSYS_CREATEPLAYERORGROUP system message that will be sent to all the other players. The application can subsequently use the DirectPlay4.Send method 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 DirectPlay4.GetDPEnumGroups. In contrast, the DirectPlay4.CreateGroupInGroup method creates a group that is a subgroup of a parent group.

The application can also use groups 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 DirectPlay4.StartSession.

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

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

See Also

DirectPlay4.AddGroupToGroup,DirectPlay4.DestroyGroup, DirectPlay4.GetDPEnumGroupPlayers, DirectPlay4.GetGroupFlags, DirectPlay4.SetGroupData, DirectPlay4.SetGroupName