Description

Top-level functionality of this library - most commonly used functions can be found here.

Collaboration diagram for Main API:

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.

Function Documentation

◆ RcInit()

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.

Parameters

enableServer	enables the server mode: false => server is off, independent on the configuration environment. true => enable server if and as set in the configuration environment.
inBackground	switches on the timer thread using 'TimerStart' and friends. If disabled, the caller is responsible for iterating the timer. This can be the case if the caller itself has an own background timer thread (e.g. 'home2l-wallclock') or if RcRun() / RcStop() is to be used for the main program.

◆ RcRun()

int RcRun ( bool catchSignals = true )

Run RcStart(), then RcIterate() in a main event loop until RcStop() is called.

Parameters

catchSignals controls whether the signals SIGTERM ("exit nicely", default of the kill(1) command) and SIGINT (Ctrl-C) are caught temporarly and lead to an immediate return of this function.

Returns: the signal number if the function has been stopped by a caught signal, else 0.

◆ RcGetResource()

static CResource * RcGetResource	(	const char *	uri,
		bool	allowWait = `false`
	)

inlinestatic

Lookup a resource by its URI and return a reference to it.

Parameters

uri	is the full URI of the resource.
allowWait	allows to wait for network operations if the resource is not yet known. This is useful for the Home2L Shell to display the properties (type, state, value) right afterwards. In most other applications, the default value of 'false' is more appropriate.

If the URI is not absolute, it is relative to "/alias".

The returned pointer is always valid (!= NULL) unless the URI is syntactically incorrect and will neither now nor in the future refer to a valid resource. Hence, the pointer can be used for identity comparisons. It will be uniquely associated with the URI until the program terminates or RcGarbageCollection() is called. It is allowed to pass 'uri == NULL', in which case NULL will be returned without any warning.

Definition at line 2878 of file resources.H.

◆ RcGarbageCollection()

static void RcGarbageCollection ( )

inlinestatic

(For experts) Remove all presently unregistered resources from memory.

 This may free some memory, but at the same time invalidates any existing reference to @ref CResource objects.
 Can only be called if no 'CResource *' reference is presently used!

Definition at line 2895 of file resources.H.

◆ RcBump()

void RcBump	(	CResource *	rc = `NULL`,
		bool	soft = `false`
	)

(For experts) Try to reconnect a remote host now.

This may be used to accelerate automatic network reconnections, for example, if it is known that a link has just been re-established.

Parameters

rc	is a resource which should be updated soon. Its host will be reconnected. If NULL is passed, all remote hosts are (re)connected.
soft	selects whether a (re-)connection attempt is omitted if the connection is in standby mode.

◆ RcNewSubscriber() [1/2]

CRcSubscriber * RcNewSubscriber	(	const char *	subscrLid,
		CResource *	rc = `NULL`
	)

Create and register a new subscriber object and optionally subscribe to the given resource.

Parameters

subscrLid	is the local ID of the subscriber.
rc	is a reference to the resource to subscribe to (or NULL if no resource should be added now).

Returns: new subscriber object.

◆ RcNewSubscriber() [2/2]

CRcSubscriber * RcNewSubscriber	(	const char *	subscrLid,
		const char *	pattern
	)

Create and register a new subscriber and subscribe to a set of resources.

Parameters

subscrLid	is the local ID of the subscriber.
pattern	may be the URI of a resource, a pattern with allowed wildcards, or a comma-separated list of URIs/patterns.

Returns: new subscriber object.

◆ RcSetRequest() [1/2]

void RcSetRequest	(	const char *	rcUri,
		CRcRequest *	req
	)

Add or replace a request (generic version).

Parameters

rcUri	identifies the resource.
req	must by a dynamically allocated object, which is handed over and must no longer be used by the caller afterwards.

◆ RcSetRequest() [2/2]

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).

Parameters

rcUri	identifies the resource.
value	specifies the requested value (only type and value are used).
reqGid	identifies the request (default: instance name).
priority	is the request priority attribute (default: 'rctPrioNormal').
t0	is the activation (start) time attribute (optional).
t1	is the expiration (stop) time attribute (optional).
repeat	is the repetition interval attribute (optional).
hysteresis	is the hysteresis attribute (optional).

The request attributes are explaind in the Home2L Book.

◆ RcDelRequest()

void RcDelRequest	(	const char *	rcUri,
		const char *	reqGid = `NULL`,
		TTicks	t1 = `NEVER`
	)

Delete a request.

Parameters

rcUri	identifies the resource.
reqGid	is the global request identifier (GID) and identifies the request. If set to 'NULL', the instance name is used.
t1	is the time at which the deletion takes effect.

If t1 is non-zero and a request with the given reqId exists, its off-time is replaced by t1.

◆ RcRegisterDriver()

CRcEventDriver * RcRegisterDriver	(	const char *	drvLid,
		ERcState	_successState = `rcsNoReport`
	)

Register an event-based driver and return a reference to the event processor.

Driven values are collected by the returned event processor, and the caller must process the events accordingly. Reporting of values can be done via the 'Report...()' methods of the respective resources. The CRcEventProcessor object remains owned by the library.

Parameters

drvLid	is the ID of the new driver.
_successState'	is the value returned by DriveValue(); possible values are:

'rcsNoReport' or 'rcsUnknown' (default): nothing is reported back automatically; the application must report something soon (e.g. a busy state by calling CResource::ReportBusy() ) and should report a valid and up-to-date value later.
'rcsBusy': 'rcsBusy' with the old value is reported now; the application must report a valid and up-to-date value later.
'rcsValid': the driven value is reported back; no further action by the driver necessary, but no errors are allowed to happen.

Description

Init/Done ...

Running the library tasks in foreground ...

Accessing resources ...

Subscriptions...

Placing requests ...

Drivers: Registering a new driver ...

Drivers: Registering a new resource to a driver ...

Function Documentation

◆ RcInit()

◆ RcRun()

◆ RcGetResource()

◆ RcGarbageCollection()

◆ RcBump()

◆ RcNewSubscriber() [1/2]

◆ RcNewSubscriber() [2/2]

◆ RcSetRequest() [1/2]

◆ RcSetRequest() [2/2]

◆ RcDelRequest()

◆ RcRegisterDriver()