Windows Desktop Sharing API

[MicrosoftSecurityandComplianceTeam]

First published on CloudBlogs on Mar, 08 2007

Windows Desktop Sharing API Basics

Microsoft Terminal Services provides a public "Windows Desktop Sharing API" based on RDP to enable customers to write custom collaboration solutions in Windows Vista . These API's are available on all the SKU's starting with Windows Vista Home Basics. You can write a customized collaboration application that can do either or all kinds of sharing including desktop, application and region.  Useful MSDN documentation of these API's is available at:

http://msdn2.microsoft.com/en-us/library/aa373852.aspx

Highlights:

Windows desktop sharing is a multi-party screen sharing technology in Windows Vista, wherein a local desktop can be transmitted over an RDP connection without creating an additional session.

• a) Connectivity: Windows Desktop Sharing does support connectivity to intelligent appliances, wireless devices and PC's in uPnP framework and also teredo tunneling to provide connectivity to IPV6 machines behind IPV4 NAT's.
• b) Reverse Connect : It is an interesting feature, where sharer can connect to the viewer if viewer cannot reach the sharer via direct connect. For example, the viewer may not be able to connect to the sharer because of network address translation (NAT).
• c) Authentication : API supports creating tickets/ invitations on the sharer side that can be routed by the API consumer application or IM's to the viewers.
• d) Sharing Modes: API supports sharing desktop , application or a region .
• e) Control Modes : Sharer always has full control of his desktop/ application/region. Each viewer can be tuned to no-view/view or interactive control. Sharer controls the control level for each viewer and viewers can request promotion in control level to sharer.
• f) Smart sizing : Smart sizing is well-supported and is a client/ viewer option that can be turned on and off.
• g) Virtual channels : Virtual channels can be used to exchange other data like documents, application data, chat messages etc.

Microsoft Collaboration Solutions :

"Windows Meeting Space" and "Remote Assistance" in Windows Vista are based on these public API's -

• a) Remote Assistance : Remote assistance is 1:1 sharing mechanism wherein the helper (expert) can get to see and control novice's desktop. Application and region sharing is not exposed via RA in Windows Vista.
• b) Windows Meeting Space : Windows Meeting Space is a peer-to-peer application that enables multiple users to conduct virtual meeting. Participants can share their desktop, documents and applications, exchange notes, give presentations by connecting to a network projector. Network projector in this scenario is a intelligent device in uPnP framework that plays a role of viewer.

API support versus perceived limitations in Windows Meeting Space :

• a) Multi-monitor remoting - In Windows Meeting Space the sharer does not allow sharing of both or the secondary monitor in multi-monitor arrangement. However, the API allows you to attach the appropriate region of the composite monitor and hence it can be flexible enough to share any particular monitor, if needed. It could get very interesting with more than 2 monitors.
• b) Easy Switching among desktop/ application sharing - "Windows Meeting Space" doesn't allow flexible switching between desktop and application sharing. You need to select either one of them. To switch you need to restart the session (Meeting Space session). The API allows you to switch between various sharing methods without closing the session.
• c) Application Sharing (minimize->on-screen) - In "Windows Meeting Space" when the viewer has the control of the sharer's application and viewer minimizes the application then he/she doesn't have a way to work on that application further (until sharer clicks on the taskbar on the minimized application). The API does provide a way for the viewer to bring back the minimized application on desktop. Hence a better user experience can be provided on the viewer side.

Frequently Asked Questions:

1. What is the behavior with DWM?
   Windows desktop sharing API turns off "Desktop Windows Manager/ DWM" on the sharer's machine when the desktop/ application sharing is active.
2. What is the behavior when "Secure Desktop" pops up while sharing?
   "Pause screen- Black screen with two bars(indicating pause) at lower right" is remoted when secure desktop (UAC prompts) is up on sharer's machine, when sharing process is run as a non-system process. Also, the pause screen is shown if sharer opts to suspend graphics encoding for some reason via IRDPSRAPISharingSession::Pause .
3. Why does the remoted screen refresh for all connected clients whenever a new viewer joins the session?
   The protocol tries to make sure that the graphics updates sent to all the connected viewers are synchronized. To do so, it needs to refresh the graphics stream for each previously connected client.
4. Why does sharer's monitor flash while sharing? Is there anything that I can do to avoid multiple set of DWM on/off flashes, typically in 1:M scenarios?
   Currently, the protocol does not support remoting glass so it turns DWM off while sharing. Turning DWM off/ on causes a flash on the sharer's monitor [only in case if DWM was on]. You cannot entirely avoid on/off flash but you can avoid multiple on/off flashes.  Depending on your preference you can select dynamic/ static loading of mirror driver. In static mode, sharer will load mirror driver [& turn DWM off if it is on] only once when it puts a session in active state and unload mirror driver [& turns DWM on if it was on earlier] only once when it puts session in inactive state . So, in static mirror driver load mode you won't see multiple set of DWM on/off flashes. However, note that in static mirror driver load DWM/ glass will be turned off even if there are no clients connected. In dynamic mirror driver load mode DWM/ glass is turned off only when there is at least one connected client and is turned on whenever there are no connected clients. There is a property DrvConAttach that you can set via IRDPSRAPISessionProperties to control this behavior.
5. Can multiple viewers have simultaneous control of sharer's desktop/ application?
   Yes. Sharer can permit each viewer a none, view only OR interactive control. Of course, viewers input (mouse movements/ keyboard input) will only be directed to sharer's machine when viewer has interactive control and the active X control has focus.
6. Can you force sharer or viewer[in reverse connect scenario] to use particular port/ protocol for listening for connection and communication?
   Yes. You can use IRDPSRAPISessionProperties property - PortId and PortProtocol to use specific port and protocol.
7. Why does requesting color depth change from the viewer via IRDPSRAPIViewer::RequestColorDepthChange fail?
   Currently, protocol does not allow viewer to request/ control the color depth change. Only the sharer can control the color depth via put property IRDPSRAPISharingSession::put_ColorDepth. IRDPSRAPIViewer::RequestColorDepthChange returns E_NOTIMPL in the current release.
8. Does the API support clipboard?
   No. Windows Desktop Sharing API doesn't provide automatic text/ file clipboard solution yet. This might be a good proposal for new feature in future versions.
9. Does the API support Audio/ Multi - media ?
   No audio can be redirected to and fro from viewers/ sharer via "Windows Desktop Sharing API". This might be a good proposal for new feature in future versions.