home *** CD-ROM | disk | FTP | other *** search
/ Amiga MA Magazine 1998 #6 / amigamamagazinepolishissue1998.iso / disks / tools / hdoff_1.37a / developers.doc < prev    next >
Text File  |  1977-12-31  |  6KB  |  181 lines
  1.  
  2.                          HDOff - Developer`s Note v1.11
  3.                 © 1996 by Gideon Zenz - all rights reserved
  4.  
  5. INTRODUCTION
  6.  
  7. This  is  my  2nd  try  of  the Developer`s Guide for HDOff.  I hope it`s a
  8. little bit better than the 1st version.  New for this, the port`s structure
  9. is also included in a C-version, and also a C example program.
  10.  
  11. CHANGES
  12.  
  13. I  decided  to  make  some adjustements on the portstructure!  Note the new
  14. field HD_Reserved, and also that there are now NO BYTE fields!  I hope this
  15. makes programming a bit easier.
  16.  
  17. Changes for port 101: (HDOff 1.35)
  18. hd_(Un|%)Subscribe  doesn`t return 0 on failure, but hd_Failure instead (as
  19. 0  ^=  hd_GetStats).   Thx to M.Andree for this.  Cleaned up the cmd`s, now
  20. hd_Die is -1 instead of 0xff.
  21.  
  22. Changes for port 103: (HDOff 1.36)
  23. - HDOff  is   multi-thread  now,  so  your  msg`s  are (nearly) immediately
  24.   processed now!
  25. - A   hd_SetStats  with  0  disables now the HD for HDOff.  A value between
  26.   0<x<60 will be ignored
  27. - New command hd_HDoffVersion
  28.  
  29. Changes for port 104: (HDOff 1.37)
  30. - New command hd_QueryCtrl
  31.  
  32. THE PORT
  33.  
  34. HDOff  communicates  with  the  world  using  an exec messageport.  You can
  35. simply  send  messages  to  this  port to get informations about the actual
  36. status  f.e.   of the harddrives or set new parameter and so on.  If you do
  37. not  now how to use such a port, have a look in the RKRM`s and the included
  38. demosource  (GetStats.c).   It is written in C, but you should hopefully be
  39. able to understand this, even if you now little about C.
  40.  
  41. Now the real part:
  42.  
  43. The name of the port is "HDOFF_PORT"
  44.  
  45. Here is the structure for C :
  46.  
  47. NOTE the actual portversion is 104  (standing for 1.04)
  48.  
  49. NOTE also that HD_Reserved must be 0!
  50.  
  51. /****************************************************************************/
  52. /* The message-structure*/
  53.  struct HD {
  54.      struct  Message HD_Msg;
  55.      WORD    HD_Cmd;
  56.      UWORD   HD_TimeHD0;
  57.      UWORD   HD_TimeHD1;
  58.      UWORD   HD_TimeLeftHD0;
  59.      UWORD   HD_TimeLeftHD1;
  60.      BOOL    HD_StatHD0;
  61.      BOOL    HD_StatHD1;
  62.      ULONG   HD_PortVer;
  63.      LONG    HD_Reserved;
  64.      }
  65. /* define HDOff`s commands*/
  66. #define hd_GetStats     0x0
  67. #define hd_SetStats     0x1
  68. #define hd_Subscribe    0x2
  69. #define hd_Unsubscribe  0x3
  70. #define hd_StopDrive    0x4
  71. #define hd_Quit         0x5
  72. #define hd_ForceQuit    0x6
  73. #define hd_HDoffVersion 0x7
  74. #define hd_QueryCtrl    0x8
  75. #define hd_Failure      -2
  76. #define hd_Die          -1
  77. /****************************************************************************/
  78.  
  79. And here the assemblerstructure:
  80.  
  81. /****************************************************************************/
  82.     STRUCTURE       HD,MN_SIZE
  83.         WORD    HD_Cmd
  84.         UWORD   HD_TimeHD0      ;Time in secs (startvalue)
  85.         UWORD   HD_TimeHD1
  86.         UWORD   HD_TimeLeftHD0  ;Time in secs (actual)
  87.         UWORD   HD_TimeLeftHD1
  88.         BOOL    HD_StatHD0      ;$ffff(TRUE): Drive off
  89.         BOOL    HD_StatHD1
  90.         ULONG   HD_PortVer      ;Version of the port
  91.         LONG    HD_Reserved     ;reserved for future use! Set to 0!
  92.         LABEL   HD_SIZE
  93.  
  94. hd_GetStats     equ     $00
  95. hd_SetStats     equ     $01
  96. hd_Subscribe    equ     $02
  97. hd_Unsubscribe  equ     $03
  98. hd_StopDrive    equ     $04
  99. hd_Quit         equ     $05
  100. hd_ForceQuit    equ     $06
  101. hd_HDoffVersion    equ    $07
  102. hd_QueryCtrl    equ     $08
  103. hd_Failure      equ     -2
  104. hd_Die          equ     -1
  105. /****************************************************************************/
  106.  
  107.  
  108. COMMAND DOCUMENTATION
  109.  
  110. hd_GetStats     equ     $00
  111. ~~~~~~~~~~~
  112. This gives you back the message filled with valid values.
  113.  
  114. hd_SetStats     equ     $01
  115. ~~~~~~~~~~~
  116. You  can  set  HD_TimeHD0 and HD_TimeHD1 to new values, and you will get an
  117. answer like hd_GetStats.  This means, you have to initalize HD_TimeHDx with
  118. the  number  of seconds(!) you want and PutMsg() it.  HDOff reset`s now its
  119. internal timecounters to your values.
  120.  
  121. hd_Subscribe    equ     $02
  122. ~~~~~~~~~~~~
  123. If  you  subscribe,  you  will  get  a  message  everytime a drive has been
  124. switched  on/off.  Check the answer!  If HD_Cmd=hd_Failure your subscribing
  125. was unsuccessfull.
  126.  
  127. If  a drive changed its status, you`ll get a messy with HD_Cmd=hd_Subscribe
  128. filled  with the new datas.  You must not change/reply or do something else
  129. with this messy (except reading it out, of course ;) !
  130.  
  131. hd_Unsubscribe  equ     $03
  132. ~~~~~~~~~~~~~~
  133. You   won`t   get  a  messys  on  a  drive  power  down/up  any  more.   If
  134. HD_Cmd=hd_Failure you weren`t subscribed :)
  135.  
  136. hd_StopDrive    equ     $04
  137. ~~~~~~~~~~~~
  138. Here you can switch a drive off by setting HD_StatHDx to 0xFFFF.
  139.  
  140. hd_Quit         equ     $05
  141. ~~~~~~~
  142. This tries to terminate HDOff.  If the reply has HD_Cmd=hd_Die quitting was
  143. successfull, if not not :)
  144.  
  145. hd_ForceQuit    equ     $06
  146. ~~~~~~~~~~~~
  147. The  same as hd_Quit, but using the force option (can`t fail), and you will
  148. get a reply.  NOTE:  read the warning about the FORCE-option in the doc!
  149.  
  150. hd_Die          equ     -1
  151. ~~~~~~
  152. NOTE:  you can _only_ recive this!  If you get this Message, HDOff has been
  153. terminated and you must stop using the port any longer!  (You will only get
  154. this if you subscribed).
  155.  
  156. hd_Failure      equ     -2
  157. ~~~~~~~~~~
  158. NOTE:   you  can  only recive this, too!  It`s returned by hd_Subscribe and
  159. hd_Unsubscribe on error.
  160.  
  161. hd_HDoffVersion    equ    $07
  162. ~~~~~~~~~~~~~~~
  163. This  one  gives you a pointer to HDOff`s versionstring in HD_PortVer back,
  164. e.g.  "$VER:  HDOff x.x (x.x.x)". NOTE: Of cause read only!
  165.  
  166. hd_QueryCtrl    equ     $08
  167. ~~~~~~~~~~~~
  168. This  nice thing will tell you wich controller you`re on.  The result is in
  169. HD_StatHD0.  A 0 means A600/A1200, a 1 A4000.
  170.  
  171. EXAMPLE
  172.  
  173. If  you  want, have a look in GetStats.c.  It shows you how to deal with an
  174. exec port and how to use the hd_GetStats and hd_HDoffVersion commands.
  175.  
  176. HISTORY
  177.     v1.0  - extremly quick&dirty docs about the port
  178.     v1.1  - Reformated the text and added the C informations
  179.     v1.11 - Adapted for HDOff 1.36
  180.         v1.12 - Adapted for HDOff 1.37
  181.