IDirectPlayLobby3::Connect

The IDirectPlayLobby3::Connect method connects an application to the session specified by the DPLCONNECTION structure currently stored with the DirectPlayLobby object.

Note This method will return an IDirectPlay2 or IDirectPlay2A interface. If this is not the desired DirectPlay COM interface, the application must obtain the correct interface (for example, IDirectPlay4 or IDirectPlay4A) by using QueryInterface and release this interface. A newer method, IDirectPlayLobby3::ConnectEx, allows the application to specify which DirectPlay COM interface to return.

By default, Connect returns after a connection is made or when the connection has timed out. If you use the DPCONNECT_RETURNSTATUS flag, Connect returns immediately with a DPERR_CONNECTING error code indicating the connection is in progress. The application must continue calling this method periodically until DP_OK or a failure code is returned. The application can cancel the connection by releasing the IDirectPlayLobby3 interface.

HRESULT Connect(
  DWORD dwFlags,
  LPDIRECTPLAY2 *lplpDP,
  IUnknown FAR *pUnk
);

Parameters

dwFlags

Flags indicating how the connection is to be done. By default (dwFlags = 0), the method returns once a connection has been established or the operation has timed out.

DPCONNECT_RETURNSTATUS

Returns immediately with the status of the connection. The application must continue calling Connect until a success or error code is returned.

lplpDP

Pointer to a pointer to be initialized with a valid interface—either IDirectPlay2 (if called on IDirectPlayLobby3) or IDirectPlay2A (if called on IDirectPlayLobby3A). Note that if some other interface is desired, the application should use QueryInterface to obtain a pointer to the new interface and to release this one. Alternatively, the ConnectEx method can be used.

pUnk

Pointer to the containing IUnknown interface. This parameter is provided for future compatibility with COM aggregation features. Presently, however, IDirectPlayLobby3::Connect returns an error if this parameter is anything but NULL.

Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

The method returns DPERR_CONNECTING while the connection operation is in progress. Call the methods again to get an updated status.

Remarks

There is an upper limit of one minute on connection time-out.

After this method is successfully completed, the application can skip the process of calling IDirectPlay4::InitializeConnection, IDirectPlay4::EnumSessions, and IDirectPlay4::Open. The application should not ask the user a name but instead create a player using the player name information in the DPLCONNECTION structure.

Before calling this method, the application can examine the connection settings that will be used to start the application by using the IDirectPlayLobby3::GetConnectionSettings method. The application then can modify these settings and set them by using the IDirectPlayLobby3::SetConnectionSettings method. The application should pay particular attention to the DPSESSIONDESC2 structure to ensure that the proper session properties are set, especially dwFlags, dwMaxPlayers, and the dwUser members.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
  Header: Declared in dplobby.h.
  Import Library: Use dplayx.lib.

See Also

IDirectPlayLobby3::ConnectEx