HDOff - Developer`s Note v1.2
                © 1997 by Gideon Zenz - all rights reserved

INTRODUCTION

This  is  my  2nd  try  of  the Developer`s Guide for HDOff.  I hope it`s a
little bit better than the 1st version.  New for this, the port`s structure
is also included in a C-version, and also a C example program.

CHANGES

I  decided  to  make  some adjustements on the portstructure!  Note the new
field HD_Reserved, and also that there are now NO BYTE fields!  I hope this
makes programming a bit easier.

Changes for port 101: (HDOff 1.35)
hd_(Un|%)Subscribe  doesn`t return 0 on failure, but hd_Failure instead (as
0  ^=  hd_GetStats).   Thx to M.Andree for this.  Cleaned up the cmd`s, now
hd_Die is -1 instead of 0xff.

Changes for port 103: (HDOff 1.36)
- HDOff  is   multi-thread  now,  so  your  msg`s  are (nearly) immediately
  processed now!
- A   hd_SetStats  with  0  disables now the HD for HDOff.  A value between
  0<x<60 will be ignored
- New command hd_HDoffVersion

Changes for port 104: (HDOff 1.37)
- New command hd_QueryCtrl

Changes for port 105: (HDOff 1.40)
- New Option ProModule for hd_QueryCtrl

THE PORT

HDOff  communicates  with  the  world  using  an exec messageport.  You can
simply  send  messages  to  this  port to get informations about the actual
status  f.e.   of the harddrives or set new parameter and so on.  If you do
not  now how to use such a port, have a look in the RKRM`s and the included
demosource  (GetStats.c).   It is written in C, but you should hopefully be
able to understand this, even if you now little about C.

Now the real part:

The name of the port is "HDOFF_PORT"

Here is the structure for C :

NOTE the actual portversion is 105  (standing for 1.05)

NOTE also that HD_Reserved must be 0!

/****************************************************************************/
/* The message-structure*/
 struct HD {
     struct  Message HD_Msg;
     WORD    HD_Cmd;
     UWORD   HD_TimeHD0;
     UWORD   HD_TimeHD1;
     UWORD   HD_TimeLeftHD0;
     UWORD   HD_TimeLeftHD1;
     BOOL    HD_StatHD0;
     BOOL    HD_StatHD1;
     ULONG   HD_PortVer;
     LONG    HD_Reserved;
     }
/* define HDOff`s commands*/
#define hd_GetStats     0x0
#define hd_SetStats     0x1
#define hd_Subscribe    0x2
#define hd_Unsubscribe  0x3
#define hd_StopDrive    0x4
#define hd_Quit         0x5
#define hd_ForceQuit    0x6
#define hd_HDoffVersion 0x7
#define hd_QueryCtrl    0x8
#define hd_Failure      -2
#define hd_Die          -1
/****************************************************************************/

And here the assemblerstructure:

/****************************************************************************/
	STRUCTURE       HD,MN_SIZE
		WORD    HD_Cmd
		UWORD   HD_TimeHD0      ;Time in secs (startvalue)
		UWORD   HD_TimeHD1
		UWORD   HD_TimeLeftHD0  ;Time in secs (actual)
		UWORD   HD_TimeLeftHD1
		BOOL    HD_StatHD0      ;$ffff(TRUE): Drive off
		BOOL    HD_StatHD1
		ULONG   HD_PortVer      ;Version of the port
		LONG    HD_Reserved     ;reserved for future use! Set to 0!
		LABEL   HD_SIZE

hd_GetStats     equ     $00
hd_SetStats     equ     $01
hd_Subscribe    equ     $02
hd_Unsubscribe  equ     $03
hd_StopDrive    equ     $04
hd_Quit         equ     $05
hd_ForceQuit    equ     $06
hd_HDoffVersion	equ	$07
hd_QueryCtrl    equ     $08
hd_Failure      equ     -2
hd_Die          equ     -1
/****************************************************************************/


COMMAND DOCUMENTATION

hd_GetStats     equ     $00
~~~~~~~~~~~
This gives you back the message filled with valid values.

hd_SetStats     equ     $01
~~~~~~~~~~~
You  can  set  HD_TimeHD0 and HD_TimeHD1 to new values, and you will get an
answer like hd_GetStats.  This means, you have to initalize HD_TimeHDx with
the  number  of seconds(!) you want and PutMsg() it.  HDOff reset`s now its
internal timecounters to your values.

hd_Subscribe    equ     $02
~~~~~~~~~~~~
If  you  subscribe,  you  will  get  a  message  everytime a drive has been
switched  on/off.  Check the answer!  If HD_Cmd=hd_Failure your subscribing
was unsuccessfull.

If  a drive changed its status, you`ll get a messy with HD_Cmd=hd_Subscribe
filled  with the new datas.  You must not change/reply or do something else
with this messy (except reading it out, of course ;) !

hd_Unsubscribe  equ     $03
~~~~~~~~~~~~~~
You   won`t   get  a  messys  on  a  drive  power  down/up  any  more.   If
HD_Cmd=hd_Failure you weren`t subscribed :)

hd_StopDrive    equ     $04
~~~~~~~~~~~~
Here you can switch a drive off by setting HD_StatHDx to 0xFFFF.

hd_Quit         equ     $05
~~~~~~~
This tries to terminate HDOff.  If the reply has HD_Cmd=hd_Die quitting was
successfull, if not not :)

hd_ForceQuit    equ     $06
~~~~~~~~~~~~
The  same as hd_Quit, but using the force option (can`t fail), and you will
get a reply.  NOTE:  read the warning about the FORCE-option in the doc!

hd_Die          equ     -1
~~~~~~
NOTE:  you can _only_ recive this!  If you get this Message, HDOff has been
terminated and you must stop using the port any longer!  (You will only get
this if you subscribed).

hd_Failure      equ     -2
~~~~~~~~~~
NOTE:   you  can  only recive this, too!  It`s returned by hd_Subscribe and
hd_Unsubscribe on error.

hd_HDoffVersion	equ	$07
~~~~~~~~~~~~~~~
This  one  gives you a pointer to HDOff`s versionstring in HD_PortVer back,
e.g.  "$VER:  HDOff x.x (x.x.x)". NOTE: Of cause read only!

hd_QueryCtrl    equ     $08
~~~~~~~~~~~~
This  nice thing will tell you wich controller you`re on.  The result is in
HD_StatHD0.   A  0  means  A600/A1200, a 1 A4000, and new for 1.40, 2 means
CD32 ProModule.

EXAMPLE

If  you  want, have a look in GetStats.c.  It shows you how to deal with an
exec port and how to use the hd_GetStats and hd_HDoffVersion commands.

HISTORY
	v1.0  - extremly quick&dirty docs about the port
	v1.1  - Reformated the text and added the C informations
	v1.11 - Adapted for HDOff 1.36
        v1.12 - Adapted for HDOff 1.37
        v1.2  - Adapted for HDOff 1.40