=============================================================================
MsgMon - Monitor Wimp Messages with Reporter                     Version 1.04

(C) Stephen Fryatt 2010-2020                                   30 August 2020
=============================================================================

Licence
-------

  MsgMon is licensed under the EUPL, Version 1.2 only (the "Licence"); you
  may not use this work except in compliance with the Licence.

  You may obtain a copy of the Licence at
  http://joinup.ec.europa.eu/software/page/eupl

  Unless required by applicable law or agreed to in writing, software
  distributed under the Licence is distributed on an "AS IS" basis, WITHOUT
  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

  See the Licence for the specific language governing permissions and
  limitations under the Licence.

  The source for MsgMon can be found alongside this binary download, at
  http://www.stevefryatt.org.uk/software

  The necessary libraries and build tools can be found at
  http://www.stevefryatt.org.uk/software/build



Introduction
------------

  MsgMon is a module to work with Reporter, from Chris Morison and Martin
  Avison, in order to display details of messages passed between applications
  using the Wimp's User Message protocol.  When run, it installs a set of
  filters to watch for messages; these are decoded and, if they are in the
  list of message codes that MsgMon is interested in, displayed in the
  Reporter window.

  Copies of the latest version of Reporter can be found on Martin Avison's
  website, at http://www.avisoft.force9.co.uk/



Installation and Use
--------------------

  MsgMon requires RISC OS 3.1 or later, and a copy of Reporter from
  http://www.avisoft.force9.co.uk/

  The module does not require installation, and it can simply be started from
  the Filer by double-clicking on it.  As long as Reporter is also running,
  details of all Wimp messages passing between the applications running on
  the system will start to be shown in the Reporter window.

  As an example, a simple two message exchange would be shown in Reporter by
  MsgMon as follows:

    Message_DataOpen (&000005) [Message Recorded]
    From 'Filer' to 'StrongED'
    My ref: &0007E35B; Your ref: &00000000
    20  : 20909099 : ...  : 546345113
    24  : FFFFFFFF : .... : -1
    28  : 0000063C : <... : 1596
    32  : 0000021E : .... : 542
    36  : 00000000 : .... : 0
    40  : 00000FFF : .... : 4095
    44  : 53464441 : ADFS : 1397113921
    48  : 79493A3A : ::Iy : 2034842170
    52  : 78696E6F : onix : 2020175471
    56  : 522E242E : .$.R : 1378755630
    60  : 726F7065 : epor : 1919905893
    64  : 73694C74 : tLis : 1936280692
    68  : 00000074 : t... : 116
    72  : 000006BE : .... : 1726
    76  : 000003D4 : .... : 980

    Message_DataLoadAck (&000004) [Message]
    From 'StrongED' to 'Filer'
    My ref: &0007E35C; Your ref: &0007E35B
    20  : 20909099 : ...  : 546345113
    24  : FFFFFFFF : .... : -1
    28  : 0000063C : <... : 1596
    32  : 0000021E : .... : 542
    36  : 00000000 : .... : 0
    40  : 00000FFF : .... : 4095
    44  : 53464441 : ADFS : 1397113921
    48  : 79493A3A : ::Iy : 2034842170
    52  : 78696E6F : onix : 2020175471
    56  : 522E242E : .$.R : 1378755630
    60  : 726F7065 : epor : 1919905893
    64  : 73694C74 : tLis : 1936280692
    68  : 00000074 : t... : 116
    72  : 000006BE : .... : 1726
    76  : 000003D4 : .... : 980

  Each message consists of three header lines in black, followed by a dump of
  the message contents (where applicable) in blue.  The first line of each
  header is highlighted with a cream background to make individual messages
  stand out.

  The first line of the header consists of the message name (as defined by
  Acorn and their successors or by the third parties responsible) with the
  32-bit hexadecimal message number following it in parentheses.  If the
  message does not appear in the list of numbers that MsgMon knows about, a
  textual name will not be given.  At the end of the line is the type of
  message, in square brackets: this will either be "Message", "Message
  Recorded" or "Message Acknowledge", which correspond to the Wimp_Poll
  reason codes 17, 18 and 19 respectively.

  The second header line shows the applications sending and receiving the
  message, converted from task handles into task names.  Broadcast messages
  will be reported multiple times: once for each application that they are
  sent to before being claimed.  In some cases, when the system itself sends
  the message, the 'From' field will appear as an empty string.

  The third header line gives the My Ref and Your Ref fields from the
  message, again as hexadecimal 32-bit numbers.

  If the message block was longer than the basic 20 bytes, subsequent lines
  of the report show the block contents as a series of 32-bit integers.  Each
  appears on its own line, containing from left to right the offset into the
  message block, the value of the word in hexadecimal, the value of the word
  as four ASCII bytes shown LSB to MSB, and the value of the word in signed
  decimal.  In the case of the ASCII bytes, characters outside of the range
  32 to 126 (space to '~') are shown as full-stops.

  To stop MsgMon sending messages to Reporter, the module should be killed
  using "*RMKill MsgMon" at the command line: this could be placed in an Obey
  file to save typing it regularly.


  Narrowing down the messages
  ---------------------------

  By default, MsgMon will report all the messages that occur on the system;
  this very quickly becomes unwieldy.  Using the "*MsgMonAddMsg" command it
  is possible to narrow down the messages that get reported: once at least
  one message has been added to MsgMon's list, only listed messages will be
  included.

  The easiest way to use the command is to create Obey files containing lists
  of messages belonging to specific groups.  For example, the following saved
  as an Obey file would cause messages belonging to the Data Transfer
  Protocol and the Block Transfer Protocol to be shown:

    MsgMonAddMsg 1
    MsgMonAddMsg 2
    MsgMonAddMsg 3
    MsgMonAddMsg 4
    MsgMonAddMsg 5
    MsgMonAddMsg 6
    MsgMonAddMsg 7
    MsgMonaddMsg &D
    MsgMonAddMsg &F
    MsgMonAddMsg &10
    MsgMonAddMsg &11
    MsgMonAddMsg &12
    MsgMonAddMsg &13

  Alternatively, messages can be specified by name, using the names in
  message file (see Configuring the Module) with "Message_" at the start.
  The list above could also be written as follows, with the same effect (the
  names are matched case-insensitively):

    MsgMonAddMsg Message_DataSave
    MsgMonAddMsg Message_DataSaveAck
    MsgMonAddMsg Message_DataLoad
    MsgMonAddMsg Message_DataLoadAck
    MsgMonAddMsg Message_DataOpen
    MsgMonAddMsg Message_RAMFetch
    MsgMonAddMsg Message_RAMTransmit
    MsgMonAddMsg Message_DataSaved
    MsgMonAddMsg Message_PreQuit
    MsgMonAddMsg Message_PaletteChange
    MsgMonAddMsg Message_SaveDesktop
    MsgMonAddMsg Message_DeviceClaim
    MsgMonAddMsg Message_DeviceInUse
    MsgMonAddMsg Message_Shutdown
    MsgMonAddMsg Message_ClaimEntity
    MsgMonAddMsg Message_DataRequest
    MsgMonAddMsg Message_Dragging
    MsgMonAddMsg Message_DragClaim
    MsgMonAddMsg Message_ReleaseEntity

  Similarly, a file could be created to report on messages in the Colour
  Picker Protocol:

    MsgMonAddMsg Message_ColourChoice
    MsgMonAddMsg Message_ColourChanged
    MsgMonAddMsg Message_CloseRequest
    MsgMonAddMsg Message_OpenParent

  Calls to "*MsgMonAddMsg" are additive, so running these two Obey files in
  sequence would result in messages belonging to all three protocols being
  displayed.  To remove messages from the list, the "*MsgMonRemoveMsg"
  command can be used in a similar way; in addition, "*MsgMonRemoveMsg -all"
  would clear the entire list and return MsgMon to reporting all messages
  that are sent.  This could be used in the Obey files to make each file
  select just its own messages by including it before the new messages are
  added:

    MsgMonRemoveMsg -all
    MsgMonAddMsg Message_ColourChoice
    MsgMonAddMsg Message_ColourChanged
    MsgMonAddMsg Message_CloseRequest
    MsgMonAddMsg Message_OpenParent

  More details of the commands offered by MsgMon can be found in the section
  on Configuring the Module.



Configuring the Module
----------------------

  MsgMon provides a number of *commands which can be used to control and
  interrogate its operation.

  *MsgMonAddMsg [-message] <message code>

    The command "*MsgMonAddMsg" is used to add a message to the list to be
    reported (with an empty list, all messages will be returned).

    The <message code> parameter is a numeric Wimp message code in decimal
    (or hex, if preceded by "&"), or a message name starting with "Message_":
    for example, "1<code> or <code>Message_DataSave" would be equivalent.

  *MsgMonRemoveMsg [-message] <message code> | -all

    The command "*MsgMonRemoveMsg" removes a message or messages from the
    interception list.

    If the <message code> parameter is used, then an individual message will
    be removed from the list: the code is a numeric Wimp message code in
    decimal (or hex, if preceded by "&"), or a message name starting with
    "Message_".

    If -all is used, then all the messages in the list will be removed and
    MsgMon will start reporting on all messages again.

  *MsgMonListMsgs

    "*MsgMonListMsgs" will display a list of messages being reported by
    MsgMon; entries can be added or removed by "*MsgMonAddMsg" and
    "*MsgMonRemoveMsg" respectively.

    An empty list indicates that all messages will be reported.

  *MsgMonLoadMsgs [-file] <message file>

    Load a new file of mappings between message numbers and names, used by
    MsgMon to look up messagee names passed to the "*MsgMonAddMsg" and
    "*MsgMonRemoveMsg" commands, and include names in the Reporter window.
    This will only be necessary if your system is using non-standard messages
    provided by third-party applications.

    The file pointed to by <message file> is a simple RISC OS format text
    file, consisting of a one line per message.  Each line consists of the
    message number in hex (with a leading "&") followed by a tab character
    (ASCII 9) and then the part of the message name following "Message_"".

    As an example, a file defining message &1 as Message_DataSave and message
    &400C0 as Message_MenuWarning would appear as follows (note that tabs
    have been replaced by spaces):

      &1     DataSave
      &400C0 MenuWarning

    The standard file used by MsgMon can be found in ResourceFS at
    Resources:$.ThirdParty.MsgMon.MsgList when the module is loaded.  This
    can be copied and used as a basis for updates if required; if you add any
    useful definitions, please consider submitting your amendments for
    inclusion in a future release.



Version History
---------------


  1.00 (20 May 2010)
  ------------------

  First public release.


  1.01 (22 May 2010)
  ------------------

  Update to first public release.

  * String copies terminate on NULL or LF to correctly handle the full range
    of task names returned by the Task Manager.


  1.02 (12 July 2013)
  -------------------

  Update to first public release.

  * Port from ExtBasAsm to ObjAsm/Asasm and restructure for cross-assembly.
  * Fix broken workspace structure and remove unused memory allocations.
  * Replace all non-X SWIs and fix error handling.
  * Check for ARMv7 compatibility.


  1.03 (1 September 2014)
  -----------------------

  Update to first public release.

  * Correctly terminate module title string.
  * Correct 32-bit detection in exit code.


  1.04 (30 August 2020)
  ---------------------

  Update to first public release.

  * Licence updated to EUPL v1.2.
  * "*MsgMonAddMsg" and "*MsgMonRemoveMsg" can take message names as well as
    numbers.
  * Wrap message body lines in double-quotation marks to resolve problems
    with Reporter interpreting "\" characters.
  * Replace """ with "." in ASCII display, to avoid catching Reporter out.



Updates and Contacting Me
-------------------------

  If you have any comments about MsgMon, or would like to report any bugs
  that you find, you can email me at the address below.

  Any updates to the module will be made available on my website, at
  http://www.stevefryatt.org.uk/software/msgmon/

  Stephen Fryatt
  email: steve@stevefryatt.org.uk
