Microsoft DirectX 8.0 (C++) |
Establishes the connection to the server. After a connection is established, the communication channel on the interface is open and the application should expect messages to arrive immediately. No messages can be sent by means of the IDirectPlay8Client::Send method until the connection has completed.
Before this method is called, you can obtain an application description by calling IDirectPlay8Client::EnumHosts. The EnumHosts method returns a DPN_APPLICATION_DESC structure for each hosted application. The structure describes the application, including the GUID of the application.
If this method is called asynchronously (by default), when the connection completes a DPN_MSGID_CONNECT_COMPLETE message is sent to the application's message handler.
HRESULT Connect( const DPN_APPLICATION_DESC *const pdnAppDesc, IDirectPlay8Address *const pHostAddr, IDirectPlay8Address *const pDeviceInfo, const DPN_SECURITY_DESC *const pdnSecurity, const DPN_SECURITY_CREDENTIALS *const pdnCredentials, const void *const pvUserConnectData, const DWORD dwUserConnectDataSize, void *const pvAsyncContext, DPNHANDLE *const phAsyncHandle, const DWORD dwFlags );
Returns S_OK if this method is processed synchronously and is successful. If the request is processed asynchronously, S_OK will be returned if the method is instantly processed. By default, this method is run asynchronously and generally returns DPNSUCCESS_PENDING or one of the following error values.
Although multiple enumerations can be run concurrently, and can be run across the duration of a connection, only one connection is allowed per interface. To establish a connection to more than one application, you must create another interface.
When this method is called, a DPN_MSGID_INDICATE_CONNECT message is posted to the server's message handler. On retrieval of this message, the host can pass back connection reply data to the Connect method. Connection reply data can send a message indicating that the host does not approve the connection. The calling application can then handle this reply appropriately.
The hResultCode on the completion will indicate S_OK if the Connect() attempt was successful, or an error otherwise. If the Host player returned anything other than S_OK from the DPN_MSGID_INDICATE_CONNECT message, the likely error code in the completion will be DPNERR_HOSTREJECTEDCONNECTION.
When the connection completes, a DPN_MSGID_CONNECT_COMPLETE message is sent to the application's message handler.
To close the connection established with this method, call the IDirectPlay8Client::Close method.
Note If you set the DPNCONNECT_OKTOQUERYFORADDRESSING flag in dwFlags, the service provider may attempt to display a dialog box to ask the user to complete the address information. You must have a visible window present when the service provider tries to display the dialog box, or your application will lock.
Windows NT/2000: Available as a redistributable for Windows 2000 and later.
Windows 95/98: Available as a redistributable for Windows 95 and later.
Header: Declared in Dplay8.h.