CRcRequest Class Reference

Description

Request description object.

Request objects define the request for a certain value together with some additional attributes. The concept of requests is introduced to deal with potentially concurrent write accesses to resources. Besides the requested value, a request may have some optional attributes set, which are explaind in detail in the Home2L Book.

Definition at line 2056 of file resources.H.

#include "resources.H"

Public Member Functions
	CRcRequest ()
	Default constructor.
	CRcRequest (CRcRequest *req)
	Construct by cloning an existing request object (the origin is set, not cloned).
	CRcRequest (CRcValueState *_value, const char *_gid=NULL, int _priority=rcPrioNone, TTicks _t0=NEVER, TTicks _t1=NEVER, TTicks repeat=NEVER, TTicks _hysteresis=NEVER)
	Construct with value and optional attributes.
	CRcRequest (bool _value, const char *_gid=NULL, int _priority=rcPrioNone, TTicks _t0=NEVER, TTicks _t1=NEVER, TTicks repeat=NEVER, TTicks _hysteresis=NEVER)
	Construct with value and optional attributes.
	CRcRequest (int _value, const char *_gid=NULL, int _priority=rcPrioNone, TTicks _t0=NEVER, TTicks _t1=NEVER, TTicks repeat=NEVER, TTicks _hysteresis=NEVER)
	Construct with value and optional attributes.
	CRcRequest (float _value, const char *_gid=NULL, int _priority=rcPrioNone, TTicks _t0=NEVER, TTicks _t1=NEVER, TTicks repeat=NEVER, TTicks _hysteresis=NEVER)
	Construct with value and optional attributes.
	CRcRequest (const char *_value, const char *_gid=NULL, int _priority=rcPrioNone, TTicks _t0=NEVER, TTicks _t1=NEVER, TTicks repeat=NEVER, TTicks _hysteresis=NEVER)
	Construct with value and optional attributes.
	CRcRequest (TTicks _value, const char *_gid=NULL, int _priority=rcPrioNone, TTicks _t0=NEVER, TTicks _t1=NEVER, TTicks repeat=NEVER, TTicks _hysteresis=NEVER)
	Construct with value and optional attributes.

Friends
class	CResource

Setting properties ...
void	Reset ()
	Clear the value and set default attributes ( NO_VALUE_STATE, NEVER, NULL or equivalent; priority = rcPrioNormal; origin to here and now). The GID is left unmodified unless it is an empty string.
void	Set (CRcRequest *req)
	Define a request by copying attributes from another. The origin is not copied.
void	Set (CRcValueState *_value=NULL, const char *_gid=NULL, int _priority=rcPrioNone, TTicks _t0=NEVER, TTicks _t1=NEVER, TTicks _repeat=NEVER, TTicks _hysteresis=NEVER)
	Define a request with all parameters and attributes. More...
void	Set (bool _value, const char *_gid=NULL, int _priority=rcPrioNone, TTicks _t0=NEVER, TTicks _t1=NEVER, TTicks _repeat=NEVER, TTicks _hysteresis=NEVER)
void	Set (int _value, const char *_gid=NULL, int _priority=rcPrioNone, TTicks _t0=NEVER, TTicks _t1=NEVER, TTicks _repeat=NEVER, TTicks _hysteresis=NEVER)
void	Set (float _value, const char *_gid=NULL, int _priority=rcPrioNone, TTicks _t0=NEVER, TTicks _t1=NEVER, TTicks _repeat=NEVER, TTicks _hysteresis=NEVER)
void	Set (const char *_value, const char *_gid=NULL, int _priority=rcPrioNone, TTicks _t0=NEVER, TTicks _t1=NEVER, TTicks _repeat=NEVER, TTicks _hysteresis=NEVER)
void	Set (TTicks _value, const char *_gid=NULL, int _priority=rcPrioNone, TTicks _t0=NEVER, TTicks _t1=NEVER, TTicks _repeat=NEVER, TTicks _hysteresis=NEVER)
void	SetValue (CRcValueState *_value)
	Set value (no state!) (argument must be != NULL).
void	SetValue (bool _value)
void	SetValue (int _value)
void	SetValue (float _value)
void	SetValue (const char *_value)
void	SetValue (TTicks _value)
void	SetGid (const char *_gid)
	Set GID (argument must be != NULL).
void	SetPriority (int _priority)
	Set GID (argument must be != rcPrioNone).
void	SetTimeOn (TTicks _t0)
	Set on time (argument must be != NEVER).
void	SetTimeOff (TTicks _t1)
	Set off time (argument must be != NEVER).
void	SetRepeat (TTicks _repeat)
	Set repetition interval (argument must be != NEVER).
void	SetHysteresis (TTicks _hysteresis)
	Set hysteresis (argument must be != NEVER).
void	SetForTrigger ()
	Set value and type suitable for 'rctTrigger' resources and reset fields irrelevant for triggers.

Type conversion/setting ...
void	Convert (CResource *rc, bool warn=true)
	Try to convert type to match the given resource and set 'isCompatible' according to the success. On failure (incompatible types), a warning is emitted if 'warn == true'.

Getting properties ...
bool	IsCompatible ()
	Returns whether the request is compatible with the type of the resource recently passed to Convert().
const char *	Gid ()
	Requests only have a global ID, no local ID, since they do not "belong" to the initiating host or process. Based on the GID, the request can be set, changed or removed freely from any host or process in the Home2L cluster.
const char *	Origin ()
	Origin of the request. It is automatically set by Reset() to the request creation information in the form "<hostname>:<process name>[<pid>] <yyyy-mm-dd-hhmmss>".
ERcType	Type ()
CRcValueState *	Value ()
int	Priority ()
TTicks	TimeOn ()
TTicks	TimeOff ()
TTicks	Repeat ()
TTicks	Hysteresis ()

String-based access ...
bool	SetFromStr (const char *str)
	Set the request based on a textual definition. More...
bool	SetAttrsFromStr (const char *str)
	Set request attributes (no value) base on a textual definition. More...
const char *	ToStr (CString *ret, bool precise=true, bool tabular=false, TTicks relativeTimeThreshold=NEVER, const char *skipAttrs=CString::emptyStr)
	Return a string in the format accepted by SetFromStr(). More...

Member Function Documentation

Set()

void CRcRequest::Set	(	CRcValueState *	_value = NULL,
		const char *	_gid = NULL,
		int	_priority = rcPrioNone,
		TTicks	_t0 = NEVER,
		TTicks	_t1 = NEVER,
		TTicks	_repeat = NEVER,
		TTicks	_hysteresis = NEVER
	)

Define a request with all parameters and attributes.

Parameters

_value	is the requested value; Only the type and value are used, the state is irrelevant besides the convention that 'rcsUnknown' indicates that no value set.
_gid	is the user-defined global ID (GID); If 'NULL', the instance name is used as the GID.
_priority	is the request priority attribute.
_t0	is the activation (on/start) time attribute (optional; NEVER = since ever).
_t1	is the expiration (off/stop) time attribute (optional; NEVER = forever).
_repeat	is the repetition interval (optional; 0 = no repetition); If set, both t0 and t1 are incremented by this after time t1 instead of removing the request.
_hysteresis	is the hysteresis attribute (optional).

The request attributes are explaind in the Home2L Book. Attributes left with the defaults are not changed. Negative values or 0 for t0 and t1 are interpreted as a time relative from now in the future (= t_now - t<n>).

SetFromStr()

bool CRcRequest::SetFromStr

(

const char *

str

)

Set the request based on a textual definition.

Syntax: <value without type> [<attributes>]

The optional request attributes are described with CRcRequest::SetAttrsFromStr(). Unspecified attributes are left unchanged.

On success, 'true' is returned. On error, a warning is emmited. The type is auto-detected.

SetAttrsFromStr()

bool CRcRequest::SetAttrsFromStr

(

const char *

str

)

Set request attributes (no value) base on a textual definition.

The string must contain a one or multiple whitespace-separated options with the following syntax:

#<id>           : Request ID [default: instance name]
 
*<prio>         : Priority (0..9) [default: 3]
 
[+<rep>]+<time> : Start time and optionally repeat interval.
                  <rep> may be empty (= repeat daily), or a ticks value as
                  described in TicksFromString(). e.g. "2d" for 2 days. The most
                  common case is to have a daily repetition, in which case just
                  an additional '+' needs to be added to the start time. For
                  example, to turn on some resource daily from 5 to 7 p.m.,
                  enter "++17:00 -19:00"
 
-<time>         : End time.
                  <time> may be an absolute date/time in the format
                  'YYYY-MM-DD-HHMM[SS[.frac]]' or a relative time `<n>`, where
                  <n> is the number of milliseconds in the future.
                  See TicksFromString() for details and further options.
 
~<hyst>         : Hysteresis as a relative time (see TicksFromString() for details)
 
@<origin>       : Origin in the form `<host>/<issue time>`;
                  should never be set manually.

If some parameter is specified multiple times, the last occurence will overwrite the others. Unspecified attributes are left unchanged.

On success, 'true' is returned. On error, a warning is emmited.

ToStr()

const char* CRcRequest::ToStr	(	CString *	ret,
		bool	precise = true,
		bool	tabular = false,
		TTicks	relativeTimeThreshold = NEVER,
		const char *	skipAttrs = CString::emptyStr
	)

Return a string in the format accepted by SetFromStr().

Parameters

ret	stores the result.
precise	decides whether the value is written in a bit-precise (and potentially not human-readable) way. It is passed to CRcValueState::ToStr().
tabular	inserts spaces and aligns fields to make a table if multiple such strings are printed after each other.
relativeTimeThreshold	allows to pass relative times in some cases. If 't0' or 't1' are defined, in the future, and in less than 'relativeTimeThreshold' milliseconds from now, the time settings are output relative to the current time. This is useful if the request string is to be transmitted to another computer with a slightly different local time. (Example: A door opener request is timed for 1 second. If the server's local clock deviates from the local one by more than one second, this request may be completely ignored.)
skipAttrs	allows to selectively skip some attributs from the output. The parameter is a string with the initial characters of the attributes to be skipped. The character 'i' suppresses an eventual "(incompatible)" notice.

---

The documentation for this class was generated from the following file:

• resources/resources.H