IRDPSRAPIViewer::Connect method (rdpencomapi.h)

  • Article

[The IRDPSRAPIViewer interface is no longer available for use for UWP applications as of Windows 10, version 1709. It is still supported for Desktop apps.]

Starts the actual connection to the sharer.

Syntax

HRESULT Connect(
  [in] BSTR bstrConnectionString,
  [in] BSTR bstrName,
  [in] BSTR bstrPassword
);

Parameters

[in] bstrConnectionString

Type: BSTR

The connection string used to connect to the sharer and authenticate the viewer.

[in] bstrName

Type: BSTR

Name for the viewer. The name is sent to the sharer and other viewers. The string is limited to 255 characters.

[in] bstrPassword

Type: BSTR

Password used for authentication. The password is sent out-of-band from the sharer.

Return value

Type: HRESULT

If the method succeeds, the return value is S_OK. Otherwise, the return value is an error code.

Remarks

The connection string contained in the bstrConnectionString parameter is generated by the sharer and obtained by the viewer by completing the following steps:

  1. The sharer obtains an instance of the IRDPSRAPIInvitationManager interface from the IRDPSRAPISharingSession::Invitations property.
  2. The sharer obtains an instance of the IRDPSRAPIInvitation interface by calling the IRDPSRAPIInvitationManager::CreateInvitation method.
  3. The sharer obtains the connection string from the IRDPSRAPIInvitation::ConnectionString property.
  4. The sharer sends the connection string to the viewer in an application-defined method, such as storing the connection string in a file and sharing the file with the viewer.
For increased security, applications can associate passwords with an invitation on the sharer side. Such passwords are usually distributed to viewers through some mechanism other than the one that is used to send the connection string. This is to prevent network "sniffing" types of attacks. If an invitation has a password associated with it, the password must be passed in through this API. Otherwise, the attendee will be disconnected.

The bstrName string that is set in this property is sent to the sharer after the connection is started. The property is a friendly name that the sharer application can choose to display. The property is useful when an invitation is used to authenticate multiple attendees because it allows the sharer and the other viewers to identify who is participating in a Windows Desktop Sharing session.

Requirements

Requirement Value
Minimum supported client Windows Vista [desktop apps only]
Minimum supported server Windows Server 2008 [desktop apps only]
Target Platform Windows
Header rdpencomapi.h
DLL RdpEncom.dll

See also

IRDPSRAPIViewer