resources.H

Go to the documentation of this file.

/*
 *  This file is part of the Home2L project.
 *
 *  (C) 2015-2024 Gundolf Kiefer
 *
 *  Home2L is free software: you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation, either version 3 of the License, or
 *  (at your option) any later version.
 *
 *  Home2L is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with Home2L. If not, see <https://www.gnu.org/licenses/>.
 *
 */
 
 
/* Home2L Resources interface file.
 *
 * This file contains the shared interface for the Home2L Resources library.
 * It is the sole file to be included by any client application.
 * Also, it serves as a SWIG input file for the Python library 'home2l'.
 */
 
 
#ifndef _RC_LIB_
#define _RC_LIB_
 
 
// This file is SWIG-readable and part of the Python library.
 
 
#include "env.H"
 
 
 
 
 
// ***** Doxygen Header *****
 
 
#ifdef SWIG
%pythoncode %{
## @file
##
##
## @defgroup resources Resources
## @brief The *Home2L Resources* library.
##
## The API exports a large number of low-level C/C++ functions and classes, which in many cases
## are not relevant for rules scripts or Python-based drivers and are not documented in detail here.
## As a rule of thumb, the level of documentation reflects the relevance of some function.
##
## The most common functions can be found in section @ref resources_general.
## Besides this, the classes CResource (@ref resources_rc) and CRcValueState (@ref resources_values)
## are important for accessing the data transported via resource objects.
##
## Most of the information presented here is also available as *Python docstrings*
## (avaliable via `help(<name>)` in a *Python* shell).
## Additional information can be found in the
## [*C/C++ API documentation*](../home2l-api_c/group__resources.html).
##
## @{
##
## @defgroup resources_general Main API
## @brief Top-level functionality of the *Resources* library - most commonly used functions can be found here.
##
## @defgroup resources_values Values, Types and States
## @brief Basic definitions for values and their types and state.
## Most relevant is the CRcValueState class to access the present value and state of a resource.
## More details can be found in the [*C/C++ API documentation*](../home2l-api_c/group__resources__values.html).
##
## @defgroup resources_rc Resource Objects
## @brief Accessing resource objects.
## More details can be found in the [*C/C++ API documentation*](../home2l-api_c/group__resources__rc.html).
##
## @defgroup resources_directory Directory Services
## @brief Querying local metadata (for interactive debugging).
## More details can be found in the [*C/C++ API documentation*](../home2l-api_c/group__resources__directory.html).
##
## @defgroup resources_subscribe Subscriptions
## @brief Low-level access to the C/C++ subscriber classes.
## More details can be found in the [*C/C++ API documentation*](../home2l-api_c/group__resources__subscribe.html).
##
## @defgroup resources_requests Requests
## @brief Low-level access to the C/C++ request class.
## More details can be found in the [*C/C++ API documentation*](../home2l-api_c/group__resources__requests.html).
##
## @defgroup resources_drivers Drivers
## @brief Low-level access to the C/C++ driver-related classes.
## More details can be found in the [*C/C++ API documentation*](../home2l-api_c/group__resources__drivers.html).
## Normally, the functions and decorators described in module [*Home2L / Resources*](group__home2l__resources.html)
## should be used to define custom drivers in Python.
%}
#endif // SWIG
 
 
 
 
 
// *************************** (Forward) Declararions ****************************
 
 
#ifndef SWIG
 
 
// Forward declarations (full declaration below)...
class CRcSubscriber;
class CRcRequest;
 
 
 
// ***** Internal classes *****
 
class CRcHost;            // represents a (remote) host
class CRcDriver;          // represents a (local) driver
class CRcSubscriberLink;
class CResourceLink;
 
 
#endif // #ifndef SWIG
 
 
 
// ***** Request priorities *****
 
#ifdef SWIG
%pythoncode %{
## @addtogroup resources_requests
## @{
%}
#endif // SWIG
 
#define rcPrioMin     0           
#define rcPrioNormal  3           
#define rcPrioMax     9           
 
#define rcPrioDefault 0           
#define rcPrioRuleMin 1           
#define rcPrioRule    3           
#define rcPrioRuleMax 5           
#define rcPrioUser    6           
#define rcPrioShell   7           
#define rcPrioSafety  8           
#define rcPrioIKnowWhatImDoing 9  
 
#define rcPrioNone   -1           
 
 
 
typedef CDict<CRcRequest> CRcRequestSet;
 
extern const char *const rcDefaultRequestId;    
 
 
#ifdef SWIG
%pythoncode %{
## @}
%}
#endif // SWIG
 
 
 
 
 
// *************************** Values, Types and States ************************
 
 
#ifdef SWIG
%pythoncode %{
## @addtogroup resources_values
## @{
%}
#endif // SWIG
 
 
 
 
 
// ***** Types *****
 
 
#define rctBasicTypesBase rctBool
#define rctBasicTypesLast rctTime
 
#define rctSpecialTypesBase rctTrigger
#define rctSpecialTypesLast rctMutex
 
#define rctUnitTypesBase 0x40
#define rctUnitTypesLast (rctUnitTypesEND-1)
 
#define rctEnumTypesBase 0x80
#define rctEnumTypesLast (rctEnumTypesEND-1)
 
 
enum ERcType {
  rctNone = 0,    
 
  rctBool,        
  rctInt,         
  rctFloat,       
  rctString,      
  //~ rctBlob,        ///< Binary data (not implemented yet, TBD)
  rctTime,        
  //~ rctColor,       ///< Color value (not implemented yet, TBD)
 
  rctTrigger,   
  rctMutex,     
 
  rctPercent = rctUnitTypesBase,
  rctTemp,      
  rctPower,     
  rctUnitTypesEND,
 
  rctUseState = rctEnumTypesBase,
  rctWindowState,
  rctPhoneState,
  rctPlayerState,
  rctEnumTypesEND
};
 
 
// Type names ...
const char *RcTypeGetName (ERcType t);
ERcType RcTypeGetFromName (const char *name);
 
// Get base type ...
ERcType RcTypeGetBaseType (ERcType t);
bool RcTypeIsStringBased (ERcType t);
 
// Unit types ...
static inline bool RcTypeIsUnitType (ERcType t) { return t >= rctUnitTypesBase && t <= rctEnumTypesBase; }
const char *RcTypeGetUnit (ERcType t);
 
// Enumeration types ...
static inline bool RcTypeIsEnumType (ERcType t) { return t >= rctEnumTypesBase; }
int RcTypeGetEnumValues (ERcType t);
const char *RcTypeGetEnumValue (ERcType t, int idx, bool warn = true);
int RcTypeGetEnumIdx (ERcType t, const char *value, bool warn = true);
 
 
 
 
 
// ***** Enum declarations for enumeration types *****
 
 
enum ERctUseState {
  rcvUseDay = 0,  
  rcvUseNight,    
  rcvUseAway,     
  rcvUseVacation  
};
 
 
enum ERctWindowState {
  rcvWindowClosed = 0,    
  rcvWindowTilted,        
  rcvWindowOpen,          
  rcvWindowOpenOrTilted   
};
 
 
enum ERctPhoneState {
  rcvPhoneIdle = 0,   
  rcvPhoneInCall,     
  rcvPhoneRinging     
};
 
 
enum ERctPlayerState {
  rcvPlayerStopped = 0, 
  rcvPlayerPaused,      
  rcvPlayerPlaying      
};
 
 
 
 
 
// ***** Values *****
 
 
// Union for an untyped value (for internal use only) @private
#ifdef SWIG
%immutable vString;
//~ %immutable vBlob;
#endif
union URcValue {
  uint64_t vAny;          // Pseudo-field to clear/compare independent of type
 
  bool vBool;
  int vInt;               // Width/value range can be machine dependent, but must be at least 32 bits (-2^31 .. +2^31-1).
  float vFloat;           // Encoding must be 32-bit floating point according to IEEE 754
  const char *vString;    // Pointer to a dynamically allocated string; NULL <=> string is empty ("")
  //~ uint8_t *vBlob;         // Binary data of any size (not implemented yet, TBD)
  TTicks vTime;
  //~ uint32_t vColor;        // Color value (ARGB) (not implemented yet, TBD)
};
 
 
#ifndef SWIG
STATIC_ASSERT(sizeof (URcValue) == sizeof (URcValue::vAny));
#endif
 
 
 
 
 
// ***** State *****
 
 
enum ERcState {
  rcsUnknown = 0,   
  rcsBusy,          
  rcsValid,         
 
  // Aliases ...
  rcsNoReport = rcsUnknown
};
 
 
 
 
 
// ***** CRcValueState *****
 
 
#ifdef SWIG
%feature("docstring") CRcValueState "Typed value tagged with a state and a time stamp.\n\n"
  "The constants for type 'ERcType' have the prefix 'rct*'."
  "The state may be one of:\n"
  "  'rcsUnknown': The value is unknown.\n"
  "  'rcsBusy': The value is known, the underlying device is busy.\n"
  "  'rcsValid': The value is known and stable.\n"
  "The time stamp reflects the age of a value (last change/update). It is\n"
  "generally not valid to judge from the time stamp whether the value is\n"
  "outdated, since there are other mechanisms in the library setting the\n"
  "state to 'rcsUnknown' if, for example, the connection to a remote resource\n"
  "got lost."
#endif
class CRcValueState {
  public:
    CRcValueState () { type = rctNone; Clear (); }
    CRcValueState (const CRcValueState *vs) { type = rctNone; Set (vs); if (vs) timeStamp = vs->timeStamp; }
    CRcValueState (ERcType _type) { type = rctNone; Clear (_type); }   
 
    CRcValueState (ERcType _type, bool _val, ERcState _state = rcsValid) { type = rctNone; SetBool (_val, _state); }
    CRcValueState (ERcType _type, int _val, ERcState _state = rcsValid) { type = rctNone; SetGenericInt (_val, _type, _state); }
    CRcValueState (ERcType _type, float _val, ERcState _state = rcsValid) { type = rctNone; SetGenericFloat (_val, _type, _state); }
    CRcValueState (ERcType _type, const char *_val, ERcState _state = rcsValid) { type = rctNone; SetGenericString (_val, _type, _state); }
    CRcValueState (ERcType _type, TTicks _val, ERcState _state = rcsValid) { type = rctNone; SetTime (_val, _state); }
 
    ~CRcValueState () { Clear (rctNone); }
 
#ifndef SWIG
    CRcValueState& operator = (const CRcValueState &_vs) { Set (&_vs); timeStamp = _vs.timeStamp; return *this; }
#endif
 
    void Clear () { Clear (type); }
    void Clear (ERcType _type, ERcState _state = rcsUnknown);
    void Set (const CRcValueState *vs2);
 
    void SetToReportBusy () { SetToReportBusyOldVal (); }
    void SetToReportBusyOldVal () { Clear (rctNone, rcsBusy); }
    void SetToReportBusyNewVal () { state = rcsBusy; }
    void SetToReportNothing () { state = rcsUnknown; }
 
    void SetGenericInt (int _val, ERcType _type, ERcState _state = rcsValid);
    void SetGenericFloat (float _val, ERcType _type, ERcState _state = rcsValid);
    bool SetGenericString (const char *_val, ERcType _type, ERcState _state = rcsValid);
 
    void SetBool (bool _val, ERcState _state = rcsValid)            { SetGenericInt    (_val, rctBool, _state);    }
    void SetInt (int _val, ERcState _state = rcsValid)              { SetGenericInt    (_val, rctInt, _state);     }
    void SetFloat (float _val, ERcState _state = rcsValid)          { SetGenericFloat  (_val, rctFloat, _state);   }
    bool SetString (const char *_val, ERcState _state = rcsValid)   { return SetGenericString (_val, rctMutex, _state);   }
    void SetTime (TTicks _val, ERcState _state = rcsValid);
 
    void SetTrigger (int _val = 1, ERcState _state = rcsValid)      { SetGenericInt    (_val, rctTrigger, _state); }
    bool SetMutex (const char *_val, ERcState _state = rcsValid)    { return SetGenericString (_val, rctMutex, _state);   }
 
    void SetUnitInt (ERcType type, int _val, ERcState _state = rcsValid)      { SetGenericInt   (_val, type, _state); }
    void SetUnitFloat (ERcType type, float _val, ERcState _state = rcsValid)  { SetGenericFloat (_val, type, _state); }
 
    void SetEnum (ERcType type, int _val, ERcState _state = rcsValid)         { SetGenericInt   (_val, type, _state); }
 
    int           GenericInt () const     { ASSERT (RcTypeGetBaseType (type) == rctInt);    return val.vInt;   }
    float         GenericFloat () const   { ASSERT (RcTypeGetBaseType (type) == rctFloat);  return val.vFloat; }
    const char *  GenericString () const  { ASSERT (RcTypeGetBaseType (type) == rctString); return val.vString; }
 
    bool          Bool () const     { ASSERT (type == rctBool);     return val.vBool;   }
    int           Int () const      { ASSERT (type == rctInt);      return val.vInt; }
    float         Float () const    { ASSERT (type == rctFloat);    return val.vFloat; }
    const char *  String () const   { ASSERT (type == rctString);   return val.vString; }
    TTicks        Time () const     { ASSERT (type == rctTime);     return val.vTime;  }
 
    int           Trigger () const  { ASSERT (type == rctTrigger);  return val.vInt;    }
    const char *  Mutex () const    { ASSERT (type == rctMutex);    return val.vString; }
 
    int           UnitInt (ERcType _type) const    { ASSERT (type == _type);  return val.vInt;    }
    float         UnitFloat (ERcType _type) const  { ASSERT (type == _type);  return val.vFloat;  }
 
    int           EnumIdx () const  { ASSERT (RcTypeIsEnumType (type)); return val.vInt; }
 
#ifndef SWIG
    ERcState GetValue (bool *retBool);
    ERcState GetValue (int *retInt);
    ERcState GetValue (float *retFloat);
    ERcState GetValue (CString *retString);
    ERcState GetValue (TTicks *retTime);
#endif
 
    bool          ValidBool (bool defaultVal = false);
    int           ValidInt (int defaultVal = 0);
    float         ValidFloat (float defaultVal = 0.0);
    const char *  ValidString (const char *defaultVal = CString::emptyStr);
    TTicks        ValidTime (TTicks defaultVal = 0);
 
    int           ValidTrigger (int defaultVal = 0)                       { return ValidInt (defaultVal); }
    const char *  ValidMutex (const char *defaultVal = CString::emptyStr) { return ValidString (defaultVal); }
 
    int           ValidUnitInt (ERcType _type, int defaultVal = 0) const;
    float         ValidUnitFloat (ERcType _type, float defaultVal = 0.0) const;
    int           ValidEnumIdx (ERcType _type, int defaultVal = 0) const;
 
    void SetType (ERcType _type) { Clear (_type); }
    void SetState (ERcState _state) { state = _state; }
    void SetTimeStamp (TTicks _timeStamp) { timeStamp = _timeStamp; }
 
    ERcType Type () const { return type; }
    ERcState State () const { return state; }
    TTicks TimeStamp () const { return timeStamp; }
 
    bool IsValid () const { return state == rcsValid; }
    bool IsBusy () const { return state == rcsBusy; }
    bool IsKnown () const { return state != rcsUnknown; }
 
    bool Equals (const CRcValueState *vs2) const;
    bool ValueEquals (const CRcValueState *vs2) const;
 
    bool Convert (ERcType _type);
 
    const char *ToStr (CString *ret, bool withType = false, bool withTimeStamp = false, bool precise = false, int stringChars = 20) const;
 
    bool SetFromStr (const char *str);
    bool SetFromStrFast (const char *str, bool warn = true);
 
    void ToHuman (char *retBuf, int retBufSize);
 
  protected:
    friend class CResource;
 
    // Fields...
    ERcType type;
    URcValue val;
    ERcState state;
    TTicks timeStamp;   
};
 
 
// Python extension...
#ifdef SWIG
%extend CRcValueState {
  %newobject __str__ ();
  const char *__str__ () { CString s; $self->ToStr (&s); return s.Disown (); }
  %newobject __repr__ ();
  const char *__repr__ () { CString s, s1; s.SetF ("(CRcValueState) %s", $self->ToStr (&s1, true)); return s.Disown (); }
  bool __eq__ (CRcValueState *other) { return $self->Equals (other); }
  bool __ne__ (CRcValueState *other) { return !$self->Equals (other); }
  %pythoncode %{
    pass    # (Workaround to keep SWIG from scrambling the indentation of the following code.)
 
    ## Return the value as a Python object.
    def Value(self):
      """Return the value as a Python object. In case of a state of 'rcsUnknown' or\n\
      if 'self' is not defined, 'None' is returned. 'self == None' is allowed.\n\
      """
      if not self: return None
      if self.State () == rcsUnknown: return None
      t = RcTypeGetBaseType (self.Type ())
      if   t == rctBool:   return self.Bool()
      elif t == rctInt:    return self.GenericInt()
      elif t == rctFloat:  return self.GenericFloat()
      elif t == rctString: return self.GenericString()
      elif t == rctTime:   return self.Time()
      else: return None
 
    ## Return the most appropriate valid value as a Python object.
    def ValidValue(self, defaultVal):
      """Return the value as a Python object. Unlike 'Value', this method never\n\
      returns 'None', but reverts to the given default value, if 'self' does not\n\
      transort a valid value. 'self == None' is tolerated\n\
      """
      ret = self.Value ()
      if ret == None: ret = defaultVal
      return ret
  %} // %pythoncode
}; // %extend CRcValueState
#endif
 
 
#define NO_VALUE_STATE ((CRcValueState *) NULL)
 
 
#ifdef SWIG
%pythoncode %{
## @}
%}
#endif // SWIG
 
 
 
 
 
// *************************** Resources ***************************************
 
 
#ifdef SWIG
%pythoncode %{
## @addtogroup resources_rc
## @{
%}
#endif // SWIG
 
 
#ifdef SWIG
%feature("docstring") CResource "Home2L Resource.\n\n"
  "This is the most central class of the library. A 'Resource' may represent\n"
  "a sensor, an actor, a stored value, a virtual device, a mutex, an event\n"
  "trigger - almost anything. Resources are identified by a uniform resource\n"
  "identifier (URI)."
#endif
class CResource /* final */ {
  public:
 
 
    // ***** For applications *****
 
    static CResource *Get (const char *uri, bool allowWait = false);
    static void GarbageCollection ();
 
    const char *Uri () { return gid.Get (); }         
    const char *Gid () { return gid.Get (); }         
    const char *Lid () { return ATOMIC_READ (lid); }
 
    bool Is (const char *uri);                        
    bool Is (CResource *rc) { return this == rc; }    
    bool IsLike (const char *pattern);                
 
    bool IsWritable () { return writable; }
 
    const char *ToStr (CString *ret, bool pathLocal = false);   // semi-static, iff 'pathLocal' == true!!
 
 
#ifndef SWIG
 
    void GetValueState (CRcValueState *retValueState);
 
    // Get value (relaxed typing) ...
    ERcState GetValue (bool *retBool, TTicks *retTimeStamp = NULL);
    ERcState GetValue (int *retInt, TTicks *retTimeStamp = NULL);
    ERcState GetValue (float *retFloat, TTicks *retTimeStamp = NULL);
    ERcState GetValue (CString *retString, TTicks *retTimeStamp = NULL);
    ERcState GetValue (TTicks *retTime);
 
    // Get value (relaxed typing with auto-correction) ...
    bool          ValidBool (bool defaultVal = false, TTicks *retTimeStamp = NULL);
    int           ValidInt (int defaultVal = 0, TTicks *retTimeStamp = NULL);
    float         ValidFloat (float defaultVal = 0.0, TTicks *retTimeStamp = NULL);
    const char *  ValidString (CString *ret, const char *defaultVal = CString::emptyStr, TTicks *retTimeStamp = NULL);
    TTicks        ValidTime (TTicks defaultVal = 0, TTicks *retTimeStamp = NULL);
 
    int           ValidTrigger (int defaultVal = 0, TTicks *retTimeStamp = NULL)  { return ValidInt (defaultVal, retTimeStamp); }
    const char *  ValidMutex (CString *ret, const char *defaultVal = CString::emptyStr, TTicks *retTimeStamp = NULL)  { return ValidString (ret, defaultVal, retTimeStamp); }
 
    int           ValidUnitInt (ERcType _type, int defaultVal = 0, TTicks *retTimeStamp = NULL);
    float         ValidUnitFloat (ERcType _type, float defaultVal = 0.0, TTicks *retTimeStamp = NULL);
    int           ValidEnumIdx (ERcType _type, int defaultVal = 0, TTicks *retTimeStamp = NULL);
 
#endif
 
    // Get attributes  ...
    ERcType Type () const { return ATOMIC_READ (valueState.type); }
    ERcState State () const { return ATOMIC_READ (valueState.state); }
    TTicks TimeStamp () const { return ATOMIC_READ (valueState.timeStamp); }
 
    bool IsValid () const { return ATOMIC_READ (valueState.state) == rcsValid; }
    bool IsBusy () const { return ATOMIC_READ (valueState.state) == rcsBusy; }
    bool IsKnown () const { return ATOMIC_READ (valueState.state) != rcsUnknown; }
 
    bool Equals (const CRcValueState *vs2) { CRcValueState vs; GetValueState (&vs); return vs.Equals (vs2); }
    bool ValueEquals (const CRcValueState *vs2) { CRcValueState vs; GetValueState (&vs); return vs.ValueEquals (vs2); }
 
 
 
    CResource *Subscribe (CRcSubscriber *subscr) { SubscribePAL (subscr); return this; }
    void Unsubscribe (CRcSubscriber *subscr) { UnsubscribePAL (subscr); }
 
 
 
#ifndef SWIG
    void SetRequestFromObj (CRcRequest *_request);
    void SetRequest (CRcRequest *_request) { SetRequestFromObj (_request); }
    void SetRequest (CRcValueState *value, const char *reqGid = NULL, int priority = rcPrioNone, TTicks t0 = NEVER, TTicks t1 = NEVER, TTicks repeat = NEVER, TTicks hysteresis = NEVER);
    void SetRequest (bool valBool,          const char *reqGid = NULL, int priority = rcPrioNone, TTicks t0 = NEVER, TTicks t1 = NEVER, TTicks repeat = NEVER, TTicks hysteresis = NEVER);
    void SetRequest (int valInt,            const char *reqGid = NULL, int priority = rcPrioNone, TTicks t0 = NEVER, TTicks t1 = NEVER, TTicks repeat = NEVER, TTicks hysteresis = NEVER);
    void SetRequest (float valFloat,        const char *reqGid = NULL, int priority = rcPrioNone, TTicks t0 = NEVER, TTicks t1 = NEVER, TTicks repeat = NEVER, TTicks hysteresis = NEVER);
    void SetRequest (const char *valString, const char *reqGid = NULL, int priority = rcPrioNone, TTicks t0 = NEVER, TTicks t1 = NEVER, TTicks repeat = NEVER, TTicks hysteresis = NEVER);
    void SetRequest (TTicks valTime,        const char *reqGid = NULL, int priority = rcPrioNone, TTicks t0 = NEVER, TTicks t1 = NEVER, TTicks repeat = NEVER, TTicks hysteresis = NEVER);
    void SetRequestFromStr (const char *reqDef);
 
    void SetTrigger (const char *reqGid, int priority = rcPrioNone, TTicks t0 = NEVER, TTicks repeat = NEVER);
    void SetTriggerFromStr (const char *reqDef);
 
    void DelRequest (const char *reqGid = NULL, TTicks t1 = NEVER);
 
#endif // SWIG
 
    bool GetRequestSet (CRcRequestSet *ret, bool allowNet = true);
    CRcRequest *GetRequest (const char *reqGid, bool allowNet = true);
 
 
 
#ifndef SWIG
    void ReadValueState (CRcValueState *retValueState, TTicks maxTime = -1);
#endif
    void WriteValue (CRcValueState value, int priority = rcPrioNone, const char *reqGid = "write") { SetRequest (&value, reqGid, priority); }
    void UnWrite (const char *reqGid = "write") { DelRequest (reqGid); }
 
 
 
    // ***** For drivers *****
 
 
#ifndef SWIG
    static CResource *Register (CRcDriver *_rcDriver, const char *_lid, ERcType _type, bool _writable, void *_data = NULL) { return Register (NULL, _rcDriver, _lid, _type, _writable, _data); }
    static CResource *Register (CRcDriver *_rcDriver, const char *_lid, const char *rcTypeDef, void *_data = NULL) { return Register (NULL, _rcDriver, _lid, rcTypeDef, _data); }
#endif
 
    void SetDefault (CRcValueState *vs)     { SetRequest (vs,         rcDefaultRequestId, rcPrioDefault); }
    void SetDefault (bool valBool)          { SetRequest (valBool,    rcDefaultRequestId, rcPrioDefault); }
    void SetDefault (int valInt)            { SetRequest (valInt,     rcDefaultRequestId, rcPrioDefault); }
    void SetDefault (float valFloat)        { SetRequest (valFloat,   rcDefaultRequestId, rcPrioDefault); }
    void SetDefault (const char *valString) { SetRequest (valString,  rcDefaultRequestId, rcPrioDefault); }
    void SetDefault (TTicks valTime)        { SetRequest (valTime,    rcDefaultRequestId, rcPrioDefault); }
 
    void Unregister ();
 
 
    void SetUserData (void *_data) { ATOMIC_WRITE (rcUserData, _data); }
    void *UserData () { return ATOMIC_READ (rcUserData); }
 
    void ReportValueState (const CRcValueState *_valueState);
#ifndef SWIG
    void ReportValue (bool _value, ERcState _state = rcsValid);
    void ReportValue (int _value, ERcState _state = rcsValid);
    void ReportValue (float _value, ERcState _state = rcsValid);
    void ReportValue (const char *_value, ERcState _state = rcsValid);
    void ReportValue (TTicks _value, ERcState _state = rcsValid);
#endif // SWIG
    void ReportTrigger ();
    void ReportState (ERcState _state) { CRcValueState vs; vs.SetState (_state); ReportValueState (&vs); }
    void ReportBusy () { ReportState (rcsBusy); }
    void ReportUnknown () { ReportValueState (NULL); }
 
    void RedriveValue (bool force = true) { EvaluateRequests (force); }
 
 
    // ***** For info & directory services *****
 
 
#ifndef SWIG
    const char *GetInfo (CString *ret, int verbosity = 1, bool allowNet = true);
#endif
    void PrintInfo (FILE *f = stdout, int verbosity = 1, bool allowNet = true);
 
    int LockLocalSubscribers ();
    CRcSubscriber *GetLocalSubscriber (int n);
    void UnlockLocalSubscribers () { Unlock (); }
 
    int LockLocalRequests ();
    CRcRequest *GetLocalRequest (int n);
    void UnlockLocalRequests () { Unlock (); }
 
 
#ifndef SWIG
 
 
    class CRcHost *Host () { return ATOMIC_READ (rcHost); }
    class CRcDriver *Driver () { return ATOMIC_READ (rcDriver); }
 
    unsigned RegSeq () { return ATOMIC_READ (regSeq); }
 
    bool IsRegistered () { return (ATOMIC_READ (regSeq) & 1) == 1; }
    void WaitForRegistration ();
    bool HasSubscribers () { return ATOMIC_READ (subscrList) != NULL; }
    bool HasRequests () { return ATOMIC_READ (requestList) != NULL; }
 
 
#endif
 
 
    // ***** Private *****
 
    // Constructor/destructor (private!)...
    //   Only this class itself is allowed to create or destroy new objects.
    //   SWIG is the only reason why the con- & destructor are not declared private.
#ifndef SWIG  // for not offering the constructor in the API
    CResource ();
    ~CResource ();
#endif
 
  private:
 
#ifndef SWIG
    friend void CResourceRequestsTimerCallback (CTimer *, void *);
    friend class CRcSubscriber;
    friend class CRcHost;
#endif
 
    // Registration and life cycle management ...
    static CResource *GetUnregistered (const char *uri);
    void PutUnregistered ();
 
    static CResource *Register (CRcHost *_rcHost, CRcDriver *_rcDriver, const char *_lid, ERcType _type, bool _writable, void *_data);
      // Generic & main registration method; used by all other 'Registration' variants
    static CResource *Register (CRcHost *_rcHost, CRcDriver *_rcDriver, const char *_lid, const char *rcTypeDef, void *_data);
      // Register with textual description; used by full textual registration (below) and for the "external" driver
      // Syntax of 'rcTypeDef':   <type> (ro|wr)
      // returns 'NULL' on error and prints a warning
    static CResource *Register (const char *rcDef, void *_data);
      // Register with full textual description; used by 'rc_core' for remote resources
      // Syntax: <URI> <type> (ro|wr)
      // returns 'NULL' on error and prints a warning
 
    // Value & state...
    const CRcValueState *ValueState () { return &valueState; }      // 'this' must be locked as long as the returned value is accessed
 
    // Reading values...
    void SubscribePAL (CRcSubscriber *subscr, bool resLocked = false, bool subLocked = false);
      // 'resLocked' and 'subLocked' must be set if a lock on the resource or subscription is already held.
      // The method may temporarily release a lock to avoid deadlocks.
    void UnsubscribePAL (CRcSubscriber *subscr, bool resLocked = false, bool subLocked = false);
      // 'resLocked' and 'subLocked' must be set if a lock on the resource or subscription is already held.
      // The method may shortly release a lock to avoid deadlocks.
 
    // Requests...
    void UpdatePersistentRequestAL (const char *reqId, CRcRequest *req);
    bool DoDelRequestAL (CRcRequest **pList, const char *reqGid, TTicks t1, bool updatePersistence);
    bool DelRequestNoEvaluate (const char *reqGid, TTicks t1);
    void SetRequestFromObjNoEvaluate (CRcRequest *_request);
 
    CRcRequest *GetWinningRequest (TTicks t);
    void EvaluateRequests (bool force = false);    // check and process all pending requests
 
    // Drivers ...
    //   The '...AL' method variants assume that the resource has already been locked by the caller.
    void NotifySubscribers (int evType, const char *evAttr = NULL);
    void NotifySubscribersAL (int evType, const char *evAttr = NULL);    // 'evType' is effectively of type 'ERcEventType'
    void ReportNetLost ();
      // Report that the network connection to the server was lost (like 'ReportUnknown' but
      // with different time stamp behaviour; see above).
 
    void ReportValueStateAL (const CRcValueState *_valueState, TTicks _timeStamp = 0);
    void ReportUnknownAL () { CRcValueState vs (Type ()); ReportValueStateAL (&vs); }
 
    // Driving values to the real device...
    void DriveValue (CRcValueState *vs, bool force);
      // Propagate a new requested value to the driver (to make that happen in the real device).
      // 'force == true': Call the driver function in any case, not only on a true VS change
 
    // Helpers...
    void Lock () { mutex.Lock (); }
    void Unlock () { mutex.Unlock (); }
 
 
    // BEGIN static data (never changed after the initialization of the object)...
    //   No locking required.
    CString gid;                // aka URI
 
    // BEGIN semi-static data ...
    //   Fields marked with "[atomic]" must be accessed using the 'ATOMIC_*' macros on each write access and on read accesses if'this' is not locked.
    //   Fields marked with "[mutex]" may only be accessed if 'this' is locked.
    //   The consistency of all semi-static data as a whole is protected by the sequence lock 'regSeq'.
 
    // Resource identification...
    class CRcHost *rcHost;      // [atomic] 'NULL' => local resource or unregistered
    class CRcDriver *rcDriver;  // [atomic] 'NULL' => remote resource or unregistered
    void *rcUserData;         // optional user data that can be used by the driver (driver cares for concurrent access)
    const char *lid;            // [atomic] local resources: relative path without driver; remote: with driver name as first component; points into 'gid.Get ()'.
 
    // Resource properties...
    unsigned regSeq;            // [atomic]
    bool writable, persistent;  // (not "atomic" since only one byte is relevant)
 
    // BEGIN dynamic data ...
    //   All fields may only be accessed if 'this' is locked.
 
    // Current value, its type, and its state...
    CRcValueState valueState;   // only state and value are dynamic; 'valueState.type' is semi-static (not "atomic" since only one byte is relevant)
 
    // Internal...
    //   'CResource' objects are managed by a 'CDict' associated with a driver (local resources) or
    //   host (remote resources).
    CMutex mutex;               // protects 'this' including the request list
    CRcRequest *requestList;
    CTimer requestTimer;        // timer for the next evaluation of requests
    CRcSubscriberLink *subscrList;
};
 
 
// Python extensions...
#ifdef SWIG
%extend CResource {
  %newobject __str__ ();
  const char *__str__ () { CString s; $self->ToStr (&s); return s.Disown (); }
  %newobject __repr__ ();
  const char *__repr__ () { CString s, s2; s.SetF ("(CResource) %s", $self->ToStr (&s2)); return s.Disown (); }
  bool __eq__ (CResource *other) { return $self == other; }
  bool __ne__ (CResource *other) { return $self != other; }
 
  %delobject SetRequestFromObj ();
 
  %feature("docstring") ValueState "Get the current value and state of the resource."
  %newobject ValueState ();
  CRcValueState *ValueState () { CRcValueState *ret = new CRcValueState (); $self->GetValueState (ret); return ret; }
 
  void _SetRequestFromObj (CRcRequest *_request) { $self->SetRequestFromObj (_request); }
  void _DelRequest (const char *reqGid = NULL, TTicks t1 = NEVER) { $self->DelRequest (reqGid, t1); }
 
  %pythoncode %{
    pass    # (Workaround to keep SWIG from scrambling the indentation of the following code.)
 
    def Value (self):
      """Get a value ('None' if invalid) of this resource (use ValueState() to get the complete value and state)."""
      return self.ValueState ().Value ()
 
    def ValidValue (self, defaultVal):
      """Get a valid value of this resource (use ValueState() to get the complete value and state)."""
      return self.ValueState ().ValidValue (defaultVal)
 
    def SetRequest (self, reqDef = None, attrs = None, value = None, id = None, priority = None, t0 = None, t1 = None, repeat = None, hysteresis = None, delDelay = None):
      """Set or delete a request with selected attributes.\n\
      \n\
      This method allows to set any subset of attributes in a flexible way, either by (named) function arguments\n\
      or by a textual description as accepted by the Home2L Shell or CRcRequest::SetFromStr().\n\
      \n\
      If the effective value is 'None' (no value is passed), the call will delete the request with\n\
      the specified ID passing 'delDelay' as the 't1' argument of DelRequest().\n\
      \n\
      See RcSetRequest() for a detailed explanation of the arguments and examples.\n\
      """
      if RcTypeIsStringBased (self.Type ()) and reqDef != None:
        print ("WARNING: Setting a request to the string-type resource '" + str(self) + "' using the 'reqDef' argument is ambiguous!")
      req = CRcRequest ()
      req.Set (reqDef = reqDef, attrs = attrs, value = value, id = id, priority = priority, t0 = t0, t1 = t1, repeat = repeat, hysteresis = hysteresis)
      if req.Value ().IsKnown ():
        req.thisown = 0   # tell swig to disown the object ([2021-01-03]: '%delobject SetRequestFromObj ()' silently does not work)
        self._SetRequestFromObj (req)
      else:
        self.DelRequest (req.Gid (), delDelay)
 
    def SetTrigger (self, attrs = None, id = None, priority = None, t0 = None, t1 = None, repeat = None, hysteresis = None):
      """Set a request for a trigger resource with selected attributes."""
      req = CRcRequest ()
      req.Set (value = 1, attrs = attrs, id = id, priority = priority, t0 = t0, t1 = t1, repeat = repeat, hysteresis = hysteresis)
      req.thisown = 0   # tell swig to disown the object ([2021-01-03]: '%delobject SetRequestFromObj ()' silently does not work)
      self._SetRequestFromObj (req)
 
    def DelRequest (self, reqId = None, t1 = None):
      """Delete a request by its ID."""
      if t1 == None: self._DelRequest (reqId)
      else: self._DelRequest (reqId, TicksAbsOf (t1))
 
    def ReportValue (self, value, state = rcsValid):
      """Report a new value and optionally its state. If '_value == None', 'ReportUnknown()' is called."""
      if value == None: self.ReportUnknown ()
      else: self.ReportValueState (CRcValueState (self.Type (), value, state))
 
  %}
};  // %extend CResource
#endif
 
 
#ifdef SWIG
%pythoncode %{
## @}
%}
#endif // SWIG
 
 
 
 
 
// *************************** Events ******************************************
 
 
#ifdef SWIG
%pythoncode %{
## @addtogroup resources_subscribe
## @{
%}
#endif // SWIG
 
 
enum ERcEventType {
  rceNone = 0,                
 
  rceTimer,                   
 
  rceValueStateChanged,       
  rceRequestChanged,          
  rceDisconnected,            
  rceConnected,               
 
  rceDriveValue               
};
 
 
 
// ***** CRcEvent *****
 
 
#ifdef SWIG
%feature("docstring") CRcEvent "Resource events delivered by a subscriber or to a driver.\n\n"
  "Possible event types are:\n"
  "  rceTimer:             Timer alarm.\n"
  "  rceValueStateChanged: The resource has changed its value.\n"
  "  rceRequestChanged:    A request has been changed or deleted. The 'ValueState ()'\n"
  "                        attribute indicates the affected request ID (type is string).\n"
  "  rceDisconnected:      The connection to the (remote) resource has\n"
  "                        been lost.\n"
  "  rceConnected:         The connection to the (remote) resource has\n"
  "                        been established (again).\n"
  "  rceDriveValue:        Drive a value (for drivers).\n"
  "  rceNone:              Nothing (dummy event: ignore).\n"
  "The attribute 'MorePending ()' indicates whether more events are waiting for the\n"
  "same subscriber. This can be used for performance optimizations to avoid\n"
  "unecessary recomputations."
#endif
class CRcEvent {
  public:
    CRcEvent (ERcEventType _type = rceNone, CResource *_resource = NULL, CRcValueState *_valueState = NULL, void *_data = NULL) { Set (_type, _resource, _valueState, _data); }
 
    void Clear () { Set (); }
    void Set (ERcEventType _type = rceNone, CResource *_resource = NULL, CRcValueState *_valueState = NULL, void *_data = NULL);
 
    void SetType (ERcEventType _type) { type = _type; }
    void SetResource (CResource *_resource) { resource = _resource; }
    void SetValueState (CRcValueState *_valueState);
    void SetData (void *_data) { data = _data; }
 
    ERcEventType Type () { return type; }
    CResource *Resource () { return resource; }
    CRcValueState *ValueState () { return &valueState; }
    void *Data () { return data; }
 
    const char *ToStr (CString *ret); 
 
  protected:
    friend class CRcEventProcessor;
 
    ERcEventType type;          // event type
    CResource *resource;
    CRcValueState valueState;   // a) value + state for 'rceValueStateChanged'
                                // b) value for 'rceDriveValue'
                                // c) request ID for 'rceRequestChanged'
    void *data;                 // user data
 
    bool morePending;   // After 'PollEvent'/'WaitEvent' indicates whether more events are pending for
                        // the current subscriber to allow for optimized processing afterwards.
                        // Note: This should only be used if either all or no events are processed by callbacks.
 
    CRcEvent *next;
};
 
 
// Python extension...
#ifdef SWIG
%extend CRcEvent {
  %newobject __str__ ();
  const char *__str__ () { CString s; $self->ToStr (&s); return s.Disown (); }
  %newobject __repr__ ();
  const char *__repr__ () { CString s, s1; s.SetF ("(CRcEvent) %s", $self->ToStr (&s1)); return s.Disown (); }
}
#endif
 
 
 
// ***** CRcEventProcessor *****
 
 
typedef bool FRcEventFunc (class CRcEventProcessor *, CRcEvent *, void *);
 
 
class CRcEventProcessor {
  public:
    CRcEventProcessor (bool _inSelectSet = false);
    virtual ~CRcEventProcessor ();
 
    void PutEvent (CRcEvent *ev);     
 
#ifndef SWIG
 
    bool PollEvent (CRcEvent *ev);
    bool WaitEvent (CRcEvent *ev, TTicks *maxTime = NULL);
    void Interrupt ();    
    void FlushEvents ();  
 
    virtual bool OnEvent (CRcEvent *ev);
    void SetCbOnEvent (FRcEventFunc *_cbEvent, void *_cbEventData = NULL);
    void ClearCbOnEvent () { SetCbOnEvent (NULL, NULL); }
 
#endif // SWIG
 
    void SetInSelectSet (bool _inSelectSet);
    bool InSelectSet () { return inSelectSet; }
 
    static CRcEventProcessor *Select (TTicks maxTime = -1);
    // TBD: Implement 'InterruptSelect' to interrupt a waiting 'Select'
 
    virtual const char *TypeId () { return CString::emptyStr; }   
    virtual const char *InstId () { return CString::emptyStr; }   
 
    const char *ToStr (CString *ret) { return StringF (ret, "%s:%s", TypeId (), InstId ()); }
 
  private:
 
    // Internal helpers ...
    bool DoPollEventAL (CRcEvent *ev);
 
    void DeleteFirstEventAL ();
 
    void LinkAL ();
    void UnlinkAL ();
    bool IsLinkedAL () { return next || pLastProc == &next; }
 
    // Dynamic data (protected by 'globMutex')...
    static CMutex globMutex;        // protects dynamic data of all event processors
    static CCond globCond;          // global condition variable for 'Select'
    CCond cond;                     // per-object condition variable for 'WaitEvent', mutex is 'globMutex'
    volatile bool interrupted;      // used (only) in 'WaitEvent' and 'Interrupt'
 
    FRcEventFunc *cbEvent;
    void *cbEventData;
 
    CRcEvent *firstEv, **pLastEv;   // linked list with efficient appending
 
    bool inSelectSet;
    static CRcEventProcessor *firstProc, **pLastProc;     // linked list of event processors with pending events
    CRcEventProcessor *next;        // 'next' pointer for 'firstProc'/'pLastProc' list
};
 
 
// Python extension...
#ifdef SWIG
%extend CRcEventProcessor {
  %newobject __str__ ();
  const char *__str__ () { CString s; $self->ToStr (&s); return s.Disown (); }
  %newobject __repr__ ();
  const char *__repr__ () { CString s, s1; s.SetF ("(CRcEventProcessor) %s", $self->ToStr (&s1)); return s.Disown (); }
 
  %newobject PollEvent ();
  CRcEvent *PollEvent () {
    CRcEvent ev, *ret;
    if (!$self->PollEvent (&ev)) return NULL;
    ret = new CRcEvent ();
    *ret = ev;
    //~ INFOF (("### Python: Pollevent () -> %08x", ret));
    return ret;
  }
};  // %extend CRcEventProcessor
#endif
 
 
 
 
 
// ***** CRcEventTimer *****
 
 
#ifdef SWIG
%warnfilter(401) CRcEventTimer;     // class 'CTimer' is not known to SWIG
#endif
 
class CRcEventTimer: public CTimer, public CRcEventProcessor {
  public:
    CRcEventTimer (const char *_id, void *_data = NULL) { id.Set (_id); Set (_data); }
    CRcEventTimer (TTicks _time, TTicks _interval = 0, void *_data = NULL) { Set (_time, _interval, _data); }
 
    void Set (void *_data) { CTimer::Set (NULL, _data, NULL); }
    void Set (TTicks _time, TTicks _interval = 0, void *_data = NULL) { CTimer::Set (_time, _interval, NULL, _data, NULL); }
 
    virtual void OnTime () { CRcEvent ev (rceTimer, NULL, NULL, data); PutEvent (&ev); }
 
    virtual const char *TypeId () { return "T"; }         // hint for Python/SWIG API
    virtual const char *InstId () { return id.Get (); }   // hint for Python/SWIG API
 
  protected:
    CString id;
};
 
 
#ifdef SWIG
%pythoncode %{
## @}
%}
#endif // SWIG
 
 
 
 
 
// *************************** Subscribers *************************************
 
 
#ifdef SWIG
%pythoncode %{
## @addtogroup resources_subscribe
## @{
%}
#endif // SWIG
 
 
 
#ifdef SWIG
%feature("docstring") CRcSubscriber "Subscription to any number of resources.\n\n"
  "A subscriber monitors any number of resources. The resources can be\n"
  "specified by their real URIs or alias names. Wildcards as well as\n"
  "presently unkown resources are allowed. Events can be fetched using\n"
  "'Select ()' and 'PollEvent'.\n"
#endif
class CRcSubscriber: public CRcEventProcessor {
  public:
    CRcSubscriber () { resourceList = NULL; }
    CRcSubscriber (const char *_lid) { resourceList = NULL; Register (_lid); }
    virtual ~CRcSubscriber () { Unregister (); }
 
    bool Register (const char *_lid);
    void Unregister ();
 
    const char *Lid () { return lid.Get (); }
    const char *Gid () { return gid.Get (); }
 
    virtual const char *TypeId () { return "S"; }     // hint for Python/SWIG API
    virtual const char *InstId () { return Lid (); }  // hint for Python/SWIG API
 
    const char *ToStr (CString *ret);
 
    bool IsEmpty () { return resourceList == NULL && watchSet.Entries () == 0; }
 
    CResource *AddResource (CResource *rc);
    CResource *AddResources (const char *pattern);
    void DelResource (CResource *rc);
    void DelResources (const char *pattern);
    void Clear ();
 
    CResource *Subscribe (CResource *rc) { return AddResource (rc); }
    CResource *Subscribe (const char *uri) { return AddResources (uri); }
    void Unsubscribe (CResource *rc) { DelResource (rc); }
    void Unsubscribe (const char *pattern) { DelResources (pattern); }
 
#ifndef SWIG
    void GetInfo (CString *ret, int verbosity = 1);
    static void GetInfoAll (CString *ret, int verbosity = 1);
    void GetPatternSet (CKeySet *retPatternSet);
#endif // #ifndef SWIG
    void PrintInfo (FILE *f = stdout, int verbosity = 1);
 
  protected:
    friend class CResource;
    friend class CRcServer;
 
    // Locking...
    void Lock () { mutex.Lock (); } // INFOF (("# Thread #%08x: CRcSubscriber::Lock ()", pthread_self ()));
    void Unlock () { mutex.Unlock (); } // INFOF (("# Thread #08x: CRcSubscriber::Unlock ()", pthread_self ()));
 
    // Notifications from resource...
    void CheckNewResource (CResource *resource);    // check if new resource fits a watch pattern and eventually adds it
    void UnlinkResourceAL (CResource *resource);    // remove a resource and adds its name to the watch set (for temporarilly unregistered resources); Assumes that 'resource' is already locked for us.
    void NotifyAL (CRcEvent *ev) { PutEvent (ev); } // process an event from a resource; caller remains owner of 'ev'
 
    // Interaction with network server...
    void RegisterAsAgent (const char *_gid);
      // Alternative to 'Register' - register as an agent for some other (remote client) host.
    bool IsAgent () { return lid.Get () == gid.Get (); }    // subscriber is an agent
 
    // Static data...
    CString lid, gid;
 
    // Dynamic data (protected by the mutex)...
    CMutex mutex;
    CResourceLink *resourceList;
    CKeySet watchSet;     // contains URI patterns to be checked if new resources are registered
};
 
 
// Python extension...
#ifdef SWIG
%extend CRcSubscriber {
  %newobject __str__ ();
  const char *__str__ () { CString s; $self->ToStr (&s); return s.Disown (); }
  %newobject __repr__ ();
  const char *__repr__ () { CString s, s1; s.SetF ("(CRcSubscriber) %s", $self->ToStr (&s1)); return s.Disown (); }
};  // %extend CRcSubscriber
#endif
 
 
#ifdef SWIG
%pythoncode %{
## @}
%}
#endif // SWIG
 
 
 
 
 
// *************************** Requests ****************************************
 
 
#ifdef SWIG
%pythoncode %{
## @addtogroup resources_requests
## @{
%}
#endif // SWIG
 
 
const char *RcGetUserRequestId ();
const char *RcGetUserRequestAttrs ();
 
 
#ifdef SWIG
%feature("docstring") CRcRequest "Request specifications.\n\n"
  "Request objects define the request for a certain value together with some\n"
  "additional attributes. The concept of requests is introduced to deal with\n"
  "potentially concurrent write accesses to resources. Besides the requested\n"
  "value, a request has the following attributes:\n"
  "  - a unique GID by which it can be later be changed or deleted.\n"
  "  - a priority (see also: comments on the 'prio*' constants)\n"
  "  - a start (on) time (optional)\n"
  "  - an expiration (off) time (optional)\n"
  "  - a hysteresis to avoid too frequent value changes (optional)"
#endif
class CRcRequest {
  public:
    CRcRequest () { Reset (); }   
#ifndef SWIG
    CRcRequest (CRcRequest *req) { Reset (); Set (req); }
    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); }
    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); }
    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); }
    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); }
    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); }
    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); }
#endif // SWIG
 
    ~CRcRequest () {}
 
 
    void Reset ();
 
    void Set (CRcRequest *req);
    void Set (CRcValueState *_value = NULL, const char *_gid = NULL, int _priority = rcPrioNone, TTicks _t0 = NEVER, TTicks _t1 = NEVER, TTicks _repeat = NEVER, TTicks _hysteresis = NEVER);
#ifndef SWIG
    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);
#endif // SWIG
 
    void SetValue (CRcValueState *_value);                                
    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) { gid.Set (_gid); }                    
 
    void SetPriority (int _priority) { priority = _priority; }            
    void SetTimeOn (TTicks _t0) { t0 = _t0; }                             
    void SetTimeOff (TTicks _t1) { t1 = _t1; }                            
    void SetRepeat (TTicks _repeat) { repeat = _repeat; }                 
    void SetHysteresis (TTicks _hysteresis) { hysteresis = _hysteresis; } 
 
    void SetForTrigger ();
 
    void Convert (CResource *rc, bool warn = true);
 
 
    bool IsCompatible () { return isCompatible; }
    const char *Gid () { return gid.Get (); }
    const char *Origin () { return origin.Get (); }
 
    ERcType Type () { return value.Type (); }
    CRcValueState *Value () { return &value; }
    int Priority () { return priority; }
    TTicks TimeOn () { return t0; }
    TTicks TimeOff () { return t1; }
    TTicks Repeat () { return repeat; }
    TTicks Hysteresis () { return hysteresis; }
 
 
 
    bool SetFromStr (const char *str);
 
    bool SetAttrsFromStr (const char *str);
 
    const char *ToStr (CString *ret, bool precise = true, bool tabular = false, TTicks relativeTimeThreshold = NEVER, const char *skipAttrs = CString::emptyStr);
 
 
  protected:
    friend class CResource;
 
    void SetOrigin ();
    bool SetSingleAttrFromStr (const char *str);
 
    // Fields...
    bool isCompatible;
    CString gid, origin;
    CRcValueState value;
    int priority;
    TTicks t0, t1;            // start and end time (NEVER = not set); t0 == t1 => value is set once (and may then stay)
    TTicks repeat;            // repeat interval (ignored, if t0 == 0)
    TTicks hysteresis;        // hysteresis in milliseconds
 
    // Internal fields...
    //   Requests are managed as a linked list associated with a 'CResource' object.
    CRcRequest *next;
};
 
 
// Python extension...
 
#ifdef SWIG
%extend CRcRequest {
 
  %newobject __str__ ();
  const char *__str__ () { CString s; $self->ToStr (&s); return s.Disown (); }
  %newobject __repr__ ();
  const char *__repr__ () { CString s, s1; s.SetF ("(CRcRequest) %s", $self->ToStr (&s1)); return s.Disown (); }
  %pythoncode %{
    pass    # (Workaround to keep SWIG from scrambling the indentation of the following code.)
 
    ## Versatile setter.
    def Set (self, reqDef = None, attrs = None, value = None, id = None, priority = None, t0 = None, t1 = None, repeat = None, hysteresis = None):
      """Set value and/or selected request attributes.\n\
      \n\
      This method allows to set any subset of attributes in a flexible way, either by (named) function arguments\n\
      or by a textual description as accepted by the Home2L Shell or CRcRequest::SetFromStr().\n\
      \n\
      See RcSetRequest() for a detailed explanation of the arguments and examples.\n\
      """
      if reqDef != None:
        if isinstance (reqDef, str):  self.SetFromStr (reqDef)
        elif value == None:           value = reqDef
      if attrs != None: self.SetAttrsFromStr (attrs)
      if value != None: self.SetValue (value)
      if id != None: self.SetGid (id)
      if priority != None: self.SetPriority (priority)
      if t0 != None:
        ticks = TicksAbsOf (t0)
        if ticks: self.SetTimeOn (ticks)
        else: print ("WARNING: Invalid time specification '" + str(t0) + "' - ignoring!")
      if t1 != None:
        ticks = TicksAbsOf (t1)
        if ticks: self.SetTimeOff (ticks)
        else: print ("WARNING: Invalid time specification '" + str(t1) + "' - ignoring!")
      if repeat != None:
        ticks = TicksRelOf (repeat)
        if ticks: self.SetRepeat (ticks)
        else: print ("WARNING: Invalid time specification '" + str(repeat) + "' - ignoring!")
      if hysteresis != None: self.SetHysteresis (hysteresis)
 
  %} // %pythoncode
};  // %extend CRcRequest
#endif
 
 
const char *RcGetUserRequestId ();
const char *RcGetUserRequestAttrs ();
 
 
#ifdef SWIG
%pythoncode %{
## @}
%}
#endif // SWIG
 
 
 
 
 
// *************************** Drivers *****************************************
 
 
#ifdef SWIG
%pythoncode %{
## @addtogroup resources_drivers
## @{
%}
#endif // SWIG
 
 
#ifndef SWIG
 
 
enum ERcDriverOperation {
 
  // For linking in C drivers...
  rcdOpInit = 0,
 
  // Using a base-class 'CRcDriver' object to drive something...
  rcdOpStop,
  rcdOpDriveValue
};
 
 
typedef void FRcDriverFunc (ERcDriverOperation, CRcDriver *, CResource *, CRcValueState *);
 
 
#define HOME2L_DRIVER(NAME) \
  extern "C" { void Home2lRcDriverFunc_##NAME (ERcDriverOperation, CRcDriver *, CResource *, CRcValueState *); } \
  void Home2lRcDriverFunc_##NAME
 
 
class CRcDriver {
  public:
    CRcDriver (const char *_lid, FRcDriverFunc *_func = NULL) { lid.Set (_lid); func = _func; }
    virtual ~CRcDriver () {}
 
    void Register ();
    static void RegisterAndInit (const char *_lid, FRcDriverFunc *_func);
    void Unregister ();
 
    const char *Lid () { return lid.Get (); }
    const char *ToStr (CString *) { return lid.Get (); }
 
    CResource *RegisterResource (const char *rcLid, ERcType _type, bool _writable, void *_data = NULL) { return CResource::Register (this, rcLid, _type, _writable, _data); }
    CResource *RegisterResource (const char *rcLid, const char *rcTypeDef, void *_data = NULL) { return CResource::Register (this, rcLid, rcTypeDef, _data); }
 
    void PrintInfo (FILE *f = stdout);
 
    CResource *GetResource (const char *rcLid) { return resourceMap.Get (rcLid); }
 
    int LockResources () { Lock (); return resourceMap.Entries (); }
    CResource *GetResource (int n) { return resourceMap.Get (n); }
    void UnlockResources () { Unlock (); }
 
  protected:
    friend class CResource;
    friend void RcDriversStop ();
 
    virtual void Stop ();
    virtual void DriveValue (CResource *rc, CRcValueState *vs);
 
    void Lock () { mutex.Lock (); }
    void Unlock () { mutex.Unlock (); }
 
    void ClearResources ();     
 
    // Static data...
    CString lid;
    FRcDriverFunc *func;
 
    // Dynamic data (protected by the mutex)...
    CMutex mutex;
    CDictRef<CResource> resourceMap;   // object does not own the resources; when deleted here, they must be unregistered manually.
};
 
 
#endif // #ifndef SWIG
 
 
#ifdef SWIG
%warnfilter(401) CRcEventDriver;     // class 'CRcDriver' is not known to SWIG
#endif
 
 
class CRcEventDriver: public CRcDriver, public CRcEventProcessor {
  public:
    CRcEventDriver (const char *_lid, ERcState _successState = rcsBusy): CRcDriver (_lid) { successState = _successState; }
 
#ifndef SWIG
    virtual const char *TypeId () { return "D"; }     // hint for Python/SWIG API
    virtual const char *InstId () { return Lid (); }  // hint for Python/SWIG API
 
  protected:
    virtual void Stop () {}   
    virtual void DriveValue (CResource *rc, CRcValueState *vs);
 
    ERcState successState;
#endif
};
 
 
#ifdef SWIG
%pythoncode %{
## @}
%}
#endif // SWIG
 
 
 
 
 
// ************ Directory operations and host/driver/resource lookup ***********
 
 
#ifdef SWIG
%pythoncode %{
## @addtogroup resources_directory
## @{
%}
#endif // SWIG
 
 
 
// ***** Hosts *****
 
 
 
int RcGetHosts ();            
CRcHost *RcGetHost (int n);   
 
CRcHost *RcGetHost (const char *id);      
const char *RcGetHostId (CRcHost *host);  
 
 
#ifndef SWIG
extern CString localHostId;   
#endif
static inline const char *RcLocalHostId () { return localHostId.Get (); }  
#ifdef SWIG
%pythoncode %{
  pass
 
  ## Return a list of all known hosts (including our own one as #0).
  def RcHosts ():
    """Return a list of all known hosts (including our own one as #0)."""
    num = RcGetHosts ()
    ret = [ RcLocalHostId () ]
    for i in range (num):
      ret += [ RcGetHostId (RcGetHost (i)) ]
    return ret
%}
#endif
 
 
 
 
// ***** Drivers (local) *****
 
 
 
int RcGetDrivers ();
CRcDriver *RcGetDriver (int n);
 
CRcDriver *RcGetDriver (const char *lid);
const char *RcGetDriverId (CRcDriver *cur);
 
#ifdef SWIG
%pythoncode %{
  pass
 
  ## Return a list of all locally defined drivers.
  def RcDrivers ():
    """Return a list of all locally defined drivers."""
    num = RcGetDrivers ()
    ret = []
    for i in range (num):
      ret += [ RcGetDriverId (RcGetDriver (i)) ]
    return ret
%}
#endif
 
 
 
 
// ***** Resources *****
 
 
 
int RcLockHostResources (CRcHost *host);
CResource *RcGetHostResource (CRcHost *host, int n);
void RcUnlockHostResources (CRcHost *host);
 
int RcLockDriverResources (CRcDriver *driver);
CResource *RcGetDriverResource (CRcDriver *driver, int n);
void RcUnlockDriverResources (CRcDriver *driver);
 
#ifdef SWIG
%pythoncode %{
  pass
 
  ## Return all known resources of a remote host.
  def RcHostResources (hostName):
    """Return all known resources of a host. '/local' is an alias for the local host ID."""
    ret = []
    if hostName == RcLocalHostId () or hostName == "/local":
      for d in RcDrivers ():
        ret += RcDriverResources (d)
    else:
      h = RcGetHost (hostName)
      num = RcLockHostResources (h)
      for i in range (num):
        ret += [ RcGetHostResource (h, i).Uri () ]
      RcUnlockHostResources (h)
    return ret
 
  ## Return all local resources managed by a driver.
  def RcDriverResources (driverName):
    """Return all local resources managed by a driver."""
    d = RcGetDriver (driverName)
    num = RcLockDriverResources (d)
    ret = []
    for i in range (num):
      ret += [ RcGetDriverResource (d, i).Uri () ]
    RcUnlockDriverResources (d)
    return ret
 
  ## Return a complete list of all known resources.
  def RcResources ():
    """Return a complete list of all known resources."""
    ret = []
    for d in RcDrivers ():
      ret += RcDriverResources (d)
    for h in RcHosts ():
      ret += RcHostResources (h)
    return ret
 
%}
#endif // SWIG
 
 
 
 
// ***** Subscribers *****
 
 
 
#ifndef SWIG
int RcLockSubscribers ();
CRcSubscriber *RcGetSubscriber (int n);
void RcUnlockSubscribers ();
#endif
 
 
 
// Requests and per-resource subscribers: see 'class CResource'
 
 
#ifdef SWIG
%pythoncode %{
## @}
%}
#endif // SWIG
 
 
 
 
 
 
// *************************** High-level API **********************************
 
 
// ***** General functions *****
 
 
#ifdef SWIG
%pythoncode %{
## @addtogroup resources_general
## @{
%}
#endif // SWIG
 
 
#ifndef SWIG
 
 
void RcInit (bool enableServer = false, bool inBackground = false);
void RcStart ();
void RcDone ();
 
 
void RcIterate ();
int RcRun (bool catchSignals = true);
void RcStop ();
 
 
#endif
 
 
 
// ***** Looking up resources *****
 
 
#ifdef SWIG
%pythoncode %{
## @name Accessing resources ...
## @{
%}
#endif // SWIG
 
 
#ifdef SWIG
%feature("docstring") RcGetResource "Lookup a resource by its URI and return a reference to it."
%feature("docstring") RcGet "Lookup a resource by its URI and return a reference to it (shortcut for 'RcGetResource()')."
#endif
 
static inline CResource *RcGetResource (const char *uri, bool allowWait = false) { return CResource::Get (uri, allowWait); }
static inline CResource *RcGet (const char *uri, bool allowWait = false) { return CResource::Get (uri, allowWait); }
 
 
static inline void RcGarbageCollection () { CResource::GarbageCollection (); }
void RcBump (CResource *rc = NULL, bool soft = false);
 
 
#ifdef SWIG
%pythoncode %{
## @}
%}
#endif // SWIG
 
 
 
// ***** Subscriptions *****
 
 
#ifdef SWIG
%pythoncode %{
## @name Subscriptions (from C/C++ API) ...
## Low-level operations to directly create and use @ref CRcSubscriber objects.
## Most probably, you will not need these functions.
## The preferred way in Python is to use the more compfortable decorators and
## operations in section "Subscriptions, events and timers (Python API)" below.
## @{
%}
#endif // SWIG
 
 
#ifdef SWIG
%feature("docstring") RcNewSubscriber "Create and register a new subscriber object, optionally subscribe to resources."
%feature("docstring") RcUnsubscribeFromAll "Unsubscribe to all resources managed by the subscriber."
%newobject RcNewSubscriber (const char *, CResource *);
%newobject RcNewSubscriber (const char *, const char *);
#endif
 
CRcSubscriber *RcNewSubscriber (const char *subscrLid, CResource *rc = NULL);
CRcSubscriber *RcNewSubscriber (const char *subscrLid, const char *pattern);
 
static inline CRcSubscriber *RcSubscribe (CRcSubscriber *subscr, CResource *rc) { subscr->AddResource (rc); return subscr; }
static inline CRcSubscriber *RcSubscribe (CRcSubscriber *subscr, const char *pattern) { subscr->AddResources (pattern); return subscr; }
 
static inline void RcUnsubscribeFromAll (CRcSubscriber *subscr) { subscr->Clear (); }
#ifndef SWIG
static inline void RcUnsubscribeFromAll (CRcSubscriber **pSubscr) { if (*pSubscr) { delete *pSubscr; *pSubscr = NULL; } }
#endif
 
 
#ifdef SWIG
%pythoncode %{
## @}
%}
#endif // SWIG
 
 
 
// ***** Placing requests *****
 
 
#ifdef SWIG
%pythoncode %{
## @name Placing requests ...
## Details on the request arguments can be found in the
## [*C/C++ API documentation*](../home2l-api_c/classCRcRequest.html)
## and the [*Home2L Book*](../home2l-book.pdf).
## @{
%}
#endif // SWIG
 
 
#ifndef SWIG
 
// Requests...
 
static inline void RcSetRequest (CResource *rc, CRcRequest *req) { rc->SetRequest (req); }
void RcSetRequest (const char *rcUri, CRcRequest *req);
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); }
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);
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); }
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);
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); }
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);
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); }
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);
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); }
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);
static inline void RcSetRequestFromStr (CResource *rc, const char *reqDef) { rc->SetRequestFromStr (reqDef); }
void RcSetRequestFromStr (const char *rcUri, const char *reqDef);
 
static inline void RcSetTrigger (CResource *rc, const char *reqGid = NULL, int priority = rcPrioNone, TTicks t0 = NEVER, TTicks repeat = NEVER) { rc->SetTrigger (reqGid, priority, t0, repeat); }
void RcSetTrigger (const char *rcUri, const char *reqGid = NULL, int priority = rcPrioNone, TTicks t0 = NEVER, TTicks repeat = NEVER);
static inline void RcSetTriggerFromStr (CResource *rc, const char *reqDef) { rc->SetTriggerFromStr (reqDef); }
void RcSetTriggerFromStr (const char *rcUri, const char *reqDef);
 
static inline void RcDelRequest (CResource *rc, const char *reqGid = NULL, TTicks t1 = NEVER) { rc->DelRequest (reqGid, t1); }
void RcDelRequest (const char *rcUri, const char *reqGid = NULL, TTicks t1 = NEVER);
 
#else // SWIG
 
%feature("docstring") RcSetRequest "Add or change a request to a resource."
%feature("docstring") RcDelRequest "Delete a request from a resource."
%feature("docstring") RcSetTrigger "Add a trigger request."
 
%pythoncode %{
 
  def RcSetRequest (rc, reqDef = None, attrs = None, value = None, id = None, priority = None, t0 = None, t1 = None, repeat = None, hysteresis = None, delDelay = None):
    """Set a request to a resource with selected attributes.\n\
    \n\
    The attributes can be set in a flexible way, either by (named) function arguments\n\
    or by a textual description as accepted by the Home2L Shell or CRcRequest::SetFromStr().\n\
    \n\
    The parameters have the following meanings:\n\
    \n\
    - reqDef = full definition as a single string '<val> [<attrs>]' or just the value\n\
               Note: To avoid ambiguities, values of type string should never be passed by this,\n\
                     but by the 'value' and 'attrs' arguments instead.\n\
               If 'reqDef' is not a string instance, it is used as a value ('val').\n\
    - attrs  = attribute string (similar to 'reqDef', but without the first field interpreted as value)\n\
    \n\
    - value      = value (any type or string)\n\
    - id         = request ID [default = instance name]\n\
    - priority   = request priority (0..9) [default = 3 (= rcPrioNormal)]\n\
    - t0         = on time\n\
    - t1         = off time\n\
    - repeat     = repetition interval\n\
    - hysteresis = hysteresis time\n\
    - delDelay   = deletion delay (if no value is passed and the call is used to delete the request)\n\
    \n\
    Information on the syntax of textual request definition can be found in the Home2L Book and\n\
    in the C/C++ API documentation for CRcRequest::SetFromStr(). Arguments representing absolute times\n\
    (e.g. 't0', 't1') can have any type and format as accepted by 'TicksAbsOf()'.\n\
    Arguments representing relative times (e.g. 'repeat', 'hysteresis', 'delDelay') can have any type\n\
    and format as accepted by 'TicksRelOf()'.\n\
    \n\
    If an attribute is set both by means of a string ('reqDef' or 'attrs') or a named parameter,\n\
    the named parameter is taken. If no attributes are specified, their defaults as specified in [...]\n\
    above are used.\n\
    \n\
    If the effective value is 'None' (no value is passed), the call will delete the request with\n\
    the specified ID passing 'delDelay' as the the 't1' argument of RcDelRequest().\n\
    \n\
    Examples:\n\
    \n\
    - Request integer value 7 with default attributes:\n\
        RcSetRequest (rc, 7);\n\
        RcSetRequest (rc, '7');\n\
        RcSetRequest (rc, value = '7');\n\
        RcSetRequest (rc, reqDef = '7');\n\
    \n\
    - Request integer value 7 with ID '#user' and priority 3:\n\
        RcSetRequest (rc, 7, id = 'user', priority = 3);\n\
        RcSetRequest (rc, 7, '#user *3');\n\
        RcSetRequest (rc, '7 #user *3');\n\
    \n\
    - Delete this request again:\n\
        RcSetRequest (rc, value = None, id = 'user');\n\
        RcSetRequest (rc, '? #user');\n\
    \n\
    - Delete this request in 5 seconds:\n\
        RcSetRequest (rc, value = None, id = 'user', delDelay = '5s');\n\
    \n\
    - Request string value 'Hello *3' with priority 5 and an off time at 6pm today:\n\
        RcSetRequest (rc, value = 'Hello *3', attrs = '*5 -18:00');\n\
        RcSetRequest (rc, value = 'Hello *3', priority = 5, t1 = '-18:00');\n\
    \n\
    - Set request with user-supplied attributes, some of which must not be changed by user\n\
        RcSetRequest (rc, 7, userAttrs, t1 = '-23:00')    # t1 overrides an eventual off time in userAttrs\n\
    \n\
    - Set request with user-supplied attributes and defaults\n\
        req = CRcRequest (val = 7, t1 = '-23:00')       # Set value and default attributes\n\
        req->Set (attrs = userAttrs)     # userAttrs may override t1\n\
    \n\
    """
    if isinstance (rc, str): rc = RcGetResource (rc)
    rc.SetRequest (reqDef = reqDef, attrs = attrs, value = value, id = id, priority = priority, t0 = t0, t1 = t1, repeat = repeat, hysteresis = hysteresis, delDelay = delDelay)
 
  def RcSetTrigger (rc, attrs = None, id = None, priority = None, t0 = None, t1 = None, repeat = None, hysteresis = None):
    """Set a request to a trigger resource with selected attributes."""
    if isinstance (rc, str): rc = RcGetResource (rc)
    rc.SetRequest (attrs = attrs, value = 1, id = id, priority = priority, t0 = t0, t1 = t1, repeat = repeat, hysteresis = hysteresis)
 
  def RcDelRequest (rc, id = None, t1 = None):
    """Delete a request."""
    if isinstance (rc, str): rc = RcGetResource (rc)
    rc.DelRequest (id, t1)
 
  def RcSetDefault (rc, reqDef = None, attrs = None, value = None, t0 = None, t1 = None, repeat = None, hysteresis = None, delDelay = None):
    """Set a default request."""
    if isinstance (rc, str): rc = RcGetResource (rc)
    rc.SetRequest (reqDef = reqDef, attrs = attrs, value = value, id = rcDefaultRequestId, priority = rcPrioDefault, t0 = t0, t1 = t1, repeat = repeat, hysteresis = hysteresis)
 
%} // %pythoncode
#endif // SWIG
 
 
 
// Mutex operations (TBD:future) ...
//~ static inline CRcSubscriber *RcMutexRequestLock (const char *rcUri, const char *regGid, CRcSubscriber *subscr == NULL) { RcSetRequest (rcUri, reqGid, reqGid); return subscr; }
//~ void RcMutexWaitLock (const char *rcUri, const char *regGid, CRcSubscriber *subscr);
//~ bool RcMutexPollLock (const char *rcUri, const char *regGid, CRcSubscriber *subscr);
//~ void RcMutexUnlock (const char *rcUri, const char *regGid, CRcSubscriber *subscr);
 
 
#ifdef SWIG
%pythoncode %{
## @}
%}
#endif // SWIG
 
 
 
// ***** Drivers *****
 
 
#ifdef SWIG
%pythoncode %{
## @name Drivers (from C/C++ API) ...
## Low-level operations to directly create and use 'CRcDriver' objects.
## Most probably, you will not need these functions.
## The preferred way in Python is to use the more compfortable decorators and
## operations in module "Home2L / Drivers".
## @{
%}
#endif // SWIG
 
 
 
#ifdef SWIG
%feature("docstring") RcRegisterDriver "Register a new driver."
%feature("docstring") RcRegisterResource "Register a new resource to a driver."
%feature("docstring") RcRegisterSignal "Register a new signal for the built-in 'signal' driver."
#endif
 
#ifndef SWIG
static inline void RcRegisterDriver (CRcDriver *drv) { drv->Register (); }
static inline void RcRegisterDriver (const char *drvLid, FRcDriverFunc *func) { CRcDriver::RegisterAndInit (drvLid, func); }
#endif
CRcEventDriver *RcRegisterDriver (const char *drvLid, ERcState _successState = rcsNoReport);
 
#ifndef SWIG
static inline CResource *RcRegisterResource (CRcDriver *drv, const char *rcLid, ERcType _type, bool _writable, void *_data = NULL) { return CResource::Register (drv, rcLid, _type, _writable, _data); }
static inline CResource *RcRegisterResource (CRcDriver *drv, const char *rcLid, const char *rcTypeDef, void *_data = NULL) { return CResource::Register (drv, rcLid, rcTypeDef, _data); }
#endif
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);
CResource *RcRegisterSignal (const char *name, CRcValueState *vs);
 
 
#ifdef SWIG
%pythoncode %{
## @}
%}
#endif // SWIG
 
 
 
 
// ***** Executing shell commands *****
 
// TBD
 
 
 
 
#ifdef SWIG
%pythoncode %{
## @}
%}
#endif // SWIG
 
 
 
 
 
 
// ***** Doxygen Footer *****
 
#ifdef SWIG
%pythoncode %{
## @}
%}
#endif // SWIG
 
 
 
#endif // _RC_LIB_