home *** CD-ROM | disk | FTP | other *** search
/ Archive Magazine 1997 / ARCHIVE_97.iso / discs / mag_discs / volume_08 / issue_06 / risc_os / !Alarm next >
Text File  |  1988-12-22  |  3KB  |  79 lines
  1. Additional Alarm documentation (0.98)
  2. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  3. In addition to the "normal" user facilities of !Alarm as documented in the
  4. User Guide, it is also possible for applications to set and receive alarms
  5. by using some WIMP messages. These are as follows:
  6.  
  7. To set a task alarm, send the following message.
  8.  
  9. block+16     &500          indicate message to !Alarm
  10.      +20     0/1           indicate set an alarm (1 if 5 byte format)
  11.      +24     date/time
  12.      +30     name of task sender, terminated by 0
  13.      +n      task-specific unique alarm identifier, terminated by 0
  14.  
  15. Date & time must be given in standard 5 byte format if +20 is 1, otherwise
  16. the layout is:
  17.  
  18. +24     year as low-byte/high-byte
  19. +26     month
  20. +27     date
  21. +28     hour
  22. +29     minutes
  23.  
  24. Neither the name nor the alarm identifier may be longer than 40 chars each.
  25.  
  26. To cancel the alarm, use the following message block:
  27.  
  28. block+16     &500          indicate message to !Alarm
  29.      +20     2             indicate cancel an alarm
  30.      +24     name of task, terminated by 0
  31.      +n      task-specific unique alarm identifier, terminated by 0
  32.  
  33. The name & identifier must match exactly for the alarm to be successfully
  34. cancelled. It is not necessary to specify the time of the alarm, as this may
  35. have changed due to being deferred by Alarm.
  36.  
  37. If these messages are sent recorded, !Alarm will acknowledge with 0 if
  38. successful, or a 0 terminated error string.
  39.  
  40. When an alarm goes off, the format of the block sent by !Alarm as a
  41. broadcast is:
  42.  
  43. block+16     &501          indicate an alarm has gone off
  44.      +20     name of task sender, terminated by 0
  45.      +n      task-specific unique alarm identifier, terminated by 0
  46.  
  47. If the named task recognises the identifier, it must acknowledge this
  48. message, otherwise !Alarm will ask the user to install the named
  49. application. If the latter occurs, the alarm is deferred for one minute to
  50. allow the task to be installed.
  51.  
  52. All alarms set are stored in <Alarm$Dir>.!Alarm. This is a data file
  53. containing a linked list of alarms as follows:
  54.  
  55. PTR     Contents
  56. ~~~     ~~~~~~~~
  57. 0       PTR to first alarm, -1 if none set
  58. 5       PTR to first free space, -1 if none available
  59. ...
  60. For each alarm or free space block:
  61. n       PTR to next alarm/free space block, -1 if last
  62. n+5     PTR to previous alarm/free space block, -1 if first
  63. n+10    set alarm time stored as five byte format plus urgent flag
  64. n+17    alarm text
  65.         contains 3 strings, each a maximum of 40 characters
  66.         if a task alarm then string 1 is the task name
  67.                              string 2 is the unique indentifier
  68. n+144   flags:
  69.         bit 0 = task alarm
  70.             1 = repeating alarm
  71. n+145   repeat period:
  72.         bit 0 = minutes
  73.             1 = hours
  74.             2 = days
  75.             3 = weeks
  76.             4 = months
  77.             5 = years
  78. n+146   repeat multiplier (1 byte)
  79.