IDirectPlay8Peer::Connect Method

Establishes the connection to all the peers in a peer-to-peer session. When 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.

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 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 interface that specifies the 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 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 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 Value

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.

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_ALREADYINITIALIZED	The object has already been initialized.

Remarks

Before this method is called, you can obtain application descriptions and the addresses of the associated hosts by calling IDirectPlay8Peer::EnumHosts. When you call IDirectPlay8Peer::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 IDirectPlay8Peer::Connect method.

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

If you do call the IDirectPlay8Peer::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 IDirectPlay8Peer::Connect method. 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 IDirectPlay8Peer::Connect method. To pass the address objects to IDirectPlay8Peer::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 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 host 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 host 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.

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

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.