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. When you call EnumHosts, DPN_MSGID_ENUM_HOSTS_RESPONSE messages are sent to your message handler with the IDirectPlay8Address objects and the DPN_APPLICATION_DESC structure for each host found. This information can be passed without modification to the Connect method.

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

[in] 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

[in] Pointer to an IDirectPlay8Address interface that specifies the addressing information to use to connect to the computer that is hosting. The user can be queried for any missing address information if you set the DPNENUMHOSTS_OKTOQUERYFORADDRESSING flag in the dwFlags parameter.

pDeviceInfo

[in] Pointer to an IDirectPlay8Address object that specifies what network adapter (for example, NIC, modem, and so on) to use to connect to the server. Some service providers allow this parameter to be NULL or be an address object containing only the service provider component. In this case, they will use the most appropriate device to reach the designated host. If you set the DPNCONNECT_OKTOQUERYFORADDRESSING flag in dwFlags, the user can be queried for any missing address information.

pdnSecurity

[in] Reserved. Must be NULL.

pdnCredentials

[in] Reserved. Must be NULL.

pvUserConnectData

[in] Pointer to application-specific data provided to the host or server to further validate the connection. DirectPlay will make a copy of this data when the method is called and therefore you can modify or destroy this data once the connection is complete. This data is sent to the DPN_MSGID_INDICATE_CONNECT message in the pvUserConnectData member. This parameter is optional and can be set to NULL if no additional connection validation is provided by the user code.

dwUserConnectDataSize

[in] Variable of type DWORD that specifies the size of the data contained in the pvUserConnectData parameter.

pvPlayerContext

[in] 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 can be set to NULL.

pvAsyncContext

[in] 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 can be set to NULL.

phAsyncHandle

[out] 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

[in] 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 might also return one of the following error values.

Remarks

It is not required to enumerate hosts before calling Connect if you know the appropriate host and device information.

If you do call the IDirectPlay8Client::EnumHosts method and you want to ensure better network address translation (NAT) and proxy support when using the TCP/IP service provider or prevent redialing with the modem service provider, keep the enumeration active when calling Connect. To prevent the enumeration from completing, set the dwEnumCount parameter to INFINITE and do not use the IDirectPlay8Peer::CancelAsyncOperation to terminate the enumeration before the connect operation has completed. You should also pass the pAddressSender and pAddressDevice address objects in the DPNMSG_ENUM_HOSTS_RESPONSE message without modification into the pHostAddr and pDeviceInfo parameters of the Connect method. To pass the address objects to Connect outside of the callback function, use IDirectPlay8Address::Duplicate or IDirectPlay8Address::AddRef to prevent the object from being destroyed, and store the pointers using thread-safe code. DirectPlay will automatically cancel the enumeration when the connect completes with DPN_OK or when IDirectPlay8Peer::Close is called.

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 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.

If Connect is called synchronously, the following outcomes are possible.

• Connection Successful. The application will receive a DPN_MSGID_CONNECT_COMPLETE message containing the success code, and the Connect method will return with DPN_OK.
• Connection fails because the host rejects the connection. The application will receive a DPN_MSGID_CONNECT_COMPLETE message containing the DPNERR_HOSTREJECTEDCONNECTION failure code. The Connect method will also return with the error code DPNERR_HOSTREJECTEDCONNECTION. The DPN_MSGID_CONNECT_COMPLETE message provides an opportunity for the client application to inspect any data the host returns with the rejection.
• Connection fails for any other reason. The application will not receive a DPN_MSGID_CONNECT_COMPLETE message and the Connect method will return with the appropriate error code.

If Connect is called asynchronously, the method returns immediately with DPNSUCCESS_PENDING. A DPN_MSGID_CONNECT_COMPLETE message will follow after the connection completes, containing the result of the connection. The only time the method does not return DPNSUCCESS_PENDING is when validation of the supplied parameters fails, in which case the appropriate error code is returned.

When the connection request completes, all outstanding enumerations are canceled with the return of DPNERR_USERCANCEL.

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 might 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/XP: Available as a redistributable for Windows 2000 and later.
  Windows 98/Me: Available as a redistributable for Windows 98 and later.
  Header: Declared in Dplay8.h.