Window region user mode monitoring

In this article, we will describe the method to perform user mode region monitoring of the specified window. It will be useful for the software developers who need run-time monitoring information about specified window position and its region on Windows OS.

General description

A region is a rectangle, polygon, or ellipse (or a combination of two or more of these shapes) that can be filled, painted, inverted, framed, and used to perform hit testing (testing for the cursor location). In general, the window`s region is the set of the rectangles that construct a visible part of the window.

The specified window`s region monitoring, for example, can be used in Virtual channels development.

Virtual channels are software extensions that can be used to add functional enhancements to a Remote Desktop Services application. Examples of functional enhancements may include support of the special types of hardware, audio, or other additions to the core functionality provided by the Remote Desktop Services Remote Desktop Protocol (RDP).

To use virtual channels, you should provide the server-side and client-side modules of the virtual channels application. The server-side module can be a user-mode application or a kernel-mode driver. The client-side module should be a DLL.

Client side module as a rule is mstsc add-in. Sometimes such application needs to perform some action at the window`s region changes. So we can monitor the server window and send information about its region to the client. On the client we can use the information to get visible parts of the server window.

For example we need to improve video rendering in the terminal session. We can create some optimal scheme for data transporting from the server to the client and show the movie window on the client side instead of the server. This technique allows user to watch movie as on the local machine. The client video window should be drown over the server one. But if the server window is partially hidden by some other windows, we should update our client window.

In this article we present user adopted library to get run-time information about the window region.

Library description

Input information: handle of the window to monitor , time out, observers to hold region and errors notifications.

Output information: region data structure RGNDATA, errors reports.

The separate thread starts in the library core. According to timeout, it collects information about the window`s region and sends it to the observer. If we get some problems in the thread we use NotifyZero() method to send zero size region. Windows region APIs were used to collect this information (see references). Main steps are shown below.

1. Get device context

{code} HDC hDC = ::GetDC(m_window); {/code}

2. Create empty region

{code} HRGN hRgn = ::CreateRectRgn(0, 0, 0, 0); {/code}

3. Copy region of the selected window

{code} ::GetRandomRgn(hDC, hRgn, SYSRGN); {/code}

4. Determine the size of region data

{code} DWORD size = GetRegionData(hRgn, 0, 0); {/code}

5. Reserve buffer

{code} std::vector<char> rgnDataBuf(size); {/code}

6. Get region data

{code} RGNDATA * pRgnData = reinterpret_cast<RGNDATA*>(&rgnDataBuf.front()); GetRegionData(hRgn, size, pRgnData) {/code}

7. Notify client via observer

{code} pEventObserver->WinEventNotify(pRgnData); {/code}

Public interface description

Callback interface to send region data to the client code:

{code}struct IWinRegionObserver { virtual ~IWinEventObserver(){} virtual void WinEventNotify(const _RGNDATA *) = 0; }; {/code}

Callback interface to inform about errors:

{code}struct IErrorObserver { virtual ~IWinEventErrorObserver(){} virtual void OnWinEventError(__in const char *) = 0; }; {/code}

Restrictions

This method doesn`t work on Windows 7 and higher systems if aero theme is selected.

In aero theme window region always consists of one rectangle, even if a window is partially hidden by other windows. Windows 7 uses its core mechanism to show only visible parts. So library will always report about one rectangle in the window region.

How to use

To use this library you should create core object and events observers. To create the core use the next constructor:

{code}CWinRegionObserver( HWND hWnd, IWinRegionObserver * pEventObserver, IErrorObserver* pErrorObserver, DWORD TimeOut = 200 ); {/code}

All data will be sent to the application by IWinRegionObserver and IErrorObserver interfaces.

In your client code, you can parse region information to determine visible parts of the window, for example. In our test application we just write the number of rectangles, which construct the window region, to the log file.

Sample description

MFC dialog-based application was created to demonstrate the library work. The main window of this application is monitored by the library. To see monitoring results use log file in the sample folder.
For example, let’s suppose that we have a window.

We will use our library to monitor its region rectangles.

At this image, the visible region of the window consists of 1 rectangle.

At the next image, the region still consists of 1 rectangle.

But at the next image, the window region consists of 2 regions.

So, using this library we can find visible regions and use this information in your program.

Library build requirements

Software

Visual Studio 2008 sp1
Boost 1.40.0 source code (see http://boost.org)

Environment Variables

BOOST_ROOT – should contain the path to the Boost directory

Preparing Build System

Before building the sample solution from the source code, you should perform several simple preliminary steps. First of all, you should install all the applications specified in the Software section, and set mentioned environment variables .

After that, you should build Boost libraries from the source code. To do this, go to the Boost directory (BOOST_ROOT) and invoke the following two commands one after another:

  bootstrap.bat
  bjam.exe toolset=msvc --build-type=complete

For more detailed information, see the Boost documentation.

Downloads

Download sources (136 KB) of described library and sample application.