home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / n / newsflash / !FileBase / !NewsFlash / Docs / Developers / Utilities < prev   
Encoding:
Text File  |  1996-07-10  |  3.5 KB  |  100 lines
  1. Last update: 5/1/96
  2.  
  3. This file gives the NewsFlash Utility file format/structure and explains the
  4. NewsFlash Utility protocol.
  5.  
  6. The structure of WIMP messages mentioned here can be found in
  7. Developers.Messages.
  8.  
  9. ----------------------------------------------------------
  10.  
  11. Utility file format
  12. ===================
  13.  
  14. &00 = "NFUT"
  15. &04 = Utility flags:
  16.  
  17. bit 0 - Allow only one instantiation
  18.  
  19. &08 = Utility ID
  20. &0C = 8 bit utility version low
  21. &0D = 8 bit utility version high
  22. &0E = 16 bit release number
  23.  
  24. &10 = Offset to utilty code (will become the current task at &8000)
  25. &14 = Size of utility code
  26.  
  27. &18 = Offset to utilty help text
  28. &1C = Size of utility help text
  29.  
  30. &20 = 32 byte null terminated utility name
  31. &40 = 32 byte null terminated utility author name
  32.  
  33. &60 = Size of initial workspace required.
  34.  
  35. ----------------------------------------------------------
  36.  
  37. Utility Protocol
  38. ================
  39.  
  40. The Utility system provides and easy way for applications to perform common
  41. BBS orientated tasks without having to write a lot of code. The task can make
  42. use of utilities which have been written to perform the operation whilst
  43. multitasking.
  44.  
  45. The utilities can also be upgraded/added seperately without the task having
  46. to change.
  47.  
  48. Each utility has a unique 1 word (32 bit/4 byte) ID which is used by calling
  49. tasks to identify it. For example the local upload utility's ID is "UPLD".
  50. However, as tasks may wish to keep track of utilities they have called then
  51. the task can use a seperate word ID of it's own choosing, as well as the
  52. utility ID itself.
  53.  
  54. When a utility is run it is started by utility mananger. The code at the
  55. offset specified at (&10) in the utility code is then loaded in at &8000 and
  56. called with a WIMP slot of (&14)+(&60) bytes. If the utility wishes to use more
  57. memory than this then it must call Wimp_SlotSize itself.
  58.  
  59. Once the utility has been run Utility Manager will pass it the paramaters
  60. from the original UtilityManager_StartUtility message using a
  61. UtilityManager_Paramaters. This message will contain the utility ID, which
  62. should be checked for security.
  63.  
  64. Once the utility has received it's paramters it should not act straight away.
  65. All other utilities of the same ID will be sent a UtilityManager_Verify
  66. message containing the paramaters sent to a new instance.
  67.  
  68. If a new instance has the same or similar paramaters to another instance it
  69. may request a new instance to quit by sending UtilityManager_Abort.
  70.  
  71. Therefore, if a new instance receives a UtilityManager_Abort message at *any*
  72. time during it's life then it should quit straight away (sending an
  73. appropiate message to Utility Manager).
  74.  
  75. A new instance should wait for a short while (several WIMP polls) to allow
  76. any UtilityManager_Abort messages to get through to it before assuming it can
  77. start.
  78.  
  79. If a utility does start then it should send a UtilityManager_UtilityStarting
  80. message to Utility Manager (note: this does not have to contain the
  81. reference ID or the task handle of initiator). A similar message will be
  82. relayed to the initiating task.
  83.  
  84. If a utility fails to start (for any reason) then it should send a
  85. UtilityManager_StartFailed to Utility Manager (note: this does not have to
  86. contain the reference ID or the task handle of initiator). A similar message
  87. will be relayed to the initiating task. This message *must not* be sent if
  88. the instance has already sent a UtilityManager_UtilityStarting.
  89.  
  90. Contacting me
  91. -------------
  92.  
  93. If anyone wishes to contact me please send e-mail to:
  94.  
  95. Chris Davis..
  96.  
  97. Fidonet         2:253/417.6 or 2:257/501.7 
  98. Internet        chris@armadilo.demon.co.uk
  99. Highlander BBS  01452 384557/384702
  100.