110 ## @defgroup resources Resources
111 ## @brief The *Home2L Resources* library.
113 ## The API exports a large number of low-level C/C++ functions and classes, which in many cases
114 ## are not relevant for rules scripts or Python-based drivers and are not documented in detail here.
115 ## As a rule of thumb, the level of documentation reflects the relevance of some function.
117 ## The most common functions can be found in section @ref resources_general.
118 ## Besides this, the classes CResource (@ref resources_rc) and CRcValueState (@ref resources_values)
119 ## are important for accessing the data transported via resource objects.
121 ## Most of the information presented here is also available as *Python docstrings*
122 ## (avaliable via `help(<name>)` in a *Python* shell).
123 ## Additional information can be found in the
124 ## [*C/C++ API documentation*](../home2l-api_c/group__resources.html).
128 ## @defgroup resources_general Main API
129 ## @brief Top-level functionality of the *Resources* library - most commonly used functions can be found here.
131 ## @defgroup resources_values Values, Types and States
132 ## @brief Basic definitions for values and their types and state.
133 ## Most relevant is the CRcValueState class to access the present value and state of a resource.
134 ## More details can be found in the [*C/C++ API documentation*](../home2l-api_c/group__resources__values.html).
136 ## @defgroup resources_rc Resource Objects
137 ## @brief Accessing resource objects.
138 ## More details can be found in the [*C/C++ API documentation*](../home2l-api_c/group__resources__rc.html).
140 ## @defgroup resources_directory Directory Services
141 ## @brief Querying local metadata (for interactive debugging).
142 ## More details can be found in the [*C/C++ API documentation*](../home2l-api_c/group__resources__directory.html).
144 ## @defgroup resources_subscribe Subscriptions
145 ## @brief Low-level access to the C/C++ subscriber classes.
146 ## More details can be found in the [*C/C++ API documentation*](../home2l-api_c/group__resources__subscribe.html).
148 ## @defgroup resources_requests Requests
149 ## @brief Low-level access to the C/C++ request class.
150 ## More details can be found in the [*C/C++ API documentation*](../home2l-api_c/group__resources__requests.html).
152 ## @defgroup resources_drivers Drivers in C/C++
153 ## @brief Native API for defining custom drivers.
154 ## More details can be found in the [*C/C++ API documentation*](../home2l-api_c/group__resources__requests.html).
178 class CRcSubscriberLink;
192 ## @addtogroup resources_requests
209 #define rcPrioNormal 3
212 #define rcPrioDefault 0
213 #define rcPrioRuleMin 1
215 #define rcPrioRuleMax 5
217 #define rcPrioShell 7
218 #define rcPrioSafety 8
219 #define rcPrioIKnowWhatImDoing 9
221 #define rcPrioNone -1
250 ## @addtogroup resources_values
262 #define rctBasicTypesBase rctBool
263 #define rctBasicTypesLast rctTime
265 #define rctSpecialTypesBase rctTrigger
266 #define rctSpecialTypesLast rctMutex
268 #define rctUnitTypesBase 0x40
269 #define rctUnitTypesLast (rctUnitTypesEND-1)
271 #define rctEnumTypesBase 0x80
272 #define rctEnumTypesLast (rctEnumTypesEND-1)
349 const char *RcTypeGetName (
ERcType t);
350 ERcType RcTypeGetFromName (
const char *name);
412 rcvPlayerStopped = 0,
443 STATIC_ASSERT(
sizeof (URcValue) ==
sizeof (URcValue::vAny));
473 %feature(
"docstring")
CRcValueState "Typed value tagged with a state and a time stamp.\n\n"
474 "The constants for type '
ERcType' have the prefix 'rct*'."
475 "The state may be one of:\n"
477 " '
rcsBusy': The value is known, the underlying device is busy.\n"
478 " '
rcsValid': The value is known and stable.\n"
479 "The time stamp reflects the age of a value (last change/update). It is\n"
480 "generally not valid to judge from the time stamp whether the value is\n"
481 "outdated, since there are other mechanisms in the library setting the\n"
482 "state to '
rcsUnknown' if, for example, the connection to a remote resource\n"
587 bool Bool ()
const {
ASSERT (type ==
rctBool);
return val.vBool; }
588 int Int ()
const {
ASSERT (type ==
rctInt);
return val.vInt; }
589 float Float ()
const {
ASSERT (type ==
rctFloat);
return val.vFloat; }
590 const char * String ()
const {
ASSERT (type ==
rctString);
return val.vString; }
594 const char * Mutex ()
const {
ASSERT (type ==
rctMutex);
return val.vString; }
596 int UnitInt (
ERcType _type)
const {
ASSERT (type == _type);
return val.vInt; }
597 float UnitFloat (
ERcType _type)
const {
ASSERT (type == _type);
return val.vFloat; }
616 ERcState GetValue (
float *retFloat);
631 bool ValidBool (
bool defaultVal =
false);
632 int ValidInt (
int defaultVal = 0);
633 float ValidFloat (
float defaultVal = 0.0);
637 int ValidTrigger (
int defaultVal = 0) {
return ValidInt (defaultVal); }
638 const char * ValidMutex (
const char *defaultVal =
CString::emptyStr) {
return ValidString (defaultVal); }
640 int ValidUnitInt (
ERcType _type,
int defaultVal = 0)
const;
641 float ValidUnitFloat (
ERcType _type,
float defaultVal = 0.0)
const;
642 int ValidEnumIdx (
ERcType _type,
int defaultVal = 0)
const;
649 void SetState (
ERcState _state) { state = _state; }
652 ERcType Type ()
const {
return type; }
653 ERcState State ()
const {
return state; }
678 const char *
ToStr (
CString *ret,
bool withType =
false,
bool withTimeStamp =
false,
bool precise =
false,
int stringChars = 20)
const;
742 %newobject __str__ ();
743 const char *__str__ () {
CString s; $self->ToStr (&s);
return s.
Disown (); }
744 %newobject __repr__ ();
745 const char *__repr__ () {
CString s, s1; s.
SetF (
"(CRcValueState) %s", $self->ToStr (&s1,
true));
return s.
Disown (); }
746 bool __eq__ (
CRcValueState *other) {
return $self->Equals (other); }
747 bool __ne__ (
CRcValueState *other) {
return !$self->Equals (other); }
749 pass # (Workaround to keep SWIG from scrambling the indentation of the following code.)
751 ## Return the value as a Python object.
753 """Return the value as a Python object. In case of a state of 'rcsUnknown' or\n\
754 if 'self' is not defined, 'None' is returned. 'self == None' is allowed.\n\
756 if not self: return None
759 if t ==
rctBool: return self.Bool()
760 elif t ==
rctInt: return self.GenericInt()
761 elif t ==
rctFloat: return self.GenericFloat()
762 elif t ==
rctString: return self.GenericString()
763 elif t ==
rctTime: return self.Time()
766 ## Return the most appropriate valid value as a Python object.
767 def ValidValue(self, defaultVal):
768 """Return the value as a Python object. Unlike 'Value', this method never\n\
769 returns 'None', but reverts to the given default value, if 'self' does not\n\
770 transort a valid value. 'self == None' is tolerated\n\
773 if ret == None: ret = defaultVal
780 #define NO_VALUE_STATE ((CRcValueState *) NULL)
867 ## @addtogroup resources_rc
889 %feature(
"docstring")
CResource "Home2L Resource.\n\n"
890 "This is the most central class of the library. A 'Resource' may represent\n"
891 "a sensor, an actor, a stored value, a virtual device, a mutex, an event\n"
892 "trigger - almost anything. Resources are identified by a uniform resource\n"
934 const char *
Uri () {
return gid.
Get (); }
935 const char *
Gid () {
return gid.
Get (); }
936 const char *
Lid () {
return ATOMIC_READ (lid); }
939 bool Is (
const char *uri);
943 ERcType Type () {
return valueState.type; }
944 bool IsWritable () {
return writable; }
949 const char *ToStr (
CString *ret,
bool pathLocal =
false);
1052 void SetRequestFromObj (
CRcRequest *_request);
1142 void UnWrite (
const char *reqGid =
"write") {
DelRequest (reqGid); }
1263 void PrintInfo (FILE *f = stdout,
int verbosity = 1,
bool allowNet =
true);
1271 void UnlockLocalSubscribers () { Unlock (); }
1279 void UnlockLocalRequests () { Unlock (); }
1290 class CRcHost *Host () {
return ATOMIC_READ (rcHost); }
1291 class CRcDriver *Driver () {
return ATOMIC_READ (rcDriver); }
1293 unsigned RegSeq () {
return ATOMIC_READ (regSeq); }
1298 bool IsRegistered () {
return (ATOMIC_READ (regSeq) & 1) == 1; }
1324 friend void CResourceRequestsTimerCallback (
CTimer *,
void *);
1326 friend class CRcHost;
1330 static CResource *GetUnregistered (
const char *uri);
1331 void PutUnregistered ();
1348 void SubscribePAL (
CRcSubscriber *subscr,
bool resLocked =
false,
bool subLocked =
false);
1351 void UnsubscribePAL (
CRcSubscriber *subscr,
bool resLocked =
false,
bool subLocked =
false);
1356 void UpdatePersistentRequestAL (
const char *reqId,
CRcRequest *req);
1357 bool DoDelRequestAL (
CRcRequest **pList,
const char *reqGid,
TTicks t1,
bool updatePersistence);
1358 bool DelRequestNoEvaluate (
const char *reqGid,
TTicks t1);
1359 void SetRequestFromObjNoEvaluate (
CRcRequest *_request);
1362 void EvaluateRequests (
bool force =
false);
1366 void NotifySubscribers (
int evType,
const char *evAttr = NULL);
1367 void NotifySubscribersAL (
int evType,
const char *evAttr = NULL);
1368 void ReportNetLost ();
1373 void ReportUnknownAL () {
CRcValueState vs (Type ()); ReportValueStateAL (&vs); }
1381 void Lock () { mutex.Lock (); }
1382 void Unlock () { mutex.Unlock (); }
1395 class CRcHost *rcHost;
1402 bool writable, persistent;
1416 CRcSubscriberLink *subscrList;
1423 %newobject __str__ ();
1424 const char *__str__ () {
CString s; $self->ToStr (&s);
return s.
Disown (); }
1425 %newobject __repr__ ();
1426 const char *__repr__ () {
CString s, s2; s.
SetF (
"(CResource) %s", $self->ToStr (&s2));
return s.
Disown (); }
1427 bool __eq__ (
CResource *other) {
return $self == other; }
1428 bool __ne__ (
CResource *other) {
return $self != other; }
1430 %delobject SetRequestFromObj ();
1432 %feature(
"docstring") ValueState "Get the current value and state of the resource."
1433 %newobject ValueState ();
1436 void _SetRequestFromObj (
CRcRequest *_request) { $self->SetRequestFromObj (_request); }
1437 void _DelRequest (
const char *reqGid = NULL,
TTicks t1 =
NEVER) { $self->DelRequest (reqGid, t1); }
1440 pass # (Workaround to keep SWIG from scrambling the indentation of the following code.)
1443 """Get a value ('None' if invalid) of this resource (use ValueState() to get the complete value and state)."""
1444 return self.ValueState ().Value ()
1446 def ValidValue (self, defaultVal):
1447 """Get a valid value of this resource (use ValueState() to get the complete value and state)."""
1448 return self.ValueState ().ValidValue (defaultVal)
1451 """Get the type of this resource."""
1452 return self.ValueState ().Type ()
1454 def SetRequest (self, reqDef = None, attrs = None, value = None,
id = None, priority = None, t0 = None, t1 = None, repeat = None, hysteresis = None, delDelay = None):
1455 """Set or delete a request with selected attributes.\n\
1457 This method allows to set any subset of attributes in a flexible way, either by (named) function arguments\n\
1458 or by a textual description as accepted by the Home2L Shell or
CRcRequest::SetFromStr().\n\
1460 If the effective value is 'None' (no value is passed), the call will delete the request with\n\
1461 the specified ID passing 'delDelay' as the 't1' argument of DelRequest().\n\
1463 See
RcSetRequest() for a detailed explanation of the arguments and examples.\n\
1466 print ("
WARNING: Setting a request to the
string-type resource '" + str(self) + "' using the 'reqDef' argument is ambiguous!")
1468 req.Set (reqDef = reqDef, attrs = attrs, value = value,
id =
id, priority = priority, t0 = t0, t1 = t1, repeat = repeat, hysteresis = hysteresis)
1469 if req.Value ().IsKnown ():
1470 req.thisown = 0
# tell swig to disown the object ([2021-01-03]: '%delobject SetRequestFromObj ()' silently does not work)
1471 self._SetRequestFromObj (req)
1473 self.DelRequest (req.Gid (), delDelay)
1475 def SetTrigger (
self, attrs = None,
id = None, priority = None, t0 = None, t1 = None, repeat = None, hysteresis = None):
1476 """Set a request for a trigger resource with selected attributes."""
1478 req.Set (value = 1, attrs = attrs,
id =
id, priority = priority, t0 = t0, t1 = t1, repeat = repeat, hysteresis = hysteresis)
1479 req.thisown = 0
# tell swig to disown the object ([2021-01-03]: '%delobject SetRequestFromObj ()' silently does not work)
1480 self._SetRequestFromObj (req)
1482 def DelRequest (
self, reqId = None, t1 = None):
1483 """Delete a request by its ID."""
1484 if t1 == None: self._DelRequest (reqId)
1485 else: self._DelRequest (reqId, TicksAbsOf (t1))
1487 def ReportValue (self, value, state =
rcsValid):
1488 """Report a new value and optionally its state. If '_value == None', 'ReportUnknown()' is called."""
1489 if value == None: self.ReportUnknown ()
1490 else: self.ReportValueState (
CRcValueState (self.Type (), value, state))
1527 ## @addtogroup resources_subscribe
1557 %feature(
"docstring")
CRcEvent "Resource events delivered by a subscriber or to a driver.\n\n"
1558 "Possible event types are:\n"
1561 "
rceRequestChanged: A request has been changed or deleted. The 'ValueState ()'\n"
1562 " attribute indicates the affected request ID (type is
string).\n"
1565 "
rceConnected: The connection to the (remote) resource has\n"
1566 " been established (again).\n"
1568 "
rceNone: Nothing (dummy event: ignore).\n"
1569 "The attribute 'MorePending ()' indicates whether more events are waiting for the\n"
1570 "same subscriber. This can be used for performance optimizations to avoid\n"
1571 "unecessary recomputations."
1579 void Clear () {
Set (); }
1592 void SetResource (
CResource *_resource) { resource = _resource; }
1594 void SetData (
void *_data) { data = _data; }
1600 CResource *Resource () {
return resource; }
1603 void *Data () {
return data; }
1632 %newobject __str__ ();
1633 const char *__str__ () {
CString s; $self->ToStr (&s);
return s.
Disown (); }
1634 %newobject __repr__ ();
1635 const char *__repr__ () {
CString s, s1; s.
SetF (
"(CRcEvent) %s", $self->ToStr (&s1));
return s.
Disown (); }
1717 void SetCbOnEvent (
FRcEventFunc *_cbEvent,
void *_cbEventData = NULL);
1718 void ClearCbOnEvent () { SetCbOnEvent (NULL, NULL); }
1727 bool InSelectSet () {
return inSelectSet; }
1758 void DeleteFirstEventAL ();
1762 bool IsLinkedAL () {
return next || pLastProc == &next; }
1766 static CCond globCond;
1768 volatile bool interrupted;
1784 %newobject __str__ ();
1785 const char *__str__ () {
CString s; $self->ToStr (&s);
return s.
Disown (); }
1786 %newobject __repr__ ();
1787 const char *__repr__ () {
CString s, s1; s.
SetF (
"(CRcEventProcessor) %s", $self->ToStr (&s1));
return s.
Disown (); }
1789 %newobject PollEvent ();
1792 if (!$self->PollEvent (&ev))
return NULL;
1825 virtual const char *
TypeId () {
return "T"; }
1826 virtual const char *
InstId () {
return id.Get (); }
1853 ## @addtogroup resources_subscribe
1874 %feature(
"docstring")
CRcSubscriber "Subscription to any number of resources.\n\n"
1875 "A subscriber monitors any number of resources. The resources can be\n"
1876 "specified by their real URIs or alias names. Wildcards as well as\n"
1877 "presently unkown resources are allowed. Events can be fetched using\n"
1878 "'Select ()' and 'PollEvent'.\n"
1897 const char *Lid () {
return lid.
Get (); }
1898 const char *Gid () {
return gid.
Get (); }
1900 virtual const char *
TypeId () {
return "S"; }
1901 virtual const char *
InstId () {
return Lid (); }
1903 const char *ToStr (
CString *ret);
1905 bool IsEmpty () {
return resourceList == NULL && watchSet.
Entries () == 0; }
1948 void Unsubscribe (
CResource *rc) { DelResource (rc); }
1949 void Unsubscribe (
const char *pattern) {
DelResources (pattern); }
1962 void PrintInfo (FILE *f = stdout,
int verbosity = 1);
1967 friend class CRcServer;
1970 void Lock () { mutex.Lock (); }
1971 void Unlock () { mutex.Unlock (); }
1974 void CheckNewResource (
CResource *resource);
1975 void UnlinkResourceAL (
CResource *resource);
1979 void RegisterAsAgent (
const char *_gid);
1981 bool IsAgent () {
return lid.
Get () == gid.
Get (); }
1988 CResourceLink *resourceList;
1996 %newobject __str__ ();
1997 const char *__str__ () {
CString s; $self->ToStr (&s);
return s.
Disown (); }
1998 %newobject __repr__ ();
1999 const char *__repr__ () {
CString s, s1; s.
SetF (
"(CRcSubscriber) %s", $self->ToStr (&s1));
return s.
Disown (); }
2022 ## @addtogroup resources_requests
2045 %feature(
"docstring")
CRcRequest "Request specifications.\n\n"
2046 "Request objects define the request for a certain value together with some\n"
2047 "additional attributes. The concept of requests is introduced to deal with\n"
2048 "potentially concurrent write accesses to resources. Besides the requested\n"
2049 "value, a request has the following attributes:\n"
2050 " - a unique GID by which it can be later be changed or deleted.\n"
2051 " - a priority (see also: comments on the 'prio*' constants)\n"
2052 " - a start (on) time (optional)\n"
2053 " - an expiration (off) time (optional)\n"
2054 " - a hysteresis to avoid too frequent value changes (optional)"
2062 CRcRequest (
CRcValueState *_value,
const char *_gid = NULL,
int _priority =
rcPrioNone,
TTicks _t0 =
NEVER,
TTicks _t1 =
NEVER,
TTicks repeat =
NEVER,
TTicks _hysteresis =
NEVER) {
Reset ();
Set (_value, _gid, _priority, _t0, _t1, _hysteresis); }
2064 CRcRequest (
bool _value,
const char *_gid = NULL,
int _priority =
rcPrioNone,
TTicks _t0 =
NEVER,
TTicks _t1 =
NEVER,
TTicks repeat =
NEVER,
TTicks _hysteresis =
NEVER) {
Reset ();
Set (_value, _gid, _priority, _t0, _t1, _hysteresis); }
2066 CRcRequest (
int _value,
const char *_gid = NULL,
int _priority =
rcPrioNone,
TTicks _t0 =
NEVER,
TTicks _t1 =
NEVER,
TTicks repeat =
NEVER,
TTicks _hysteresis =
NEVER) {
Reset ();
Set (_value, _gid, _priority, _t0, _t1, _hysteresis); }
2068 CRcRequest (
float _value,
const char *_gid = NULL,
int _priority =
rcPrioNone,
TTicks _t0 =
NEVER,
TTicks _t1 =
NEVER,
TTicks repeat =
NEVER,
TTicks _hysteresis =
NEVER) {
Reset ();
Set (_value, _gid, _priority, _t0, _t1, _hysteresis); }
2070 CRcRequest (
const char *_value,
const char *_gid = NULL,
int _priority =
rcPrioNone,
TTicks _t0 =
NEVER,
TTicks _t1 =
NEVER,
TTicks repeat =
NEVER,
TTicks _hysteresis =
NEVER) {
Reset ();
Set (_value, _gid, _priority, _t0, _t1, _hysteresis); }
2072 CRcRequest (
TTicks _value,
const char *_gid = NULL,
int _priority =
rcPrioNone,
TTicks _t0 =
NEVER,
TTicks _t1 =
NEVER,
TTicks repeat =
NEVER,
TTicks _hysteresis =
NEVER) {
Reset ();
Set (_value, _gid, _priority, _t0, _t1, _hysteresis); }
2113 void SetValue (
const char *_value);
2116 void SetGid (
const char *_gid) { gid.Set (_gid); }
2149 ERcType Type () {
return value.Type (); }
2151 int Priority () {
return priority; }
2152 TTicks TimeOn () {
return t0; }
2153 TTicks TimeOff () {
return t1; }
2154 TTicks Repeat () {
return repeat; }
2155 TTicks Hysteresis () {
return hysteresis; }
2233 bool SetSingleAttrFromStr (
const char *str);
2255 %newobject __str__ ();
2256 const char *__str__ () {
CString s; $self->ToStr (&s);
return s.
Disown (); }
2257 %newobject __repr__ ();
2258 const char *__repr__ () {
CString s, s1; s.
SetF (
"(CRcRequest) %s", $self->ToStr (&s1));
return s.
Disown (); }
2260 pass # (Workaround to keep SWIG from scrambling the indentation of the following code.)
2262 ## Versatile setter.
2263 def Set (
self, reqDef = None, attrs = None, value = None,
id = None, priority = None, t0 = None, t1 = None, repeat = None, hysteresis = None):
2264 """Set value and/or selected request attributes.\n\
2266 This method allows to set any subset of attributes in a flexible way, either by (named) function arguments\n\
2267 or by a textual description as accepted by the Home2L Shell or CRcRequest::SetFromStr().\n\
2269 See RcSetRequest() for a detailed explanation of the arguments and examples.\n\
2272 if isinstance (reqDef, str): self.SetFromStr (reqDef)
2273 elif value == None: value = reqDef
2274 if attrs != None: self.SetAttrsFromStr (attrs)
2275 if value != None: self.SetValue (value)
2276 if id != None: self.SetGid (id)
2277 if priority != None: self.SetPriority (priority)
2279 ticks = TicksAbsOf (t0)
2280 if ticks: self.SetTimeOn (ticks)
2281 else: print (
"WARNING: Invalid time specification '" + str(t0) +
"' - ignoring!")
2283 ticks = TicksAbsOf (t1)
2284 if ticks: self.SetTimeOff (ticks)
2285 else: print (
"WARNING: Invalid time specification '" + str(t1) +
"' - ignoring!")
2287 ticks = TicksRelOf (repeat)
2288 if ticks: self.SetRepeat (ticks)
2289 else: print (
"WARNING: Invalid time specification '" + str(repeat) +
"' - ignoring!")
2290 if hysteresis != None: self.SetHysteresis (hysteresis)
2339 ## @addtogroup resources_drivers
2381 #define HOME2L_DRIVER(NAME) \
2382 extern "C" { void Home2lRcDriverFunc_##NAME (ERcDriverOperation, CRcDriver *, CResource *, CRcValueState *); } \
2383 void Home2lRcDriverFunc_##NAME
2451 const char *Lid () {
return lid.
Get (); }
2452 const char *ToStr (
CString *) {
return lid.
Get (); }
2458 CResource *RegisterResource (
const char *rcLid,
const char *rcTypeDef,
void *_data = NULL) {
return CResource::Register (
this, rcLid, rcTypeDef, _data); }
2464 void PrintInfo (FILE *f = stdout);
2466 CResource *GetResource (
const char *rcLid) {
return resourceMap.Get (rcLid); }
2468 int LockResources () { Lock ();
return resourceMap.
Entries (); }
2469 CResource *GetResource (
int n) {
return resourceMap.Get (n); }
2470 void UnlockResources () { Unlock (); }
2475 friend void RcDriversStop ();
2479 virtual void Stop ();
2517 void Lock () { mutex.Lock (); }
2518 void Unlock () { mutex.Unlock (); }
2558 virtual const char *
TypeId () {
return "D"; }
2559 virtual const char *
InstId () {
return Lid (); }
2592 ## @addtogroup resources_directory
2620 ## Return a list of all known hosts (including our own one as #0).
2622 """Return a list of all known hosts (including our own one as #0)."""
2625 for i in range (num):
2641 int RcGetDrivers ();
2644 CRcDriver *RcGetDriver (
const char *lid);
2645 const char *RcGetDriverId (
CRcDriver *cur);
2651 ## Return a list of all locally defined drivers.
2653 """Return a list of all locally defined drivers."""
2654 num = RcGetDrivers ()
2656 for i in range (num):
2657 ret += [ RcGetDriverId (RcGetDriver (i)) ]
2678 CResource *RcGetHostResource (CRcHost *host,
int n);
2679 void RcUnlockHostResources (CRcHost *host);
2687 void RcUnlockDriverResources (
CRcDriver *driver);
2693 ## Return all known resources of a remote host.
2694 def RcHostResources (hostName):
2695 """Return all known resources of a host. '/local' is an alias for the local host ID."""
2698 for d in RcDrivers ():
2699 ret += RcDriverResources (d)
2703 for i in range (num):
2704 ret += [ RcGetHostResource (h, i).Uri () ]
2705 RcUnlockHostResources (h)
2708 ## Return all local resources managed by a driver.
2709 def RcDriverResources (driverName):
2710 """Return all local resources managed by a driver."""
2711 d = RcGetDriver (driverName)
2714 for i in range (num):
2715 ret += [ RcGetDriverResource (d, i).Uri () ]
2716 RcUnlockDriverResources (d)
2719 ## Return a complete list of all known resources.
2721 """Return a complete list of all known resources."""
2723 for d in RcDrivers ():
2724 ret += RcDriverResources (d)
2725 for h in RcHosts ():
2726 ret += RcHostResources (h)
2749 void RcUnlockSubscribers ();
2780 ## @addtogroup resources_general
2791 void RcInit (
bool enableServer =
false,
bool inBackground =
false);
2816 int RcRun (
bool catchSignals =
true);
2837 ## @name Accessing resources ...
2844 %feature(
"docstring")
RcGetResource "Lookup a resource by its URI and return a reference to it."
2845 %feature("docstring")
RcGet "Lookup a resource by its URI and return a reference to it (shortcut for '
RcGetResource()')."
2897 ## @name Subscriptions (from C/C++ API) ...
2898 ## Low-level operations to directly create and use @ref CRcSubscriber objects.
2899 ## Most probably, you will not need these functions.
2900 ## The preferred way in Python is to use the more compfortable decorators and
2901 ## operations in section "Subscriptions, events and timers (Python API)" below.
2908 %feature(
"docstring")
RcNewSubscriber "Create and register a new subscriber
object, optionally subscribe to resources."
2909 %feature("docstring")
RcUnsubscribeFromAll "Unsubscribe to all resources managed by the subscriber."
2955 ## @name Placing requests ...
2956 ## Details on the request arguments can be found in the
2957 ## [*C/C++ API documentation*](../home2l-api_c/classCRcRequest.html)
2958 ## and the [*Home2L Book*](../home2l-book.pdf).
2973 static inline 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) { rc->
SetRequest (value, reqGid, priority, t0, t1, repeat, hysteresis); }
2987 static inline 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) { rc->
SetRequest (valBool, reqGid, priority, t0, t1, repeat, hysteresis); }
2990 static inline 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) { rc->
SetRequest (valInt, reqGid, priority, t0, t1, repeat, hysteresis); }
2993 static inline 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) { rc->
SetRequest (valFloat, reqGid, priority, t0, t1, repeat, hysteresis); }
2996 static inline 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) { rc->
SetRequest (valString, reqGid, priority, t0, t1, repeat, hysteresis); }
3024 %feature(
"docstring")
RcSetRequest "Add or change a request to a resource."
3025 %feature("docstring")
RcDelRequest "Delete a request from a resource."
3026 %feature("docstring")
RcSetTrigger "Add a trigger request."
3030 def
RcSetRequest (rc, reqDef = None, attrs = None, value = None,
id = None, priority = None, t0 = None, t1 = None, repeat = None, hysteresis = None, delDelay = None):
3031 """Set a request to a resource with selected attributes.\n\
3033 The attributes can be set in a flexible way, either by (named) function arguments\n\
3034 or by a textual description as accepted by the Home2L Shell or CRcRequest::SetFromStr().\n\
3036 The parameters have the following meanings:\n\
3038 - reqDef = full definition as a single string '<val> [<attrs>]' or just the value\n\
3039 Note: To avoid ambiguities, values of type string should never be passed by this,\n\
3040 but by the 'value' and 'attrs' arguments instead.\n\
3041 If 'reqDef' is not a string instance, it is used as a value ('val').\n\
3042 - attrs = attribute string (similar to 'reqDef', but without the first field interpreted as value)\n\
3044 - value = value (any type or string)\n\
3045 - id = request ID [default = instance name]\n\
3046 - priority = request priority (0..9) [default = 3 (= rcPrioNormal)]\n\
3049 - repeat = repetition interval\n\
3050 - hysteresis = hysteresis time\n\
3051 - delDelay = deletion delay (if no value is passed and the call is used to delete the request)\n\
3053 Information on the syntax of textual request definition can be found in the Home2L Book and\n\
3054 in the C/C++ API documentation for CRcRequest::SetFromStr(). Arguments representing absolute times\n\
3055 (e.g. 't0', 't1') can have any type and format as accepted by 'TicksAbsOf()'.\n\
3056 Arguments representing relative times (e.g. 'repeat', 'hysteresis', 'delDelay') can have any type\n\
3057 and format as accepted by 'TicksRelOf()'.\n\
3059 If an attribute is set both by means of a string ('reqDef' or 'attrs') or a named parameter,\n\
3060 the named parameter is taken. If no attributes are specified, their defaults as specified in [...]\n\
3063 If the effective value is 'None' (no value is passed), the call will delete the request with\n\
3064 the specified ID passing 'delDelay' as the the 't1' argument of RcDelRequest().\n\
3068 - Request integer value 7 with default attributes:\n\
3069 RcSetRequest (rc, 7);\n\
3070 RcSetRequest (rc, '7');\n\
3071 RcSetRequest (rc, value = '7');\n\
3072 RcSetRequest (rc, reqDef = '7');\n\
3074 - Request integer value 7 with ID '#user' and priority 3:\n\
3075 RcSetRequest (rc, 7, id = 'user', priority = 3);\n\
3076 RcSetRequest (rc, 7, '#user *3');\n\
3077 RcSetRequest (rc, '7 #user *3');\n\
3079 - Delete this request again:\n\
3080 RcSetRequest (rc, value = None, id = 'user');\n\
3081 RcSetRequest (rc, '? #user');\n\
3083 - Delete this request in 5 seconds:\n\
3084 RcSetRequest (rc, value = None, id = 'user', delDelay = '5s');\n\
3086 - Request string value 'Hello *3' with priority 5 and an off time at 6pm today:\n\
3087 RcSetRequest (rc, value = 'Hello *3', attrs = '*5 -18:00');\n\
3088 RcSetRequest (rc, value = 'Hello *3', prio = 5, t1 = '-18:00');\n\
3090 - Set request with user-supplied attributes, some of which must not be changed by user\n\
3091 RcSetRequest (rc, 7, userAttrs, t1 = '-23:00') # t1 overrides an eventual off time in userAttrs\n\
3093 - Set request with user-supplied attributes and defaults\n\
3094 req = CRcRequest (val = 7, t1 = '-23:00') # Set value and default attributes\n\
3095 req->Set (attrs = userAttrs) # userAttrs may override t1\n\
3099 rc.SetRequest (reqDef = reqDef, attrs = attrs, value = value, id = id, priority = priority, t0 = t0, t1 = t1, repeat = repeat, hysteresis = hysteresis, delDelay = delDelay)
3101 def
RcSetTrigger (rc, attrs = None, id = None, priority = None, t0 = None, t1 = None, repeat = None, hysteresis = None):
3102 """Set a request to a trigger resource with selected attributes."""
3104 rc.SetRequest (attrs = attrs, value = 1, id = id, priority = priority, t0 = t0, t1 = t1, repeat = repeat, hysteresis = hysteresis)
3107 """Delete a request."""
3109 rc.DelRequest (id, t1)
3111 def RcSetDefault (rc, reqDef = None, attrs = None, value = None, t0 = None, t1 = None, repeat = None, hysteresis = None, delDelay = None):
3112 """Set a default request."""
3114 rc.SetRequest (reqDef = reqDef, attrs = attrs, value = value, id =
rcDefaultRequestId, priority =
rcPrioDefault, t0 = t0, t1 = t1, repeat = repeat, hysteresis = hysteresis)
3146 ## @name Drivers (from C/C++ API) ...
3147 ## Low-level operations to directly create and use 'CRcDriver' objects.
3148 ## Most probably, you will not need these functions.
3149 ## The preferred way in Python is to use the more compfortable decorators and
3150 ## operations in module "Home2L / Drivers".
3159 %feature("docstring") RcRegisterResource "Register a new resource to a driver."
3160 %feature("docstring")
RcRegisterSignal "Register a new signal for the built-in 'signal' driver."
3193 static inline CResource *RcRegisterResource (
CRcDriver *drv,
const char *rcLid,
const char *rcTypeDef,
void *_data = NULL) {
return CResource::Register (drv, rcLid, rcTypeDef, _data); }
3195 CResource *RcRegisterResource (
const char *drvLid,
const char *rcLid,
ERcType _type,
bool _writable,
void *_data = NULL);
3196 CResource *RcRegisterResource (
const char *drvLid,
const char *rcLid,
const char *rcTypeDef,
void *_data = NULL);
Class to wrap (POSIX) condition variables.
int Entries() const
Get number of entries.
Class to wrap (POSIX) mutex objects.
Driver for local resources.
void Unregister()
Unregister the driver. This is only allowed in the elaboration phase or on shutdown....
virtual void DriveValue(CResource *rc, CRcValueState *vs)
Callback to drive a new value, will be called from CResource::DriveValue().
static void RegisterAndInit(const char *_lid, FRcDriverFunc *_func)
Create, register and initialize a function-based driver.
virtual void Stop()
Stop all (own) threads and close all I/Os properly; Will be called from RcDone(). Resources are still...
void ClearResources()
Unregister all resources.
void Register()
Register and enable the driver. This must be done between the calls to RcInit() and RcStart(),...
Local driver using the event processor mechanism for the 'DriveValue()' functionality.
virtual const char * InstId()
(optional) Hint for the main event loop: object instance
virtual void DriveValue(CResource *rc, CRcValueState *vs)
Callback to drive a new value, will be called from CResource::DriveValue().
virtual void Stop()
The caller/owner must do this before 'RcDone()'. (The event processor may not work anymore by the tim...
CRcEventDriver(const char *_lid, ERcState _successState=rcsBusy)
Initialize the driver (does not register).
virtual const char * TypeId()
(optional) Hint for the main event loop: object type
virtual const char * TypeId()
(optional) Hint for the main event loop: object type
void SetInSelectSet(bool _inSelectSet)
Set whether or not the event processor is contained in the set of upcoming Select() operations.
bool WaitEvent(CRcEvent *ev, TTicks *maxTime=NULL)
Wait for an event and return it at '*ev'.
bool PollEvent(CRcEvent *ev)
Check for an event (non-blocking) and return it at '*ev'.
void PutEvent(CRcEvent *ev)
Enqueue/process an event; caller remains owner of 'ev'.
static CRcEventProcessor * Select(TTicks maxTime=-1)
Wait until any of the existing 'CRcEventProcessor' objects has an event available.
void FlushEvents()
Remove all presently queued events; also waits until a concurrently running OnEvent() invocation retu...
virtual bool OnEvent(CRcEvent *ev)
Handle an event asynchronously (may have been called from any thread)
virtual const char * InstId()
(optional) Hint for the main event loop: object instance
void Interrupt()
Request a running WaitEvent() to stop now.
Timer that sends 'rceTimer' events over the event system.
virtual void OnTime()
[T:timer] Virtual function called when the timer triggers.
void Set(void *_data)
Setup timer without (re-)scheduling it.
void Set(TTicks _time, TTicks _interval=0, void *_data=NULL)
Setup and (re-)schedule timer (see CTimer::Set() ).
virtual const char * InstId()
(optional) Hint for the main event loop: object instance
virtual const char * TypeId()
(optional) Hint for the main event loop: object type
Events delivered by a subscriber or to a driver.
CRcValueState * ValueState()
Get the value/state attribute of the event. See Set() for further details.
const char * ToStr(CString *ret)
Get a readable string.
void Set(ERcEventType _type=rceNone, CResource *_resource=NULL, CRcValueState *_valueState=NULL, void *_data=NULL)
Set event attributes.
Request description object.
void SetValue(CRcValueState *_value)
Set value (no state!) (argument must be != NULL).
CRcRequest(CRcRequest *req)
Construct by cloning an existing request object (the origin is set, not cloned).
const char * Origin()
Origin of the request. It is automatically set by Reset() to the request creation information in the ...
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.
void SetForTrigger()
Set value and type suitable for 'rctTrigger' resources and reset fields irrelevant for triggers.
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 Reset()
Clear the value and set default attributes ( NO_VALUE_STATE, NEVER, NULL or equivalent; priority = rc...
CRcRequest()
Default constructor.
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 pro...
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(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.
void Convert(CResource *rc, bool warn=true)
Try to convert type to match the given resource and set 'isCompatible' according to the success....
void SetPriority(int _priority)
Set GID (argument must be != rcPrioNone).
void SetGid(const char *_gid)
Set GID (argument must be != NULL).
bool SetFromStr(const char *str)
Set the request based on a textual definition.
bool SetAttrsFromStr(const char *str)
Set request attributes (no value) base on a textual definition.
void SetTimeOn(TTicks _t0)
Set on time (argument must be != NEVER).
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.
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().
void Set(CRcRequest *req)
Define a request by copying attributes from another. The origin is not copied.
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(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(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.
Subscriber to follow an arbitrary set of resources.
void Clear()
Remove all resources.
virtual const char * InstId()
(optional) Hint for the main event loop: object instance
void Unregister()
Clear and unregister the subscriber.
void GetPatternSet(CKeySet *retPatternSet)
Get current pattern set. Patterns from the watch set are followed by a "?".
void DelResources(const char *pattern)
Remove resources by pattern. See AddResources() for details on possible patterns.
static void GetInfoAll(CString *ret, int verbosity=1)
Get info for all subscribers of this instance (see GetInfo() for info on 'verbosity').
virtual const char * TypeId()
(optional) Hint for the main event loop: object type
void GetInfo(CString *ret, int verbosity=1)
Get Info. 'verbosity == 0': single line, 1: list entries / resources.
bool Register(const char *_lid)
Enable the subscriber, set its LID and GID. Caller remains owner of object. If '_lid' refers to an in...
CResource * AddResources(const char *pattern)
Add new resources by pattern. The pattern is also stored internally to catch possible resources added...
Typed value tagged with a state and a time stamp.
bool SetFromStr(const char *str)
Set the value and state based on textual information.
bool SetFromStrFast(const char *str, bool warn=true)
Set the object based on textual information (fast version).
void SetToReportNothing()
Modify object to not auto-report anything.
bool ValueEquals(const CRcValueState *vs2) const
Relaxed comparison: type and value must match exactly; state and time stamps are not compared.
void SetType(ERcType _type)
Change type in a hard way; implies resetting the state to 'rcsUnkown'.
bool Equals(const CRcValueState *vs2) const
Strict comparison: state, type and value must match exactly; time stamps are not compared.
const char * ToStr(CString *ret, bool withType=false, bool withTimeStamp=false, bool precise=false, int stringChars=20) const
Output the object contents as a string according to the synax described for 'SetFromStr'.
bool IsKnown() const
State is either rcsValid or rcsBusy; In other words: the value can be retrieved.
void SetToReportBusyNewVal()
Modify object to auto-report a busy state together with a value. This is to be used in CRcDriver::Dri...
void SetGenericInt(int _val, ERcType _type, ERcState _state=rcsValid)
Set from integer or boolean.
void Clear(ERcType _type, ERcState _state=rcsUnknown)
Clear to default value:
TTicks timeStamp
time of last value/state change or trigger
bool Convert(ERcType _type)
Try to convert the current value to a new type. If a conversion is not possible, 'false' is returned ...
CRcValueState(ERcType _type)
for initializing type, but without setting value
void SetGenericFloat(float _val, ERcType _type, ERcState _state=rcsValid)
Set from float.
void SetToReportBusy()
Modify object to auto-report a busy state.
void SetToReportBusyOldVal()
Modify object to auto-report a busy state with no value change. Note: Only for use in CRcDriver::Driv...
bool SetGenericString(const char *_val, ERcType _type, ERcState _state=rcsValid)
Set from string. On syntax error, a warning is emitted, the state is set to rcsUnknown,...
bool IsBusy() const
State is rcsBusy, neither rcsValid nor rcsUnknown.
void Clear()
Clear value, set state to 'rcsUnknown', and leave type unchanged.
bool IsValid() const
State is rcsValid, neither rcsBusy nor rcsUnknown.
void GetValueState(CRcValueState *retValueState)
Get the value and state.
void SetRequest(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). The request attributes are explaind in t...
static CResource * Register(CRcDriver *_rcDriver, const char *_lid, const char *rcTypeDef, void *_data=NULL)
Register a new local resource for a driver based on a textual type description. 'rcTypeDef' is a text...
void ReportState(ERcState _state)
Report state change only, value remains unmodified.
unsigned RegSeq()
The 'regSeq' number is incremented each time the resource is registered or unregistered....
void SetTriggerFromStr(const char *reqDef)
Set trigger request by textual definition.
CResource * Subscribe(CRcSubscriber *subscr)
Subscribe to this resource. The caller remains owner of 'subscr'.
void SetRequest(CRcRequest *_request)
Add or replace a request (generic version).
const char * GetInfo(CString *ret, int verbosity=1, bool allowNet=true)
Get textual information on this resource.
void Unsubscribe(CRcSubscriber *subscr)
Unsubscribe to this resource.
int ValidInt(int defaultVal=0, TTicks *retTimeStamp=NULL)
Get a valid integer value.
void DelRequest(const char *reqGid=NULL, TTicks t1=NEVER)
Delete a request.
const char * Lid()
Get the local ID (LID). This is the path relative to a) 'this's host (remote resource) or b) driver (...
bool Is(const char *uri)
Check identity by exact match.
ERcState GetValue(int *retInt, TTicks *retTimeStamp=NULL)
Get a value of type "int" or a type based on it.
void * UserData()
Retrieve user-specified data.
int LockLocalSubscribers()
Return number of all active local subscribers for a resource and lock this object....
bool Is(CResource *rc)
Check identity (for Python & eventual wrapper classes).
ERcState GetValue(CString *retString, TTicks *retTimeStamp=NULL)
Get a value of type "string" or a type based on it.
bool ValidBool(bool defaultVal=false, TTicks *retTimeStamp=NULL)
Get a valid Boolean value. This and the following methods are shortcuts for first obtaining the 'Valu...
static CResource * Register(CRcDriver *_rcDriver, const char *_lid, ERcType _type, bool _writable, void *_data=NULL)
Register a new local resource for a driver.
void SetUserData(void *_data)
Set user-specified data for this resource.
float ValidUnitFloat(ERcType _type, float defaultVal=0.0, TTicks *retTimeStamp=NULL)
Get a valid unit-type float value.
void ReportTrigger()
For triggers, this method must be called.
void Unregister()
Unregister a resource.
CRcRequest * GetRequest(const char *reqGid, bool allowNet=true)
Query a request by its request GID.
void WriteValue(CRcValueState value, int priority=rcPrioNone, const char *reqGid="write")
Write a value by issueing or updating a request with the given global id. The implementation of this ...
void ReadValueState(CRcValueState *retValueState, TTicks maxTime=-1)
Perform a blocking read to obtain an up-to-date value from the driver. Internally,...
void SetRequest(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).
int ValidUnitInt(ERcType _type, int defaultVal=0, TTicks *retTimeStamp=NULL)
Get a valid unit-type integer value.
const char * Uri()
Get the URI (aka global ID / GID).
void SetDefault(CRcValueState *vs)
Set a default value.
void SetRequestFromStr(const char *reqDef)
Set request by textual definition. See CRcRequest::SetFromStr() and the Home2L Book for more informat...
bool HasSubscribers()
Return whether this resource is currently subscribed (dynamic, not semi-static).
void SetTrigger(const char *reqGid, int priority=rcPrioNone, TTicks t0=NEVER, TTicks repeat=NEVER)
Set a trigger request (no value needs to be given).
void SetRequest(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 GarbageCollection()
Remove all unregistered resources.
ERcState GetValue(float *retFloat, TTicks *retTimeStamp=NULL)
Get a value of type "float" or a type based on it.
void ReportValueState(const CRcValueState *_valueState)
Report value and state; if different from previous value/state, notify all subscribers....
void SetRequest(TTicks valTime, 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).
bool IsLike(const char *pattern)
Check identity by pattern.
bool HasRequests()
Return whether this resource has requests (dynamic, not semi-static).
static CResource * Get(const char *uri, bool allowWait=false)
Look up a resource by its URI and return a reference to it.
void ReportUnknown()
Report an unknown state.
void WaitForRegistration()
Wait until registered or a network timeout occured.
const char * ValidString(CString *ret, const char *defaultVal=CString::emptyStr, TTicks *retTimeStamp=NULL)
Get a valid string value.
void ReportBusy()
Report a busy state (without changing the value).
bool GetRequestSet(CRcRequestSet *ret, bool allowNet=true)
Query all pending requests.
int ValidEnumIdx(ERcType _type, int defaultVal=0, TTicks *retTimeStamp=NULL)
Get a valid enumeration value index.
void SetRequest(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).
TTicks ValidTime(TTicks defaultVal=0, TTicks *retTimeStamp=NULL)
Get a valid time value.
int LockLocalRequests()
Return number of active requests for a local resource and lock this object. During the locked state,...
float ValidFloat(float defaultVal=0.0, TTicks *retTimeStamp=NULL)
Get a valid float value.
void SetRequest(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).
void RedriveValue(bool force=true)
Drive the currently requested value again.
ERcState GetValue(bool *retBool, TTicks *retTimeStamp=NULL)
Get a value of type "Bool" or a type based on it.
ERcState GetValue(TTicks *retTime)
Get a value of type "time".
const char * Gid()
Get the global ID.
const char * ValidMutex(CString *ret, const char *defaultVal=CString::emptyStr, TTicks *retTimeStamp=NULL)
Get a valid mutex value.
int ValidTrigger(int defaultVal=0, TTicks *retTimeStamp=NULL)
Get a valid trigger value.
Dynamically allocated string.
char * Get() const
Get the C string. Unless explicitely set by 'SetC', this will never return NULL or an invalid pointer...
static const char *const emptyStr
Use this whenever you need an empty string ("")
void SetF(const char *fmt,...)
Set using printf() formatting.
char * Disown()
Return current string as a dynamic object and clear 'this'.
void Set(FTimerCallback *_func, void *_data=NULL, void *_creator=NULL)
Setup timer without (re-)scheduling it.
int64_t TTicks
Time value (relative, absolute, or monotonic).
#define NEVER
Special value that may represent "never" for absolute or monotonic times. Other application-specific ...
#define ASSERT(COND)
Check a condition and abort the application if not true.
#define WARNING(MSG)
Print a warning message to the console.
const char * StringF(class CString *ret, const char *fmt,...)
Return 'ret->Get ()'.
const char * RcGetHostId(CRcHost *host)
Get textual ID of 'host'.
CRcHost * RcGetHost(int n)
Get reference to host n, 0 <= n < number of hosts.
int RcLockHostResources(CRcHost *host)
Query number of resources for a remote host.
static const char * RcLocalHostId()
Get the ID of the local instance.
int RcGetHosts()
Get number of known hosts.
int RcLockSubscribers()
Query the number of existing subscribers and lock the subscriber database.
int RcLockDriverResources(CRcDriver *driver)
Query the number of resources for a local driver.
void FRcDriverFunc(ERcDriverOperation, CRcDriver *, CResource *, CRcValueState *)
Resources driver function.
ERcDriverOperation
Driver operations.
@ rcdOpDriveValue
Drive a value; refers to CRcDriver::DriveValue(). Parameters: CRcDriver *driver, CResource *rc,...
@ rcdOpInit
Initialize driver object(s) of a linked-in driver. Parameter: CRcDriver *drv.
@ rcdOpStop
Stop the driver; refers to CRcDriver::Stop(). Parameter: CRcDriver *drv.
void RcIterate()
Perform pending actions, call TimerIterate() and return.
static void RcGarbageCollection()
(For experts) Remove all presently unregistered resources from memory.
void RcStop()
Stop a loop started by RcRun().
int RcRun(bool catchSignals=true)
Run RcStart(), then RcIterate() in a main event loop until RcStop() is called.
CResource * RcRegisterSignal(const char *name, ERcType type)
Register a new resource for the built-in 'signal' driver.
void RcDone()
Shutdown the Resources library.
void RcBump(CResource *rc=NULL, bool soft=false)
(For experts) Try to reconnect a remote host now.
void RcStart()
Complete the elaboration phase and start active operation. No more drivers and resources may be decla...
void RcInit(bool enableServer=false, bool inBackground=false)
Initialize the Resources library (and start the elaboration phase). This may be followed by driver de...
static CResource * RcGetResource(const char *uri, bool allowWait=false)
Lookup a resource by its URI and return a reference to it.
void RcDelRequest(const char *rcUri, const char *reqGid=NULL, TTicks t1=NEVER)
Delete a request.
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 RcUnsubscribeFromAll(CRcSubscriber *subscr)
Unsubscribe from all resources presently subscribed by 'subscr'. The caller remains owner of 'subscr'...
void RcSetTriggerFromStr(const char *rcUri, const char *reqDef)
Set trigger request by textual definition.
static void RcRegisterDriver(CRcDriver *drv)
Register a pre-initialized driver object (typically an object of a derived class with overloaded meth...
void RcSetRequestFromStr(const char *rcUri, const char *reqDef)
Set request by textual definition - see CRcRequest::SetFromStr() and the Home2L Book for more informa...
static CRcSubscriber * RcSubscribe(CRcSubscriber *subscr, CResource *rc)
Subscribe to an additional resource.
CRcSubscriber * RcNewSubscriber(const char *subscrLid, CResource *rc=NULL)
Create and register a new subscriber object and optionally subscribe to the given resource.
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).
void RcSetRequest(const char *rcUri, CRcRequest *req)
Add or replace a request (generic version).
const char *const rcDefaultRequestId
Request ID for default requests ("default")
const char * RcGetUserRequestId()
Get the request ID for user interactions (see 'rc.userReqId').
const char * RcGetUserRequestAttrs()
Get the default request attributes for user interactions (see 'rc.userReqAttrs').
#define rcPrioDefault
Preset defaults (typically by the driver)
CDict< CRcRequest > CRcRequestSet
Set of requests (for CResource::GetRequestSet() )
#define rcPrioNone
Undefined priority (special value)
bool FRcEventFunc(class CRcEventProcessor *, CRcEvent *, void *)
Event processor callback function. Example: bool OnEventFunc (CRcEventProcessor *ep,...
@ rceDisconnected
[subscriber] Connection to resource was lost
@ rceValueStateChanged
[subscriber] Value or state has changed
@ rceTimer
[timer] Timer alarm
@ rceNone
None (for dummy events)
@ rceConnected
[subscriber] Connection to resource is (re-)established
@ rceDriveValue
[driver] Drive a new value
@ rceRequestChanged
[subscriber] Request has changed
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,...
int RcTypeGetEnumValues(ERcType t)
Return the number of possible values for an enumeration type.
bool RcTypeIsStringBased(ERcType t)
Return if the base type is 'rctString'; This is the set of types that have dynamic data.
ERctUseState
Use/presence state of the home (for 'rctUseState')
ERcType RcTypeGetBaseType(ERcType t)
Return the underlying base type as a unique representative for compatible classes (e....
static bool RcTypeIsUnitType(ERcType t)
Return whether the type is a unit type.
ERctWindowState
Window state (for 'rctWindowState')
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,...
ERctPhoneState
Phone state (for 'rctPhoneState')
static bool RcTypeIsEnumType(ERcType t)
Return whether the type is a enumeration type.
ERcType
Resource major type.
ERctPlayerState
Music player state (for 'rctPlayerState')
const char * RcTypeGetUnit(ERcType t)
Return the unit string; For non-unit types, an empty string is returned.
@ rcsNoReport
Alias to make the 'successState' attribute in CRcEventDriver more intuitive.
@ rcsUnknown
Value is presently unknown (e.g. outdated).
@ rcsValid
Value is valid.
@ rcsBusy
Devices is busy and/or switching to the value indicated by the associate value.
@ rcvUseVacation
User is away temporarily (e.g. for work)
@ rcvUseNight
User is at home and present at day time.
@ rcvUseAway
User is at home, but sleeping (e.g. doors should be locked)
@ rcvWindowOpenOrTilted
(wide) open
@ rcvPhoneRinging
in call, including any 'psDialing' and 'psTransfer...' states (anything where a user is actively usin...
@ rctPercent
[float] Percentage (0.0 .. 100.0)
@ rctMutex
[rctString] resource represents a mutex (not implemented yet)
@ rctUseState
Use/presence state ("day", "night", "away", "vacation")
@ rctWindowState
Window opening state ("closed", "tilted", "open", "openOrTilted")
@ rctTrigger
[rctInt] Resource does not carry a value, but can transport events ("triggers"); 'vTriggerCount' coun...
@ rctPhoneState
Phone state ("idle", "ringing", "inCall")
@ rctPlayerState
Music player state ("stop", "pause", "play")
@ rctTemp
[float] Temperature in degree centigrade