Creates or joins a secure session. When joining a secure session, use this method to supply login credentials.
When creating a new session, the host computer can specify an alternate security package to use. When joining a session, a computer can specify a user name and password.
HRESULT IDirectPlay3::SecureOpen(
LPCDPSESSIONDESC2 lpsd,
DWORD dwFlags,
LPCDPSECURITYDESC lpSecurity,
LPCDPCREDENTIALS lpCredentials
)
Parameters
lpsd
Pointer to the DPSESSIONDESC2 structure describing the session to be created or joined. If a session is to be joined, then only the guidInstance and lpszPassword members need to be specified. The password need only be supplied if the enumerated session had the DPSESSION_PASSWORDREQUIRED flag set.
If a session is to be 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. NOTE: The DPSESSION_SECURESERVER flag must be set to indicate that all computers attempting to open the session must be authenticated.
If you don't specify the DPSESSION_SECURESERVER flag when filling out the DPSESSIONDESC2 structure, SecureOpen will open an unsecure session, just as if you had called Open.
dwFlags
One of the following flags:
Creates a new instance of a secured session.
Joins an existing instance of a secured session.
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 SecureOpen until either DP_OK is returned, indicating successful completion, or some other error code is returned, indicating an error.
lpSecurity
Pointer to a DPSECURITYDESC structure containing the security package to use. Set this parameter to NULL to use the default security package (NT LAN Manager) and CryptoAPI package (Microsoft RSA Base Cryptographic Provider). Relevant only when creating a session. Must be set to NULL when joining a session.
lpCredentials
Pointer to a DPCREDENTIALS structure containing the logon name, password, and domain to be authenticated on the server. NULL if there are no credentials. Credentials are ignored when creating a session.
Return Values
Returns DP_OK if successful or one of the following error values:
This method DPERR_LOGONDENIED after being called with invalid creadentials or without credentials when credentials are required. The application must collect the user's credentials and call SecureOpen again.
Remarks
When joining a session, first call SecureOpen with no credentials. If the method returns DPERR_LOGONDENIED, then the application must collect the user name and password from the user and call SecureOpen again, passing in the user's credentials through the lpCredentials parameter. If the method returns DP_OK, then the player was able to login with the credentials he or she had specified earlier during system logon (network logon in NTLM).
See Also