RISCOS Ltd                                                         RISCOS Ltd

            -------------------------------------------------
            TECHNICAL NOTE: TASK MANAGER CHANGES IN RISC OS 4
            -------------------------------------------------


   Document: 19990712-001
  
    Version: 1.00 (15 Jun 1999) JRF: Initial documentation written
             1.01 (15 Jun 1999) JRF: Amended with comments from MB
             1.02 (06 Oct 1999) DPT: Reformatted to new style
  
  Author(s): Justin Fletcher (justin@riscos.com)
             Matthew Bullock (matthew@riscos.com)


NEW TASK MANAGER SERVICE CALL IN RISC OS 4.00

Service_TaskManagerAcknowledgements (&42680)

Notify taskmanager of licence acknowledgements.

  => R1 = &42680
     R2 = pointer to code to call to add messages, or
          0 to notify TaskManager that the acknowledgements have changed.
  
  <= All registers preserved

This service call is used to allow modules to communicate information about
their licences which they are required to state, but would otherwise have no
other means of displaying. Primarily it is intended for commercial developers
and software built into the OS itself, but may be used by anyone. You should
not claim this service.

The code to add messages must be called as:

  => R0 = Group identifier of form &GMMM, were G is :
            0 = system overview            \
            1 = system required components  } For RISCOS Ltd use only
            2 = subsiduary components      /
            3 = commercial components
            4 = freeware components
            5 = user components             - For private use only
          The MMM field should be set to 0 and is for future developments.
     R1 = Pointer to zero terminated component title
     R2 = Pointer to zero terminated acknowledgement details
          Details should be formatted into 60 character-long maximum, LF
          terminated strings. Try to remember to include full stops at the
          ends of sentences. Thus, in BASIC, you might use:
          "© Fred Bloggs, 1998."+CHR$(10)+"© Sue Bloggs, 1999."+CHR$(0)
  <= All registers preserved
     return with MOV pc,link (ie do not preserve the flags)

You should /only/ call the entry point when requested for information by
TaskManager. TaskManager 1.11 and later support this service. Data will be
copied so you can build strings in a temporary area if necessary.


In assembler, you might use code something like the following to register
messages:

  svc_acknowledgements
          TEQ     r2, #0
          MOVEQS  pc, r14
          STMFD   r13!, {r0-r3, r14}
          MOV     r3, r2
          MOV     r0, #&5000           ; group id
          ADR     r1, Title            ; pointer to your module title string
          ADR     r2, CopyrightMessage ; some copyright message
          MOV     r14, pc
          MOV     pc, r3
          MOV     r0, r0
          LDMFD   r13!, {r0-r3, pc}^
  
  CopyrightMessage
          = "This software is based in part on work by Diaxos Holdings", 10
          = "Incorporated.", 10
          = "Some sections have been provided by Wally Williams.", 0


In C you might use code something like the following:

  typedef void (*addmessages_func)(unsigned int group, char const *title,
                                   char const *message);
  
  #define Service_TaskManagerAcknowledgements 0x42680
  
  void main_service(int service_number, _kernel_swi_regs *r, void *pw)
  {
    if (service_number == Service_TaskManagerAcknowledgements)
    {
      addmessages_func func = (addmessages_func)r->r[2];
  
      if (func != NULL)
      {
        func(0x5000, Module_Title, "This software is based in part on the work of the Independent\nJPEG Group.");
      }
    }
  }


On module initialisation and finalisation you should notify TaskManager of
the change to the acknowledgement messages by issuing the service with R2 set
to 0, in C you might do this as :

  /* Let TaskManager know it's changed */
  _swix(XOS_ServiceCall, _INR(1,2), Service_TaskManagerAcknowledgements, 0);


In assembler, this could be :

  ; Cause a re-cache of the acknowledgements window
          LDR     r1, =&42680
          MOV     r2, #0
          SWI     XOS_ServiceCall

-- 
Comment: TaskManager_Acknowledgements service documentation
Part: 19990712-001