Changes between Initial Version and Version 1 of PlugIns/MFC/MFCEventParsing


Ignore:
Timestamp:
10/02/12 13:16:14 (12 years ago)
Author:
sherbold
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • PlugIns/MFC/MFCEventParsing

    v1 v1  
     1[[TracNav(TOC|nocollapse)]] 
     2 
     3= Parsing of usagelog.dll logs into Events = 
     4 
     5The windows messages that the [wiki:MFC/usagelog.dll usagelog.dll] logs are aggregated into events using a set of rules defined in XML. The order of the rules in the XML file defines their priority.  
     6 
     7== Single Messages and Sequences == 
     8 
     9There 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}}}: 
     10{{{ 
     11<msg type="&WM_LBUTTONDOWN;"/> 
     12<msg type="&WM_LBUTTONUP;"/> 
     13}}} 
     14 
     15Sequences of the same message occur, e.g., when scrolling: 
     16{{{ 
     17<msg type="&WM_LBUTTONDOWN;"/> 
     18<msg type="&WM_HSCROLL;" multiple=true/> 
     19<msg type="&WM_LBUTTONUP;"/> 
     20}}} 
     21 
     22The distinction is using the {{{multiple}}} attribute of the {{{msg}}} node, 
     23which is per default false. If it is true, it means ``at least one'', similar to 
     24``+'' in regular expressions.  
     25 
     26== Storage of messages == 
     27 
     28Each message or message sequence can be stored for later use, e.g., comparisons 
     29with other messages or generating replays. This is done using the {{{store}}} 
     30and {{{storeSeq}}} nodes: 
     31{{{ 
     32<msg type="&WM_LBUTTONDOWN;"> 
     33  <store var="clicked"/> 
     34</msg> 
     35<msg type=&WM_HSCROLL;" multiple=true> 
     36  <storeSeq varSeq="scrolls/> 
     37</msg> 
     38}}} 
     39 
     40When storing a message, the {{{window.hwnd}}} is automatically resolved and its 
     41target string is stored as an attribute of the message ({{{winParamType}}}). If 
     42other parameters contain HWNDs that need to be later on to address a target, 
     43they can be resolved manually and stored as a further parameter: 
     44{{{ 
     45<msg type=&WM_HSCROLL;" multiple=true> 
     46  <storeSeq varSeq="scrolls> 
     47    <resolveHwnd param="scrollBarHandle" storeParam="scrollBarTarget"/> 
     48  </storeSeq> 
     49</msg> 
     50}}} 
     51 
     52== Checking equalities == 
     53 
     54Only matching messages by their type is insufficient. Comparisons between their 
     55parameters are also required. This can be done using {{{equals}}} nodes: 
     56{{{ 
     57<msg type="&WM_LBUTTONDOWN;"> 
     58  <store var="clicked"/> 
     59</msg> 
     60<msg type="&WM_LBUTTONUP;"> 
     61  <equals> 
     62    <paramValue obj="this" param="window.hwnd"/> 
     63    <paramvalue obj="clicked" param="window.hwnd/> 
     64  </equals> 
     65</msg> 
     66}}} 
     67In the example above, the {{{equals}}} node compares whether the value of the 
     68parameter ``window.hwnd'' is equal for the stored variable ``clicked'' and the 
     69current message itself, i.e., ``this''.  
     70 
     71In general, each {{{equals}}} node has the same structure: 
     72{{{ 
     73<equals> 
     74  termNode1 
     75  termNode2 
     76</equals> 
     77}}} 
     78There are four types of term nodes: 
     79 1. {{{paramValue}}}: of the messages (example above) 
     80 1. {{{constValue}}}: constant value, e.g., {{{<constValue value="Button"/>}}} 
     81 1. {{{winInfoValue}}}: information about the target of the message. 
     82  - {{{<winInfoValue obj="this" winParam="class"/>}}} for the class of the target 
     83  - {{{<winInfoValue obj="this" winParam="hwnd"/>}}} for the HWND 
     84  - {{{<winInfoValue obj="this" winParam="resourceId"/>}}} for the resource Id. 
     85  - {{{<winInfoValue obj="this" winParam="parentTarget"/>}}} for the target of the GUI objects parent 
     86 1. {{{msgInfoValue}}}: information about the type and target of the message. 
     87  - {{{<msgInfoValue obj="this" msgParam="type"/>}}} for the type of the message (its integer) 
     88  - {{{<msgInfoValue obj="this" msgParam="target"/>}}} for the target of the message (its string representation) 
     89 
     90The comparison of sequence variables is not yet implemented! 
     91 
     92== Generation of replay sequences == 
     93If a message sequence has been successfully matched to a rule, a replay sequence 
     94is generated. This is done using {{{genMsg}}} and {{{genMsgSeq}}} nodes. 
     95 
     96The first way to generate a replay message is to directly replay a message that 
     97has been stored during the matching phase: 
     98{{{ 
     99<genMsg delay="100"> 
     100  <storedVar obj=clicked"/> 
     101</genMsg> 
     102}}} 
     103The delay attribute signifies that the replaying tool pauses for 100 ms after 
     104sending the message stored in the variable ``clicked''.  
     105 
     106The second way is to ``construct'' it: 
     107{{{ 
     108<genMsg delay="100"> 
     109  <type> 
     110    <msgInfoValue obj="cmd" msgParam="type"/> 
     111  </type> 
     112  <target> 
     113    <msgInfoValue obj="cmd" msgParam="target"/> 
     114  </target> 
     115  <LPARAM> 
     116    <paramValue obj="cmd" param="sourceDesc"/> 
     117  </LPARAM> 
     118  <WPARAM> 
     119    <paramValue obj="cmd" param="WPARAM"/> 
     120  </WPARAM> 
     121</genMsg> 
     122}}} 
     123The type needs to be an integer. The target needs to be a target string.  
     124The LPARAM and WPARAM are both optional, their default values are 0. They can be 
     125either numerical or target strings. Furthermore, it is possible to define the 
     126HI and LO word of them separatly: 
     127{{{ 
     128<LPARAM> 
     129  <LOWORD> 
     130    value 
     131  </LOWORD> 
     132  <HIWORD> 
     133    value 
     134  </HIWORD> 
     135</LPARAM> 
     136}}} 
     137 
     138The value types are the same that can be used as terms for {{{equals}}} nodes.  
     139 
     140To generate message sequences, the {{{genMsgSeq}}} node is used: 
     141{{{ 
     142<genMsgSeq delay="20"> 
     143  <type> 
     144    <constValue value="&TBM_SETPOS;"/> 
     145  </type> 
     146  <target> 
     147    <seqValue seqObj="scrolls" param="scrollBarTarget"/> 
     148  </target> 
     149  <LPARAM> 
     150    <constValue value="1"/> 
     151  </LPARAM> 
     152  <WPARAM> 
     153    <seqValue seqObj="scrolls" param="scrollPos"/> 
     154  </WPARAM> 
     155</genMsgSeq> 
     156}}} 
     157The three value types used for equals are allowed. However, either the 
     158type or the target must be of a {{{seqValue}}}, otherwise the 
     159creation will fail. In case more than one {{{seqValue}}} variable is used, 
     160e.g., a different one for the LPARAM than for the target, both sequences must 
     161have the same length.  
     162