Distribution: COMPANY CONFIDENTIAL
Project: Applications
Issue: 0.10
Author(s): Steve Cormie, Julian Smith
Date: 27 Jun 1996
Last Issue: 0.09
0.01 JS 05-Jun-96 First created.
0.02 SMC 11-Jun-96 Reorganised and firmed up.
0.03 JS 14-Jun-96 Added SWI TaskModule_StartTask.
0.04 JS 17-Jun-96 Added allocated SWI numbers.
0.05 JS 24-Jun-96 Service-call handling moved into
standard spec, and allocated SWI
numbers.
Added detection of broadcast messages
for non-task modules.
0.06 JS 24-Jun-96 Added message number for Message_Service.
0.07 JS 24-Jun-96 TaskModule_DeRegisterService can now
deregister all services calls registered
with a task.
0.08 JS 24-Jun-96 Only r0-r9 are sent in Message_Service.
0.09 JS 27-Jun-96 Carified task handle=0 in
TaskModule_(De)RegisterService.
0.10 JS 03 Jul 96 Now copes with Event 18 messages which
are acknowledged.
This document contains the software functional specification for the TaskModule module.
The module is intended to give modules limited access to the Wimp message system and, similarly, non-module Wimp tasks limited access to OS notification functions eg. service calls.
This is done by enabling Wimp messages to be sent from non-tasks via a TaskModule SWI, and the sending of Wimp messages containing service-call information to those tasks that request them.
Italicised text is used where issues are still to be decided or where contents are liable to change.
TaskModule provides the following SWIs:
Send a Wimp message from a non-task.
On entry: r0 = flags (reserved, must be 0) r1 = message block as used by Wimp_SendMessage r2 = destination task handle/window (or 0 to broadcast) r3 = icon (c.f. Wimp_SendMessage) r4 = reply handler, or 0 r5 = r12 value with which to call r4-function (if r4 <> 0) On exit: All registers preserved
This SWI enables modules to send Wimp messages and receive their replies, without them having to be full module-tasks, optionally providing the address of a function to be called with any reply. It is intended for use by modules which only send messages infrequently, to avoid the complexity of making the module into a task.
If r4 (reply handler) is not 0 then it is a pointer to a function to call with any reply to the message which was sent. TaskModule_SendMessage sends the message as event number 18, so there will always be a reply of some sort (either event 17/18 from a task, or event 19 denoting no reply) sent to the reply handler.
There is one exception to this - if a receiver acknowledges the message with a reply with Wimp event number 19, this prevents any sort of reply being sent back to TaskModule (See PRMs 3-197). This means that TaskModule could potentially be left waiting for a reply forever.
To cope with this, TaskModule registers a handler for null-events as well as message-events each time it sends a message. These event-claims and the data associated with the message-reply detection are freed on receipt of either a reply to the message or a null-event.
Because null-events are only delivered at lower pririty than messages, this mechanism ensures that 1) TaskModule cleans up its data-structure for acknowledged messages and 2) null-events are only actually delivered to TaskModule when a message is acknowleged.
If r4 is 0 then TaskModule_SendMessage sends the message as event number 17, and any reply is ignored.
The reply handler is called in SVC mode as follows, and is allowed to call TaskModule SWIs.
On entry: r0 = Wimp event number (17, 18 or 19) r1 = Pointer to message block r12= private word (r5 in original call to TaskModule_SendMessage) On exit: All registers preserved
On entry: r0 = pointer to *command to be executed with Wimp_StartTask. r1 = pointer to function to be called with information returned in r0 by Wimp_StartTask, or 0. r2 = r12 value with which to call r1 function. On exit All registers preserved.This provides non-tasks with access to the Wimp_StartTask SWI (PRM 3-177). Wimp_StartTask is called at some future time by the wimp-task part of TaskModule, and any call-back function (address in r1 on entry) is then called in SVC mode with the returned registers from Wimp_StartTask. The conditions for the call-back function are:
On entry r0 = handle of task started, if it is still alive; 0 otherwise. r12= private word (r2 in original call to TaskModule_StartTask). SVC mode. On exit All registers preserved
Register interest in a service call.
On entry: r0 = flags r1 = service number r2 = task handle On exit: All registers preserved
This is for use by non-module tasks which want to hear about a specific service calls. The task is notified of service calls using the following Wimp message.
r1+20 = register set r0-r9
NB, only r0-r9 are sent because these are all that are available to TaskModule from its CMHG veneer.
Calling with r2 (task handle) = 0 results in the message being broadcast.
The task deregisters interest in a service call using:
De-register interest in a service call.
On entry: r0 = flags r1 = service number, or 0 to deregister all the task's services. r2 = task handle On exit: All registers preserved
R0-r2 should be the same as in a previous call to TaskModule_RegisterService (including the case where r2=0, messages are broadcast), except that r1=0 deregisters all the task's service-call registrations.
r2=0 only effects service-call broadcasts, not specific-task service-call messages.
Thus r1=r2=0 will deregister all service-call broadcasts. It won't de-register registrations for specific tasks. TaskModule looks for applications quitting using Service_WimpCloseDown and de- registers service call interest automatically.
However, it is expected that applications call SWI TaskModule_DeRegisterService before they exit for all registered service-calls, eg with r1=0.
This is for use by non-task modules which want to hear about broadcast Wimp messages.
On entry: r0 = Flags (must be 0) r1 = Pointer to list of messages, terminated by 0 word. An empty list means all broadcast messages, as in Wimp_Initialise (see PRMs 5a-666) r1 = 0 means no messages (which is pointless of course) r2 = Address of handler routine. r3 = r12 value with which to call handler. On exit: All registers preserved.The handler routine is called in SVC mode as follows:
On entry: r0 = Wimp event number (17, 18 or 19) r1 = Pointer to message block r12= private word (r3 in original call to TaskModule_RegisterBroadcastMessage) On exit: All registers preservedThe module can unregister interest in broadcast messages using:
On entry: r0 = Flags (must be 0) r1 = Reserved (must be 0) r2 = Address of handler routine, as passed to TaskModule_RegisterBroadcastMessage r3 = r12 value, as passed to TaskModule_RegisterBroadcastMessage On exit: All registers preserved.It is impractical for TaskModule to keep track of modules quitting, so all client modules' finalisation code must ensure that all broadcast-handlers are unregistered.
It might be useful to make TaskModule provide non-module applications with Wimp message versions of UpCalls, especially UpCall 3 (file being modified).