resources.H File Reference

#include "env.H"

Include dependency graph for resources.H:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
class	CRcValueState
	Typed value tagged with a state and a time stamp. More...
class	CResource
	Home2L Resource. More...
class	CRcEvent
	Events delivered by a subscriber or to a driver. More...
class	CRcEventProcessor
	Event processor. More...
class	CRcEventTimer
	Timer that sends 'rceTimer' events over the event system. More...
class	CRcSubscriber
	Subscriber to follow an arbitrary set of resources. More...
class	CRcRequest
	Request description object. More...
class	CRcDriver
	Driver for local resources. More...
class	CRcEventDriver
	Local driver using the event processor mechanism for the 'DriveValue()' functionality. More...

Macros
#define	NO_VALUE_STATE   ((CRcValueState *) NULL)
	Special value meaning "none" for request values, should be used instead of 'NULL'.
#define	HOME2L_DRIVER(NAME)
	Define the entry point of a binary driver. More...
Request Priorities
Request priorities are in the range from 0..9, and the following constants define some recommended values. For writable resources, their drivers should set a permanent request at prio 0 for the default value. If no default is set, this lib will keep the last value if the last request is removed.
#define	rcPrioMin   0
	Minimum (lowest) priority.
#define	rcPrioNormal   3
	General default for new requests and default for automation rules.
#define	rcPrioMax   9
	Maximum (highest) priority.
#define	rcPrioDefault   0
	Preset defaults (typically by the driver)
#define	rcPrioRuleMin   1
	Minimum for automation rules.
#define	rcPrioRule   3
	Default for automation rules.
#define	rcPrioRuleMax   5
	Maximum for automation rules (unless safety-relevant, see rcPrioSafety)
#define	rcPrioUser   6
	Direct user interaction (e.g. user pushes button to open window shades)
#define	rcPrioShell   7
	Shell or administrative interaction (default priority in the Home2l shell)
#define	rcPrioSafety   8
	Automatic actions necessary to avoid damage (e.g. close roof window on bad weather)
#define	rcPrioIKnowWhatImDoing   9
	Maximum priority is reserved for explicit manual intervention (should not be used by any automation rule)
#define	rcPrioNone   -1
	Undefined priority (special value)

Typedefs
typedef CDict< CRcRequest >	CRcRequestSet
	Set of requests (for CResource::GetRequestSet() )
typedef bool	FRcEventFunc(class CRcEventProcessor *, CRcEvent *, void *)
	Event processor callback function. Example: bool OnEventFunc (CRcEventProcessor *ep, CRcEvent *ev, void *data);
typedef void	FRcDriverFunc(ERcDriverOperation, CRcDriver *, CResource *, CRcValueState *)
	Resources driver function. More...

Enumerations
enum	ERcType {   rctNone = 0 , rctBool , rctInt , rctFloat ,   rctString , rctTime , rctTrigger , rctMutex ,   rctPercent = rctUnitTypesBase , rctTemp , rctUnitTypesEND , rctUseState = rctEnumTypesBase ,   rctWindowState , rctPhoneState , rctPlayerState , rctEnumTypesEND }
	Resource major type. More...
enum	ERctUseState { }
	Use/presence state of the home (for 'rctUseState') More...
enum	ERctWindowState { }
	Window state (for 'rctWindowState') More...
enum	ERctPhoneState { }
	Phone state (for 'rctPhoneState') More...
enum	ERctPlayerState { }
	Music player state (for 'rctPlayerState') More...
enum	ERcState { rcsUnknown = 0 , rcsBusy , rcsValid , rcsNoReport = rcsUnknown }
	Resource state. More...
enum	ERcEventType {   rceNone = 0 , rceTimer , rceValueStateChanged , rceRequestChanged ,   rceDisconnected , rceConnected , rceDriveValue }
	Event type. More...
enum	ERcDriverOperation { rcdOpInit = 0 , rcdOpStop , rcdOpDriveValue }
	Driver operations. More...

Functions
ERcType	RcTypeGetBaseType (ERcType t)
	Return the underlying base type as a unique representative for compatible classes (e.g. rctFloat/rctTemp -> rctFloat)
bool	RcTypeIsStringBased (ERcType t)
	Return if the base type is 'rctString'; This is the set of types that have dynamic data.
static bool	RcTypeIsUnitType (ERcType t)
	Return whether the type is a unit type.
const char *	RcTypeGetUnit (ERcType t)
	Return the unit string; For non-unit types, an empty string is returned.
static bool	RcTypeIsEnumType (ERcType t)
	Return whether the type is a enumeration type.
int	RcTypeGetEnumValues (ERcType t)
	Return the number of possible values for an enumeration type.
const char *	RcTypeGetEnumValue (ERcType t, int idx, bool warn=true)
	Return the value for 'idx' for an enumeration type. Allowed index vaules range from 0 to N-1, where N is the number of possible values. If the index is invalid, "?" is returned and, if 'warn == true', a warning is logged.
int	RcTypeGetEnumIdx (ERcType t, const char *value, bool warn=true)
	Return the index of some value for an enumeration type. If the 'value' is out of range, -1 is returned and, if 'warn == true', a warning is logged.
const char *	RcGetUserRequestId ()
	Get the request ID for user interactions (see 'rc.userReqId'). More...
const char *	RcGetUserRequestAttrs ()
	Get the default request attributes for user interactions (see 'rc.userReqAttrs'). More...
Drivers (local) ...
int	RcGetDrivers ()
CRcDriver *	RcGetDriver (int n)
CRcDriver *	RcGetDriver (const char *lid)
const char *	RcGetDriverId (CRcDriver *cur)
Resources ...
int	RcLockHostResources (CRcHost *host)
	Query number of resources for a remote host. More...
CResource *	RcGetHostResource (CRcHost *host, int n)
void	RcUnlockHostResources (CRcHost *host)
int	RcLockDriverResources (CRcDriver *driver)
	Query the number of resources for a local driver. More...
CResource *	RcGetDriverResource (CRcDriver *driver, int n)
void	RcUnlockDriverResources (CRcDriver *driver)
Subscribers ...
int	RcLockSubscribers ()
	Query the number of existing subscribers and lock the subscriber database. More...
CRcSubscriber *	RcGetSubscriber (int n)
void	RcUnlockSubscribers ()
Init/Done ...
void	RcInit (bool enableServer=false, bool inBackground=false)
	Initialize the Resources library (and start the elaboration phase). This may be followed by driver declarations, and after that RcStart() must be called. More...
void	RcStart ()
	Complete the elaboration phase and start active operation. No more drivers and resources may be declared after this.
void	RcDone ()
	Shutdown the Resources library.
Running the library tasks in foreground ...
Functions to run the background work of the Resources library in a user-supplied thread. The following functions are only necessary and allowed if 'inBackground = false' was passed to RcInit() and the main program does not maintain the timers otherwise (see section Timers in file common/base.H). In other words: These functions may be used if there is no main event loop yet.
void	RcIterate ()
	Perform pending actions, call TimerIterate() and return.
int	RcRun (bool catchSignals=true)
	Run RcStart(), then RcIterate() in a main event loop until RcStop() is called. More...
void	RcStop ()
	Stop a loop started by RcRun().
Accessing resources ...
static CResource *	RcGetResource (const char *uri, bool allowWait=false)
	Lookup a resource by its URI and return a reference to it. More...
static CResource *	RcGet (const char *uri, bool allowWait=false)
	Lookup a resource by its URI and return a reference to it (shortcut for RcGetResource() ).
static void	RcGarbageCollection ()
	(For experts) Remove all presently unregistered resources from memory. More...
void	RcBump (CResource *rc=NULL, bool soft=false)
	(For experts) Try to reconnect a remote host now. More...
Subscriptions...
CRcSubscriber *	RcNewSubscriber (const char *subscrLid, CResource *rc=NULL)
	Create and register a new subscriber object and optionally subscribe to the given resource. More...
CRcSubscriber *	RcNewSubscriber (const char *subscrLid, const char *pattern)
	Create and register a new subscriber and subscribe to a set of resources. More...
static CRcSubscriber *	RcSubscribe (CRcSubscriber *subscr, CResource *rc)
	Subscribe to an additional resource.
static CRcSubscriber *	RcSubscribe (CRcSubscriber *subscr, const char *pattern)
	Subscribe to an additional set of resources.
static void	RcUnsubscribeFromAll (CRcSubscriber *subscr)
	Unsubscribe from all resources presently subscribed by 'subscr'. The caller remains owner of 'subscr', which does not need to reside in the heap.
static void	RcUnsubscribeFromAll (CRcSubscriber **pSubscr)
	Unsubscribe from all resources defined by 'subscr' and remove the subscriber object from heap.
Placing requests ...
static void	RcSetRequest (CResource *rc, CRcRequest *req)
void	RcSetRequest (const char *rcUri, CRcRequest *req)
	Add or replace a request (generic version). More...
static void	RcSetRequest (CResource *rc, CRcValueState *value, const char *reqGid=NULL, int priority=rcPrioNone, TTicks t0=NEVER, TTicks t1=NEVER, TTicks repeat=NEVER, TTicks hysteresis=NEVER)
void	RcSetRequest (const char *rcUri, CRcValueState *value, const char *reqGid=NULL, int priority=rcPrioNone, TTicks t0=NEVER, TTicks t1=NEVER, TTicks repeat=NEVER, TTicks hysteresis=NEVER)
	Add or replace a request (generic value, direct parameters). More...
static void	RcSetRequest (CResource *rc, bool valBool, const char *reqGid=NULL, int priority=rcPrioNone, TTicks t0=NEVER, TTicks t1=NEVER, TTicks repeat=NEVER, TTicks hysteresis=NEVER)
void	RcSetRequest (const char *rcUri, bool valBool, const char *reqGid=NULL, int priority=rcPrioNone, TTicks t0=NEVER, TTicks t1=NEVER, TTicks repeat=NEVER, TTicks hysteresis=NEVER)
	Add or replace a request (direct value and parameters).
static void	RcSetRequest (CResource *rc, int valInt, const char *reqGid=NULL, int priority=rcPrioNone, TTicks t0=NEVER, TTicks t1=NEVER, TTicks repeat=NEVER, TTicks hysteresis=NEVER)
void	RcSetRequest (const char *rcUri, int valInt, const char *reqGid=NULL, int priority=rcPrioNone, TTicks t0=NEVER, TTicks t1=NEVER, TTicks repeat=NEVER, TTicks hysteresis=NEVER)
	Add or replace a request (direct value and parameters).
static void	RcSetRequest (CResource *rc, float valFloat, const char *reqGid=NULL, int priority=rcPrioNone, TTicks t0=NEVER, TTicks t1=NEVER, TTicks repeat=NEVER, TTicks hysteresis=NEVER)
void	RcSetRequest (const char *rcUri, float valFloat, const char *reqGid=NULL, int priority=rcPrioNone, TTicks t0=NEVER, TTicks t1=NEVER, TTicks repeat=NEVER, TTicks hysteresis=NEVER)
	Add or replace a request (direct value and parameters).
static void	RcSetRequest (CResource *rc, const char *valString, const char *reqGid=NULL, int priority=rcPrioNone, TTicks t0=NEVER, TTicks t1=NEVER, TTicks repeat=NEVER, TTicks hysteresis=NEVER)
void	RcSetRequest (const char *rcUri, const char *valString, const char *reqGid=NULL, int priority=rcPrioNone, TTicks t0=NEVER, TTicks t1=NEVER, TTicks repeat=NEVER, TTicks hysteresis=NEVER)
	Add or replace a request (direct value and parameters).
static void	RcSetRequestFromStr (CResource *rc, const char *reqDef)
void	RcSetRequestFromStr (const char *rcUri, const char *reqDef)
	Set request by textual definition - see CRcRequest::SetFromStr() and the Home2L Book for more information on the syntax of request definitions.
static void	RcSetTrigger (CResource *rc, const char *reqGid=NULL, int priority=rcPrioNone, TTicks t0=NEVER, TTicks repeat=NEVER)
void	RcSetTrigger (const char *rcUri, const char *reqGid=NULL, int priority=rcPrioNone, TTicks t0=NEVER, TTicks repeat=NEVER)
	Set a trigger request (no value needs to be given).
static void	RcSetTriggerFromStr (CResource *rc, const char *reqDef)
void	RcSetTriggerFromStr (const char *rcUri, const char *reqDef)
	Set trigger request by textual definition.
static void	RcDelRequest (CResource *rc, const char *reqGid=NULL, TTicks t1=NEVER)
void	RcDelRequest (const char *rcUri, const char *reqGid=NULL, TTicks t1=NEVER)
	Delete a request. More...
Drivers: Registering a new driver ...
static void	RcRegisterDriver (CRcDriver *drv)
	Register a pre-initialized driver object (typically an object of a derived class with overloaded methods).
static void	RcRegisterDriver (const char *drvLid, FRcDriverFunc *func)
	Register and initialize a driver by its function. The driver object is created internally, and 'func' is called with the 'rcdOpInit' operation.
CRcEventDriver *	RcRegisterDriver (const char *drvLid, ERcState _successState=rcsNoReport)
	Register an event-based driver and return a reference to the event processor. More...
Drivers: Registering a new resource to a driver ...
See also: CResource::Register() .
static CResource *	RcRegisterResource (CRcDriver *drv, const char *rcLid, ERcType _type, bool _writable, void *_data=NULL)
static CResource *	RcRegisterResource (CRcDriver *drv, const char *rcLid, const char *rcTypeDef, void *_data=NULL)
CResource *	RcRegisterResource (const char *drvLid, const char *rcLid, ERcType _type, bool _writable, void *_data=NULL)
CResource *	RcRegisterResource (const char *drvLid, const char *rcLid, const char *rcTypeDef, void *_data=NULL)
CResource *	RcRegisterSignal (const char *name, ERcType type)
	Register a new resource for the built-in 'signal' driver.
CResource *	RcRegisterSignal (const char *name, CRcValueState *vs)
	Register a new resource for the built-in 'signal' driver and optionally set a default request. The type is taken from 'vs', and if 'vs' is valid, a default request is set.

Variables
const char *const	rcDefaultRequestId
	Request ID for default requests ("default")

Hosts ...
int	RcGetHosts ()
	Get number of known hosts.
CRcHost *	RcGetHost (int n)
	Get reference to host n, 0 <= n < number of hosts.
CRcHost *	RcGetHost (const char *id)
	Lookup host by its ID.
const char *	RcGetHostId (CRcHost *host)
	Get textual ID of 'host'.
static const char *	RcLocalHostId ()
	Get the ID of the local instance.