IDirectPlay8Client::Connect Method

Establishes the connection to the server.

Syntax

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

[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 member of this structure that you must set is the guidApplication member. You can also set guidInstance, pwszPassword, dwFlags, and dwSize.

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, network interface card, 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. Microsoft® 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 you can pass NULL to bypass the connection validation provided by the user code.

dwUserConnectDataSize

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

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 IDirectPlay8Client::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 flag.

DPNCONNECT_OKTOQUERYFORADDRESSING

Setting this flag will display a standard 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 Value

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	The connection request was rejected. Check the ReplyData member of the DPN_MSGID_CONNECT_COMPLETE type for details.
DPNERR_INVALIDAPPLICATION	The globally unique identifier (GUID) supplied for the application is invalid.
DPNERR_INVALIDDEVICEADDRESS	The address for the local computer or adapter is invalid.
DPNERR_INVALIDFLAGS	The flags passed to this method are invalid.
DPNERR_INVALIDHOSTADDRESS	The specified remote address is invalid.
DPNERR_INVALIDINSTANCE	The GUID for the application instance is invalid.
DPNERR_INVALIDINTERFACE	The interface parameter is invalid. This value will be returned in a connect request if the connecting player was not a client in a client/server game or a peer in a peer-to-peer game.
DPNERR_INVALIDPASSWORD	An invalid password was supplied when attempting to join a session that requires a password.
DPNERR_NOCONNECTION	No communication link was established.
DPNERR_NOTHOST	The client attempted to connect to a nonhost computer. Additionally, this error value may be returned by a nonhost that tried to set the application description.
DPNERR_SESSIONFULL	The request to connect to the host or server failed because the maximum number of players allotted for the session has been reached.
DPNERR_ALREADYCONNECTED	The object is already connected to the session.
DPNERR_ALREADYINITIALIZED	The object has already been initialized.

Remarks

It is not required to enumerate hosts before calling IDirectPlay8Client::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 Transmission Control Protocol/Internet Protocol (TCP/IP) service provider or to prevent redialing with the modem service provider, keep the enumeration active when calling the IDirectPlay8Client::Connect method. To prevent the enumeration from completing, set the dwEnumCount parameter to INFINITE and do not use the IDirectPlay8Client::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 IDirectPlay8Client::Connect method. To pass the address objects to IDirectPlay8Client::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 IDirectPlay8Client::Close is called.

Before this method is called, you can obtain an application description by calling IDirectPlay8Client::EnumHosts. When you call IDirectPlay8Client::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 IDirectPlay8Client::Connect method.

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.

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

If IDirectPlay8Client::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 IDirectPlay8Client::Connect method will return with DPN_OK.
• Connection fails because the server rejects the connection. The application will receive a DPN_MSGID_CONNECT_COMPLETE message containing the DPNERR_HOSTREJECTEDCONNECTION failure code. The IDirectPlay8Client::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 server returns with the rejection.
• Connection fails for any other reason. The application will not receive a DPN_MSGID_CONNECT_COMPLETE message, and the IDirectPlay8Client::Connect method will return with the appropriate error code.

If IDirectPlay8Client::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.

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. All outstanding enumerations are canceled with the return of DPNERR_USERCANCEL.

To close the connection established with this method, call the IDirectPlay8Client::Close method.

Data Value Summary specifies the required addressing information for each service provider.

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.