IDirectPlay4::SetGroupData

The IDirectPlay4::SetGroupData method associates an application-specific data block with a group ID. Only the computer that created the group can change the remote data associated with it.

HRESULT SetGroupData(
  DPID idGroup,
  LPVOID lpData,
  DWORD dwDataSize,
  DWORD dwFlags
);

Parameters

idGroup

Group ID for which data is being set.

lpData

Pointer to the data to be set. Set to NULL to clear any existing group data.

dwDataSize

Size of the data buffer. If lpData is NULL and this parameter does not equal 0, the method returns DPERR_INVALIDPARAMS.

dwFlags

Flag indicating how the group data is propagated. If this parameter is set to 0, the remote group data will be set and propagated using nonguaranteed messaging.

DPSET_GUARANTEED

Propagates the data by using guaranteed messaging (if available). This flag can only be used with DPSET_REMOTE.

DPSET_LOCAL

This data is for local use only and will not be propagated.

DPSET_REMOTE

This data is for use by all the applications and will be propagated to all the other applications in the session. This flag can only be used on groups owned by the local session.

Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

Remarks

DirectPlay can maintain two types of group data: local and remote. Local data is available only to the application on the local computer. Remote data is propagated to all the other applications in the session. A DPMSG_SETPLAYERORGROUPDATA system message will be sent to all players (including the sender) notifying them of the change unless DPSESSION_NODATAMESSAGES is set in the session description. You can safely store pointers to resources in the local data; the local data block is available (in the DPMSG_DESTROYPLAYERORGROUP system message) when the group is being destroyed, so that the application can free those resources.

This method should not be used for updating real-time information (such as position updates) because of the overhead introduced. IDirectPlay4::Send is much more efficient for updating real-time information. IDirectPlay4::SetGroupData is more appropriate for shared-state information that does not change often and is not time-critical (such as a team color).

Requirements

  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.

See Also

DPMSG_SETPLAYERORGROUPDATA, IDirectPlay4::GetGroupData, IDirectPlay4::Send