Microsoft DirectX 8.0 (C++)

IDirectPlay8Client::Connect

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
);

Parameters

pdnAppDesc
Pointer to a DPN_APPLICATION_DESC structure that describes the application. The only member of this structure that you must set is the guidApplication member. Only some of the members of this structure are used by this method. The only member that you must set is guidApplication. You can also set guidInstance, pwszPassword, dwFlags, and dwSize.
pHostAddr
Pointer to an IDirectPlay8Address interface that specifies the addressing information to use to connect to the computer that is hosting.
pDeviceInfo
Pointer to an IDirectPlay8Address object that specifies what network adapter (for example, NIC, modem, and so on) to use to connect to the server.
pdnSecurity
Reserved. Must be NULL.
pdnCredentials
Reserved. Must be NULL.
pvUserConnectData
Pointer to application-specific data provided to the host or server to further validate the connection. This data is sent to the DPN_MSGID_INDICATE_CONNECT message in the pvUserConnectData member. This parameter is optional and you may pass NULL to bypass the connection validation provided by the user code.
dwUserConnectDataSize
Variable of type DWORD that specifies the size of the data contained in pvUserConnectData.
pvAsyncContext
Pointer to the user-supplied context, which is returned in the pvUserContext member of the DPN_MSGID_CONNECT_COMPLETE system message. This parameter is optional and may be set to NULL.
phAsyncHandle
A DPNHANDLE. When the method returns, phAsyncHandle will point to a handle that you can pass to IDirectPlay8Client::CancelAsyncOperation to cancel the operation. This parameter must be set to NULL if you set the DPNCONNECT_SYNC flag in dwFlags.
dwFlags
Flag that describes the connection mode. You can set the following flag.
DPNCONNECT_OKTOQUERYFORADDRESSING
Setting this flag will display a standard Microsoft® DirectPlay® dialog box, which queries the user for more information if not enough information is passed in this method.
DPNCONNECT_SYNC
Process the connection request synchronously. Setting this flag does not generate a DPN_MSGID_CONNECT_COMPLETE system message.

Return Values

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.

DPNERR_HOSTREJECTEDCONNECTION
DPNERR_INVALIDAPPLICATION
DPNERR_INVALIDDEVICEADDRESS
DPNERR_INVALIDFLAGS
DPNERR_INVALIDHOSTADDRESS
DPNERR_INVALIDINSTANCE
DPNERR_INVALIDINTERFACE
DPNERR_INVALIDPASSWORD
DPNERR_NOCONNECTION
DPNERR_NOTHOST
DPNERR_SESSIONFULL
DPNERR_ALREADYCONNECTED

Remarks

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.

Requirements

  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.