#ifndef TDx_PlayH #define TDx_PlayH // ========================================================================== // File: TDx_Play.H // Authors: BCB_Code_Generator v1.70, // Darren Dwyer (source code, documentation, demos, website), // Hugh Edwards (documentation, icons), // Brian Austin (some source code, documentation) // Description: This file defines the TDx_Play Component // // "TDx_Play_Library v1.70" // (c) 2003 BCB-Tools.com Pty. Ltd., Sydney, Australia. // All Rights Reserved. // // Refer to the 'Licence.Txt' file for licencing & copyright information. // ========================================================================== // -------------------------------------------------------------------------- // #includes // -------------------------------------------------------------------------- #include #include #include #include // -------------------------------------------------------------------------- #include "TDx_Library_Defns.H" #include "TDx_Library_Functions.H" // -------------------------------------------------------------------------- #include "TDx_Play_Library_Defns.H" #include "TDx_Play_Library_Functions.H" // -------------------------------------------------------------------------- // external classes used by the TDx_Play component. class TDPName; class TDPChat; class TDPLConnection; // -------------------------------------------------------------------------- // external classes used by TDx_Play methods. class TDPSessionDesc; class TDPCaps; class TDPSecurityDesc; class TDPCredentials; // -------------------------------------------------------------------------- // Definition for the OnAddGroupToGroup event. typedef __fastcall void (__closure* TDx_OnAddGroupToGroup) ( TObject* Sender, dword IdParentGroup, dword IdGroup); // Definition for the OnAddPlayerToGroup event. typedef __fastcall void (__closure* TDx_OnAddPlayerToGroup) ( TObject* Sender, dword Group, dword Player); // Definition for the OnChat event. typedef __fastcall void (__closure* TDx_OnChat) ( TObject* Sender, dword Flags, dword FromPlayer, dword ToPlayer, dword ToGroup, TDPChat* Chat); // Definition for the OnCreatePlayerOrGroup event. typedef __fastcall void (__closure* TDx_OnCreatePlayerOrGroup) ( TObject* Sender, dword PlayerType, dword Id, dword CurrentPlayers, void* Data, dword DataSize, TDPName* Name, dword IdParent, dword Flags); // Definition for the OnDeleteGroupFromGroup event. typedef __fastcall void (__closure* TDx_OnDeleteGroupFromGroup) ( TObject* Sender, dword IdParentGroup, dword IdGroup); // Definition for the OnDeletePlayerFromGroup event. typedef __fastcall void (__closure* TDx_OnDeletePlayerFromGroup) ( TObject* Sender, dword Group, dword Player); // Definition for the OnDestroyPlayerOrGroup event. typedef __fastcall void (__closure* TDx_OnDestroyPlayerOrGroup) ( TObject* Sender, dword PlayerType, dword Id, void* LocalData, dword LocalDataSize, void* RemoteData, dword RemoteDataSize, TDPName* Name, dword IdParent, dword dwFlags); // Definition for the OnGeneric event. typedef __fastcall void (__closure* TDx_OnGeneric) ( TObject* Sender, dword From, dword To, dword Flags, void* Data, dword DataSize, dword MessageType); // Definition for the OnHost event. typedef __fastcall void (__closure* TDx_OnHost) ( TObject* Sender); // Definition for the OnReceive event. typedef __fastcall void (__closure* TDx_OnDPReceive) ( TObject* Sender); // Definition for the OnSecureMessage event. typedef __fastcall void (__closure* TDx_OnSecureMessage) ( TObject* Sender, dword Flags, dword IdFrom, void* Data, dword DataSize); // Definition for the OnSendComplete event. typedef __fastcall void (__closure* TDx_OnSendComplete) ( TObject* Sender, dword From, dword To, dword Flags, dword Priority, dword Timeout, void* Context, dword MsgID, HRESULT hr, dword SendTime); // Definition for the OnSessionLost event. typedef __fastcall void (__closure* TDx_OnSessionLost) ( TObject* Sender); // Definition for the OnSetGroupOwner event. typedef __fastcall void (__closure* TDx_OnSetGroupOwner) ( TObject* Sender, dword Group, dword NewOwner, dword OldOwner); // Definition for the OnSetPlayerOrGroupData event. typedef __fastcall void (__closure* TDx_OnSetPlayerOrGroupData) ( TObject* Sender, dword PlayerType, dword Id, void* Data, dword DataSize); // Definition for the OnSetPlayerOrGroupName event. typedef __fastcall void (__closure* TDx_OnSetPlayerOrGroupName) ( TObject* Sender, dword PlayerType, dword Id, TDPName* Name); // Definition for the OnSetSessionDesc event. typedef __fastcall void (__closure* TDx_OnSetSessionDesc) ( TObject* Sender, TDPSessionDesc* Desc); // Definition for the OnStartSession event. typedef __fastcall void (__closure* TDx_OnStartSession) ( TObject* Sender, TDPLConnection* Conn); // -------------------------------------------------------------------------- // Definition for the OnEnumConnections callback event. typedef __fastcall void (__closure* TDx_EnumConnections) ( TObject* Sender, const GUID* Guid, void* Connection, dword ConnectionSize, TDPName* Name, dword Flags, void* Context, bool &Continue ); // Definition for the OnEnumGroupPlayers callback event. typedef __fastcall void (__closure* TDx_EnumGroupPlayers) ( TObject* Sender, dword Id, dword PlayerType, TDPName* Name, dword Flags, void* Context, bool &Continue ); // Definition for the OnEnumGroups callback event. typedef __fastcall void (__closure* TDx_EnumGroups) ( TObject* Sender, dword Id, dword PlayerType, TDPName* Name, dword Flags, void* Context, bool &Continue ); // Definition for the OnEnumGroupsInGroup callback event. typedef __fastcall void (__closure* TDx_EnumGroupsInGroup) ( TObject* Sender, dword Id, dword PlayerType, TDPName* Name, dword Flags, void* Context, bool &Continue ); // Definition for the OnEnumPlayers callback event. typedef __fastcall void (__closure* TDx_EnumPlayers) ( TObject* Sender, dword Id, dword PlayerType, TDPName* Name, dword Flags, void* Context, bool &Continue ); // Definition for the OnEnumSessions callback event. typedef __fastcall void (__closure* TDx_EnumSessions) ( TObject* Sender, TDPSessionDesc* SessionDesc, dword* TimeOut, dword Flags, void* Context, bool &Continue ); // ========================================================================== // Class: TDx_Play // Description: The TDx_Play component wraps the DirectX IDirectPlay4 and // IDirectPlay4A interfaces, which are used in the creation of // TDx_Play objects and for working with sessions, groups and // players. // // You may utilize Unicode or ANSI strings when using TDx_Play, // but the use of both by the same application should be // avoided. // // To create an IDirectPlay4 or IDirectPlay4A interface, use the // TDx_Play::Create() method and to destroy the interface, use // the TDx_Play::Destroy() method. // // Use the TDx_Play::OnCreate() and TDx_Play::OnDestroy() events // to simplify the creation and destruction of dependent // objects. // // For example, in the TDx_Play::OnCreate() event, you could // retrieve the interface's capabilities, create a dependant // TDx_PlayLobby, and so on. Then in the TDx_Play::OnDestroy() // event, place code to destroy the same TDx_PlayLobby and // deallocate memory used to hold the capabilities (if // required). // // Once created, call any of the TDx_Play methods and handle any // error results using the TDx_Play::OnError() event and the // TDx_Play::ErrorValue property. // ========================================================================== #if (__BORLANDC__ >= 0x0530) // BCB Version 3 + class PACKAGE TDx_Play : public TComponent { // -------------------------------------------------------------------------- #else // BCB Version 1 class TDx_Play : public TComponent { #endif // ========================================================================== __published: // ========================================================================== // ---------------------------------------------------------------------- // Property: NumPlayers // Description: The NumPlayers property defines how many players are // currently active for this component. // ---------------------------------------------------------------------- __property int NumPlayers = { read=FGetNumPlayers, write=FSetNumPlayers, default=0 }; // ---------------------------------------------------------------------- // Property: UseAnsiString // Description: The UseAnsiString property is used to toggle a DirectPlay // interface between AnsiString or UniCode. // Set this property to true to enable an AnsiString // interface. // Set this property to false to enable a Unicode interface. // You should set this property before calling the // TDx_Play::Create() method. // ---------------------------------------------------------------------- __property bool UseAnsiString = { read=FGetUseAnsiString, write=FSetUseAnsiString, default=true }; // ---------------------------------------------------------------------- // Event: OnAddGroupToGroup() // Description: The OnAddGroupToGroup event is triggered when using the // TDx_Play::ReceiveEx() method in the TDx_Play::OnReceive() // event. // // This event indicates that DPMSG_ADDGROUPTOGROUP has been // received by the component's event thread. // // DPMSG_ADDGROUPTOGROUP is sent to all players when a group // is added to a group by TDx_Play::AddGroupToGroup(). // // If the component has created several players with // TDx_Play::CreatePlayer() then several events will be // triggered, one for each player. // ---------------------------------------------------------------------- __property TDx_OnAddGroupToGroup OnAddGroupToGroup = {read=FOnAddGroupToGroup, write=FOnAddGroupToGroup, nodefault}; // ---------------------------------------------------------------------- // Event: OnAddPlayerToGroup() // Description: The OnAddPlayerToGroup event is triggered when using the // TDx_Play::ReceiveEx() method in the TDx_Play::OnReceive() // event. // // This event indicates that DPMSG_ADDPLAYERTOGROUP has been // received by the component's event thread. // // DPMSG_ADDPLAYERTOGROUP is sent to all players when a // player is added to a group by // TDx_Play::AddPlayerToGroup(). // // If the component has created several players with // TDx_Play::CreatePlayer() then several events will be // triggered, one for each player. // // ---------------------------------------------------------------------- __property TDx_OnAddPlayerToGroup OnAddPlayerToGroup = {read=FOnAddPlayerToGroup, write=FOnAddPlayerToGroup, nodefault}; // ---------------------------------------------------------------------- // Event: OnChat() // Description: The OnChat event is triggered when using the // TDx_Play::ReceiveEx() method in the TDx_Play::OnReceive() // event. // // This event indicates that DPMSG_CHAT has been received by // the component's event thread. // // DPMSG_CHAT is sent to all players when a chat message is // sent with TDx_Play::SendChatMessage(). // ---------------------------------------------------------------------- __property TDx_OnChat OnChat = {read=FOnChat, write=FOnChat, nodefault}; // ---------------------------------------------------------------------- // Event: OnCreate() // Description: The OnCreate() event is triggered by the // TDx_Play::Create() method after it has successfully // created the internal LPDIRECTPLAY4 used within the // TDx_Play component. // // Note that since this event is only called upon successful // creation, this event is an ideal place for code that is // to be activated only once, immediately upon the // successful creation of the LPDIRECTPLAY4 interface. // // For example, you could retrieve the TDx_Play component's // capabilities, Create() dependant components, allocate // memory, etc. // // When used in conjunction with the TDx_Play::OnDestroy() // event, you can fully automate and insulate your code on a // per-component basis. // ---------------------------------------------------------------------- __property TDx_Event OnCreate = {read=FOnCreate, write=FOnCreate, nodefault}; // ---------------------------------------------------------------------- // Event: OnCreatePlayerOrGroup() // Description: The OnCreatePlayerOrGroup event is triggered when using // the TDx_Play::ReceiveEx() method in the // TDx_Play::OnReceive() event. // // This event indicates that DPMSG_CREATEPLAYERORGROUP has // been received by the component's event thread. // // DPMSG_CREATEPLAYERORGROUP is sent to all players when a // player or group is added to the session by // TDx_Play::CreateGroup(), TDx_Play::CreateGroupInGroup() // or TDx_Play::CreatePlayer(). // // If the component has created several players with // TDx_Play::CreatePlayer() then several events will be // triggered, one for each player. // ---------------------------------------------------------------------- __property TDx_OnCreatePlayerOrGroup OnCreatePlayerOrGroup = {read=FOnCreatePlayerOrGroup, write=FOnCreatePlayerOrGroup, nodefault}; // ---------------------------------------------------------------------- // Event: OnDeleteGroupFromGroup() // Description: The OnDeleteGroupFromGroup event is triggered when using // the TDx_Play::ReceiveEx() method in the // TDx_Play::OnReceive() event. // // This event indicates that DPMSG_DELETEGROUPFROMGROUP has // been received by the component's event thread. // // DPMSG_DELETEGROUPFROMGROUP is sent to all players when a // group is removed from a group by // TDx_Play::DeleteGroupFromGroup(). // // If the component has created several players with // TDx_Play::CreatePlayer() then several events will be // triggered, one for each player. // ---------------------------------------------------------------------- __property TDx_OnDeleteGroupFromGroup OnDeleteGroupFromGroup = {read=FOnDeleteGroupFromGroup, write=FOnDeleteGroupFromGroup, nodefault}; // ---------------------------------------------------------------------- // Event: OnDeletePlayerFromGroup() // Description: The OnDeletePlayerFromGroup event is triggered when using // the TDx_Play::ReceiveEx() method in the // TDx_Play::OnReceive() event. // // This event indicates that DPMSG_DELETEPLAYERFROMGROUP has // been received by the component's event thread. // // DPMSG_DELETEPLAYERFROMGROUP is sent to all local players // when a player is removed from a group directly by // TDx_Play::DeletePlayerFromGroup() or indirectly via // TDx_Play::DestroyPlayer(), TDx_Play::DestroyGroup() or // TDx_Play::Close(). // // If the component has created several players with // TDx_Play::CreatePlayer() then several events will be // triggered, one for each player. // ---------------------------------------------------------------------- __property TDx_OnDeletePlayerFromGroup OnDeletePlayerFromGroup = {read=FOnDeletePlayerFromGroup, write=FOnDeletePlayerFromGroup, nodefault}; // ---------------------------------------------------------------------- // Event: OnDestroy() // Description: The OnDestroy() event is triggered by the // TDx_Play::Destroy() method, just before the TDx_Play // internal LPDIRECTPLAY4 interface is destroyed. // // Note: This event is an ideal place to place code that // reverses the results of the TDx_Play::OnCreate() event. // For example, assume you have already setup the // TDx_Play::OnCreate() event to retrieve the component's // capabilities, Create() a dependant component and allocate // some memory; // You can then fully automate and insulate your code on a // per-component basis by placing code in the // TDx_Play::OnDestroy() event to deallocate memory, // Destroy() the dependant components and, when required, // destroy the capabilities component. // ---------------------------------------------------------------------- __property TDx_Event OnDestroy = {read=FOnDestroy, write=FOnDestroy, nodefault}; // ---------------------------------------------------------------------- // Event: OnDestroyPlayerOrGroup() // Description: The OnDestroyPlayerOrGroup event is triggered when using // the TDx_Play::ReceiveEx() method in the // TDx_Play::OnReceive() event. This event indicates that // DPMSG_DESTROYPLAYERORGROUP has been received by the // component's event thread. // // DPMSG_DESTROYPLAYERORGROUP is sent to all players when a // player or group is explicitly destroyed by // TDx_Play::DestroyGroup() or TDx_Play::DestroyPlayer() or // implicitly by TDx_Play::Close(). // // If the component has created several players with // TDx_Play::CreatePlayer() then several events will be // triggered, one for each player. // ---------------------------------------------------------------------- __property TDx_OnDestroyPlayerOrGroup OnDestroyPlayerOrGroup = {read=FOnDestroyPlayerOrGroup, write=FOnDestroyPlayerOrGroup, nodefault}; // ---------------------------------------------------------------------- // Event: OnError() // Description: The OnError event is called when an error occurs in the // TDx_Play component. // ---------------------------------------------------------------------- __property TDx_Error OnError = {read=FOnError, write=FOnError, nodefault}; // ---------------------------------------------------------------------- // Event: OnGeneric() // Description: The OnGeneric event is triggered when using the // TDx_Play::ReceiveEx() method in the TDx_Play::OnReceive() // event. This event indicates that a non-system message // has been received by the component's event thread. // // These are messages sent using TDx_Play::Send() or // TDx_SendEx() that have a From identifier other than // DPID_SYSMSG. // ---------------------------------------------------------------------- __property TDx_OnGeneric OnGeneric = {read=FOnGeneric, write=FOnGeneric, nodefault}; // ---------------------------------------------------------------------- // Event: OnHost() // Description: The OnHost event is triggered when using the // TDx_Play::ReceiveEx() method in the TDx_Play::OnReceive() // event. // // This event indicates that DPMSG_HOST has been received by // the component's event thread. // // DPMSG_HOST is sent to all players on the new session host // when the old session host leaves the session. // // If the component has created several players with // TDx_Play::CreatePlayer() then several events will be // triggered, one for each player. // ---------------------------------------------------------------------- __property TDx_OnHost OnHost = {read=FOnHost, write=FOnHost, nodefault}; // ---------------------------------------------------------------------- // Event: OnReceive() // Description: The OnReceive event is triggered by the components event // thread indicating an event has been signaled. // TDx_Play::Receive() or TDx_Play::ReceiveEx() should be // called to retrieve the message from DirectX for // processing. // ---------------------------------------------------------------------- __property TDx_OnDPReceive OnReceive = {read=FOnReceive, write=FOnReceive, nodefault}; // ---------------------------------------------------------------------- // Event: OnSecureMessage() // Description: The OnAddPlayeOnSecureMessage event is triggered when // using the TDx_Play::ReceiveEx() method in the // TDx_Play::OnReceive() event. // // This event indicates that DPMSG_SECUREMESSAGE has been // received by the component's event thread. // // DPMSG_SECUREMESSAGE is sent when a signed or encrypted // message is specified by TDx_Play::Send() or // TDx_Play::SendEx(). // ---------------------------------------------------------------------- __property TDx_OnSecureMessage OnSecureMessage = {read=FOnSecureMessage, write=FOnSecureMessage, nodefault}; // ---------------------------------------------------------------------- // Event: OnSendComplete() // Description: The OnSendComplete event is triggered when using the // TDx_Play::ReceiveEx() method in the TDx_Play::OnReceive() // event. // // This event indicates that DPMSG_SENDCOMPLETE has been // received by the component's event thread. // // DPMSG_SENDCOMPLETE is sent when messages are being sent // asynchronously using TDx_Play::SendEx() and the message // is successfully sent or cancelled using // TDx_Play::CancelMessage() or TDx_Play::CancelPriority(). // ---------------------------------------------------------------------- __property TDx_OnSendComplete OnSendComplete = {read=FOnSendComplete, write=FOnSendComplete, nodefault}; // ---------------------------------------------------------------------- // Event: OnSessionLost() // Description: The OnSessionLost event is triggered when using the // TDx_Play::ReceiveEx() method in the TDx_Play::OnReceive() // event. // // This event indicates that DPMSG_SESSIONLOST has been // received by the component's event thread. // // DPMSG_SESSIONLOST is sent to all players when connection // to all other players in the session is lost. // // If the component has created several players with // TDx_Play::CreatePlayer() then several events will be // triggered, one for each player. // ---------------------------------------------------------------------- __property TDx_OnSessionLost OnSessionLost = {read=FOnSessionLost, write=FOnSessionLost, nodefault}; // ---------------------------------------------------------------------- // Event: OnSetGroupOwner() // Description: The OnSetGroupOwner event is triggered when using the // TDx_Play::ReceiveEx() method in the TDx_Play::OnReceive() // event. // // This event indicates that DPMSG_SETGROUPOWNER has been // received by the component's event thread. // // DPMSG_SETGROUPOWNER is sent when group ownership is // changed explicitly by TDx_Play::SetGroupOwner() or // implicitly by the lobby server or when the existing owner // leaves the session. // // If the component has created several players with // TDx_Play::CreatePlayer() then several events will be // triggered, one for each player. // ---------------------------------------------------------------------- __property TDx_OnSetGroupOwner OnSetGroupOwner = {read=FOnSetGroupOwner, write=FOnSetGroupOwner, nodefault}; // ---------------------------------------------------------------------- // Event: OnSetPlayerOrGroupData() // Description: The OnSetPlayerOrGroupData event is triggered when using // the TDx_Play::ReceiveEx() method in the // TDx_Play::OnReceive() event. // // This event indicates that DPMSG_ADDGROUPTOGROUP has been // received by the component's event thread. // // DPMSG_ADDGROUPTOGROUP is sent to all players when the // remote data of a player or group is changed by // TDx_Play::SetGroupData() or TDx_Play::SetPlayerData(). // // If the component has created several players with // TDx_Play::CreatePlayer() then several events will be // triggered, one for each player. // ---------------------------------------------------------------------- __property TDx_OnSetPlayerOrGroupData OnSetPlayerOrGroupData = {read=FOnSetPlayerOrGroupData, write=FOnSetPlayerOrGroupData, nodefault}; // ---------------------------------------------------------------------- // Event: OnSetPlayerOrGroupName() // Description: The OnAddPlayerToGroup event is triggered when using the // TDx_Play::ReceiveEx() method in the TDx_Play::OnReceive() // event. // // This event indicates that DPMSG_SETPLAYERORGROUPNAME has // been received by the component's event thread. // // DPMSG_SETPLAYERORGROUPNAME is sent to all players when // the name of a player or group is changed by // TDx_Play::SetGroupName() or TDx_Play::SetPlayerName(). // // If the component has created several players with // TDx_Play::CreatePlayer() then several events will be // triggered, one for each player. // ---------------------------------------------------------------------- __property TDx_OnSetPlayerOrGroupName OnSetPlayerOrGroupName = {read=FOnSetPlayerOrGroupName, write=FOnSetPlayerOrGroupName, nodefault}; // ---------------------------------------------------------------------- // Event: OnSetSessionDesc() // Description: The SetSessionDesc event is triggered when using the // TDx_Play::ReceiveEx() method in the TDx_Play::OnReceive() // event. // // This event indicates that DPMSG_SETSESSIONDESC has been // received by the component's event thread. // // DPMSG_SETSESSIONDESC is sent when the session description // is changed by TDx_Play::SetSessionDesc(). // // If the component has created several players with // TDx_Play::CreatePlayer() then several events will be // triggered, one for each player. // ---------------------------------------------------------------------- __property TDx_OnSetSessionDesc OnSetSessionDesc = {read=FOnSetSessionDesc, write=FOnSetSessionDesc, nodefault}; // ---------------------------------------------------------------------- // Event: OnStartSession() // Description: The OnStartSession event is triggered when using the // TDx_Play::ReceiveEx() method in the TDx_Play::OnReceive() // event. // // This event indicates that DPMSG_STARTSESSION has been // received by the component's event thread. // // DPMSG_STARTSESSION is sent to all players in a staging // area group when a session is started from the group with // TDx_Play::StartSession(). // // If the component has created several players with // TDx_Play::CreatePlayer() then several events will be // triggered, one for each player. // ---------------------------------------------------------------------- __property TDx_OnStartSession OnStartSession = {read=FOnStartSession, write=FOnStartSession, nodefault}; // ---------------------------------------------------------------------- // Callback: OnEnumConnections() // Description: The OnEnumConnections callback event is called for every // connection enumerated by TDx_Play::EnumConnections(). // // Set Continue to true to continue enumeration (default // value) or false to halt the enumeration process. // ---------------------------------------------------------------------- __property TDx_EnumConnections OnEnumConnections = {read=FOnEnumConnections, write=FOnEnumConnections, nodefault}; // ---------------------------------------------------------------------- // Callback: OnEnumGroupPlayers() // Description: This callback method is called for every player // enumerated by theTDx_Play::EnumGroupPlayers method.Set // Continue true to continue enumeration (default value), // false to stop enumeration. // ---------------------------------------------------------------------- __property TDx_EnumGroupPlayers OnEnumGroupPlayers = {read=FOnEnumGroupPlayers, write=FOnEnumGroupPlayers, nodefault}; // ---------------------------------------------------------------------- // Callback: OnEnumGroups() // Description: This callback method is called for every group enumerated // by the TDx_Play::EnumGroups method.Set Continue true to // continue enumeration (default value), false to stop // enumeration. // ---------------------------------------------------------------------- __property TDx_EnumGroups OnEnumGroups = {read=FOnEnumGroups, write=FOnEnumGroups, nodefault}; // ---------------------------------------------------------------------- // Callback: OnEnumGroupsInGroup() // Description: This callback method is called for every group enumerated // by the TDx_Play::EnumGroupsInGroup method.Set Continue // true to continue enumeration (default value), false to // stop enumeration. // ---------------------------------------------------------------------- __property TDx_EnumGroupsInGroup OnEnumGroupsInGroup = {read=FOnEnumGroupsInGroup, write=FOnEnumGroupsInGroup, nodefault}; // ---------------------------------------------------------------------- // Callback: OnEnumPlayers() // Description: The OnEnumPlayers callback event is called for every // player enumerated by TDx_Play::EnumPlayers(). // // Set Continue to true to continue enumeration (default // value) or false to halt the enumeration process. // ---------------------------------------------------------------------- __property TDx_EnumPlayers OnEnumPlayers = {read=FOnEnumPlayers, write=FOnEnumPlayers, nodefault}; // ---------------------------------------------------------------------- // Callback: OnEnumSessions() // Description: This callback is called for every session enumerated by // the TDx_Play::EnumSessions method. Set Continue true to // continue enumeration (default value), false to stop // enumeration. // ---------------------------------------------------------------------- __property TDx_EnumSessions OnEnumSessions = {read=FOnEnumSessions, write=FOnEnumSessions, nodefault}; // ========================================================================== public: // ========================================================================== // ---------------------------------------------------------------------- // Property: Created // Description: The Created property is true if the internal // LPDIRECTPLAY4 used in this component has been // successfully created, otherwise Created is false. // // To create the internal LPDIRECTPLAY4, call the // TDx_Play::Create() method. // ---------------------------------------------------------------------- __property bool Created = { read=FGetCreated, write=FSetCreated, default=false }; // ---------------------------------------------------------------------- // Property: ErrorValue // Description: The ErrorValue property contains the last error value // returned from a call to a TDx_Play method or fget/fset. // eg. DP_OK or DDERR_SURFACELOST or TDX_ERROR // ---------------------------------------------------------------------- __property HRESULT ErrorValue = { read=FGetErrorValue, write=FSetErrorValue, default=DP_OK }; // ---------------------------------------------------------------------- // Property: PlayerEvents // Description: The PlayerEvents property references a windows event list // that is used internally by the TDx_Play and // TDx_Play_ThreadClass. // ---------------------------------------------------------------------- __property TList* PlayerEvents = { read=FGetPlayerEvents, default=NULL }; // ---------------------------------------------------------------------- // Property: PlayerIDs // Description: The PlayerIDs property references the player ID's // belonging to this component. // ---------------------------------------------------------------------- __property TList* PlayerIDs = { read=FGetPlayerIDs, nodefault }; // ---------------------------------------------------------------------- // Method: AddGroupToGroup() // Description: The AddGroupToGroup method will add a shortcut to another // group within an existing group. // // TDx_Play::EnumGroupsInGroup() can be used to enumerate // linked groups, and a group may be linked to multiple // other groups. // TDx_Play::DeleteGroupFromGroup() can be used to remove an // existing group link. // // A DPMSG_ADDGROUPTOGROUP system message will inform // players of the change. // // Error values that can be generated are: // // DPERR_ACCESSDENIED // DPERR_CONNECTIONLOST // DPERR_INVALIDGROUP // Params: pParentGroup - // The ParentGroup parameter identifies the group to which // the link is to be added. // pGroup - // The Group parameter identifies the group whose link is to // be added to the ParentGroup. // ---------------------------------------------------------------------- virtual bool __fastcall AddGroupToGroup( DPID pParentGroup, DPID pGroup ); // ---------------------------------------------------------------------- // Method: AddPlayerToGroup() // Description: The AddPlayerToGroup method will add a player to an // existing group. // // Players may be present within multiple groups and any // player may be added to any group. // // A DPMSG_ADDPLAYERTOGROUP system message will inform other // players of the change. // // Error values that can be generated are: // // DPERR_CANTADDPLAYER // DPERR_CONNECTIONLOST // DPERR_INVALIDGROUP // DPERR_INVALIDPLAYER // DPERR_NOSESSIONS // Params: pGroup - // The Group parameter identifies the group to which the // player is to be added. // pPlayer - // The Player parameter identifies the player to be added to // the Group. // ---------------------------------------------------------------------- virtual bool __fastcall AddPlayerToGroup( DPID pGroup, DPID pPlayer ); // ---------------------------------------------------------------------- // Method: CancelMessage() // Description: The CancelMessage method is used to cancel asynchronous // messages from the send queue. // // Specific messages can be cancelled by specifying the ID // assigned to them by TDx_Play::SendEx(). // Partially sent messages cannot be cancelled, a group // message that has already been sent to at least one group // member is regarded to be partially sent. // // A DPMSG_SENDCOMPLETE system message is generated to // indicate successful cancellation. // // Error values that can be generated are: // // DPERR_CANCELFAILED // DPERR_INVALIDFLAGS // DPERR_INVALIDPARAMS // DPERR_UNKNOWNMESSAGE // DPERR_UNSUPPORTED // Params: pMsgID - // The MsgID identifies the message to be cancelled. // // Set zero to cancel all pending messages. // ---------------------------------------------------------------------- virtual bool __fastcall CancelMessage( dword pMsgID ); // ---------------------------------------------------------------------- // Method: CancelPriority() // Description: The CancelPriority method is used to cancel asynchronous // messages within a specified priority range from the send // queue. // // Partially sent messages cannot be cancelled, a group // message that has already been sent to at least one group // member is regarded to be partially sent. // // A DPMSG_SENDCOMPLETE system message will be generated for // cancelled messages, indicating successful cancellation. // // Error values that can be generated are: // // DPERR_INVALIDFLAGS // DPERR_INVALIDPARAMS // DPERR_UNSUPPORTED // Params: pMinPriority - // The MinPriority defines the lowest message priority that // is to be cancelled. // pMaxPriority - // The MaxPriority defines the highest message priority that // is to be cancelled. // // Must be higher than MinPriority. // Set MAXPRIORITY to specify the maximum possible value. // ---------------------------------------------------------------------- virtual bool __fastcall CancelPriority( dword pMinPriority, dword pMaxPriority ); // ---------------------------------------------------------------------- // Method: Close() // Description: The Close method will close a previosly created session. // // Ownership of locally created groups is migrated to the // session host and locally created players will be // destroyed. // // DPMSG_DELETEPLAYERFROMGROUP and // DPMSG_DESTROYPLAYERORGROUP system messages will be sent // as appropriate to inform other session participants of // the changes. // // Error values that can be generated are: // // DPERR_INVALIDOBJECT // DPERR_INVALIDPARAMS // DPERR_NOSESSIONS // ---------------------------------------------------------------------- virtual bool __fastcall Close(); // ---------------------------------------------------------------------- // Method: Create() // Description: The Create() method is used to automatically create the // internal LPDIRECTPLAY4 interface used in the TDx_Play // component and must be called before any methods of the // TDx_Play component will function. // ---------------------------------------------------------------------- virtual bool __fastcall Create(); // ---------------------------------------------------------------------- // Method: CreateGroup() // Description: The CreateGroup method will create a group within the // session. // // For a client server session, no group notification // messages are sent and groups are only visible on the // machine that created them. // For a peer to peer session, CreateGroup generates a // DPMSG_CREATEPLAYERORGROUP message notifying players of // the change. TDx_Play::Send() can then send messages to // all group members by sending a message to the group ID. // // Groups created with this method are the top level groups // within the session and can be enumerated by // TDx_Play::EnumGroups(). To create subgroups // TDx_Play::CreateGroupInGroup() must be used. // // The creating player is the owner and only they may change // the group properties, but any player may add or remove // members or delete the group. // // If the creating player leaves the session, ownership is // migrated to the host, and a group will persist within the // session until it is explicitly destroyed. // // Error values that can be generated are: // // DPERR_CANTADDPLAYER // DPERR_CONNECTIONLOST // DPERR_INVALIDFLAGS // DPERR_INVALIDPARAMS // Params: pGroup - // The Group parameter will reference the new groups ID if // this method returns successfully. // pGroupName - // The GroupName parameter references a TDPName component // holding the name for the new group. // // The name is assigned and used by the application, it need // not be unique and NULL can be set if no group name is // required. // pData - // The Data parameter references data to be propagated once // the group is created as if TDx_Play::SetGroupData() had // been called. // // The data is application defined and this parameter may be // set to NULL if no initial data is needed. // pDataSize - // The DataSize parameter defines the size, in bytes, of the // data referenced by the Data parameter. // pFlags - // The Flags parameter defines flags indicating the group // type to be created. // The described effect applies when the flag is set. // // Setting zero (the default) will result in a group that // migrates to the session host if its owner leaves the // session and the group must be explicitly destroyed. // Flags: // DPGROUP_HIDDEN - // The group being created will only be enumerated // when DPENUMGROUPS_HIDDEN is set in the // TDx_Play::EnumGroups() Flags parameter. // // For lobby sessions, the group will only be // available via TDx_Play::AddGroupToGroup() links. // Basically this flag is very similar to the // DPPLAYER_SPECTATOR flag for players. // DPGROUP_STAGINGAREA - // The group being created is a staging area. // ---------------------------------------------------------------------- virtual bool __fastcall CreateGroup( DPID* pGroup, TDPName* pGroupName, void* pData, dword pDataSize, dword pFlags ); // ---------------------------------------------------------------------- // Method: CreateGroupInGroup() // Description: The CreateGroupInGroup method will create a group within // an existing group. // // For a client server session, no group notification // messages are sent and groups are only visible on the // machine that created them. // For a peer to peer session, CreateGroupInGroup generates // a DPMSG_CREATEPLAYERORGROUP message notifying players of // the change. TDx_Play::Send() can then send messages to // all group members by sending a message to the group ID. // // Groups created with this method can only be enumerated by // TDx_Play::EnumGroupsInGroup() and destroyed using // TDx_Play::DestroyGroup(). // // When a parent group is destroyed, all member groups are // also destroyed and appropriate destruction messages // generated. // // Error values that can be generated are: // // DPERR_CANTADDPLAYER // DPERR_CONNECTIONLOST // DPERR_INVALIDFLAGS // DPERR_INVALIDGROUP // DPERR_INVALIDPARAMS // Params: pParentGroup - // The ParentGroup parameter identifies the parent group for // the new group. // pGroup - // The Group parameter will reference the new groups ID if // this method returns successfully. // pGroupName - // The GroupName parameter references a TDPName component // holding the name for the new group. // // The name is assigned and used by the application, it need // not be unique and NULL can be set if no group name is // required. // pData - // The Data parameter references data to be propagated once // the group is created as if TDx_Play::SetGroupData() had // been called. // // The data is application defined and this parameter may be // set to NULL if no initial data is needed. // pDataSize - // The DataSize parameter defines the size, in bytes, of the // data referenced by the Data parameter. // pFlags - // The Flags parameter defines flags indicating the group // type to be created. // The described effect applies when the flag is set. // // Setting zero will result in a normal, default, group. // Flags: // DPGROUP_HIDDEN - // The group being created will only be enumerated // when DPENUMGROUPS_HIDDEN is set in the // TDx_Play::EnumGroupInGroup() Flags parameter. // // For lobby sessions, the group will only be // available via TDx_Play::AddGroupToGroup() links. // Basically this flag is very similar to the // DPPLAYER_SPECTATOR flag for players. // DPGROUP_STAGINGAREA - // The group being created is a staging area. // ---------------------------------------------------------------------- virtual bool __fastcall CreateGroupInGroup( DPID pParentGroup, DPID* pGroup, TDPName* pGroupName, void* pData, dword pDataSize, dword pFlags ); // ---------------------------------------------------------------------- // Method: CreatePlayer() // Description: The CreatePlayer method will create a local player within // the session. // // CreatePlayer will generate a DPMSG_CREATEPLAYERORGROUP // message informing other players in the session about the // new player. // // Only the creating application may send messages for the // player or change the players name and data. // // TDx_Play::DestroyPlayer() may be used by the creating // application or session host to destroy a player. All // local players will be automatically destroyed if the // session is closed. // // Error values that can be generated are: // // DPERR_CANTADDPLAYER // DPERR_CANTCREATEPLAYER // DPERR_CONNECTIONLOST // DPERR_INVALIDFLAGS // DPERR_INVALIDPARAMS // DPERR_NOCONNECTION // Params: pPlayer - // The Player parameter will reference the new players ID if // this method returns successfully. // pPlayerName - // The PlayerName parameter references a TDPName component // holding the new players name. // // The name is assigned and used by the application, it need // not be unique and NULL can be set if no player name is // required. // pData - // The Data parameter references data to be propagated once // the player is created as if TDx_Play::SetPlayerData() had // been called. // // The data is application defined and this parameter may be // set to NULL if no initial data is needed. // pDataSize - // The DataSize parameter defines the size, in bytes, of the // data referenced by the Data parameter. // pFlags - // The Flags parameter defines flags indicating the player // type to be created. // The described effect applies when the flag is set. // // Setting zero will result in a nonspectator, nonserver // player. // Flags: // DPPLAYER_SERVERPLAYER - // The player is to be the server player in a client // server session. // // Only one server player may exist per session and it // must be created by the host. // // The player ID will always be DPID_SERVERPLAYER when // this flag is set. // DPPLAYER_SPECTATOR - // The player is designated a spectator player. // // The application must define spectator behaviour, // the player behaves normally other than having this // flag set. // ---------------------------------------------------------------------- virtual bool __fastcall CreatePlayer( DPID* pPlayer, TDPName* pPlayerName, void* pData, dword pDataSize, dword pFlags ); // ---------------------------------------------------------------------- // Method: DeleteGroupFromGroup() // Description: The DeleteGroupFromGroup method will remove a specified // group link from its parent group // // These links are added using TDx_Play::AddGroupToGroup() // Only the link is deleted, the group itself is not // destroyed. // // A DPMSG_DELETEGROUPFROMGROUP system message informing // players of the change will be generated. // // Error values that can be generated are: // // DPERR_ACCESSDENIED // DPERR_CONNECTIONLOST // DPERR_INVALIDGROUP // Params: pParentGroup - // The ParentGroup parameter identifies the group from which // the link is to be removed. // pGroup - // The Group parameter identifies the group whose link is to // be removed. // ---------------------------------------------------------------------- virtual bool __fastcall DeleteGroupFromGroup( DPID pParentGroup, DPID pGroup ); // ---------------------------------------------------------------------- // Method: DeletePlayerFromGroup() // Description: The DeletePlayerFromGroup method will remove a player // from a group. // // A player may delete any another from a group. // // A DPMSG_DELETEPLAYERFROMGROUP system message informing // players of the change will be generated. // // Error values that can be generated are: // // DPERR_CONNECTIONLOST // DPERR_INVALIDGROUP // DPERR_INVALIDOBJECT // DPERR_INVALIDPLAYER // Params: pGroup - // The Group parameter identifies the group from which the // player is to be removed. // pPlayer - // The Player parameter identifies the player that is to be // removed. // ---------------------------------------------------------------------- virtual bool __fastcall DeletePlayerFromGroup( DPID pGroup, DPID pPlayer ); // ---------------------------------------------------------------------- // Method: Destroy() // Description: The Destroy() method is used to automatically destroy the // internal LPDIRECTPLAY4 interface used in the TDx_Play // component and should be called when the internal // interface is no longer required. // // Note: This method is called by the component's // destructor. // ---------------------------------------------------------------------- virtual bool __fastcall Destroy(); // ---------------------------------------------------------------------- // Method: DestroyGroup() // Description: The DestroyGroup method will destroy a specified group // within the session. // // The group ID will not be reused during the session. // // Any application can destroy any group. // Players belonging to the group are removed but not // destroyed. // // Each player in the group will be sent a // DPMSG_DELETEPLAYERFROMGROUP and a // DPMSG_DESTROYPLAYERORGROUP system message indicating the // change. // // Error values that can be generated are: // // DPERR_CONNECTIONLOST // DPERR_INVALIDGROUP // DPERR_INVALIDOBJECT // DPERR_INVALIDPARAMS // DPERR_INVALIDPLAYER // Params: pGroup - // The Group parameter identifies the group to be destroyed. // ---------------------------------------------------------------------- virtual bool __fastcall DestroyGroup( DPID pGroup ); // ---------------------------------------------------------------------- // Method: DestroyPlayer() // Description: The DestroyPlayer method will destroy a specified player // within the session. // // The player is removed from any groups, and all messages // for the player are removed from the queue. // Any messages in the players asynchronous queue must be // cancelled or sent prior to this method call. // The player ID will not be reused during the session. // // The player is usually only destroyed by the creating // application, but the the session host may destroy any // player in the session. // // A DPMSG_DELETEPLAYERFROMGROUP message is generated for // each group the player was in, followed by a // DPMSG_DESTROYPLAYERORGROUP message. // // Error values that can be generated are: // // DPERR_ACCESSDENIED // DPERR_CONNECTIONLOST // DPERR_INVALIDOBJECT // DPERR_INVALIDPLAYER // DPERR_UNAVAILABLE // Params: pPlayer - // The Player parameter identifies the player to be // destroyed. // ---------------------------------------------------------------------- virtual bool __fastcall DestroyPlayer( DPID pPlayer ); // ---------------------------------------------------------------------- // Method: EnumConnections() // Description: The EnumConnections method will enumerate available // registered service and lobby providers. // // The order of enumeration is indeterminate and the // TDx_Play::OnEnumConnections() event will be called for // each connection enumerated. // // Some enumerated providers may not be available for use, // check the TDx_Play::InitializeConnection() return values // to be sure, an error will be returned if the connection // is unavailable. // For example, a modem service provider would still be // enumerated even if the modem is not attached to the // system. // // Error values that can be generated are: // // DPERR_CONNECTIONLOST // DPERR_INVALIDFLAGS // DPERR_INVALIDPARAMS // Params: pApplication - // The Application parameter references the application // identifier. // // Setting NULL results in all connections being enumerated, // otherwise only connections usable by the specified // application will be enumerated. // pContext - // The Context parameter references application defined data // to be passed to the callback function for each // enumeration. // pFlags - // The Flags parameter defines flags indicating the // connection types that are to be enumerated. // The described effect applies when the flag is set. // // The default setting of zero gives the same results as // DPCONNECTION_DIRECTPLAY. // Flags: // DPCONNECTION_DIRECTPLAY - // DirectPlay service providers for communicating // within application sessions are to be enumerated. // DPCONNECTION_DIRECTPLAYLOBBY - // DirectPlayLobby providers for communicating with // lobby servers are to be enumerated. // ---------------------------------------------------------------------- virtual bool __fastcall EnumConnections( const GUID* pApplication, void* pContext, dword pFlags ); // ---------------------------------------------------------------------- // Method: EnumGroupPlayers() // Description: The EnumGroupPlayers method will enumerate players // belonging to the specified group of an open session. // // Remote sessions that are not password protected can have // their players enumerated by using the // DPENUMPLAYERS_SESSION flag and specifying the GUID of the // remote session when there is no session open, but the // enumeration call must occur after // TDx_Play::EnumSessions() and before calling // TDx_Play::Open() or TDx_Play::Close(). // // The TDx_Play::OnEnumGroupPlayers() event will be called // for each player enumerated. // // To enumerate players in a lobby session, you must be // connected to it. // // Error values that can be generated are: // // DPERR_ACCESSDENIED // DPERR_CONNECTIONLOST // DPERR_INVALIDPARAMS // DPERR_INVALIDGROUP // DPERR_NOSESSIONS // DPERR_UNAVAILABLE // Params: pGroup - // The Group parameter identifies the group for which the // players are to be enumerated. // pInstance - // The Instance parameter references the identifier of the // session to be enumerated. // // Ignored unless DPENUMPLAYERS_SESSION flag is set. // These GUIDs are obtained using TDx_Play::EnumSessions(). // pContext - // The Context parameter references application defined data // to be passed to the callback function for each player // enumerated. // pFlags - // The Flags parameter defines flags indicating how to // perform the enumeration. // The described effect applies when the flag is set. // // The default setting of zero results in the enumeration of // the players within a group in the current session. // Only players meeting all of the specified criteria will // be enumerated. // Flags: // DPENUMPLAYERS_LOCAL - // Only enumerate locally created players. // DPENUMPLAYERS_OWNER - // Only enumerate the group owner. // DPENUMPLAYERS_REMOTE - // Only enumerate remotely created players. // DPENUMPLAYERS_SERVERPLAYER - // Only enumerate the server player. // DPENUMPLAYERS_SESSION - // Enumerate the players of the session identified by // the Instance parameter. // Only usable when there is no session open and the // target session is not a lobby session. // DPENUMPLAYERS_SPECTATOR - // Only enumerate spectator players. // ---------------------------------------------------------------------- virtual bool __fastcall EnumGroupPlayers( DPID pGroup, GUID* pInstance, void* pContext, dword pFlags ); // ---------------------------------------------------------------------- // Method: EnumGroups() // Description: The EnumGroups method will enumerate the top level groups // of the session. // // Remote sessions that are not password protected can have // their groups enumerated by using the DPENUMGROUPS_SESSION // flag and specifying the GUID of the remote session when // there is no session open. // // To enumerate groups in a lobby session, you must be // connected to it. // // The TDx_Play::OnEnumGroups() event will be called for // each group enumerated. // // Error values that can be generated are: // // DPERR_ACCESSDENIED // DPERR_CONNECTIONLOST // DPERR_INVALIDPARAMS // DPERR_INVALIDGROUP // DPERR_NOSESSIONS // DPERR_UNAVAILABLE // Params: pInstance - // The Instance parameter references the identifier of the // session whose groups are to be enumerated. // // Setting NULL will result in the current sessions groups // being enumerated. // // There must not be an open session and the // DPENUMGROUPS_SESSION flag must be set to use this // parameter. // // Session GUIDs are obtained by TDx_Play::EnumSessions(). // pContext - // The Context parameter references application defined data // to be passed to the callback function for each group // enumerated. // pFlags - // The Flags parameter defines flags indicating how to // perform the enumeration. // The described effect applies when the flag is set. // // The default setting of zero results in the enumeration of // all groups in the current active session. // Only groups meeting all of the specified criteria will be // enumerated. // Flags: // DPENUMGROUPS_ALL - // Enumerate all the groups in the session. // DPENUMGROUPS_HIDDEN - // Only enumerate available hidden groups. // DPENUMGROUPS_LOCAL - // Only enumerate locally created groups. // DPENUMGROUPS_REMOTE - // Only enumerate remotely created groups. // DPENUMGROUPS_SESSION - // Enumerate the groups of the session identified by // the Instance parameter. // Only usable when there is no session open and the // target session is not a lobby session. // DPENUMGROUPS_STAGINGAREA - // Only enumerate staging area groups. // ---------------------------------------------------------------------- virtual bool __fastcall EnumGroups( GUID* pInstance, void* pContext, dword pFlags ); // ---------------------------------------------------------------------- // Method: EnumGroupsInGroup() // Description: The EnumGroupsInGroup method will enumerate groups and // group links contained within the specified group. // // Only the contents of the specified group will be // enumerated, not the groups it contains. // // Remote sessions that are not password protected can have // their groups enumerated by using the DPENUMGROUPS_SESSION // flag and specifying the GUID of the remote session when // there is no session open. // // To enumerate groups in a lobby session, you must be // connected to it. // // The TDx_Play::OnEnumGroupsInGroup() event will be called // for each group enumerated. // // Error values that can be generated are: // // DPERR_CONNECTIONLOST // DPERR_INVALIDFLAGS // DPERR_INVALIDGROUP // DPERR_INVALIDPARAMS // DPERR_NOSESSIONS // DPERR_UNSUPPORTED // Params: pGroup - // The Group parameter identifies the group whose subgroups // are to be enumerated. // pInstance - // The Instance parameter references the identifier of the // session whose group is to be enumerated. // // The DPENUMGROUPS_SESSION flag must be set to use this // parameter. // // Session GUIDs are obtained by TDx_Play::EnumSessions(). // pContext - // The Context parameter references application defined data // to be passed to the callback function for each group // enumerated. // pFlags - // The Flags parameter defines flags indicating how to // perform the enumeration. // The described effect applies when the flag is set. // // The default setting of zero results in the enumeration of // all groups in the specified group. // Only groups meeting all of the specified criteria will be // enumerated. // Flags: // DPENUMGROUPS_ALL - // Enumerate all groups within the specified group. // DPENUMGROUPS_HIDDEN - // Only enumerate hidden groups within the specified // group. // DPENUMGROUPS_LOCAL - // Only enumerate locally created groups within the // specified group. // DPENUMGROUPS_REMOTE - // Only enumerate remotely created groups within the // specified group. // DPENUMGROUPS_SESSION - // Enumerate the specified group in the session // identified by the Instance parameter. // Only usable when there is no session open and the // target session is not a lobby session. // DPENUMGROUPS_SHORTCUT - // Only enumerate only the linked groups within the // specified group. // DPENUMGROUPS_STAGINGAREA - // Only enumerate staging area groups within the // specified group. // ---------------------------------------------------------------------- virtual bool __fastcall EnumGroupsInGroup( DPID pGroup, GUID* pInstance, void* pContext, dword pFlags ); // ---------------------------------------------------------------------- // Method: EnumPlayers() // Description: The EnumPlayers method will enumerate players in the // session. // // Remote sessions that are not password protected can have // their players enumerated by using the // DPENUMPLAYERS_SESSION flag and specifying the GUID of the // remote session when there is no session open, but the // enumeration call must occur after // TDx_Play::EnumSessions() and before calling // TDx_Play::Open() or TDx_Play::Close(). // // The TDx_Play::OnEnumPlayers() event will be called for // each player enumerated. // // You cannot use this method in a lobby session or from // within TDx_Play::OnEnumSessions(). // // Error values that can be generated are: // // DPERR_ACCESSDENIED // DPERR_CONNECTIONLOST // DPERR_INVALIDPARAMS // DPERR_INVALIDGROUP // DPERR_NOSESSIONS // DPERR_UNAVAILABLE // Params: pInstance - // The Instance parameter references the identifier of the // session whose players are to be enumerated. // // The DPENUMPLAYERS_SESSION flag must be set to use this // parameter. // // Session GUIDs are obtained by TDx_Play::EnumSessions(). // pContext - // The Context parameter references application defined data // to be passed to the callback function for each player // enumerated. // pFlags - // The Flags parameter defines flags indicating how to // perform the enumeration. // The described effect applies when the flag is set. // // The default setting of zero results in the enumeration of // all players within the current session. // Only players meeting all of the specified criteria will // be enumerated. // Flags: // DPENUMPLAYERS_ALL - // Enumerate all players within the session. // DPENUMPLAYERS_GROUP - // Include groups in the enumeration. // DPENUMPLAYERS_LOCAL - // Only enumerate locally created players. // DPENUMPLAYERS_REMOTE - // Only enumerate remotely created players. // DPENUMPLAYERS_SERVERPLAYER - // Only enumerate the server player. // DPENUMPLAYERS_SESSION - // Enumerate the players of the session identified by // the Instance parameter. // Only usable when there is no session open and the // target session is not a lobby session. // DPENUMPLAYERS_SPECTATOR - // Only enumerate spectator players. // ---------------------------------------------------------------------- virtual bool __fastcall EnumPlayers( GUID* pInstance, void* pContext, dword pFlags ); // ---------------------------------------------------------------------- // Method: EnumSessions() // Description: The EnumSessions method will enumerate all active and/or // lobby sessions for a specified application. // // This method should not be called while a session is open. // The TDx_Play::OnEnumSessions() event will be called for // each session enumerated. // // When enumerating synchronously, the internal session // cache is cleared, the enumeration requests sent and the // application blocked until all replies have timed out or // been enumerated. // // When enumerating asychronously, all sessions in the // internal session cache are enumerated through the // callback and the method returns. Enumeration requests are // then sent automatically, the replies to which are used to // update, remove or add to the internal session cache. // Call EnumSessions asynchronously once more to obtain the // most recent session list. // Enumeration will be performed periodically without // further calls until TDx_Play::Open() or this method with // DPENUMSESSIONS_STOPASYNC set is called. // Asychronous enumeration must be halted before changing a // sessions description. // // Error values that can be generated are: // // DPERR_CONNECTING // DPERR_CONNECTIONLOST // DPERR_EXCEPTION // DPERR_GENERIC // DPERR_INVALIDOBJECT // DPERR_INVALIDPARAMS // DPERR_NOCONNECTION // DPERR_UNINITIALIZED // DPERR_USERCANCEL // Params: pSD - // The SD parameter references a TDPSessionDesc component // defining which sessions are to be enumerated. // // TDPSessionDesc::Application identifies which application // sessions should be retrieved. (GUID_NULL for all // sessions) and TDPSessionDesc::Password is used to // enumerated private sessions. // All other TDPSessionDesc properties are ignored. // pTimeout - // The Timeout parameter defines the time, in milliseconds, // to wait for enumeration request responses (for // synchronous) or how long to broadcast enumeration // requests (for asynchronous). // // Set zero to use the default time out defined by // TDPCaps::Timeout. // pContext - // The Context parameter references application defined data // to be passed to the callback function for each session // enumerated. // pFlags - // The Flags parameter defines flags indicating which // sessions are to be enumerated. // The described effect applies when the flag is set. // // The default value of zero is equivilent to // DPENUMSESSIONS_AVAILABLE. // Flags: // DPENUMSESSIONS_ALL - // Enumerate all currently active sessions. // // DPENUMSESSIONS_PASSWORDREQUIRED is still required // to enumerate password protected sessions. // DPENUMSESSIONS_AVAILABLE is assumed if this flag is // not set. // DPENUMSESSIONS_ASYNC - // Enumerate all sessions asychronously into a session // cache. // // The session cache will be updated until // DPENUMSESSIONS_STOPASYNC is set or TDx_Play::Open() // or IUnknown::Release() is called. // Enumeration is synchronous when this flag is not // set. // DPENUMSESSIONS_AVAILABLE - // Only enumerate those sessions currently accepting // new players. // // DPENUMSESSIONS_PASSWORDREQUIRED is still required // to enumerate password protected sessions. // DPENUMSESSIONS_PASSWORDREQUIRED - // Also enumerate password protected sessions. // DPENUMSESSIONS_RETURNSTATUS - // Do not display any connection status dialog boxes. // // // DDERR_CONNECTING will be returned if the connection // cannot be made immediately. // The application should call this method until DP_OK // or a different error code is returned. // DPENUMSESSIONS_STOPASYNC - // Enumerate all the sessions currently in the session // cache and halt the asynchronous enumeration // process. // ---------------------------------------------------------------------- virtual bool __fastcall EnumSessions( TDPSessionDesc* pSD, dword pTimeout, void* pContext, dword pFlags ); // ---------------------------------------------------------------------- // Method: GetCaps() // Description: The GetCaps method will retrieve the capabilities of the // current session. // // The session must be open before the supported aspects of // TDx_Play::SendEx() can be determined. // If the host has specified DPSESSION_DIRECTPLAYPROTOCOL in // TDPSessionDesc::Flags, then all TDx_Play::SendEx() // capabilities are available. // // Error values that can be generated are: // // DPERR_INVALIDOBJECT // DPERR_INVALIDPARAMS // Params: pDPCaps - // The DPCaps parameter references a TDPCaps component for // holding the session capabilities if this method returns // successfully. // pFlags - // The Flags parameter defines flags indicating the type of // message capabilities that are to be retrieved. // // The default setting of zero results in nonguaranteed // messaging capabilities being retrieved. // Flags: // DPGETCAPS_GUARANTEED - // Retrieve the guaranteed messaging capabilities for // the session. // ---------------------------------------------------------------------- virtual bool __fastcall GetCaps( TDPCaps* pDPCaps, dword pFlags ); // ---------------------------------------------------------------------- // Method: GetGroupConnectionSettings() // Description: The GetGroupConnectionSettings method will retrieve // connection settings from the TDPLConnection component // associated with the group. // // These settings are used in any session launched from the // group. // This method is only relevent to lobby session staging // area groups. // // If a session has been launched from this group, the // TDPSessionDesc::Instance property will not be GUID_NULL. // // Error values that can be generated are: // // DPERR_ACCESSDENIED // DPERR_BUFFERTOOSMALL // DPERR_INVALIDGROUP // DPERR_INVALIDFLAGS // DPERR_INVALIDPARAMS // DPERR_UNSUPPORTED // Params: pGroup - // The Group parameter identifies the group for which // connection settings are to be retrieved. // pData - // The Data parameter references a buffer for holding the // TDPLConnection information if this method returns // successfully. // // Set NULL to allocate appropriate memory to hold the data, // the DataSize parameter will be set to the size of the // TDPLConnection data. // // If previously allocated memory is used and the amount of // data to be returned is greater than the amount specified // by the DataSize initial value, the memory will be // released and replaced with the required memory block. // pDataSize - // The DataSize parameter references the size, in bytes, of // the Data buffer. // // This parameter will be set to the size of the data when // the method returns. // ---------------------------------------------------------------------- virtual bool __fastcall GetGroupConnectionSettings( DPID pGroup, void* pData, dword* pDataSize ); // ---------------------------------------------------------------------- // Method: GetGroupData() // Description: The GetGroupData method will retrieve application // specific data previously associated with the group by // TDx_Play::SetGroupData(). // // Local data is set by this TDx_Play component using // DPSET_LOCAL, while remote data may have been set by any // application in the session using DPSET_REMOTE. // // Error values that can be generated are: // // DPERR_BUFFERTOOSMALL // DPERR_INVALIDGROUP // DPERR_INVALIDOBJECT // DPERR_INVALIDPARAMS // DPERR_INVALIDPLAYER // Params: pGroup - // The Group parameter identifies the group for which data // is being requested. // pData - // The Data parameter references a buffer for holding the // retrieved data if this method returns successfully. // // Set NULL to allocate appropriate memory to hold the data, // the DataSize parameter will be set to the size of the // data. // // If previously allocated memory is used and the amount of // data to be returned is greater than the amount specified // by the DataSize initial value, the memory will be // released and replaced with the required memory block. // pDataSize - // The DataSize parameter references the size, in bytes, of // the Data buffer. // // This parameter will be set to the size of the data when // the method returns. // pFlags - // The Flags parameter defines flags indicating which data // type is to be retrieved. // The described effect applies when the flag is set. // // The default setting of zero is equivilent to // DPGET_REMOTE. // Flags: // DPGET_LOCAL - // The local data that was set by this application // will be retrieved. // DPGET_REMOTE - // The current data of the remote shared data space // will be retrieved. // ---------------------------------------------------------------------- virtual bool __fastcall GetGroupData( DPID pGroup, void* pData, dword* pDataSize, dword pFlags ); // ---------------------------------------------------------------------- // Method: GetGroupFlags() // Description: The GetGroupFlags method will retrieve a specified // group's descriptive flags. // // Error values that can be generated are: // // DPERR_INVALIDGROUP // DPERR_INVALIDPARAMS // Params: pGroup - // The Group parameter identifies the group for which the // flags are being retrieved. // pFlags - // The Flags parameter references the group flag settings if // this method returns successfully. // The described effect applies when the flag is set. // Flags: // DPGROUP_LOCAL - // The group was created by this application. // // The absence of this flag denotes a remote group. // DPGROUP_STAGINGAREA - // The group is a staging area. // ---------------------------------------------------------------------- virtual bool __fastcall GetGroupFlags( DPID pGroup, dword* pFlags ); // ---------------------------------------------------------------------- // Method: GetGroupName() // Description: The GetGroupName method will retrieve a groups name. // // Use TDPName to retrieve the group name from the Data // parameter. // // Error values that can be generated are: // // DPERR_BUFFERTOOSMALL // DPERR_INVALIDGROUP // DPERR_INVALIDOBJECT // DPERR_INVALIDPARAMS // DPERR_INVALIDPLAYER // Params: pGroup - // The Group parameter identifies the group for which the // name is being retrieved. // pData - // The Data parameter references a buffer for holding the // TDPName information if this method returns successfully. // // Set NULL to allocate appropriate memory to hold the name, // the DataSize parameter will be set to the size of the // data. // // If previously allocated memory is used and the name // requires more memory than the amount specified by the // DataSize initial value, the memory will be released and // replaced with the required memory block. // pDataSize - // The DataSize parameter references the size, in bytes, of // the Data buffer. // // This parameter will be set to the size of the name when // the method returns. // ---------------------------------------------------------------------- virtual bool __fastcall GetGroupName( DPID pGroup, void* pData, dword* pDataSize ); // ---------------------------------------------------------------------- // Method: GetGroupOwner() // Description: The GetGroupOwner method will identify the groups owner // within a lobby session. // // Error values that can be generated are: // // DPERR_GENERIC // DPERR_INVALIDGROUP // DPERR_INVALIDPARAMS // DPERR_UNAVAILABLE // Params: pGroup - // The Group parameter identifies the group whose owner is // being requested. // pOwner - // The Owner parameter references the group owners ID if the // method returns successfully. // ---------------------------------------------------------------------- virtual bool __fastcall GetGroupOwner( DPID pGroup, DPID* pOwner ); // ---------------------------------------------------------------------- // Method: GetGroupParent() // Description: The GetGroupParent method will retrieve the ID of the // parent of the specified group. // // Error values that can be generated are: // // DPERR_INVALIDGROUP // DPERR_INVALIDPARAMS // Params: pGroup - // The Group parameter identifies the group whose parent ID // is being retrieved. // pParent - // The Parent parameter will reference the parent groups ID // if the method returns successfully. // // A result of zero denotes a root group. // ---------------------------------------------------------------------- virtual bool __fastcall GetGroupParent( DPID pGroup, DPID* pParent ); // ---------------------------------------------------------------------- // Method: GetMessageCount() // Description: The GetMessageCount method will retrieve the number of // messages in the specified local players receive queue. // // Error values that can be generated are: // // DPERR_INVALIDOBJECT // DPERR_INVALIDPARAMS // DPERR_INVALIDPLAYER // Params: pPlayer - // The Player parameter identifies the local player whose // message count is being retrieved. // pCount - // The Count parameter will reference the message count if // this method returns successfully. // ---------------------------------------------------------------------- virtual bool __fastcall GetMessageCount( DPID pPlayer, dword* pCount ); // ---------------------------------------------------------------------- // Method: GetMessageQueue() // Description: The GetMessageQueue method retrieves how many messages // are on the local send or receive queues for the session. // // On slower networks, this information can be used to // regulate network usage. // These message queues are for all local players in the // session, not neccessarily individual players. // // Error values that can be generated are: // // DPERR_INVALIDFLAGS // DPERR_INVALIDPARAMS // DPERR_INVALIDPLAYER // DPERR_UNSUPPORTED // Params: pFrom - // The From parameter identifies the player who has sent the // messages. // // Setting zero obtains the number of messages recieved from // all players. // pTo - // The To parameter identifies the player who is to receive // the messages. // // Setting zero obtains the number of messages sent to all // players. // pFlags - // The Flags parameter defines flags indicating which // queue's information is the be retrieved. // // The default value of zero is equivilent to // DPMESSAGEQUEUE_SEND. // Flags: // DPMESSAGEQUEUE_RECEIVE - // Retrieve receive queue information. // // DPMESSAGEQUEUE_SEND should not also be set. // DPMESSAGEQUEUE_SEND - // Retrieve send queue information. // // DPMESSAGEQUEUE_RECEIVE should not also be set. // pNumMsgs - // The NumMsgs parameter will reference the number of // messages in the requested queue. // // Set NULL if the number of messages is not required. // pNumBytes - // The NumMsgs parameter will reference the number of bytes // in the requested queue. // // Set NULL if the queue size is not required. // ---------------------------------------------------------------------- virtual bool __fastcall GetMessageQueue( DPID pFrom, DPID pTo, dword pFlags, dword* pNumMsgs, dword* pNumBytes ); // ---------------------------------------------------------------------- // Method: GetPlayerAccount() // Description: The GetPlayerAccount method will retrieve account // information about the specified player. // // This method can only be used by the session host during a // secure session. // // Error values that can be generated are: // // DPERR_ACCESSDENIED // DPERR_BUFFERTOOSMALL // DPERR_INVALIDFLAGS // DPERR_INVALIDPARAMS // DPERR_INVALIDPLAYER // Params: pPlayer - // The Player parameter identifies the player for which // account information is being retrieved. // pData - // The Data parameter references a buffer for holding the // TDPAccountDesc information if this method returns // successfully. // // Set NULL to allocate appropriate memory to hold the name, // the DataSize parameter will be set to the size of the // data. // // If previously allocated memory is used and the // TDPAccountDesc requires more memory than the amount // specified by the DataSize initial value, the memory will // be released and replaced with the required memory block. // pDataSize - // The DataSize parameter references the size, in bytes, of // the Data buffer. // // This parameter will be set to the size of the Data when // the method returns. // ---------------------------------------------------------------------- virtual bool __fastcall GetPlayerAccount( DPID pPlayer, void* pData, dword* pDataSize ); // ---------------------------------------------------------------------- // Method: GetPlayerAddress() // Description: The GetPlayerAddress method will retrieve the network // address of a specified player. // // TDx_PlayLobby::EnumAddress() can be used to parse the // retrieved buffer. // // If a local players address is requested, the address of // the local computer will be returned if available. // Multiple addresses may be returned if a computer has more // than one network interface. // // Error values that can be generated are: // // DPERR_BUFFERTOOSMALL // DPERR_INVALIDOBJECT // DPERR_INVALIDPARAMS // DPERR_INVALIDPLAYER // DPERR_UNAVAILABLE // Params: pPlayer - // The Player parameter identifies the player for which // address information to be retrieved. // // Setting this parameter to zero obtains a valid address // option list for the service provider. // pData - // The Data parameter references a buffer for holding the // retrieved addresses if this method returns successfully. // // Set NULL to allocate appropriate memory to hold the name, // the DataSize parameter will be set to the size of the // data. // // If previously allocated memory is used and the retrieved // data requires more memory than the amount specified by // the DataSize initial value, the memory will be released // and replaced with the required memory block. // pDataSize - // The DataSize parameter references the size, in bytes, of // the Data buffer. // // This parameter will be set to the size of the Data when // the method returns. // ---------------------------------------------------------------------- virtual bool __fastcall GetPlayerAddress( DPID pPlayer, void* pData, dword* pDataSize ); // ---------------------------------------------------------------------- // Method: GetPlayerCaps() // Description: The GetPlayerCaps method will retrieve a specific // player's current capabilities. // // Error values that can be generated are: // // DPERR_INVALIDOBJECT // DPERR_INVALIDPARAMS // DPERR_INVALIDPLAYER // Params: pPlayer - // The Player parameter identifies the player whose // capabilities are to be retrieved. // pPlayerCaps - // The PlayerCaps reference a TDPCaps component for holding // the players capabilities if this method returns // successfully. // pFlags - // The Flags parameter defines a flag indicating the // messaging type for which the players capabilities are to // be retrieved. // The described effect applies when the flag is set. // // The default setting of zero results in capabilities being // retrieved for nonguaranteed messaging. // Flags: // DPGETCAPS_GUARANTEED - // The guaranteed message delivery capabilties of the // player are to be retrieved. // ---------------------------------------------------------------------- virtual bool __fastcall GetPlayerCaps( DPID pPlayer, TDPCaps* pPlayerCaps, dword pFlags ); // ---------------------------------------------------------------------- // Method: GetPlayerData() // Description: The GetPlayerData method will retrieve application // specific data previously associated with the player by // TDx_Play::SetPlayerData(). // // Local data is set by this TDx_Play component using // DPSET_LOCAL, while remote data may have been set by any // application in the session using DPSET_REMOTE. // // Error values that can be generated are: // // DPERR_BUFFERTOOSMALL // DPERR_INVALIDFLAGS // DPERR_INVALIDOBJECT // DPERR_INVALIDPLAYER // Params: pPlayer - // The Player parameter identifies the player for which the // data is to be retrieved. // pData - // The Data parameter references a buffer for holding the // retrieved data if this method returns successfully. // // Set NULL to allocate appropriate memory to hold the data, // the DataSize parameter will be set to the size of the // data. // // If previously allocated memory is used and the retrieved // data requires more memory than the amount specified by // the DataSize initial value, the memory will be released // and replaced with the required memory block. // pDataSize - // The DataSize parameter references the size, in bytes, of // the Data buffer. // // This parameter will be set to the size of the Data when // the method returns. // pFlags - // The Flags parameter defines flags indicating which data // type is to be retrieved. // The described effect applies when the flag is set. // // The default setting of zero is equivilent to // DPGET_REMOTE. // Flags: // DPGET_LOCAL - // The local data that was set by this application // will be retrieved. // DPGET_REMOTE - // The current data of the remote shared data space // will be retrieved. // ---------------------------------------------------------------------- virtual bool __fastcall GetPlayerData( DPID pPlayer, void* pData, dword* pDataSize, dword pFlags ); // ---------------------------------------------------------------------- // Method: GetPlayerFlags() // Description: The GetPlayerFlags method will retrieve a specified // players descriptive flags. // // Error values that can be generated are: // // DPERR_INVALIDPARAMS // DPERR_INVALIDPLAYER // Params: pPlayer - // The Player parameter identifies the player for which the // flag settings are to be retrieved. // pFlags - // The Flags parameter will reference the players flag // settings if this method returns successfully. // The described effect applies when the flag is set. // Flags: // DPPLAYER_LOCAL - // The player was created by this application. // The absence of this flag denotes a remote player. // DPPLAYER_SERVERPLAYER - // In a client/server session, the player is a server // player. // DPPLAYER_SPECTATOR - // The player is a spectator. // ---------------------------------------------------------------------- virtual bool __fastcall GetPlayerFlags( DPID pPlayer, dword* pFlags ); // ---------------------------------------------------------------------- // Method: GetPlayerName() // Description: The GetPlayerName method will retrieve a groups name. // // Use TDPName to retrieve the player name from the Data // parameter. // // Error values that can be generated are: // // DPERR_BUFFERTOOSMALL // DPERR_INVALIDOBJECT // DPERR_INVALIDPLAYER // Params: pPlayer - // The Player parameter identifies the player for which the // name is being retrieved. // pData - // The Data parameter references a buffer for holding the // TDPName information if this method returns successfully. // // Set NULL to allocate appropriate memory to hold the name, // the DataSize parameter will be set to the size of the // data. // // If previously allocated memory is used and the name // requires more memory than the amount specified by the // DataSize initial value, the memory will be released and // replaced with the required memory block. // pDataSize - // The DataSize parameter references the size, in bytes, of // the Data buffer. // // This parameter will be set to the size of the name when // the method returns. // ---------------------------------------------------------------------- virtual bool __fastcall GetPlayerName( DPID pPlayer, void* pData, dword* pDataSize ); // ---------------------------------------------------------------------- // Method: GetSessionDesc() // Description: The GetSessionDesc method will retrieve the currently // open session's properties. // // Use TDPSessionDesc to retrieve the session information // from the Data parameter. // // Error values that can be generated are: // // DPERR_BUFFERTOOSMALL // DPERR_INVALIDOBJECT // DPERR_INVALIDPARAMS // DPERR_NOCONNECTION // Params: pData - // The Data parameter references a buffer for holding the // TDPSessionDesc information if this method returns // successfully. // // Set NULL to allocate appropriate memory to hold the data, // the DataSize parameter will be set to the size of the // data. // // If previously allocated memory is used and the data // requires more memory than the amount specified by the // DataSize initial value, the memory will be released and // replaced with the required memory block. // pDataSize - // The DataSize parameter references the size, in bytes, of // the Data buffer. // // This parameter will be set to the size of the data when // the method returns. // ---------------------------------------------------------------------- virtual bool __fastcall GetSessionDesc( void* pData, dword* pDataSize ); // ---------------------------------------------------------------------- // Method: InitializeConnection() // Description: The InitializeConnection method will initialize a // TDx_Play connection. // // Error values that can be generated are: // // DPERR_ALREADYINITIALIZED // DPERR_INVALIDFLAGS // DPERR_INVALIDPARAMS // DPERR_UNAVAILABLE // Params: pConnection - // The Connection parameter references a buffer detailing // the service provider, server network address and session // guid. // // The buffer contains a TDx_Play address retrieved using // TDx_Play::EnumConnections() or created using // TDx_PlayLobby::CreateCompoundAddress. // ---------------------------------------------------------------------- virtual bool __fastcall InitializeConnection( void* pConnection ); // ---------------------------------------------------------------------- // Method: Internal_EnumConnectionsCallback() // Description: The Internal_EnumConnectionsCallback method is used to // process enumeration for TDx_Play::EnumConnections(). // Params: pSP - // The SP parameter identifies the service provider being // used for the connection. // pConnection - // The Connection that is currently being enumerated. // pConnectionSize - // The ConnectionSize parameter indicates the size of the // enumerated connection. // pName - // The Name of the currently enumerated connection. // pFlags - // The Flags parameter is not used at this time. // pContext - // The Context parameter is user defined data passed to the // calling function. // ---------------------------------------------------------------------- static BOOL __stdcall Internal_EnumConnectionsCallback( LPCGUID pSP, LPVOID pConnection, DWORD pConnectionSize, LPCDPNAME pName, DWORD pFlags, LPVOID pContext ); // ---------------------------------------------------------------------- // Method: Internal_EnumGroupPlayersCallback() // Description: The Internal_EnumGroupPlayersCallback method is used to // process enumeration for TDx_Play::EnumGroupPlayers(). // Params: pId - // The Id of the player being enumerated. // pPlayerType - // The type of player being enumerated. // pName - // The Name of the currently enumerated player. // pFlags - // The Flags parameter describe the currently enumerated // player. // pContext - // The Context parameter is user defined data pased to the // calling function. // ---------------------------------------------------------------------- static BOOL __stdcall Internal_EnumGroupPlayersCallback( DPID pId, DWORD pPlayerType, LPCDPNAME pName, DWORD pFlags, LPVOID pContext ); // ---------------------------------------------------------------------- // Method: Internal_EnumGroupsCallback() // Description: The Internal_EnumGroupsCallback method is used to process // enumeration for TDx_Play::EnumGroups(). // Params: pId - // The Id of the currently enumerated group. // pPlayerType - // The PlayerType parameter describes the type of group // being enumerated. // pName - // The Name of the group being enumerated. // pFlags - // The Flags parameter describe the group being enumerated. // DPENUMGROUPS_HIDDEN // DPENUMGROUPS_SHORTCUT // DPENUMGROUPS_STAGINGAREA // DPENUMPLAYERS_GROUP // pContext - // The Context parameter is user defined data passed to the // calling function. // ---------------------------------------------------------------------- static BOOL __stdcall Internal_EnumGroupsCallback( DPID pId, DWORD pPlayerType, LPCDPNAME pName, DWORD pFlags, LPVOID pContext ); // ---------------------------------------------------------------------- // Method: Internal_EnumGroupsInGroupCallback() // Description: The Internal_EnumGroupsInGroupCallback method is used to // process enumeration for TDx_Play::EnumGroupsInGroup(). // Params: pId - // The Id of the group being enumerated. // pPlayerType - // The PlayerType parameter indicates the type of group // being enumerated. // pName - // The Name of the group being enumerated. // pFlags - // The Flags parameter describe the group being enumerated. // pContext - // The Context parameter is user defined data passed to the // calling function. // ---------------------------------------------------------------------- static BOOL __stdcall Internal_EnumGroupsInGroupCallback( DPID pId, DWORD pPlayerType, LPCDPNAME pName, DWORD pFlags, LPVOID pContext ); // ---------------------------------------------------------------------- // Method: Internal_EnumPlayersCallback() // Description: The Internal_EnumPlayersCallback method is used to // process enumeration from TDx_Play::EnumPlayers(). // Params: pId - // The Id parameter identifies the player being enumerated // pPlayerType - // The PlayerType parameter describes the player being // enumerated. // pName - // The Name parameter references a TDPName component holding // the name of the player being enumerated. // pFlags - // The Flags parameter describes the player being // enumerated. // pContext - // The Context parameter references application defined data // passed to the callback function. // ---------------------------------------------------------------------- static BOOL __stdcall Internal_EnumPlayersCallback( DPID pId, DWORD pPlayerType, LPCDPNAME pName, DWORD pFlags, LPVOID pContext ); // ---------------------------------------------------------------------- // Method: Internal_EnumSessionsCallback() // Description: The Internal_EnumSessionsCallback method is used to // process enumeration for TDx_Play::EnumSessions(). // Params: pThisSD - // The ThisSD parameter references a TDPSessionDesc // component describing the session currently being // enumerated. // pTimeOut - // The TimeOut parameter contains the curent timeout value. // // This value can be increased if the DPESC_TIMEDOUT flag is // returned. // pFlags - // The Flags parameter defines a flag indicating enumeration // status. // The described effect applies when the flag is set. // // This parameter is typically set to zero. // Flags: // DPESC_TIMEDOUT - // A timeout condition occured while waiting for // session information. // pContext - // The Context parameter references application defined data // passed to the callback fuinction. // ---------------------------------------------------------------------- static BOOL __stdcall Internal_EnumSessionsCallback( LPCDPSESSIONDESC2 pThisSD, LPDWORD pTimeOut, DWORD pFlags, LPVOID pContext ); // ---------------------------------------------------------------------- // Method: Open() // Description: The Open method will join or create a session. // // Secure sessions must be joined using // TDx_Play::SecureOpen(). // Existing sessions to join can be found using // TDx_Play::EnumSessions(). // To open more than one session, the application must // employ multiple TDx_Play components. // Once joined, messages cannot be exchanged until a local // player is created using TDx_Play::CreatePlayer(). // // Error values that can be generated are: // // DPERR_ACCESSDENIED // DPERR_ALREADYINITIALIZED // DPERR_AUTHENTICATIONFAILED // DPERR_CANNOTCREATESERVER // DPERR_CANTCREATEPLAYER // DPERR_CANTLOADCAPI // DPERR_CANTLOADSECURITYPACKAGE // DPERR_CANTLOADSSPI // DPERR_CONNECTING // DPERR_CONNECTIONLOST // DPERR_ENCRYPTIONFAILED // DPERR_ENCRYPTIONNOTSUPPORTED // DPERR_INVALIDFLAGS // DPERR_INVALIDPARAMS // DPERR_INVALIDPASSWORD // DPERR_LOGONDENIED // DPERR_NOCONNECTION // DPERR_NONEWPLAYERS // DPERR_NOSESSIONS // DPERR_SIGNFAILED // DPERR_TIMEOUT // DPERR_UNINITIALIZED // DPERR_USERCANCEL // Params: pSD - // The SD parameter references a TDPSessionDesc component // holding the relevent information about the session to be // created or joined. // // To join a session only requires the // TDPSessionDesc::Instance, and if a password is needed, // TDPSessionDesc::Password. // // To create a session all the relevent TDPSessionDesc // properties must be provided. // The session GUID will be generated by DirectPlay. // pFlags - // The Flags parameter defines flags indicating the type of // open action to be performed. // The described effect applies when the flag is set. // Flags: // DPOPEN_CREATE - // A new session instance is to be created. // The local computer will act as the name server and // session host for the new session. // DPOPEN_JOIN - // An existing session is to be joined. // DPOPEN_RETURNSTATUS - // Do not display any connection status dialog boxes. // // // DDERR_CONNECTING will be returned if the connection // cannot be made immediately. // The application should call this method until DP_OK // or a different error code is returned. // ---------------------------------------------------------------------- virtual bool __fastcall Open( TDPSessionDesc* pSD, dword pFlags ); // ---------------------------------------------------------------------- // Method: Receive() // Description: The ReceiveEx method will retrieve one message from the // incoming message queue. // // Error values that can be generated are: // // DPERR_BUFFERTOOSMALL // DPERR_GENERIC // DPERR_INVALIDOBJECT // DPERR_INVALIDPARAMS // DPERR_INVALIDPLAYER // DPERR_NOMESSAGES // Params: pFrom - // The From parameter will identify the player that sent the // message if this method returns successfully. // // When DPRECEIVE_FROMPLAYER is set, you must identify the // sending player in this parameter. // pTo - // The To parameter will identify the player receiving the // message if this method return successfully. // // When DPRECEIVE_TOPLAYER is set, you must identify the // receiving player in this parameter. // pFlags - // The Flags parameter defines flags indicating how a // message is to be retrieved and treated. // The described effect applies when the flag is set. // // The default setting of zero is equivalent to // DPRECEIVE_ALL. // Flags: // DPRECEIVE_ALL - // The first relevent message in the queue will be // retrieved. // DPRECEIVE_FROMPLAYER - // Retrieve only the messages sent from the player // identified by the From parameter. // DPRECEIVE_PEEK - // Retrieves a message defined by the other flag // settings without removing the message from the // queue. // // This flag should be set when the Data parameter is // NULL. // DPRECEIVE_TOPLAYER - // Retrieve only the messages sent to the player // identified by the To parameter. // pData - // The Data parameter references a buffer for holding the // message data if this method returns successfully. // // Set NULL to allocate appropriate memory to hold the // message data, the DataSize parameter will be set to the // size of the data. // // If previously allocated memory is used and the message // data requires more memory than the amount specified by // the DataSize initial value, the memory will be released // and replaced with the required memory block. // pDataSize - // The DataSize parameter references the size, in bytes, of // the Data buffer. // // This parameter will be set to the size of the message // data when the method returns. // ---------------------------------------------------------------------- virtual HRESULT __fastcall Receive( DPID* pFrom, DPID* pTo, dword pFlags, void* pData, dword* pDataSize ); // ---------------------------------------------------------------------- // Method: ReceiveEx() // Description: The ReceiveEx method retrieves one message from the // incoming message queue, determines what type of message // it is, converts data as necessary and triggers a // corresponding TDx_Play event, one of :- // // TDx_Play::OnCreatePlayerOrGroup() // TDx_Play::OnDestroyPlayerOrGroup() // TDx_Play::OnAddPlayerToGroup() // TDx_Play::OnDeletePlayerFromGroup() // TDx_Play::OnSessionLost() // TDx_Play::OnHost() // TDx_Play::OnSetPlayerOrGroupData() // TDx_Play::OnSetPlayerOrGroupName() // TDx_Play::OnAddGroupToGroup() // TDx_Play::OnDeleteGroupFromGroup() // TDx_Play::OnChat() // TDx_Play::OnSecureMessage() // TDx_Play::OnSendComplete() // TDx_Play::OnSetGroupOwner() // TDx_Play::OnSetSessionDesc() // TDx_Play::OnStartSession() // TDx_Play::OnGeneric() // // Error values that can be generated are: // // DPERR_BUFFERTOOSMALL // DPERR_GENERIC // DPERR_INVALIDOBJECT // DPERR_INVALIDPARAMS // DPERR_INVALIDPLAYER // DPERR_NOMESSAGES // Params: pFrom - // The From parameter will identify the player that sent the // message if this method returns successfully. // // When DPRECEIVE_FROMPLAYER is set, you must identify the // sending player in this parameter. // pTo - // The To parameter will identify the player receiving the // message if this method return successfully. // // When DPRECEIVE_TOPLAYER is set, you must identify the // receiving player in this parameter. // pFlags - // The Flags parameter defines flags indicating how a // message is to be retrieved and treated. // The described effect applies when the flag is set. // // The default setting of zero is equivalent to // DPRECEIVE_ALL. // Flags: // DPRECEIVE_ALL - // The first relevent message in the queue will be // retrieved. // DPRECEIVE_FROMPLAYER - // Retrieve only the messages sent from the player // identified by the From parameter. // DPRECEIVE_PEEK - // Retrieves a message defined by the other flag // settings without removing the message from the // queue. // This flag should be set when the Data parameter is // NULL. // DPRECEIVE_TOPLAYER - // Retrieve only the messages sent to the player // identified by the To parameter. // ---------------------------------------------------------------------- virtual HRESULT __fastcall ReceiveEx( LPDPID pFrom, LPDPID pTo, DWORD pFlags ); // ---------------------------------------------------------------------- // Method: SecureOpen() // Description: The SecureOpen method will create or join a secure // session. // // Existing sessions to join can be found using // TDx_Play::EnumSessions(). // To open more than one session, the application must // employ multiple TDx_Play components. // Once joined, messages cannot be exchanged until a local // player is created using TDx_Play::CreatePlayer(). // // Credentials supplied on system login may suffice, so when // first joining a session, supply no credentials. // If DPERR_LOGONDENIED is returned, then collect // credentials from the user and try again. // // Error values that can be generated are: // // DPERR_ACCESSDENIED // DPERR_ALREADYINITIALIZED // DPERR_AUTHENTICATIONFAILED // DPERR_CANNOTCREATESERVER // DPERR_CANTLOADCAPI // DPERR_CANTLOADSECURITYPACKAGE // DPERR_CANTLOADSSPI // DPERR_CONNECTING // DPERR_CONNECTIONLOST // DPERR_ENCRYPTIONFAILED // DPERR_ENCRYPTIONNOTSUPPORTED // DPERR_INVALIDFLAGS // DPERR_INVALIDPARAMS // DPERR_INVALIDPASSWORD // DPERR_LOGONDENIED // DPERR_NOCONNECTION // DPERR_NONEWPLAYERS // DPERR_SIGNFAILED // DPERR_TIMEOUT // DPERR_UNINITIALIZED // DPERR_USERCANCEL // Params: pSD - // The SD parameter references a TDPSessionDesc component // holding the relevent information about the secure session // to be created or joined. // // To join a secure session only requires the // TDPSessionDesc::Instance, and if a password is needed, // TDPSessionDesc::Password. // // To create a secure session all the relevent // TDPSessionDesc properties must be provided and the // TDPSessionDesc::Flags DPSESSION_SECURESERVER flag set. // The session GUID will be generated by DirectPlay. // pFlags - // The Flags parameter defines flags indicating the type of // open action to be performed. // The described effect applies when the flag is set. // Flags: // DPOPEN_CREATE - // A new secure session instance is to be created. // The local computer will act as the name server and // session host for the new session. // DPOPEN_JOIN - // An existing secure session instance is to be // joined. // DPOPEN_RETURNSTATUS - // Do not display any connection status dialog boxes. // // // DDERR_CONNECTING will be returned if the connection // cannot be made immediately. // The application should call this method until DP_OK // or a different error code is returned. // pSecurity - // The Security parameter references a TDPSecurityDesc // component holding the security package that the new // session will use. // // Set NULL when joining a session or to create a secure // session using the default security (NT lan manager) and // cryptoAPI (Microsoft RSA base cryptographic provider) // packages being used. // pCredentials - // The Credentials parameter references a TDPCredentials // component holding the logon name, password and domain to // be authenticated by the sessions hosting server. // // Set NULL if there are no credentials or the session is // being created rather than joined. // ---------------------------------------------------------------------- virtual bool __fastcall SecureOpen( TDPSessionDesc* pSD, dword pFlags, TDPSecurityDesc* pSecurity, TDPCredentials* pCredentials ); // ---------------------------------------------------------------------- // Method: Send() // Description: The Send method will send guaranteed or unguaranteed // messages to individual or multiple players. // // TDx_Play::SendEx() can be used to send messages // asynchronously. // // System messages will always be sent guaranteed. An // encypted or signed message is sent as a system message // (DPMSG_SECUREMESSAGE). // // There is no message size limit, large messages will be // broken into packets. It is reccomended large messages be // sent guaranteed, as one lost packet on an unguaranteed // message will result in the entire message being // discarded. // The largest message sendable using a single packet can be // determined by checking the TDCaps::MaxBufferSize value // returned by TDx_Play::GetCaps(). // // Error values that can be generated are: // // DPERR_BUSY // DPERR_CONNECTIONLOST // DPERR_INVALIDPARAMS // DPERR_INVALIDPLAYER // DPERR_NOTLOGGEDIN // DPERR_SENDTOOBIG // Params: pFrom - // The From parameter identifies the local player sending // the message. // pTo - // The To parameter identifies the player or group receiving // the message if this method return successfully. // // DPID_ALLPLAYERS can be specified to send the message to // all players in the session, or DPID_SERVERPLAYER to send // a message to the server player of a client server // session. // pFlags - // The Flags parameter defines flags indicating how the // message is to be sent. // The described effect applies when the flag is set. // // The default value of zero will result in a nonguaranteed // message being sent. // Flags: // DPSEND_ENCRYPTED - // The message is to be sent encrypted. // // Requires both a secure session and // DPSEND_GUARANTEED. // DPSEND_GUARANTEED - // The message is to be sent using guaranteed delivery // if available. // DPSEND_SIGNED - // The message is to be sent with a digital signature. // // Requires both a secure session and // DPSEND_GUARANTEED. // pData - // The Data parameter references the message data that is to // be sent. // pDataSize - // The DataSize parameter defines the size, in bytes, of the // message data to be sent. // ---------------------------------------------------------------------- virtual bool __fastcall Send( DPID pFrom, DPID pTo, dword pFlags, void* pData, dword pDataSize ); // ---------------------------------------------------------------------- // Method: SendChatMessage() // Description: The SendChatMessage method will send text messages to // individual or multiple players within a lobby session. // // The from ID will be DPID_SYSMSG, the TDPChat component // will identify the actual sending player. // // Error values that can be generated are: // // DPERR_ACCESSDENIED // DPERR_CONNECTIONLOST // DPERR_INVALIDFLAGS // DPERR_INVALIDPARAMS // DPERR_INVALIDPLAYER // Params: pFrom - // The From parameter identifies the local player sending // the message. // pTo - // The To parameter identifies the player or group receiving // the message if this method return successfully. // // DPID_ALLPLAYERS can also be specified to send the message // to all players in the session. // pFlags - // The Flags parameter defines a flag indicating how the // message is to be sent. // The described effect applies when the flag is set. // // The default setting of zero results in a nonguaranteed // messaging being used. // Flags: // DPSEND_GUARANTEED - // The message is to be sent using guaranteed delivery // if available. // pChatMessage - // The ChatMessage parameter references a TDPChat component // holding the message being sent. // ---------------------------------------------------------------------- virtual bool __fastcall SendChatMessage( DPID pFrom, DPID pTo, dword pFlags, TDPChat* pChatMessage ); // ---------------------------------------------------------------------- // Method: SendEx() // Description: The SendEx method will send guaranteed or unguaranteed // messages to individual or multiple players. // // It functions like TDx_Play::Send() except asyncronous // messages, message priorities and message timeouts are all // supported. // // When using asynchronous messaging, DPERR_PENDING will be // returned once the message is queued and a // DPMSG_SENDCOMPLETE message received once the send process // is completed. // // System messages will always be sent guaranteed. An // encypted or signed message is sent as a system message // (DPMSG_SECUREMESSAGE). // // There is no message size limit, large messages will be // broken into packets. It is reccomended large messages be // sent guaranteed, as one lost packet on an unguaranteed // message will result in the entire message being // discarded. // The largest message sendable using a single packet can be // determined by checking the TDCaps::MaxBufferSize value // returned by TDx_Play::GetCaps(). // // It is reccomended that all secure or signed messages be // sent with the same priority level. Secure message // validation depends on receive order, and different // priorities may change that order. // // Error values that can be generated are: // // DPERR_BUSY // DPERR_CONNECTIONLOST // DPERR_INVALIDFLAGS // DPERR_INVALIDPARAMS // DPERR_INVALIDPLAYER // DPERR_INVALIDPRIORITY // DPERR_NOTLOGGEDIN // DPERR_SENDTOOBIG // DPERR_UNSUPPORTED // Params: pFrom - // The From parameter identifies the local player sending // the message. // pTo - // The To parameter identifies the player or group receiving // the message if this method return successfully. // // DPID_ALLPLAYERS can be specified to send the message to // all players in the session, or DPID_SERVERPLAYER to send // a message to the server player of a client server // session. // pFlags - // The Flags parameter defines flags indicating how the // message is to be sent. // The described effect applies when the flag is set. // // The default value of zero will result in a nonguaranteed // message being sent. // Flags: // DPSEND_ASYNC - // Send the message asynchronously. // // The method returns immediately, DPERR_PENDING being // returned if the message was added to send queue // (rather than being sent straight away). // A DPMSG_SENDCOMPLETE message will be posted to the // senders receive queue once the message has been // sent. // DPSEND_ENCRYPTED - // Send the message as a DPMSG_SECUREMESSAGE system // message with encryption. // // Only usable in a secure session with // DPSEND_GUARANTEED also set. // DPSEND_GUARANTEED - // The message is to be sent using guaranteed delivery // if available. // DPSEND_NOSENDCOMPLETEMSG - // No DPMSG_SENDCOMPLETE message will be posted when // sending an asynchronous message. // // DPSEND_ASYNC must also be set. // DPSEND_SIGNED - // Send the message as a DPMSG_SECUREMESSAGE system // message with a digital signature. // // Only usable in a secure session with // DPSEND_GUARANTEED also set. // pData - // The Data parameter references the message data that is to // be sent. // pDataSize - // The DataSize parameter defines the size, in bytes, of the // message data to be sent. // pPriority - // The Priority parameter defines a message priority, from // lowest priority at zero to highest priority at 65535. // // Messages are sent from the queue in priority order. // // Setting a priority (non zero) when the service provider // does not support them results in a DPERR_UNSUPPORTED // error. // Use TDx_Play::GetCaps() to determine if priority // messaging is supported. // pTimeout - // The Timeout parameter defines how long, in milliseconds, // to wait before cancelling the message if it still has not // been delivered. // // A DPMSG_SENDCOMPLETE message will still be posted when a // message times out. // // Setting a timeout (non zero) when the service provider // does not support them results in a DPERR_UNSUPPORTED // error. // Use TDx_Play::GetCaps() to determine if timouts are // supported. // pContext - // The Context parameter references application defined data // to be returned in the completion message when the send is // complete. // // Set NULL if no data needs to be returned. // pID - // The ID parameter will reference the identity assigned to // an asynchronous message if the method returns // successfully. // // The message ID can be used to check the message status or // cancel it. // Set NULL if no message ID is required. // ---------------------------------------------------------------------- virtual bool __fastcall SendEx( DPID pFrom, DPID pTo, dword pFlags, void* pData, dword pDataSize, dword pPriority, dword pTimeout, void* pContext, dword* pID ); // ---------------------------------------------------------------------- // Method: SetGroupConnectionSettings() // Description: The SetGroupConnectionSettings method will define a // sessions connection settings when launched from within a // lobby session group. // // The TDPLConnection component should be checked for // predefined defaults by calling // TDx_Play::GetGroupConnectionSettings(). Trying to modify // these values may cause errors. // // TDPLConnection::Address, TDPLConnection::AddressSize and // TDPSessionDesc::Instance need not be specified for this // method to work. // // Error values that can be generated are: // // DPERR_ACCESSDENIED // DPERR_CONNECTIONLOST // DPERR_INVALIDGROUP // DPERR_INVALIDPARAMS // DPERR_UNSUPPORTED // Params: pGroup - // The Group parameter identifies the group whose connection // settings are being defined. // pConnection - // The Connection parameter references a TDPLConnection // component defining the service provider, session // description and application to be launched when starting // a session from the Group. // ---------------------------------------------------------------------- virtual bool __fastcall SetGroupConnectionSettings( DPID pGroup, TDPLConnection* pConnection ); // ---------------------------------------------------------------------- // Method: SetGroupData() // Description: The SetGroupData method will associate application // specific data with the specified group. // // There are two types of group data, local and remote. // Local data is only available to the local computer, while // remote data is propogated to all applications in the // session via a DPMSG_SETPLAYERORGROUPDATA message. // // Only the computer that created the group may modify its // data. // // To update real time information, TDx_Play::Send() or // TDx_Play::SendEx() should be used, this method is more // appropriate for sharing information that does not change // rapidly. // // Error values that can be generated are: // // DPERR_BUFFERTOOSMALL // DPERR_INVALIDGROUP // DPERR_INVALIDOBJECT // DPERR_INVALIDPARAMS // DPERR_INVALIDPLAYER // Params: pGroup - // The Group parameter identifies the group with which the // data is to be associated. // pData - // The Data parameter references the data to be associated // with the specified Group. // // Set NULL to clear any data already associated with the // specified group. // pDataSize - // The DataSize parameter defines the size of the Data // buffer. // // When Data is NULL, this parameter must be zero. // pFlags - // The Flags parameter defines flags indicating how to // propagate the data. // The described effect applies when the flag is set. // // The default value of zero will result in remote data // being propagated with non-guaranteed messaging. // Flags: // DPSET_GUARANTEED - // The remote data is to be propagated with guaranteed // messaging. // // DPSET_REMOTE must also be set. // DPSET_LOCAL - // The data is to be used locally and will not be // propagated. // DPSET_REMOTE - // The data will be propagated to all the applications // in the session. // // The group must be owned by the local session for // this flag to be set. // ---------------------------------------------------------------------- virtual bool __fastcall SetGroupData( DPID pGroup, void* pData, dword pDataSize, dword pFlags ); // ---------------------------------------------------------------------- // Method: SetGroupName() // Description: The SetGroupName method is used to change or set the name // of an existing group. // // Only the computer that created the group may modify its // name. // // All other players will receive a // DPMSG_SETPLAYERORGROUPNAME, provided // DPSESSION_NODATAMESSAGES has not been set in the session // description. // // Error values that can be generated are: // // DPERR_CONNECTIONLOST // DPERR_INVALIDGROUP // DPERR_INVALIDOBJECT // DPERR_INVALIDPARAMS // DPERR_INVALIDPLAYER // Params: pGroup - // The Group parameter identifies the group whose name is to // be set. // pGroupName - // The GroupName parameter references a TDPName component // holding the new name for the specified Group. // // Set NULL if the group has no name information. // pFlags - // The Flags parameter defines flags indicating how to // propagate the name. // The described effect applies when the flag is set. // // The default setting of zero will result in the name being // propagated to all the remote systems in the local session // using nonguaranteed messaging. // The default can only be used for groups owned by the // local session. // Flags: // DPSET_GUARANTEED - // The name is to be propagated to remote applications // using guaranteed messaging. // // DPSET_REMOTE must also be set. // DPSET_LOCAL - // The name is to be used locally and will not be // propagated. // DPSET_REMOTE - // The name will be propagated to all the applications // in the session. // // The group must be owned by the local session for // this flag to be set. // ---------------------------------------------------------------------- virtual bool __fastcall SetGroupName( DPID pGroup, TDPName* pGroupName, dword pFlags ); // ---------------------------------------------------------------------- // Method: SetGroupOwner() // Description: The SetGroupOwner method can be used to change a groups // owner. // // This method can only be used in a lobby session and will // generate a DPMSG_SETGROUPOWNER system message. // // Error values that can be generated are: // // DPERR_CONNECTIONLOST // DPERR_GENERIC // DPERR_INVALIDGROUP // DPERR_INVALIDPLAYER // DPERR_UNAVAILABLE // Params: pGroup - // The Group parameter identifies the group whose ownership // is being modified. // pOwner - // The Owner parameter identifies the player who will be the // groups new owner. // ---------------------------------------------------------------------- virtual bool __fastcall SetGroupOwner( DPID pGroup, DPID pOwner ); // ---------------------------------------------------------------------- // Method: SetPlayerData() // Description: The SetPlayerData method will associate application // specific data with the specified player. // // There are two types of player data, local and remote. // Local data is only available to the local computer, while // remote data is propogated to all applications in the // session via a DPMSG_SETPLAYERORGROUPDATA message. // // Only the computer that created the player may modify its // data. // // To update real time information, TDx_Play::Send() or // TDx_Play::SendEx() should be used, this method is more // appropriate for sharing information that does not change // rapidly. // // Error values that can be generated are: // // DPERR_ACCESSDENIED // DPERR_CONNECTIONLOST // DPERR_INVALIDFLAGS // DPERR_INVALIDOBJECT // DPERR_INVALIDPARAMS // DPERR_INVALIDPLAYER // Params: pPlayer - // The Group parameter identifies the player with which the // data is to be associated. // pData - // The Data parameter references the data to be associated // with the specified Player. // // Set NULL to clear any data already associated with the // specified Player. // pDataSize - // The DataSize parameter defines the size of the Data // buffer. // // When Data is NULL, this parameter must be zero. // pFlags - // The Flags parameter defines flags indicating how to // propagate the data. // The described effect applies when the flag is set. // // The default value of zero will result in remote data // being propagated with non-guaranteed messaging. // Flags: // DPSET_GUARANTEED - // The remote data is to be propagated with guaranteed // messaging. // // DPSET_REMOTE must also be set. // DPSET_LOCAL - // The data is to be used locally and will not be // propagated. // DPSET_REMOTE - // The data will be propagated to all the applications // in the session. // ---------------------------------------------------------------------- virtual bool __fastcall SetPlayerData( DPID pPlayer, void* pData, dword pDataSize, dword pFlags ); // ---------------------------------------------------------------------- // Method: SetPlayerName() // Description: The SetPlayerName method is used to change or set the // name of an existing player. // // Only the computer that created the player may modify its // name. // // All other players will receive a // DPMSG_SETPLAYERORGROUPNAME, provided // DPSESSION_NODATAMESSAGES has not been set in the session // description. // // Error values that can be generated are: // // DPERR_CONNECTIONLOST // DPERR_INVALIDOBJECT // DPERR_INVALIDPLAYER // Params: pPlayer - // The Player parameter identifies the player whose name is // to be set. // pPlayerName - // The PlayerName parameter references a TDPName component // holding the new name for the specified player. // // Set NULL if the player has no name information. // pFlags - // The Flags parameter defines flags indicating how to // propagate the name. // The described effect applies when the flag is set. // Flags: // DPSET_GUARANTEED - // The name is to be propagated with guaranteed // messaging. // // DPSET_REMOTE must also be set. // DPSET_LOCAL - // The name is to be used locally and will not be // propagated. // DPSET_REMOTE - // The name will be propagated to all the applications // in the session. // // This is the default value. // ---------------------------------------------------------------------- virtual bool __fastcall SetPlayerName( DPID pPlayer, TDPName* pPlayerName, dword pFlags ); // ---------------------------------------------------------------------- // Method: SetSessionDesc() // Description: The SetSessionDesc method is used to change the current // sessions properties. // // This method cannot be used in a lobby session and only // the session host can change the session properties. // // A DPMSG_SETSESSIONDESC message will inform all the other // computers in the session of the change. // // Error values that can be generated are: // // DPERR_ACCESSDENIED // DPERR_CONNECTIONLOST // DPERR_INVALIDPARAMS // DPERR_NOSESSIONS // Params: pSessDesc - // The SessDesc parameter references a TDPSessionDesc // component defining the new session settings. // // The DPSESSION_JOINDISABLED, DPSESSION_NEWPLAYERSDISABLED, // DPSESSION_NODATAMESSAGES and DPSESSION_PRIVATE flags can // be changed, along with the name and password of the // session and any application defined data. // // The maximum number of players can also be modified, // although you cannot specify a lower maximum than the // current number of players. // // Attempts to change any of the other session properties // will either generate an error or be ignored. // ---------------------------------------------------------------------- virtual bool __fastcall SetSessionDesc( TDPSessionDesc* pSessDesc ); // ---------------------------------------------------------------------- // Method: StartSession() // Description: The StartSession method will launch a TDx_Play session // from a staging area group. // // New players arriving in the staging area can use this // method to join the already running session. // // Session information such as which application to launch, // service provider to use, etc is set using // TDx_Play::SetGroupConnectionSettings(). // // Players in the group will receive a DPMSG_STARTSESSION // system message. // // Error values that can be generated are: // // DPERR_ACCESSDENIED // DPERR_CONNECTIONLOST // DPERR_INVALIDFLAGS // DPERR_INVALIDGROUP // DPERR_INVALIDPARAMS // Params: pGroup - // The Group parameter identifies the staging area group // whose session is to be started. // ---------------------------------------------------------------------- virtual bool __fastcall StartSession( DPID pGroup ); // ---------------------------------------------------------------------- // Constructor() and Destructor() // ---------------------------------------------------------------------- __fastcall TDx_Play(TComponent* Owner); virtual __fastcall ~TDx_Play(); // ---------------------------------------------------------------------- // The following properties and methods are used internally by // TDx_Play_Library and should not be used. // ---------------------------------------------------------------------- __property LPDIRECTPLAY4 Internal_LPDIRECTPLAY4 = { read=FGetInternal_LPDIRECTPLAY4, write=FSetInternal_LPDIRECTPLAY4, nodefault }; __property LPDIRECTPLAY4* Internal_LPDIRECTPLAY4_Ptr = { read=FGetInternal_LPDIRECTPLAY4_Ptr, nodefault }; void __fastcall Internal_LPDIRECTPLAY4_Update(); __property LPDIRECTPLAY Internal_LPDIRECTPLAY = { read=FGetInternal_LPDIRECTPLAY, write=FSetInternal_LPDIRECTPLAY, nodefault }; __property LPDIRECTPLAY* Internal_LPDIRECTPLAY_Ptr = { read=FGetInternal_LPDIRECTPLAY_Ptr, nodefault }; void __fastcall Internal_LPDIRECTPLAY_Update(); // ========================================================================== protected: // ========================================================================== // ---------------------------------------------------------------------- // Property Access Methods // ---------------------------------------------------------------------- bool __fastcall FGetCreated(); void __fastcall FSetCreated( bool pCreated ); HRESULT __fastcall FGetErrorValue(); void __fastcall FSetErrorValue( HRESULT pErrorValue ); int __fastcall FGetNumPlayers(); void __fastcall FSetNumPlayers(int pNumPlayers ); TList* __fastcall FGetPlayerEvents(); TList* __fastcall FGetPlayerIDs(); bool __fastcall FGetUseAnsiString(); void __fastcall FSetUseAnsiString( bool pUseAnsiString ); // ========================================================================== private: // ========================================================================== // ---------------------------------------------------------------------- // Internal Interface Access // ---------------------------------------------------------------------- LPDIRECTPLAY4 __fastcall FGetInternal_LPDIRECTPLAY4(); void __fastcall FSetInternal_LPDIRECTPLAY4( LPDIRECTPLAY4 pLPDIRECTPLAY4 ); LPDIRECTPLAY4* __fastcall FGetInternal_LPDIRECTPLAY4_Ptr(); LPDIRECTPLAY __fastcall FGetInternal_LPDIRECTPLAY(); void __fastcall FSetInternal_LPDIRECTPLAY( LPDIRECTPLAY pLPDIRECTPLAY ); LPDIRECTPLAY* __fastcall FGetInternal_LPDIRECTPLAY_Ptr(); // ---------------------------------------------------------------------- // Property Variables // ---------------------------------------------------------------------- bool fCreated; HRESULT fErrorValue; int fNumPlayers; TList* fPlayerEvents; TList* fPlayerIDs; dword fUseAnsiString; // ---------------------------------------------------------------------- // Interface Variables // ---------------------------------------------------------------------- LPDIRECTPLAY4 fLPDIRECTPLAY4; LPDIRECTPLAY fLPDIRECTPLAY; // ---------------------------------------------------------------------- // Event Variables // ---------------------------------------------------------------------- TDx_OnAddGroupToGroup FOnAddGroupToGroup; TDx_OnAddPlayerToGroup FOnAddPlayerToGroup; TDx_OnChat FOnChat; TDx_Event FOnCreate; TDx_OnCreatePlayerOrGroup FOnCreatePlayerOrGroup; TDx_OnDeleteGroupFromGroup FOnDeleteGroupFromGroup; TDx_OnDeletePlayerFromGroup FOnDeletePlayerFromGroup; TDx_Event FOnDestroy; TDx_OnDestroyPlayerOrGroup FOnDestroyPlayerOrGroup; TDx_Error FOnError; TDx_OnGeneric FOnGeneric; TDx_OnHost FOnHost; TDx_OnDPReceive FOnReceive; TDx_OnSecureMessage FOnSecureMessage; TDx_OnSendComplete FOnSendComplete; TDx_OnSessionLost FOnSessionLost; TDx_OnSetGroupOwner FOnSetGroupOwner; TDx_OnSetPlayerOrGroupData FOnSetPlayerOrGroupData; TDx_OnSetPlayerOrGroupName FOnSetPlayerOrGroupName; TDx_OnSetSessionDesc FOnSetSessionDesc; TDx_OnStartSession FOnStartSession; // ---------------------------------------------------------------------- // Callback Variables // ---------------------------------------------------------------------- TDx_EnumConnections FOnEnumConnections; TDx_EnumGroupPlayers FOnEnumGroupPlayers; TDx_EnumGroups FOnEnumGroups; TDx_EnumGroupsInGroup FOnEnumGroupsInGroup; TDx_EnumPlayers FOnEnumPlayers; TDx_EnumSessions FOnEnumSessions; }; // -------------------------------------------------------------------------- #endif // --------------------------------------------------------------------------