#ifndef TDx_PlayLobbyH #define TDx_PlayLobbyH // ========================================================================== // File: TDx_PlayLobby.H // Authors: BCB_Code_Generator v1.62, // Darren Dwyer (source code, documentation, demos, website), // Hugh Edwards (documentation, icons), // Brian Austin (some source code, documentation) // Description: This file defines the TDx_PlayLobby Component // // "TDx_Play_Library v1.62" // (c) 2002 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_PlayLobby component. class TDPLAppInfo; // -------------------------------------------------------------------------- // external classes used by TDx_PlayLobby methods. class TDPCompoundAddressElement; class TDPApplicationDesc; class TDPLConnection; // -------------------------------------------------------------------------- // Definition for the OnAppTerminated event. typedef __fastcall void (__closure* TDx_OnSystemMessage) ( TObject* Sender, GUID Instance); // Definition for the OnConnectionSettingsRead event. typedef __fastcall void (__closure* TDx_OnSystemMessage) ( TObject* Sender, GUID Instance); // Definition for the OnGeneric event. typedef __fastcall void (__closure* TDx_OnLobbyGeneric) ( TObject* Sender, dword AppID, void* Data, dword DataSize, dword Type ); // Definition for the OnGetProperty event. typedef __fastcall void (__closure* TDx_OnGetProperty) ( TObject* Sender, dword RequestID, GUID Player, GUID PropertyTag); // Definition for the OnGetPropertyResponse event. typedef __fastcall void (__closure* TDx_OnGetPropertyResponse) ( TObject* Sender, dword RequestID, GUID Player, GUID PropertyTag, HRESULT hr, dword DataSize, void* PropertyData); // Definition for the OnNewConnectionSettings event. typedef __fastcall void (__closure* TDx_OnSystemMessage) ( TObject* Sender, GUID Instance); // Definition for the OnNewSessionHost event. typedef __fastcall void (__closure* TDx_OnNewSessionHost) ( TObject* Sender, GUID Instance); // Definition for the OnPlayConnectFailed event. typedef __fastcall void (__closure* TDx_OnSystemMessage) ( TObject* Sender, GUID Instance); // Definition for the OnPlayConnectSucceeded event. typedef __fastcall void (__closure* TDx_OnSystemMessage) ( TObject* Sender, GUID Instance); // Definition for the OnReceive event. typedef __fastcall void (__closure* TDx_OnDPLReceive) ( TObject* Sender); // Definition for the OnSetProperty event. typedef __fastcall void (__closure* TDx_OnSetProperty) ( TObject* Sender, dword RequestID, GUID guidPlayer, GUID guidPropertyTag, dword DataSize, void* PropertyData); // Definition for the OnSetPropertyResponse event. typedef __fastcall void (__closure* TDx_OnSetPropertyResponse) ( TObject* Sender, dword RequestID, GUID guidPlayer, GUID guidPropertyTag, HRESULT hr); // -------------------------------------------------------------------------- // Definition for the OnEnumAddress callback event. typedef __fastcall void (__closure* TDx_EnumAddress) ( TObject* Sender, GUID DataType, dword DataSize, const void* Data, void* Context, bool &Continue); // Definition for the OnEnumAddressTypes callback event. typedef __fastcall void (__closure* TDx_EnumAddressType) ( TObject* Sender, GUID DataType, void* Context, dword Flags, bool &Continue ); // Definition for the OnEnumLocalApplications callback event. typedef __fastcall void (__closure* TDx_EnumLocalApplications) ( TObject* Sender, TDPLAppInfo* AppInfo, void* Context, dword Flags, bool &Continue ); // ========================================================================== // Class: TDx_PlayLobby // Description: The TDx_PlayLobby component wraps IDirectPlayLobby3 and // IDirectPlayLobby3A interfaces which are used in the // management of applications and associated data. // // You may utilize unicode OR ANSI strings when using // TDx_PlayLobby, but the use of both by the same application // should be avoided. // // To create an IDirectPlayLobby3 or IDirectPlayLobby3A // interface, use the TDx_PlayLobby::Create() method and to // destroy the interface, use the TDx_PlayLobby::Destroy() // method. // // Use the TDx_PlayLobby::OnCreate() and // TDx_PlayLobby::OnDestroy() events to simplify the creation // and destruction of dependent objects. // // For example, in the TDx_PlayLobby::OnCreate() event, you // could retrieve the interface's capabilities, enumerate local // applications, and so on. Then in the // TDx_PlayLobby::OnDestroy() event, place code to destroy any // dependant components and deallocate memory used to hold the // capabilities (if required). // // Once created, call any of the TDx_PlayLobby methods and // handle any error results using the TDx_PlayLobby::OnError() // event and the TDx_PlayLobby::ErrorValue property. // ========================================================================== #if (__BORLANDC__ >= 0x0530) // BCB Version 3 + class PACKAGE TDx_PlayLobby : public TComponent { // -------------------------------------------------------------------------- #else // BCB Version 1 class TDx_PlayLobby : public TComponent { #endif // ========================================================================== __published: // ========================================================================== // ---------------------------------------------------------------------- // Property: NumLobbies // Description: The NumLobbies property is internally by TDx_PlayLobby // and TDx_PlayLobbyThreadClass. // ---------------------------------------------------------------------- __property int NumLobbies = { read=FGetNumLobbies, write=FSetNumLobbies, default=0 }; // ---------------------------------------------------------------------- // Property: UseAnsiString // Description: The UseAnsiString property is defines whether the unicode // or ANSI string interface is being used. // ---------------------------------------------------------------------- __property bool UseAnsiString = { read=FGetUseAnsiString, write=FSetUseAnsiString, default=true }; // ---------------------------------------------------------------------- // Event: OnAppTerminated() // Description: The OnAppTerminated event is triggered when using the // TDx_PlayLobby::ReceiveLobbyMessageEx() method in the // TDx_PlayLobby::OnReceive() event. // // This event indicates that DPLSYS_APPTERMINATED has been // received by the component's event thread. // // DPLSYS_APPTERMINATED is sent when an application launched // by TDx_PlayLobby::RunApplication() has ended. // // ---------------------------------------------------------------------- __property TDx_OnSystemMessage OnAppTerminated = {read=FOnAppTerminated, write=FOnAppTerminated, nodefault}; // ---------------------------------------------------------------------- // Event: OnConnectionSettingsRead() // Description: The OnConnectionSettingsRead event is triggered when // using the TDx_PlayLobby::ReceiveLobbyMessageEx() method // in the TDx_PlayLobby::OnReceive() event. // // This event indicates that DPLSYS_CONNECTIONSETTINGSREAD // has been received by the component's event thread. // // DPLSYS_CONNECTIONSETTINGSREAD is sent when the // application launched by TDx_PlayLobby::RunApplication() // has read the connection settings. // ---------------------------------------------------------------------- __property TDx_OnSystemMessage OnConnectionSettingsRead = {read=FOnConnectionSettingsRead, write=FOnConnectionSettingsRead, nodefault}; // ---------------------------------------------------------------------- // Event: OnCreate() // Description: The OnCreate() event is triggered by the // TDx_PlayLobby::Create() method after it has successfully // created the internal LPDIRECTPLAYLOBBY3 used within the // TDx_PlayLobby 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 LPDIRECTPLAYLOBBY3 interface. // // For example, you could retrieve the TDx_PlayLobby // component's capabilities, Create() dependant components, // allocate memory, etc. // // When used in conjunction with the // TDx_PlayLobby::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: OnDestroy() // Description: The OnDestroy() event is triggered by the // TDx_PlayLobby::Destroy() method, just before the // TDx_PlayLobby internal LPDIRECTPLAYLOBBY3 interface is // destroyed. // // Note: This event is an ideal place to place code that // reverses the results of the TDx_PlayLobby::OnCreate() // event. For example, assume you have already setup the // TDx_PlayLobby::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_PlayLobby::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: OnError() // Description: The OnError event is called when an error occurs in the // TDx_PlayLobby component. // ---------------------------------------------------------------------- __property TDx_Error OnError = {read=FOnError, write=FOnError, nodefault}; // ---------------------------------------------------------------------- // Event: OnGeneric() // Description: The OnGeneric event is triggered when using the // TDx_PlayLobby::ReceiveLobbyMessageEx() method in the // TDx_PlayLobby::OnReceive() event. // // This event indicates that DPMSG_GENERIC has been received // by the component's event thread. // // DPMSG_GENERIC is triggered when a generic messsage is // received. // ---------------------------------------------------------------------- __property TDx_OnLobbyGeneric OnGeneric = {read=FOnGeneric, write=FOnGeneric, nodefault}; // ---------------------------------------------------------------------- // Event: OnGetProperty() // Description: The OnGetProperty event is triggered when using the // TDx_PlayLobby::ReceiveLobbyMessageEx() method in the // TDx_PlayLobby::OnReceive() event. // // This event indicates that DPLSYS_GETPROPERTY has been // received by the component's event thread. // // DPLSYS_GETPROPERTY is sent when an application requests // property values from the lobby. // // ---------------------------------------------------------------------- __property TDx_OnGetProperty OnGetProperty = {read=FOnGetProperty, write=FOnGetProperty, nodefault}; // ---------------------------------------------------------------------- // Event: OnGetPropertyResponse() // Description: The OnGetPropertyResponse event is triggered when using // the TDx_PlayLobby::ReceiveLobbyMessageEx() method in the // TDx_PlayLobby::OnReceive() event. // // This event indicates that DPLSYS_GETPROPERTYRESPONSE has // been received by the component's event thread. // // DPLSYS_GETPROPERTYRESPONSE is sent by a lobby responding // to an OnGetProperty message. // ---------------------------------------------------------------------- __property TDx_OnGetPropertyResponse OnGetPropertyResponse = {read=FOnGetPropertyResponse, write=FOnGetPropertyResponse, nodefault}; // ---------------------------------------------------------------------- // Event: OnNewConnectionSettings() // Description: The OnNewConnectionSettings event is triggered when using // the TDx_PlayLobby::ReceiveLobbyMessageEx() method in the // TDx_PlayLobby::OnReceive() event. // // This event indicates that DPLSYS_NEWCONNECTIONSETTINGS // has been received by the component's event thread. // // DPLSYS_NEWCONNECTIONSETTINGS is sent if a waiting // application was found when a lobby client called // TDx_PlayLobby::RunApplication(). The waiting application // can read the connection settings and join the session. // ---------------------------------------------------------------------- __property TDx_OnSystemMessage OnNewConnectionSettings = {read=FOnNewConnectionSettings, write=FOnNewConnectionSettings, nodefault}; // ---------------------------------------------------------------------- // Event: OnNewSessionHost() // Description: The OnNewSessionHost event is triggered when using the // TDx_PlayLobby::ReceiveLobbyMessageEx() method in the // TDx_PlayLobby::OnReceive() event. // // This event indicates that DPLSYS_NEWSESSIONHOST has been // received by the component's event thread. // // DPLSYS_NEWSESSIONHOST is generated by DirectPlay and sent // to the lobby client when the client becomes the new // session host. // ---------------------------------------------------------------------- __property TDx_OnNewSessionHost OnNewSessionHost = {read=FOnNewSessionHost, write=FOnNewSessionHost, nodefault}; // ---------------------------------------------------------------------- // Event: OnPlayConnectFailed() // Description: The OnPlayConnectFailed event is triggered when using the // TDx_PlayLobby::ReceiveLobbyMessageEx() method in the // TDx_PlayLobby::OnReceive() event. // // This event indicates that DPLSYS_DPLAYCONNECTFAILED has // been received by the component's event thread. // // DPLSYS_DPLAYCONNECTFAILED is sent when the application // launched by TDx_PlayLobby::RunApplication() has failed to // connect to a session. // ---------------------------------------------------------------------- __property TDx_OnSystemMessage OnPlayConnectFailed = {read=FOnPlayConnectFailed, write=FOnPlayConnectFailed, nodefault}; // ---------------------------------------------------------------------- // Event: OnPlayConnectSucceeded() // Description: The OnPlayConnectSucceeded event is triggered when using // the TDx_PlayLobby::ReceiveLobbyMessageEx() method in the // TDx_PlayLobby::OnReceive() event. // // This event indicates that DPLSYS_DPLAYCONNECTSUCCEEDED // has been received by the component's event thread. // // DPLSYS_DPLAYCONNECTSUCCEEDED is sent when the application // launched by TDx_PlayLobby::RunApplication() has joined or // created a session. // ---------------------------------------------------------------------- __property TDx_OnSystemMessage OnPlayConnectSucceeded = {read=FOnPlayConnectSucceeded, write=FOnPlayConnectSucceeded, nodefault}; // ---------------------------------------------------------------------- // Event: OnReceive() // Description: The OnReceive event is triggered by the components event // thread indicating an event has been signaled. // TDx_PlayLobby::ReceiveLobbyMessage() or // TDx_Play::ReceiveLobbyMessageEx() should be called to // retrieve the message from DirectX for processing. // ---------------------------------------------------------------------- __property TDx_OnDPLReceive OnReceive = {read=FOnReceive, write=FOnReceive, nodefault}; // ---------------------------------------------------------------------- // Event: OnSetProperty() // Description: The OnSetProperty event is triggered when using the // TDx_PlayLobby::ReceiveLobbyMessageEx() method in the // TDx_PlayLobby::OnReceive() event. // // This event indicates that DPLSYS_SETPROPERTY has been // received by the component's event thread. // // DPLSYS_SETPROPERTY is sent when the application informs // the lobby that a specific property has changed. // ---------------------------------------------------------------------- __property TDx_OnSetProperty OnSetProperty = {read=FOnSetProperty, write=FOnSetProperty, nodefault}; // ---------------------------------------------------------------------- // Event: OnSetPropertyResponse() // Description: The OnSetPropertyResponse event is triggered when using // the TDx_PlayLobby::ReceiveLobbyMessageEx() method in the // TDx_PlayLobby::OnReceive() event. // // This event indicates that DPLSYS_SETPROPERTYRESPONSE has // been received by the component's event thread. // // DPLSYS_SETPROPERTYRESPONSE is sent as a confirmation of // the message identified by the RequestId parameter. // ---------------------------------------------------------------------- __property TDx_OnSetPropertyResponse OnSetPropertyResponse = {read=FOnSetPropertyResponse, write=FOnSetPropertyResponse, nodefault}; // ---------------------------------------------------------------------- // Callback: OnEnumAddress() // Description: The OnEnumAddress method is called for every data chunk // that is part of the compound address being parsed by the // EnumAddress method. Set Continue true to continue // enumeration (default value), false to stop enumeration. // ---------------------------------------------------------------------- __property TDx_EnumAddress OnEnumAddress = {read=FOnEnumAddress, write=FOnEnumAddress, nodefault}; // ---------------------------------------------------------------------- // Callback: OnEnumAddressTypes() // Description: This callback is called for every address type required // to build a DirectPlay address, as enumerated by the // EnumAddressTypes method. Set Continue true to continue // enumeration (default value), false to stop enumeration. // ---------------------------------------------------------------------- __property TDx_EnumAddressType OnEnumAddressTypes = {read=FOnEnumAddressTypes, write=FOnEnumAddressTypes, nodefault}; // ---------------------------------------------------------------------- // Callback: OnEnumLocalApplications() // Description: The OnEnumLocalApplications Callback is called for every // application that has be registered with DirectPlay. Set // Continue true to continue enumeration (default value), // false to stop enumeration. // ---------------------------------------------------------------------- __property TDx_EnumLocalApplications OnEnumLocalApplications = {read=FOnEnumLocalApplications, write=FOnEnumLocalApplications, nodefault}; // ========================================================================== public: // ========================================================================== // ---------------------------------------------------------------------- // Property: Created // Description: The Created property is true if the internal // LPDIRECTPLAYLOBBY3 used in this component has been // successfully created, otherwise Created is false. // // To create the internal LPDIRECTPLAYLOBBY3, call the // TDx_PlayLobby::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_PlayLobby method or // fget/fset. eg. DP_OK or DDERR_SURFACELOST or TDX_ERROR // ---------------------------------------------------------------------- __property HRESULT ErrorValue = { read=FGetErrorValue, write=FSetErrorValue, default=DP_OK }; // ---------------------------------------------------------------------- // Property: LobbyEvents // Description: The LobbyEvents property is internally by the // TDx_PlayLobby component to store events used by the // TDx_PlayLobbyThreadClass. // ---------------------------------------------------------------------- __property TList* LobbyEvents = { read=FGetLobbyEvents, write=FSetLobbyEvents, default=NULL }; // ---------------------------------------------------------------------- // Method: ConnectEx() // Description: The ConnectEx method will connect an application to a // session using the information stored in the associated // TDPLConnection component. // // The method will attempt to connect for a maximum of one // minute. // // You can check the current connection settings with // TDx_PlayLobby::GetConnectionSettings() and modify them // using TDx_PlayLobby::SetConnectionSettings(). // // Error values that can be generated are: // // DPERR_CONNECTING // DPERR_INVALIDFLAGS // DPERR_INVALIDPARAMS // Params: pFlags - // The Flags parameter defines a flag indicating how to // establish the connection. // The described effect applies when the flag is set. // // The default value of zero indicates the method will // return after connection is made or it times out. // Flags: // DPCONNECT_RETURNSTATUS - // The method will obtain the connection status and // return immediately. // // The method will return DPERR_CONNECTING // immediately, call the method periodically until // DP_OK is returned. // pIID - // The IID parameter identifies which com interface to // return. // // The possible values are: // // IID_IDirectPlay4A // IID_IDirectPlay4 // pDP - // The DP parameter references a TDx_Play component to be // initialized with the interface specified by the IID // parameter. // ---------------------------------------------------------------------- virtual HRESULT __fastcall ConnectEx( dword pFlags, REFIID pIID, void** pDP ); // ---------------------------------------------------------------------- // Method: Create() // Description: The Create() method is used to automatically create the // internal LPDIRECTPLAYLOBBY3 interface used in the // TDx_PlayLobby component and must be called before any // methods of the TDx_PlayLobby component will function. // ---------------------------------------------------------------------- virtual bool __fastcall Create(); // ---------------------------------------------------------------------- // Method: CreateAddress() // Description: The CreateAddress method will create a TDx_Play address // from a network address specific to a service provider. // // The resulting address identifies the service provider and // includes a network address the service provider can // understand. // // TDx_PlayLobby::CreateCompoundAddress() can be used to // create addresses with more than one data chunk and is // generally much more useful. // // Error values that can be generated are: // // DPERR_BUFFERTOOSMALL // DPERR_INVALIDPARAMS // Params: pSP - // The SP parameter identifies the service provider. // pDataType - // The DataType parameter identifies the type of network // address being used. // // The predefined address types are: // // DPAID_Comport // DPAID_INet // DPAID_INetW // DPAID_INetPort // DPAID_LobbyProvider // DPAID_Modem // DPAID_ModemW // DPAID_Phone // DPAID_PhoneW // DPAID_ServiceProvider // DPAID_TotalSize // pData - // The Data parameter references the network address being // used to create the TDx_Play address. // // The data referenced and how it is interpreted depends on // the type specified in DataType. // // DPAID_ComPort // A TDPComportAddress component defining COM port settings. // // DPAID_INet // An ANSI representation of an IP or domain address. // For Example: "220.150.10.102" or "game.com". // Using an empty string ("") causes the Internet TCP/IP // connection service provider enumerate active sessions on // the specified network address or broadcast on the subnet. // The DataSize must include the terminator. // // DPAID_INetW // A unicode representation of an IP or domain address. // For Example: "220.150.10.102" or "game.com". // Using an empty string ("") causes the Internet TCP/IP // connection service provider enumerate active sessions on // the specified network address or broadcast on the subnet. // The DataSize must include the terminator. // // DPAID_INetPort // An integer specifying which port number to use for // communications. // // DPAID_LobbyProvider // A 16-byte GUID identifying the lobby provider the address // applies to. // // DPAID_Modem // A NULL terminated ANSI value specifying which modem to // use. // Available modems can be determined with // TDx_Play::GetPlayerAddress(). // The DataSize must include the terminator. // // DPAID_ModemW // A NULL terminated unicode value specifying which modem to // use. // Available modems can be determined with // TDx_Play::GetPlayerAddress(). // The DataSize must include the terminator. // // DPAID_Phone // An ANSI value defining a phone number. // The modem service provider will call this number when // TDx_Play::EnumSessions() is called. // If no modem is specified, the first available modem will // be used. // The DataSize must include the terminator. // // DPAID_PhoneW // A unicode value defining a phone number. // The modem service provider will call this number when // TDx_Play::EnumSessions() is called. // If no modem is specified, the first available modem will // be used. // The DataSize must include the terminator. // // DPAID_ServiceProvider // A 16-byte GUID identifying the service provider the // address applies to. // // DPAID_TotalSize // A dword holding the size of the internal DPADDRESS // structure. // pDataSize - // The DataSize parameter defines the size, in bytes, of the // network address in the Data parameter. // pAddress - // The Address parameter will reference the newly created // address if this method returns successfully. // // Set NULL to retrieve the required buffer size in the // AddressSize parameter. // pAddressSize - // The AddressSize parameter references the size, in bytes, // of the Address buffer // // Before the call, set this to the size of the Address // buffer. // After the call, it will indicate how many bytes were // written to the Address buffer. // If the Address buffer was too small, this parameter will // be set to the required size and DPERR_BUFFERTOOSMALL // returned. // ---------------------------------------------------------------------- virtual bool __fastcall CreateAddress( REFGUID pSP, REFGUID pDataType, const void* pData, dword pDataSize, void* pAddress, dword* pAddressSize ); // ---------------------------------------------------------------------- // Method: CreateCompoundAddress() // Description: The CreateCompoundAddress method will create a TDx_Play // address from a network address specific to a service // provider. // // The resulting address is constructed from multiple data // chunks identifying the service provider and includes a // network address the service provider can understand. // // Error values that can be generated are: // // DPERR_BUFFERTOOSMALL // DPERR_INVALIDFLAGS // DPERR_INVALIDPARAMS // Params: pElements - // The Elements parameter references first // TDPCompoundAddressElement component in the array being // used to construct the TDx_Play address. // pElementCount - // The ElementCount parameter defines the number of elements // in the Elements array. // pAddress - // The Address parameter will reference the newly created // address if this method returns successfully. // // Set NULL to retrieve the required buffer size in the // AddressSize parameter. // pAddressSize - // The AddressSize parameter references the size, in bytes, // of the Address buffer // // Before the call, set this to the size of the Address // buffer. // After the call, it will indicate how many bytes were // written to the Address buffer. // If the Address buffer was too small, this parameter will // be set to the required size and DPERR_BUFFERTOOSMALL // returned. // ---------------------------------------------------------------------- virtual bool __fastcall CreateCompoundAddress( TDPCompoundAddressElement* pElements, dword pElementCount, void* pAddress, dword* pAddressSize ); // ---------------------------------------------------------------------- // Method: Destroy() // Description: The Destroy() method is used to automatically destroy the // internal LPDIRECTPLAYLOBBY3 interface used in the // TDx_PlayLobby 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: EnumAddress() // Description: The EnumAddress method will identify and parse data // chunks from a TDx_Play address. // // The TDx_PlayLobby::OnEnumAddress() event will be called // for each data chunk enumerated. // // Error values that can be generated are: // // DPERR_EXCEPTION // DPERR_INVALIDOBJECT // DPERR_INVALIDPARAMS // Params: pAddress - // The Address parameter references the TDx_Play address to // be parsed. // pAddressSize - // The AddressSize parameter defines the size, in bytes, of // the address being enumerated. // pContext - // The Context parameter references application defined data // to be passed to the callback function each time it is // called. // ---------------------------------------------------------------------- virtual bool __fastcall EnumAddress( const void* pAddress, dword pAddressSize, void* pContext ); // ---------------------------------------------------------------------- // Method: EnumAddressTypes() // Description: The EnumAddressTypes method will enumerate the address // types the specified service provider will need when // building a TDx_Play address. // // The TDx_PlayLobby::OnEnumAddressTypes() event will be // called for each address type enumerated. // // Error values that can be generated are: // // DPERR_EXCEPTION // DPERR_INVALIDOBJECT // DPERR_INVALIDPARAMS // Params: pSP - // The SP parameter identifies the service provider whose // address types are to be enumerated. // pContext - // The Context parameter references application defined data // to be passed to the callback function each time it is // called. // ---------------------------------------------------------------------- virtual bool __fastcall EnumAddressTypes( REFGUID pSP, void* pContext ); // ---------------------------------------------------------------------- // Method: EnumLocalApplications() // Description: The EnumLocalApplications method will enumerate any // applications that have been registered using // TDx_PlayLobby::RegisterApplication(). // // The TDx_PlayLobby::OnEnumLocalApplications() event will // be called for each application enumerated. // // Error values that can be generated are: // // DPERR_GENERIC // DPERR_INVALIDINTERFACE // DPERR_INVALIDOBJECT // DPERR_INVALIDPARAMS // DPERR_OUTOFMEMORY // Params: pContext - // The Context parameter references application defined data // to be passed to the callback function each time it is // called. // ---------------------------------------------------------------------- virtual bool __fastcall EnumLocalApplications( void* pContext ); // ---------------------------------------------------------------------- // Method: GetConnectionSettings() // Description: The GetConnectionSettings method will retrieve the // TDPLConnection information associated with the lobby. // // These connection settings are used to start and connect a // specific application. // They will be identical to those passed to // TDx_PlayLobby::RunApplication() by the lobby client or // set using TDx_PlayLobby::SetConnectionSettings(). // // Error values that can be generated are: // // DPERR_BUFFERTOOSMALL // DPERR_GENERIC // DPERR_INVALIDINTERFACE // DPERR_INVALIDOBJECT // DPERR_INVALIDPARAMS // DPERR_NOTLOBBIED // DPERR_OUTOFMEMORY // Params: pAppID - // The AppID parameter identifies the application for which // the connection settings are to be retrieved. // // Only set this parameter when the method is called from a // lobby client. // Zero should be set when calling the method from an // application. // pData - // The Data parameter will reference the connection settings // if the method returns successfully. // // Set NULL to retrieve the required buffer size in the // DataSize parameter. // pDataSize - // The DataSize parameter references the size, in bytes, of // the Data buffer. // // Before the call, set this to the size of the Data buffer. // After the call, it will indicate how many bytes were // written to the Data buffer. // If the Data buffer was too small, this parameter will be // set to the required size and DPERR_BUFFERTOOSMALL // returned. // ---------------------------------------------------------------------- virtual bool __fastcall GetConnectionSettings( dword pAppID, void* pData, dword* pDataSize ); // ---------------------------------------------------------------------- // Method: Internal_EnumAddressCallback() // Description: The Internal_EnumAddressCallback method is used to // process enumeration for TDx_PlayLobby::EnumAddress(). // Params: pDataType - // The DataType parameter // pDataSize - // The DataSize parameter // pData - // The Data parameter // pContext - // The Context parameter // ---------------------------------------------------------------------- static BOOL __stdcall Internal_EnumAddressCallback( REFGUID pDataType, DWORD pDataSize, LPCVOID pData, LPVOID pContext ); // ---------------------------------------------------------------------- // Method: Internal_EnumAddressTypesCallback() // Description: The Internal_EnumAddressTypesCallback method is used to // process enumeration for // TDx_PlayLobby::EnumAddressTypes(). // Params: pDataType - // The DataType parameter // pContext - // The Context parameter // pFlags - // The Flags parameter // ---------------------------------------------------------------------- static BOOL __stdcall Internal_EnumAddressTypesCallback( REFGUID pDataType, LPVOID pContext, DWORD pFlags ); // ---------------------------------------------------------------------- // Method: Internal_EnumLocalApplicationsCallback() // Description: The Internal_EnumLocalApplicationsCallback method is used // to process enumeration for // TDx_PlayLobby::EnumLocalApplicationsCallback(). // Params: pAppInfo - // The AppInfo parameter // pContext - // The Context parameter // pFlags - // The Flags parameter // ---------------------------------------------------------------------- static BOOL __stdcall Internal_EnumLocalApplicationsCallback( LPCDPLAPPINFO pAppInfo, LPVOID pContext, DWORD pFlags ); // ---------------------------------------------------------------------- // Method: ReceiveLobbyMessage() // Description: The ReceiveLobbyMessage method will retrieve messages // sent between lobby client and application. // // Error values that can be generated are: // // DPERR_APPNOTSTARTED // DPERR_BUFFERTOOSMALL // DPERR_GENERIC // DPERR_INVALIDINTERFACE // DPERR_INVALIDOBJECT // DPERR_INVALIDPARAMS // DPERR_NOMESSAGES // DPERR_OUTOFMEMORY // Params: pAppID - // The AppID parameter identifies which applications // messages to retrieve. // // Only valid when the method is being called by a lobby // client. // Set zero when calling from an application. // pMessageFlags - // The MessageFlags parameter defines flags indicating the // type of message being retrieved. // The described effect applies when the flag is set. // // The default setting of zero indicates a custom message // defined by the sender. // Flags: // DPLMSG_STANDARD - // The message is a standard DirectPlay defined // message. // // Processing of the message is optional. // DPLMSG_SYSTEM - // The message was generated by the system to inform // the lobby of application status changes. // pData - // The Data parameter will reference the retrieved message // if the method returns successfully. // // Set NULL to retrieve the required buffer size in the // DataSize parameter. // pDataSize - // The DataSize parameter references the size, in bytes, of // the Data buffer. // // Before the call, set this to the size of the Data buffer. // After the call, it will indicate how many bytes were // written to the Data buffer. // If the Data buffer was too small, this parameter will be // set to the required size and DPERR_BUFFERTOOSMALL // returned. // ---------------------------------------------------------------------- virtual bool __fastcall ReceiveLobbyMessage( dword pAppID, dword* pMessageFlags, void* pData, dword* pDataSize ); // ---------------------------------------------------------------------- // Method: ReceiveLobbyMessageEx() // Description: The ReceiveLobbyMessageEx method will retrieve messages // sent between lobby client and application, generating // OnDPLMSG_x events when appropriate. // // Error values that can be generated are: // // DPERR_APPNOTSTARTED // DPERR_BUFFERTOOSMALL // DPERR_GENERIC // DPERR_INVALIDINTERFACE // DPERR_INVALIDOBJECT // DPERR_INVALIDPARAMS // DPERR_NOMESSAGES // DPERR_OUTOFMEMORY // Params: pAppID - // The AppID parameter identifies which applications // messages to retrieve. // // Only valid when the method is being called by a lobby // client. // Set zero when calling from an application. // ---------------------------------------------------------------------- virtual bool __fastcall ReceiveLobbyMessageEx( DWORD pAppID ); // ---------------------------------------------------------------------- // Method: RegisterApplication() // Description: The RegisterApplication method is used to register lobby // aware applications with DirectPlay so they can be // launched by a lobby. // // Registration need only be done once and // TDx_PlayLobby::UnregisterApplication() can be used to // unregister an application when it is uninstalled. // // Error values that can be generated are: // // DPERR_INVALIDFLAGS // DPERR_INVALIDPARAMS // Params: pAppDesc - // The AppDesc parameter references a TDPApplicationDesc // component holding the values required to register the // application. // ---------------------------------------------------------------------- virtual HRESULT __fastcall RegisterApplication( TDPApplicationDesc* pAppDesc ); // ---------------------------------------------------------------------- // Method: RunApplication() // Description: The RunApplication method allows a lobby client to start // an application, passing it all the required session // connection information. // // Once the application process has been created, the lobby // client will receive a system message indicating the // applications status. // // If the application is hosting the session, wait for a // DPLSYS_DPLAYCONNECTSUCCEEDED message before starting // other applications that wish to join the session. // // Failure to create or join a session generates a // DPLSYS_DPLAYCONNECTFAILED message and a terminating // application will generate a DPLSYS_APPTERMINATED // message. // // Once the application has read the connection settings, it // sends a DPLSYS_CONNECTIONSETTINGSREAD message. Do not // release the lobby interface until this message is // retrieved by either the synchronization event or a call // to TDx_PlayLobby::ReceiveLobbyMessage() or // TDx_PlayLobby::ReceiveLobbyMessageEx(). // // Error values that can be generated are: // // DPERR_CANTCREATEPROCESS // DPERR_GENERIC // DPERR_INVALIDINTERFACE // DPERR_INVALIDOBJECT // DPERR_INVALIDPARAMS // DPERR_OUTOFMEMORY // DPERR_UNKNOWNAPPLICATION // Params: pAppID - // The AppID parameter reference the identifier assigned to // the application if the method returns successfully. // // This identifier is used by // TDx_PlayLobby::SendLobbyMessage() and // TDx_PlayLobby::ReceiveLobbyMessage(). // pConn - // The Conn parameter references a TDPLConnection component // detailing which application to start and the relevant // session connection information. // ---------------------------------------------------------------------- virtual bool __fastcall RunApplication( dword* pAppID, TDPLConnection* pConn ); // ---------------------------------------------------------------------- // Method: SendLobbyMessage() // Description: The SendLobbyMessage method will send messages between // lobby client and application. // // Error values that can be generated are: // // DPERR_APPNOTSTARTED // DPERR_BUFFERTOOLARGE // DPERR_GENERIC // DPERR_INVALIDINTERFACE // DPERR_INVALIDOBJECT // DPERR_INVALIDPARAMS // DPERR_OUTOFMEMORY // DPERR_TIMEOUT // Params: pFlags - // The Flags parameter defines flags indicating the type of // message being sent. // The described effect applies when the flag is set. // // The default setting of zero indicates an application // defined message is being sent. // Flags: // DPLMSG_STANDARD - // The message is a standard DirectPlay defined // message. // pAppID - // The AppID parameter identifies the destination // application for the message. // // Set zero when the method is called from an application. // This is the identifier returned by // TDx_PlayLobby::RunApplication(). // pData - // The Data parameter references the message data to be // sent. // // The standard DirectX message structures used when // DPLMSG_STANDARD is set are: // // typedef struct { // dword Type; // dword RequestID; // GUID Player; // GUID PropertyTag; // } TDPLMSG_GetProperty, FAR *LPDPLMSG_GetProperty; // // // typedef struct { // dword Type; // dword RequestID; // GUID Player; // GUID PropertyTag; // dword DataSize; // dword PropertyData[1]; // } TDPLMSG_SetProperty, FAR *LPDPLMSG_SetProperty; // // For the above structures, the following descriptions // apply to their members. // // Type // The type of system message that is being sent. // Possible values are DPLSYS_GETPROPERTY and // DPLSYS_SETPROPERTY respectivly. // A system DPLSYS_GETPROPERTYRESPONSE or // DPLSYS_SETPROPERTYRESPONSE will be triggered. // // RequestID // An application defined unique identifier used to match // requests to lobby responses. // // Player // The GUID of the player the property applies to. // Non player specific information will have this set to // GUID_NULL. // // PropertyTag // The GUID of the property being set. Standard DirectX // properties are: // // DPLPROPERTY_LobbyGuid // DPLPROPERTY_MessagesSupported // DPLPROPERTY_PlayerGuid // DPLPROPERTY_PlayerScore // // DataSize // The size of the property data. // // PropertyData // A buffer of information that is to be interpreted based // on the PropertyTag member. // pDataSize - // The DataSize parameter defines the size, in bytes, of the // Data buffer. // ---------------------------------------------------------------------- virtual bool __fastcall SendLobbyMessage( dword pFlags, dword pAppID, void* pData, dword pDataSize ); // ---------------------------------------------------------------------- // Method: SetConnectionSettings() // Description: The SetConnectionSettings method will modify the // application start and connection information associated // with the lobby. // // Error values that can be generated are: // // DPERR_GENERIC // DPERR_INVALIDINTERFACE // DPERR_INVALIDOBJECT // DPERR_INVALIDPARAMS // DPERR_OUTOFMEMORY // Params: pAppID - // The AppID parameter identifies which applications // connection settings are being changed. // // Set zero when the method is called from an application. // This is the identifier returned by // TDx_PlayLobby::RunApplication(). // pConn - // The Conn parameter references a TDPLConnection component // holding the new connection information. // ---------------------------------------------------------------------- virtual bool __fastcall SetConnectionSettings( dword pAppID, TDPLConnection* pConn ); // ---------------------------------------------------------------------- // Method: UnregisterApplication() // Description: The UnRegisterApplication method is used to deregister a // lobby aware application so the uninstall process can be // complete. // // Error values that can be generated are: // // DPERR_INVALIDFLAGS // DPERR_INVALIDPARAMS // DPERR_UNKNOWNAPPLICATION // Params: pApplication - // The Application parameter identifies which applications // registry entries to delete. // ---------------------------------------------------------------------- virtual bool __fastcall UnregisterApplication( REFGUID pApplication ); // ---------------------------------------------------------------------- // Method: WaitForConnectionSettings() // Description: The WaitForConnectionSettings method will make an // application wait for connection settings. // // When the lobby client calls // TDx_PlayLobby::RunApplication(), it will not create a new // application instance, instead sending a // DPLSYS_NEWCONNECTIONSETTINGS message to the waiting // application. // // The application can then obtain the connection settings // with TDx_PlayLobby::GetConnectionSettings() and use // TDx_PlayLobby::ConnectEx() to join the session. // // Error values that can be generated are: // // DPERR_INVALIDFLAGS // DPERR_UNAVAILABLE // Params: pFlags - // The Flags parameter defines a flag indicating whether // wait mode should be activated or cancelled. // The described effect applies when the flag is set. // // The default value of zero indicates the application // should be placed in wait mode. // Flags: // DPLWAIT_CANCEL - // Take the application out of wait mode. // // This will occur automatically on receipt of a // DPLSYS_NEWCONNECTIONSETTINGS message by the // application. // ---------------------------------------------------------------------- virtual bool __fastcall WaitForConnectionSettings( dword pFlags ); // ---------------------------------------------------------------------- // Constructor() and Destructor() // ---------------------------------------------------------------------- __fastcall TDx_PlayLobby(TComponent* Owner); virtual __fastcall ~TDx_PlayLobby(); // ---------------------------------------------------------------------- // The following properties and methods are used internally by // TDx_Play_Library and should not be used. // ---------------------------------------------------------------------- __property LPDIRECTPLAYLOBBY3 Internal_LPDIRECTPLAYLOBBY3 = { read=FGetInternal_LPDIRECTPLAYLOBBY3, write=FSetInternal_LPDIRECTPLAYLOBBY3, nodefault }; __property LPDIRECTPLAYLOBBY3* Internal_LPDIRECTPLAYLOBBY3_Ptr = { read=FGetInternal_LPDIRECTPLAYLOBBY3_Ptr, nodefault }; void __fastcall Internal_LPDIRECTPLAYLOBBY3_Update(); __property LPDIRECTPLAYLOBBY Internal_LPDIRECTPLAYLOBBY = { read=FGetInternal_LPDIRECTPLAYLOBBY, write=FSetInternal_LPDIRECTPLAYLOBBY, nodefault }; __property LPDIRECTPLAYLOBBY* Internal_LPDIRECTPLAYLOBBY_Ptr = { read=FGetInternal_LPDIRECTPLAYLOBBY_Ptr, nodefault }; void __fastcall Internal_LPDIRECTPLAYLOBBY_Update(); // ========================================================================== protected: // ========================================================================== // ---------------------------------------------------------------------- // Property Access Methods // ---------------------------------------------------------------------- bool __fastcall FGetCreated(); void __fastcall FSetCreated( bool pCreated ); HRESULT __fastcall FGetErrorValue(); void __fastcall FSetErrorValue( HRESULT pErrorValue ); TList* __fastcall FGetLobbyEvents(); void __fastcall FSetLobbyEvents( TList* pLobbyEvents ); int __fastcall FGetNumLobbies(); void __fastcall FSetNumLobbies( int pNumLobbies ); bool __fastcall FGetUseAnsiString(); void __fastcall FSetUseAnsiString( bool pUseAnsiString ); // ========================================================================== private: // ========================================================================== // ---------------------------------------------------------------------- // Internal Interface Access // ---------------------------------------------------------------------- LPDIRECTPLAYLOBBY3 __fastcall FGetInternal_LPDIRECTPLAYLOBBY3(); void __fastcall FSetInternal_LPDIRECTPLAYLOBBY3( LPDIRECTPLAYLOBBY3 pLPDIRECTPLAYLOBBY3 ); LPDIRECTPLAYLOBBY3* __fastcall FGetInternal_LPDIRECTPLAYLOBBY3_Ptr(); LPDIRECTPLAYLOBBY __fastcall FGetInternal_LPDIRECTPLAYLOBBY(); void __fastcall FSetInternal_LPDIRECTPLAYLOBBY( LPDIRECTPLAYLOBBY pLPDIRECTPLAYLOBBY ); LPDIRECTPLAYLOBBY* __fastcall FGetInternal_LPDIRECTPLAYLOBBY_Ptr(); // ---------------------------------------------------------------------- // Property Variables // ---------------------------------------------------------------------- bool fCreated; HRESULT fErrorValue; TList* fLobbyEvents; dword fNumLobbies; bool fUseAnsiString; // ---------------------------------------------------------------------- // Interface Variables // ---------------------------------------------------------------------- LPDIRECTPLAYLOBBY3 fLPDIRECTPLAYLOBBY3; LPDIRECTPLAYLOBBY fLPDIRECTPLAYLOBBY; // ---------------------------------------------------------------------- // Event Variables // ---------------------------------------------------------------------- TDx_OnSystemMessage FOnAppTerminated; TDx_OnSystemMessage FOnConnectionSettingsRead; TDx_Event FOnCreate; TDx_Event FOnDestroy; TDx_Error FOnError; TDx_OnLobbyGeneric FOnGeneric; TDx_OnGetProperty FOnGetProperty; TDx_OnGetPropertyResponse FOnGetPropertyResponse; TDx_OnSystemMessage FOnNewConnectionSettings; TDx_OnNewSessionHost FOnNewSessionHost; TDx_OnSystemMessage FOnPlayConnectFailed; TDx_OnSystemMessage FOnPlayConnectSucceeded; TDx_OnDPLReceive FOnReceive; TDx_OnSetProperty FOnSetProperty; TDx_OnSetPropertyResponse FOnSetPropertyResponse; // ---------------------------------------------------------------------- // Callback Variables // ---------------------------------------------------------------------- TDx_EnumAddress FOnEnumAddress; TDx_EnumAddressType FOnEnumAddressTypes; TDx_EnumLocalApplications FOnEnumLocalApplications; }; // -------------------------------------------------------------------------- #endif // --------------------------------------------------------------------------