Platform SDK: DirectX

CONST_DPSYSMSGTYPES

The members of the CONST_DPSYSMSGTYPES enumeration are used to identify the different kinds of system messages and lobby messages. Every DirectPlayMessage object that represents a system or lobby message will return one of these constants from the first call to DirectPlayMessage.ReadLong. It is up to the application to determine the message type and then parse any further data by using appropriate calls to the various read methods of DirectPlayMessage.

Two lobby messages, DPLSYS_GETPROPERTY and DPLSYS_SETPROPERTY, are sent by the application rather than by the system. The application must write the type identifier and the rest of the data to the message using the appropriate write methods of DirectPlayMessage.

It is important that applications deal separately with ordinary system messages and lobby messages. Some lobby and nonlobby messages share the same value (for example, DPLSYS_SETPROPERTY and DPSYS_DESTROYPLAYERORGROUP). It would be unwise, therefore, to send all messages to a common handler without any information about whether they were lobby or nonlobby messages.

Enum CONST_DPSYSMSGTYPES
    DPLSYS_APPTERMINATED =          4 
    DPLSYS_CONNECTIONSETTINGSREAD = 1 
    DPLSYS_DPLAYCONNECTFAILED =     2 
    DPLSYS_DPLAYCONNECTSUCCEEDED =  3 
    DPLSYS_GETPROPERTY =            7 
    DPLSYS_GETPROPERTYRESPONSE =    8 
    DPLSYS_NEWCONNECTIONSETTINGS = 10 
    DPLSYS_NEWSESSIONHOST =         9 
    DPLSYS_SETPROPERTY =            5 
    DPLSYS_SETPROPERTYRESPONSE  =   6 
    DPSYS_ADDGROUPTOGROUP =       261 (&H105)
    DPSYS_ADDPLAYERTOGROUP =        7 
    DPSYS_CHAT =                  265 (&H109)
    DPSYS_CREATEPLAYERORGROUP =     3 
    DPSYS_DELETEGROUPFROMGROUP =  262 (&H106)
    DPSYS_DELETEPLAYERFROMGROUP =  33 (&H21)
    DPSYS_DESTROYPLAYERORGROUP =    5 
    DPSYS_HOST =                  257 (&H101)
    DPSYS_SECUREMESSAGE =         263 (&H107)
    DPSYS_SENDCOMPLETE =          269 (&H10D)
    DPSYS_SESSIONLOST =            49 (&H31)
    DPSYS_SETGROUPOWNER =         266 (&H10A)
    DPSYS_SETPLAYERORGROUPDATA =  258 (&H102)
    DPSYS_SETPLAYERORGROUPNAME =  259 (&H103)
    DPSYS_SETSESSIONDESC =        260 (&H104)
    DPSYS_STARTSESSION =          264 (&H108)
End Enum

The following descriptions include lists of any extra data members in each message type, in the order in which they occur in the underlying structure. (For more information on the underlying C/C++ structures, see System Messages.) It is assumed that the application has already extracted the message type by using ReadLong.

If the message data consisted of a Long followed by a GUID, your application would parse the data by calling first DirectPlayMessage.ReadLong and then DirectPlayMessage.ReadGuid. In cases where the underlying structure contains a pointer to a buffer, you must use a special method such as DirectPlayMessage.ReadSysChatString in order to get the data from the buffer.

Standard Lobby Messages

DPLSYS_APPTERMINATED

The application started by DirectPlayLobby3.RunApplication has terminated.

GUID: Unique identifier of the session to which this lobby message applies.

DPLSYS_CONNECTIONSETTINGSREAD

The application started by the DirectPlayLobby3.RunApplication method has read the connection settings.

GUID: Unique identifier of the session to which this lobby message applies.

DPLSYS_DPLAYCONNECTFAILED

The application started by DirectPlayLobby3.RunApplication failed to connect to a session.

GUID: Unique identifier of the session to which this lobby message applies.

DPLSYS_DPLAYCONNECTSUCCEEDED

The application started by DirectPlayLobby3.RunApplication has created a session and is ready for other applications to join or has successfully joined a session.

GUID: Unique identifier of the session to which this lobby message applies.

DPLSYS_GETPROPERTY

Message sent by an application to the lobby to request the current value of a property.

Long: Application-generated ID to identify the request. The lobby's response will be tagged with this ID. The application can use the request ID to match responses to pending requests.
GUID: Unique identifier of the player that this property applies to (if applicable). If the property is not player-specific, this member should be set to an empty string.
GUID: Unique identifier of the property that is being requested. DirectPlay defines certain properties. The application or lobby can define its own GUIDs for additional properties. For more information, see DirectPlay Defined Properties in the C++ reference for DirectPlay.

DPLSYS_GETPROPERTYRESPONSE

Message sent by the lobby to the application in response to a DPLSYS_GETPROPERTY message.

Long

ID of the request being responded to.

GUID

Unique identifier of the player that this property applies to. If the property is not player-specific, this member will be set to an empty string. This is the same value as was given in the DPLSYS_GETPROPERTY message.

GUID

Unique identifier of the property that is being requested. This is the same value as was given in the DPLSYS_GETPROPERTY message.

Long

Return code for the get property request. Zero if the request was successful, or one of the following values otherwise:

DPERR_UNKNOWNMESSAGE

DPERR_UNAVAILABLE

Long

Size of the data, in bytes. This value is followed by a variable-size buffer that contains the property data. The property tag determines how this data should be read and interpreted. For more information, see DirectPlay Defined Properties in the C++ reference for DirectPlay.

DPLSYS_NEWCONNECTIONSETTINGS

Lobby system message. A waiting application was found when a lobby client called DirectPlayLobby3.RunApplication.The waiting application can now read the connection settings by using DirectPlayLobby3.GetConnectionSettings.

GUID: Unique identifier of the session to which this lobby message applies.

DPLSYS_NEWSESSIONHOST

Message sent by the lobby to the application instance that has become the new session host.

GUID: Unique identifier of this instance.

DPLSYS_SETPROPERTY

Message sent by an application to the lobby to set the value of a property.

Long: Application-generated ID to identify the request. The lobby's response will be tagged with this ID. The application can use the request ID to match responses to pending requests.
GUID: Unique identifier of the player that this property applies to. If the property is not player-specific, this member should be set to an empty string.
GUID: Unique identifier of the property that is being requested. DirectPlay defines certain properties. The application or lobby can define its own GUIDs for additional properties.
Long: Size of the data, in bytes. This value is followed by a variable-size buffer that contains the property data. The property tag determines how the data is organized and should be written. For example, for the DPLPROPERTY_PlayerScore property, you would call DirectPlayMessage.WriteLong once to record the number of scores, and then again for each score. For more information, see DirectPlay Defined Properties in the C++ reference for DirectPlay.

DPLSYS_SETPROPERTYRESPONSE

Message sent by the lobby to the application in response to a DPLSYS_SETPROPERTY message.

Long

ID of the request being responded to.

GUID

Unique identifier of the player that this property applies to (if applicable). If the property is not player-specific, this member will be set to an empty string. This is the same value as was given in the DPLSYS_SETPROPERTY message.

GUID

Unique identifier of the property that is being requested. This is the same value as was given in the DPLSYS_SETPROPERTY message.

Long

Return code for the set property request. Zero if the request was successful, or one of the following values otherwise:

DPERR_ACCESSDENIED

DPERR_UNKNOWNMESSAGE

Nonlobby System Messages

DPSYS_ADDGROUPTOGROUP

A group has been added to a group.

Long: ID of the group to which the group was added.
Long: ID of the group that was added to the group.

DPSYS_ADDPLAYERTOGROUP

A player has been added to a group.

Long: ID of the group to which the player was added.
Long: ID of the player that was added to the group.

DPSYS_CHAT

The message is a chat string transmitted through the lobby.

Long: Flags. Always 0.
Long: ID of the player from whom the message originated. DPID_SERVERPLAYER indicates the message originated from the server.
Long: ID of the player to whom the message was directed. If this ID is 0, then the message was sent to a group or broadcast to everyone.
Long: ID of the group to whom the message was directed. If this ID is 0 and the previous Long is also 0, then the message was broadcast to everyone.
Long: Pointer to the chat string. Read this string by using the DirectPlayMessage.ReadSysChatString method.

DPSYS_CREATEPLAYERORGROUP

A player or group was created.

Long: Flag indicating whether a player (DPPLAYERTYPE_PLAYER) or a group (DPPLAYERTYPE_GROUP) was created.
Long: ID of player or group created.
Long: Number of players in the session.
Long (2): Pointer to, and size of, a buffer containing local data for the group. The contents of this buffer are retrieved by using the DirectPlayMessage.ReadSysMsgData method.
Long (2): Pointer to, and size of, a buffer containing remote data for the group. The contents of this buffer are retrieved by using ReadSysMsgData.
Long: Size of the underlying name structure, in bytes. Can be discarded.
Long: Flags for the name structure. Always 0.
String: Short name of the group.
String: Long name of the group.
Long: ID of the parent group if the group was created by a call to DirectPlay4.CreateGroupInGroup. Otherwise the value is 0.
Long: Player or group flags. Can be 0 or DPGROUP_HIDDEN (see CONST_DPGROUPFLAGS).

DPSYS_DELETEGROUPFROMGROUP

A group was removed from a group.

Long: ID of the group from which the group was removed.
Long: ID of the group that was removed.

DPSYS_DELETEPLAYERFROMGROUP

A player was removed from a group.

Long: ID of the group from which the player was removed.
Long: ID of the player that was removed.

DPSYS_DESTROYPLAYERORGROUP

A player or group was destroyed.

Long

Flag indicating whether a player (DPPLAYERTYPE_PLAYER) or a group (DPPLAYERTYPE_GROUP) was destroyed.

Long

ID of player or group that has been destroyed.

Long (2)

Pointer to, and size of, a buffer containing local data for the group. The contents of this buffer are retrieved by using the DirectPlayMessage.ReadSysMsgData method.

Long (2)

Pointer to, and size of, a buffer containing remote data for the group. The contents of this buffer are retrieved by using ReadSysMsgData.

Long

Size of the underlying name structure, in bytes. Can be discarded.

Long

Flags for the name structure. Always 0.

String

Short name of the group.

String

Long name of the group.

Long

ID of the parent group if the group being destroyed is a subgroup of the parent group—that is, the group being destroyed was created by a call to DirectPlay4.CreateGroupInGroup. Otherwise the value is 0.

Long

Player or group flags. Can contain one or more of the following values from the CONST_DPGROUPFLAGS enumeration:

DPGROUP_HIDDEN

Set when a hidden group is destroyed.

DPGROUP_STAGINGAREA

Set when a group that is a staging area is destroyed.

DPPLAYER_SERVERPLAYER

Set when the player being destroyed is a server player for client/server communications.

DPPLAYER_SPECTATOR

Set when the player destroyed is a spectator.

DPSYS_HOST

The player receiving the message is now the session host. This message contains no extra data.

DPSYS_SECUREMESSAGE

A signed or encrypted message has been received from another player.

Long

Flag indicating how the message was secured by the sender. One of the following values from the CONST_DPSENDFLAGS enumeration:

DPSEND_SIGNED

The message was signed by the sender and the signature was successfully verified.

DPSEND_ENCRYPTED

The message was encrypted by the sender and successfully decrypted.

Long

ID of the player who sent the message.

To read the decrypted message, use the DirectPlayMessage.MoveToSecureMessage method to move the read pointer to the beginning of the data buffer. Read the data by using the standard read methods of DirectPlayMessage.

DPSYS_SENDCOMPLETE

Message sent to an application to inform it of the completion status of an asynchronous send. This message is generated by default whenever an asynchronous message is sent using the DPSEND_ASYNC flag in DirectPlay4.SendEx.

Long

ID of the player who sent the message.

Long

ID of the player the message was sent to.

Long

Flags specified in SendEx when the message was sent.

Long

Priority that the message was sent at.

Long

Time-out specified when the message was sent (specified in SendEx). Zero indicates the default time-out.

Long

The context parameter supplied by the application to SendEx.

Long

Message ID returned to the application by SendEx.

Long

Result of the asynchronous message. Zero if the message was successfully sent, or one of the following error codes:

DPERR_ABORTED

The message was canceled while it was being transmitted.

DPERR_CANCELLED

The message was canceled while it was still in the send queue.

DPERR_GENERIC

The message could not be sent.

DPERR_TIMEOUT

The message timed out and was removed from the send queue.

Long

The elapsed time, in milliseconds, between the time the message was sent by the application and the time DirectPlay was able to send the message. This includes the time spent in the send queue and the time to hand the message off to the service provider. For guaranteed messages, this also includes the time to acknowledge delivery of the message.

DPSYS_SESSIONLOST

The connection to all the other players in the session was lost. After the session is lost, messages cannot be sent to remote players, but all data at the time the session was lost is still available. The application should try to recover gracefully and exit if this message is received. The message contains no extra data.

DPSYS_SETGROUPOWNER

The owner of a group has changed. Group ownership can be changed by the current owner leaving the session, by a call to DirectPlay4.SetGroupOwner, or, arbitrarily, by the lobby server in a lobby session.

Long: ID of the group whose owner changed.
Long: Player ID of the new owner of the group.
Long: Player ID of the old owner of the group.

DPSYS_SETPLAYERORGROUPDATA

DirectPlay generates this message and sends it to each player when the remote data of a player or group changes. This message will not be generated if the DPSESSION_NODATAMESSAGES flag is specified in the session description.

Long: Identifies whether the message applies to a player (DPPLAYERTYPE_PLAYER) or a group (DPPLAYERTYPE_GROUP).
Long: ID of the player or group whose data changed.
Long (2): Pointer, and size of, a buffer containing application-specific data. The contents of this buffer are retrieved by using the DirectPlayMessage.ReadSysMsgData method.

DPSYS_SETPLAYERORGROUPNAME

DirectPlay generates this message and sends it to each local player on the computer when the name of a player or group changes. This message will not be generated if the DPSESSION_NODATAMESSAGES flag is specified in the session description.

Long: Identifies whether the message applies to a player (DPPLAYERTYPE_PLAYER) or a group (DPPLAYERTYPE_GROUP).
Long: ID of the player or group whose name changed.
Long: Size of the underlying name structure. Can be discarded.
Long: Flags. Always 0.
String: New short name of the player or group.
String: New long name of the player or group.

DPSYS_SETSESSIONDESC

Every player receives this system message when the session description changes. The new session description can be obtained by using DirectPlayMessage.ReadSysMsgSessionDesc.

DPSYS_STARTSESSION

The lobby server sends this message to each player in a group when it is time for that player to join an application session. The connection data can be retrieved by using the DirectPlayMessage.ReadSysMsgConnection method.