= MFCReplay =

[[TracNav(TOC|nocollapse)]]
[[TOC(inline)]]

== Recent Changes ==

[[ChangeLog(/trunk/MFCtooling/replay, 3)]]

== Requirements ==

== Description ==

The task of this tool is to replay events  of Windows MFC applications. The tool itself is mainly a SAX parser that gradually parsers the file that sends messages as specified.

To trigger any events we first need to identify the GUI object, where it took place. This is done using a heuristic. To understand the heuristic rudimental knowledge about Windows GUI objects is required. The most important concept are ''window handles''. Window handles are of the type {{{HWND}}} and are the Id a GUI object. The HWND of each GUI object is assigned when it is created and unique, as long as the window exists. Furthermore, GUI objects may have parent/child windows. The parents and children are assigned using their handles. Therefore, all open GUI objects can be thought of as a huge tree of handles. Additionally, each GUI object contains some information about itself, that is rather general:
 * a resource Id;
 * its title;
 * the class that it is associated with. 
Resource ids identify the kind of the GUI object. However, for certain types of GUI objects, it is not possible to obtain this value, so that is may be 0. While the GUI objects title may change over time and can contain dynamic parts, it is still a very powerful tool to identify most GUI objects. The class of a GUI object is not unique, i.e., there are often several objects of class ''Button'', but together with the name and the resource id it is another indicator to identify the correct GUI object. The target GUI object is described by all these informations:
 * description of the parents of the target GUI object
 * the resource Id, title, and class.

The replay mechanism uses the {{{EnumWindows()}}} (enumerates all ''top-level'' windows) and {{{EnumChildWindows(hwnd)}}} (enumerates all child windows of window hwnd) functions of the Windows API to locate the event targets. This way, a breadth-first search over all windows in the system is performed. It traverses the hierarchy of GUI objects and matches it to the description of the target. On each level, from top-level parent to the desired target object, as scoring function is used to identify the best possible match:
 * 6 points: resource id, window name and window class are equal
 * 5 points: resource id and window name are equal
 * 4 points: resource id is equal
 * 3 points: window name and window class are equal
 * 2 points: window name is equal
 * 1 point: window class is equal
 * 0 points: nothing is equal
Then, for all GUI objects, that have the maximum score, all child windows are search for a match of the next window in the hierarchy, until the target object is found. Modal dialogs pose a special problem for this procedure. While modal dialogs can have a parent, they are always top-level windows and are not found using {{{EnumChildWindows}}}. Therefore, the logged information must also include, whether a window is model or not. If it is, {{{EnumWindows}}} needs to be used and the parent needs to be compared using the {{{GetParent}}} function of the Windows API. 

Once the target GUI object is found, the message describe in the {{{replay.xml}}} is send using the {{{SendMessage}}} message function of the Windows API. 

== Architecture ==

The tool is implemented as a console application that can start the target applications and then parses an XML file to replays the events. 

The XML file is parsed using a SAX parser based on the MSXML API, Version 4.0 implemented in the class {{{LogParser}}}. It implements events for {{{startElement}}} and {{{endElement}}}.

== How to use ==

The tool is executed as follows:
{{{
replay.exe <replayfile> <exetuable> [options]
}}}
The following options are allowed:
{{{
-r --resultfile <string>: file where the results of the execution are stored (pass/fail of sessions); default: no file
-d --msgdelay <number>: if this value is non-zero, a constant delay between the messages is used; default: 0
-w --wait <number>: if this value is non-zero, the program waits before terminating for the user to press any key; default: 1
-s --startdelay <number>: miliseconds that the program waits between starting the application under test and the replay; default 5000
-p --path <string>: working directory of the startup program; default: ""
}}}
Example:
{{{
replay.exe C:\replays\replay1.xml C:\TestApp\testapp.exe -r C:\results\result1.xml -s 3000