SensorMaster Library

From wiki.amiga.org
Jump to navigation Jump to search
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 what 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 unit of measure) only.

   SYNOPSIS
      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 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 storage);

   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 returned
 		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 either '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 length, 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 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 paired 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 Message 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 "token" parameter.
 
 		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 numbered 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_EXACT.
 		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 TriggerMessage
		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 EndNotify() 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 returned 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()