Microsoft DirectX 8.0 (C++)

IDirectPlay8Peer::Connect

Establishes the connection to all the peers in a peer-to-peer session. Once 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 way of the IDirectPlay8Peer::SendTo method until the connection has completed.

Before this method is called, you can obtain application descriptions and the addresses of the associated hosts by calling IDirectPlay8Peer::EnumHosts. The EnumHosts method returns a DPN_APPLICATION_DESC structure for each currently hosted application. The structure describes the application, including the instance GUID of the application.

If this method is called asynchronously (which is the default choice) and returns DPNSUCCESS_PENDING, 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 pvPlayerContext,
void *const pvAsyncContext,
DPNHANDLE *const phAsyncHandle,
const DWORD dwFlags
);

Parameters

pdnAppDesc
Pointer to a DPN_APPLICATION_DESC structure that describes the application. Only some of the members of this structure are used by this method. The only members that you must set are dwSize and guidApplication. You can also set guidInstance, pwszPassword, and dwFlags.
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 interface that specifies the 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 may be set to NULL if no additional connection validation is provided by the user code.
dwUserConnectDataSize
Variable of type DWORD that specifies the size of the data contained in the pvUserConnectData parameter.
pvPlayerContext
Pointer to the context value of the local player. This value is preset when the local computer handles the DPN_MSGID_CREATE_PLAYER message. This parameter is optional and may be set to NULL.
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 IDirectPlay8Peer::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 flags.
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. Your message handler still receives a DPN_MSGID_CONNECT_COMPLETE message, so that you can process any connection reply data from the host. You will receive this message before IDirectPlay8Peer::Connect returns.

Return Values

Returns S_OK if this method is processed synchronously and is successful. By default, this method runs asynchronously and normally returns DPNSUCCESS_PENDING. It may also return 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

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.

If this method is called asynchronously (which is the default choice), when the connection completes a DPN_MSGID_CONNECT_COMPLETE message is posted to the application's message handler. If this method returns an error, no completion message is posted.

When this method is called, a DPN_MSGID_INDICATE_CONNECT message is posted to the host's message handler. When the host handles this message, it can specify connection reply data that the player will receive with the DPN_MSGID_CONNECT_COMPLETE message. If the host accepts the connection, the connection reply data might contain custom startup information. If the connection was rejected, the connection reply data might contain an explanation of the rejection.

You must call IDirectPlay8Peer::Close to end the connection to the host.

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.