Changes between Version 3 and Version 4 of Software/EventBenchConsole

Timestamp:

04/06/11 16:53:57 (13 years ago)

Author:

sherbold

Comment:

--

Software/EventBenchConsole

@@ -21 +21 @@
   - Examples:
    - {{{generateReplayfile d:/replay.xml}}}
+
+== Translating MFC Messages into Events ==
+
+The messages are aggregated into events using a set of rules defined in XML. The order of the rules in the XML file defines their priority. 
+
+=== Single Messages and Sequences ===
+
+There is a distinction between single messages and whole sequences of messages of the same type. The former may be used for, e.g., {{{WM_LBUTTONDOWN}}} and {{{WM_LBUTTONUP}}}:
+{{{
+<msg type="&WM_LBUTTONDOWN;"/>
+<msg type="&WM_LBUTTONUP;"/>
+}}}
+
+Sequences of the same message occur, e.g., when scrolling:
+{{{
+<msg type="&WM_LBUTTONDOWN;"/>
+<msg type="&WM_HSCROLL;" multiple=true/>
+<msg type="&WM_LBUTTONUP;"/>
+}}}
+
+The distinction is using the {{{multiple}}} attribute of the {{{msg}}} node,
+which is per default false. If it is true, it means ``at least one'', similar to
+``+'' in regular expressions. 
+
+=== Storage of messages ===
+
+Each message or message sequence can be stored for later use, e.g., comparisons
+with other messages or generating replays. This is done using the {{{store}}}
+and {{{storeSeq}}} nodes:
+{{{
+<msg type="&WM_LBUTTONDOWN;">
+  <store var="clicked"/>
+</msg>
+<msg type=&WM_HSCROLL;" multiple=true>
+  <storeSeq varSeq="scrolls/>
+</msg>
+}}}
+
+When storing a message, the {{{window.hwnd}}} is automatically resolved and its
+target string is stored as an attribute of the message ({{{winParamType}}}). If
+other parameters contain HWNDs that need to be later on to address a target,
+they can be resolved manually and stored as a further parameter:
+{{{
+<msg type=&WM_HSCROLL;" multiple=true>
+  <storeSeq varSeq="scrolls>
+    <resolveHwnd param="scrollBarHandle" storeParam="scrollBarTarget"/>
+  </storeSeq>
+</msg>
+}}}
+
+=== Checking equalities ===
+
+Only matching messages by their type is insufficient. Comparisons between their
+parameters are also required. This can be done using {{{equals}}} nodes:
+{{{
+<msg type="&WM_LBUTTONDOWN;">
+  <store var="clicked"/>
+</msg>
+<msg type="&WM_LBUTTONUP;">
+  <equals>
+    <paramValue obj="this" param="window.hwnd"/>
+    <paramvalue obj="clicked" param="window.hwnd/>
+  </equals>
+</msg>
+}}}
+In the example above, the {{{equals}}} node compares whether the value of the
+parameter ``window.hwnd'' is equal for the stored variable ``clicked'' and the
+current message itself, i.e., ``this''. 
+
+In general, each {{{equals}}} node has the same structure:
+{{{
+<equals>
+  termNode1
+  termNode2
+</equals>
+}}}
+There are four types of term nodes:
+ 1. {{{paramValue}}}: of the messages (example above)
+ 1. {{{constValue}}}: constant value, e.g., {{{<constValue value="Button"/>}}}
+ 1. {{{winInfoValue}}}: information about the target of the message.
+  - {{{<winInfoValue obj="this" winParam="class"/>}}} for the class of the target
+  - {{{<winInfoValue obj="this" winParam="hwnd"/>}}} for the HWND
+  - {{{<winInfoValue obj="this" winParam="resourceId"/>}}} for the resource Id.
+ 1. {{{msgInfoValue}}}: information about the type and target of the message.
+  - {{{<msgInfoValue obj="this" msgParam="type"/>}}} for the type of the message (its integer)
+  - {{{<msgInfoValue obj="this" msgParam="target"/>}}} for the target of the message (its string representation)
+
+The comparison of sequence variables is not yet implemented!
+
+=== Generation of replay sequences ===
+If a message sequence has been successfully matched to a rule, a replay sequence
+is generated. This is done using {{{genMsg}}} and {{{genMsgSeq}}} nodes.
+
+The first way to generate a replay message is to directly replay a message that
+has been stored during the matching phase:
+{{{
+<genMsg delay="100">
+  <storedVar obj=clicked"/>
+</genMsg>
+}}}
+The delay attribute signifies that the replaying tool pauses for 100 ms after
+sending the message stored in the variable ``clicked''. 
+
+The second way is to ``construct'' it:
+{{{
+<genMsg delay="100">
+  <type>
+    <msgInfoValue obj="cmd" msgParam="type"/>
+  </type>
+  <target>
+    <msgInfoValue obj="cmd" msgParam="target"/>
+  </target>
+  <LPARAM>
+    <paramValue obj="cmd" param="sourceDesc"/>
+  </LPARAM>
+  <WPARAM>
+    <paramValue obj="cmd" param="WPARAM"/>
+  </WPARAM>
+</genMsg>
+}}}
+The type needs to be an integer. The target needs to be a target string. 
+The LPARAM and WPARAM are both optional, their default values are 0. They can be
+either numerical or target strings. Furthermore, it is possible to define the
+HI and LO word of them separatly:
+{{{
+<LPARAM>
+  <LOWORD>
+    value
+  </LOWORD>
+  <HIWORD>
+    value
+  </HIWORD>
+</LPARAM>
+}}}
+
+The value types are the same that can be used as terms for {{{equals}}} nodes. 
+
+To generate message sequences, the {{{genMsgSeq}}} node is used:
+{{{
+<genMsgSeq delay="20">
+  <type>
+    <constValue value="&TBM_SETPOS;"/>
+  </type>
+  <target>
+    <seqValue seqObj="scrolls" param="scrollBarTarget"/>
+  </target>
+  <LPARAM>
+    <constValue value="1"/>
+  </LPARAM>
+  <WPARAM>
+    <seqValue seqObj="scrolls" param="scrollPos"/>
+  </WPARAM>
+</genMsgSeq>
+}}}
+The three value types used for equals are allowed. However, either the
+type or the target must be of a {{{seqValue}}}, otherwise the
+creation will fail. In case more than one {{{seqValue}}} variable is used,
+e.g., a different one for the LPARAM than for the target, both sequences must
+have the same length. 
+