Platform SDK: DirectX

IDirectPlay4::Open

The IDirectPlay4::Open method is used to join a session that has been enumerated by a previous call to IDirectPlay4::EnumSessions or to create a new session that other users can enumerate and join.

HRESULT Open(
  LPDPSESSIONDESC2 lpsd,
  DWORD dwFlags
);

Parameters

lpsd
Pointer to the DPSESSIONDESC2 structure describing the session to be created or joined. If a session is being joined, then only the dwSize, guidInstance, and lpszPassword data members need to be specified. A password need only be supplied if the enumerated session had the DPSESSION_PASSWORD flag set.

If a session is being created, then the application must completely fill out the DPSESSIONDESC2 structure with the properties of the sessions to be created. The guidInstance will be generated by DirectPlay.

dwFlags
One and only one of the following flags:
DPOPEN_CREATE
Create a new instance of an application session. The local computer will be the name server and host of the session.
DPOPEN_JOIN
Join an existing instance of an application session for the purpose of participating. The application will be able to create players and send and receive messages.
DPOPEN_RETURNSTATUS
If this flag is specified, the method will not display any dialog boxes showing the connection progress status. If the connection cannot be made immediately, the method will return with the DPERR_CONNECTING error. The application must keep calling Open until either DP_OK is returned, indicating successful completion, or some other error code is returned, indicating an error.

Return Values

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

DPERR_ACCESSDENIED
DPERR_ALREADYINITIALIZED
DPERR_AUTHENTICATIONFAILED
DPERR_CANNOTCREATESERVER
DPERR_CANTCREATEPLAYER
DPERR_CANTLOADCAPI
DPERR_CANTLOADSECURITYPACKAGE
DPERR_CANTLOADSSPI
DPERR_CONNECTING
DPERR_CONNECTIONLOST
DPERR_ENCRYPTIONFAILED
DPERR_ENCRYPTIONNOTSUPPORTED
DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS
DPERR_INVALIDPASSWORD
DPERR_LOGONDENIED
DPERR_NOCONNECTION
DPERR_NONEWPLAYERS
DPERR_NOSESSIONS
DPERR_SIGNFAILED
DPERR_TIMEOUT
DPERR_UNINITIALIZED
DPERR_USERCANCEL

This method returns DPERR_ALREADYINITIALIZED if there is already an open session on this DirectPlay object.

It return DPERR_CANTCREATEPLAYER if the maximum number of players in the session description has already been reached.

It returns DPERR_TIMEOUT if the session did not respond to the Open request.

It returns DPERR_USERCANCEL if the user canceled the enumeration process(usually by canceling a service provider dialog box).

It returns DPERR_NOSESSIONS if it is called to join an existing session but the session isn't in the internal session list (or the session guidInstance is corrupted).

Remarks

Once an application has joined a session, it can create a player and start communicating with other players in the session. The application will not receive any messages nor can it send any messages on this DirectPlay object until it creates a local player using IDirectPlay4::CreatePlayer.

In order to have two sessions open simultaneously, the application must create two DirectPlay objects and open a session on each one.

To join a session, it is only necessary to fill in the dwSize and guidInstance members of the DPSESSIONDESC2 structure. The lpszPassword member must also be filled in if the session was marked as password protected. An enumerated session will have the DPSESSION_PASSWORDREQUIRED flag set if it requires a password.

If joining a secure session, you must use SecureOpen to provide logon credentials. The enumerated session will have the DPSESSION_SECURESERVER flag set if it requires credentials.

If you specify the DPSESSION_SECURESERVER flag in the DPSESSIONDESC2 structure, the session will be opened with the default security package, NTLM (NT LAN Manager). To specify an alternate security package, use SecureOpen.

When an application attempts to join a session, the server can reject the Open request or ignore it (in which case Open will time-out). Attempting to join a session where new players are disabled, joining is disabled, the player limit has been reached, or an incorrect password is supplied will result in a DPERR_NONEWPLAYERS or DPERR_INVALIDPASSWORD error.

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 dplay.h.
  Import Library: Use dplayx.lib.

See Also

DPSESSIONDESC2, IDirectPlay4::Close, IDirectPlay4::SecureOpen, IDirectPlay4::EnumSessions