SensorMaster Library - Revision history

Admin at 14:38, 28 October 2018

2018-10-28T14:38:28Z

Admin: Created page with "

 TABLE OF CONTENTS  sensormaster/main/EndNotify sensormaster/main/FullSensorTable sensormaster/main/ReadFromManyByType sensormaster/main/ReadFromOneSensor sensormaster/ma..."

2018-10-28T14:34:01Z

Created page with "<pre> TABLE OF CONTENTS sensormaster/main/EndNotify sensormaster/main/FullSensorTable sensormaster/main/ReadFromManyByType sensormaster/main/ReadFromOneSensor sensormaster/ma..."

New page

<pre>
TABLE OF CONTENTS

sensormaster/main/EndNotify
sensormaster/main/FullSensorTable
sensormaster/main/ReadFromManyByType
sensormaster/main/ReadFromOneSensor
sensormaster/main/SensorTableByType
sensormaster/main/StartNotify
sensormaster/main/TotalSensors
sensormaster/main/WriteToOneSensor
sensormaster/main/EndNotify sensormaster/main/EndNotify

NAME
EndNotify -- Removes resources allocated by StartNotify().

SYNOPSIS
BOOL EndNotify(const APTR Trigger);

FUNCTION
This is the clean-up function to be called after StartNotify().

INPUTS
APTR Trigger : The APTR resulting from calling StartNotify()

RESULT
BOOL : Wheather it succeded or not.

EXAMPLE
See StartNotify() for a (somewhat) complete example.

NOTES
You must call EndNotify even on notifications that haven't been triggered.

BUGS

SEE ALSO
StartNotify(), libraries/sensormaster.h , libraries/hm_sensor.h

sensormaster/main/FullSensorTable sensormaster/main/FullSensorTable

NAME
FullSensorTable -- Return the full table of available sensors.

SYNOPSIS
uint32 FullSensorTable(void * const buffer, const uint32 length);

FUNCTION

INPUTS
buffer : pointer to an already allocated buffer to receive the buffer table
.
length : size of the buffer above. This should be sized in according to wh
at
TotalSensors() return.

RESULT
uint32: The actual amount of data written to the buffer.

EXAMPLE
const size_t s_table_size = sizeof(Sensor) * TotalSensors();
buffer = AllocVecTags(s_table_size, TAG_DONE);
uint32 result = FullSensorTable(buffer, s_table_size);
[use it]
FreeVec(s_table_size);

NOTES

BUGS

SEE ALSO
TotalSensors(), libraries/sensormaster.h

sensormaster/main/ReadFromManyByType sensormaster/main/ReadFromManyByType

NAME
ReadFromManyByType -- Returns all readings for one kind of sensor (by u
nit of measure) only.

SYNOPSIS
uint32 ReadFromManyByType(const enum UnitOfMeasure Unit, struct FullSen
sorReading * const Buffer, const uint32 buffer_size);

FUNCTION
This function is intended for those clients that only care about monitoring
ONE kind of measure, might it be fans, voltages or anything else currently supported.

INPUTS
Unit The unit of measure you want to know about: see libraries/hm_sensor.h
for definitions.
Buffer A pre-allocated buffer to hold enough items. Note that this will be
filled with FullSensorReading entries!
Buffer_size The size of said buffer.

RESULT
uint32: size of the actual buffer used.

EXAMPLE

NOTES

BUGS

SEE ALSO
ReadFromOneSensor(), SensorTableByType()
sensormaster/main/ReadFromOneSensor sensormaster/main/ReadFromOneSensor

NAME
ReadFromOneSensor -- Reads a sensor value (shocker!)

SYNOPSIS
BOOL ReadFromOneSensor(const uint32 index, SensorLevelType * const stor
age);

FUNCTION
Reads the value from one sensor.

INPUTS
index: which sensor to read. This index corresponds to the position of this
sensor
in the table returned by TotalSensors(ANY_UNIT) or si_Index in the table r
eturned
by SensorTableByType().

storage: pointer to a destination where to write the sensor value.

RESULT

BOOL: success. Returns TRUE if the read was successfull, FALSE if eith
er 'index' is too large or
said sensor is not readable.

EXAMPLE

NOTES
It's up to each sensor sub-library to read the value and possibly cache it.
Thus it's possible that a value has been cached according to the polling in
terval.

BUGS

SEE ALSO

sensormaster/main/SensorTableByType sensormaster/main/SensorTableByType

NAME
SensorTableByType -- Returns a table of all sensors by type.

SYNOPSIS
uint32 SensorTableByType(struct SensorIdent * buffer, const uint32 leng
th, const enum UnitOfMeasure type);

FUNCTION

INPUTS
buffer: A properly allocated buffer for SensorIdent structures
length: the length of the buffer.
type: which type of sensor you want.

RESULT
uint32: the actual size of the buffer that was used (written to).

EXAMPLE

NOTES

BUGS

SEE ALSO

sensormaster/main/StartNotify sensormaster/main/StartNotify

NAME
StartNotify -- Register for notification on sensor level change.

SYNOPSIS
BOOL StartNotify(const uint32 sensor_number, const SensorLevelType leve
l, enum SensorCondition condition, const struct MsgPort * const call_me_maybe, const uint32 userdata);

FUNCTION
Registers for a notification upon level change. This function *MUST* be pai
red with a corresponding call to EndNotify().
Internally, it allocates a full TriggerMessage on the caller's behalf, and
sends it via PutMsg()
to the sensormaster notification process.
Once a notification is started, the caller must wait on the supplied Messa
ge Port.
Multiple notifications can be active at the same time; if this is the case
,
to distinguish between different notifications, the caller can use the "tok
en" parameter.

Once the caller receives the notification (via a properly filled-up Trigge
rMessage), it
must call EndNotify().

INPUTS
sensor_number: the number of sensor this trigger refers to. Sensors are num
bered from 0
and found via FullSensorTable() (or SensorTableByType() ).

level: the level you want to trigger the sensor on. Remember to use values
consistent with the type
of each sensor. Check for those in include/hm_sensor.h.

condition: to be paired with the above, one of SC_BELOW, SC_ABOVE, SC_EXA
CT.
SC_BELOW and SC_ABOVE respectively resolve to <= and >= .
Don't use SC_EXACT unless you really mean it.

call_me_maybe: message port to send the TriggerMessage back to.

userdata: can be anything the user-program wants to. It'll be put in the T
riggerMessage
structure that'll be sent back to the message port, in the tm_UserData fiel
d.

RESULT
APTR : an opaque handle representing the trigger. To be passed to EndN
otify() to deallocate
associated resources.

EXAMPLE
MsgPort * mport = (MsgPort*)IExec->AllocSysObjectTags(ASOT_PORT,
ASOPORT_AllocSig, TRUE,
ASOPORT_Action, PA_SIGNAL,
ASOPORT_Target, IExec->FindTask(NULL),
TAG_DONE);
APTR handle=nullptr;
handle = StartNotify(16, 300l, SC_BELOW, mport, 666);

if(handle != nullptr)
{
IExec->WaitPort(mport);
//Trigger arrived!!
EndNotify(handle);
}

NOTES

BUGS

SEE ALSO
EndNotify(), libraries/sensormaster.h , libraries/hm_sensor.h

sensormaster/main/TotalSensors sensormaster/main/TotalSensors

NAME
TotalSensors -- Returns total number of sensors.

SYNOPSIS
uint32 TotalSensors(const enum UnitOfMeasure unit);

FUNCTION
Returns the total number of sensors available in the system.
The unit of measure parameter can be used to filter out what kind you want
.

INPUTS
Unit : which unit of measure the sensors belong to. You can supply ANY_UNIT
(conveniently numbered 0)
to have the complete number.

RESULT
uint32 : the total number of sensor for the type supplied in "Unit" or
all of them if ANY_UNIT was used.

EXAMPLE

NOTES

BUGS
Sheesh! My code is perfect!

SEE ALSO
SensorTableByType() , libraries/hm_sensor.h
sensormaster/main/WriteToOneSensor sensormaster/main/WriteToOneSensor

NAME
WriteToOneSensor -- Writes to one sensor. No surprise there.

SYNOPSIS
BOOL WriteToOneSensor(const uint32 index, const SensorLevelType value);

FUNCTION
Writes the supplied value to the sensor specified in 'index'.

INPUTS
index: index for the sensor to write, as seen in the full sensor table retu
rned by FullSensorTable() or in SensorIdent->si_Index from SensorTableByType().

RESULT
BOOL: success. True if the sensor allows writing to it.

EXAMPLE

NOTES

BUGS

SEE ALSO
FullSensorTable(), SensorTableByType()
</pre>

@@ Line 50: / Line 50: @@
     INPUTS
-		buffer : pointer to an already allocated buffer to receive the buffer table
+		buffer : pointer to an already allocated buffer to receive the buffer table.
+  		length : size of the buffer above. This should be sized in according to what TotalSensors() return.
     RESULT
@@ Line 76: / Line 73: @@
     NAME
-       ReadFromManyByType -- Returns all readings for one kind of sensor (by u
+       ReadFromManyByType -- Returns all readings for one kind of sensor (by unit of measure) only.
     SYNOPSIS
-       uint32 ReadFromManyByType(const enum UnitOfMeasure Unit, struct FullSen
+       uint32 ReadFromManyByType(const enum UnitOfMeasure Unit, struct FullSensorReading * const Buffer, const uint32 buffer_size);
     FUNCTION
-		This function is intended for those clients that only care about monitoring
+		This function is intended for those clients that only care about monitoring ONE kind of measure, might it be fans, voltages or anything else currently supported.
     INPUTS
-		Unit	The unit of measure you want to know about: see libraries/hm_sensor.h
+		Unit	The unit of measure you want to know about: see libraries/hm_sensor.h for definitions.
-for definitions.
+  		Buffer	A pre-allocated buffer to hold enough items. Note that this will be filled with FullSensorReading entries!
   		Buffer_size The size of said buffer.
@@ Line 111: / Line 103: @@
     SYNOPSIS
-       BOOL ReadFromOneSensor(const uint32 index, SensorLevelType * const stor
+       BOOL ReadFromOneSensor(const uint32 index, SensorLevelType * const storage);
     FUNCTION
@@ Line 118: / Line 109: @@
     INPUTS
-		index: which sensor to read. This index corresponds to the position of this
+		index: which sensor to read. This index corresponds to the position of this sensor
- sensor
+  		in the table returned by TotalSensors(ANY_UNIT) or si_Index in the table returned
   		by SensorTableByType().
@@ Line 128: / Line 117: @@
     RESULT
-        BOOL: success. Returns TRUE if the read was successfull, FALSE if eith
+        BOOL: success. Returns TRUE if the read was successfull, FALSE if either 'index' is too large or said sensor is not readable.
     EXAMPLE
@@ Line 149: / Line 136: @@
     SYNOPSIS
-       uint32 SensorTableByType(struct SensorIdent * buffer, const uint32 leng
+       uint32 SensorTableByType(struct SensorIdent * buffer, const uint32 length, const enum UnitOfMeasure type);
     FUNCTION
@@ Line 176: / Line 162: @@
     SYNOPSIS
-       BOOL StartNotify(const uint32 sensor_number, const SensorLevelType leve
+       BOOL StartNotify(const uint32 sensor_number, const SensorLevelType level, enum SensorCondition condition, const struct MsgPort * const call_me_maybe, const uint32 userdata);
     FUNCTION
-		Registers for a notification upon level change. This function *MUST* be pai
+		Registers for a notification upon level change. This function *MUST* be paired with a corresponding call to EndNotify().
-red with a corresponding call to EndNotify().
+  		Internally, it allocates a full TriggerMessage on the caller's behalf, and sends it via PutMsg()
   		to the sensormaster notification process.
-  		Once a notification is started, the caller must wait on the supplied Messa
+  		Once a notification is started, the caller must wait on the supplied Message Port.
-ge Port.
+  		Multiple notifications can be active at the same time; if this is the case,
-  		Multiple notifications can be active at the same time; if this is the case
+		to distinguish between different notifications, the caller can use the "token" parameter.
-  		Once the caller receives the notification (via a properly filled-up Trigge
+  		Once the caller receives the notification (via a properly filled-up TriggerMessage), it
   		must call EndNotify().
     INPUTS
-		sensor_number: the number of sensor this trigger refers to. Sensors are num
+		sensor_number: the number of sensor this trigger refers to. Sensors are numbered from 0
   		and found via FullSensorTable() (or SensorTableByType() ).
-  		level: the level you want to trigger the sensor on. Remember to use values
+  		level: the level you want to trigger the sensor on. Remember to use values consistent with the type
   		of each sensor. Check for those in include/hm_sensor.h.
-  		condition: to be paired with the above, one of 	SC_BELOW, SC_ABOVE, SC_EXA
+  		condition: to be paired with the above, one of 	SC_BELOW, SC_ABOVE, SC_EXACT.
   		SC_BELOW and SC_ABOVE respectively resolve to <= and >= .
   		Don't use SC_EXACT unless you really mean it.
@@ Line 212: / Line 188: @@
   		call_me_maybe: message port to send the TriggerMessage back to.
-  		userdata: can be anything the user-program wants to. It'll be put in the T
+  		userdata: can be anything the user-program wants to. It'll be put in the TriggerMessage
-riggerMessage
+		structure that'll be sent back to the message port, in the tm_UserData field.
     RESULT
-        APTR : an opaque handle representing the trigger. To be passed to EndN
+        APTR : an opaque handle representing the trigger. To be passed to EndNotify() to deallocate
   		associated resources.
@@ Line 256: / Line 229: @@
     FUNCTION
 		Returns the total number of sensors available in the system.
-  		The unit of measure parameter can be used to filter out what kind you want
+  		The unit of measure parameter can be used to filter out what kind you want.
     INPUTS
-		Unit : which unit of measure the sensors belong to. You can supply ANY_UNIT
+		Unit : which unit of measure the sensors belong to. You can supply ANY_UNIT(conveniently numbered 0)
   		to have the complete number.
     RESULT
-        uint32 : the total number of sensor for the type supplied in "Unit" or
+        uint32 : the total number of sensor for the type supplied in "Unit" or all of them if ANY_UNIT was used.
     EXAMPLE
@@ Line 289: / Line 259: @@
     INPUTS
-		index: index for the sensor to write, as seen in the full sensor table retu
+		index: index for the sensor to write, as seen in the full sensor table returned by FullSensorTable() or in SensorIdent->si_Index from SensorTableByType().
     RESULT