Platform SDK: DirectX

DirectPlay4.Open

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

object.Open(sessionDesc As DirectPlaySessionData, _
    flags As CONST_DPOPENFLAGS)

Parameters

object
Object expression that resolves to a DirectPlay4 object.
sessionDesc
DirectPlaySessionData object describing the session. This object is obtained by using the DirectPlay4.CreateSessionData method.

If a session is to be created, then the application must completely initialize the DirectPlaySessionData object with the properties of the session to be created, except for the GuidInstance, which DirectPlay will supply.

flags
Flags from the CONST_DPOPENFLAGS enumeration.

Error Codes

If the method fails, an error is raised and Err.Number may be set to one of the following values:

DPERR_ACCESSDENIED
DPERR_ALREADYINITIALIZED
DPERR_AUTHENTICATIONFAILED
DPERR_CANNOTCREATESERVER
DPERR_CANTCREATEPLAYER
DPERR_CANTLOADCAPI
DPERR_CANTLOADSECURITYPACKAGE
DPERR_CANTLOADSSPI
DPERR_CONNECTING
DPERR_CONNECTIONLOST
DPERR_ENCRYPTIONFAILED
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 there is no open session matching the description, if the session isn't in the internal session list, or the session GUID is corrupted.

Remarks

After 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 DirectPlay4.CreatePlayer.

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

DirectPlaySessionData.SetSessionPassword must be called 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 DirectPlay4.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, the session will be opened with the default security package, NTLM. 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.

See Also

DirectPlay4.Close