Public Member Functions | Static Public Member Functions | Static Public Attributes | Protected Member Functions | Static Protected Member Functions | Protected Attributes | Static Protected Attributes | Friends | List of all members
YFunction Class Reference

#include <yocto_api.h>

Inheritance diagram for YFunction:
Inheritance graph
[legend]

Public Member Functions

void _clearDataStreamCache ()
 
string _decode_json_string (const string &json)
 
string _download (const string &url)
 
YDataStream_findDataStream (YDataSet &dataset, const string &def)
 
string _get_json_path (const string &json, const string &path)
 
virtual int _invokeValueCallback (string value)
 
vector< string > _json_get_array (const string &json)
 
string _json_get_key (const string &json, const string &data)
 
string _json_get_string (const string &json)
 
int _parseEx (yJsonStateMachine &j)
 
virtual int _parserHelper (void)
 
string _parseString (yJsonStateMachine &j)
 
string _request (const string &request)
 
string _requestEx (int tcpchan, const string &request, yapiRequestProgressCallback callback, void *context)
 
void _throw (YRETCODE errType, string errMsg)
 
YRETCODE _upload (const string &path, const string &content)
 
YRETCODE _uploadWithProgress (const string &path, const string &content, yapiRequestProgressCallback callback, void *context)
 
string advertisedValue (void)
 
void clearCache ()
 
string describe (void)
 
string errMessage (void)
 
string errorMessage (void)
 
YRETCODE errorType (void)
 
YRETCODE errType (void)
 
YFUN_DESCR functionDescriptor (void)
 
string get_advertisedValue (void)
 
string get_errorMessage (void)
 
YRETCODE get_errorType (void)
 
virtual string get_friendlyName (void)
 
YFUN_DESCR get_functionDescriptor (void)
 
string get_functionId (void)
 
string get_hardwareId (void)
 
string get_hubSerial ()
 
string get_logicalName (void)
 
YModuleget_module (void)
 
void * get_userData (void)
 
bool isOnline (void)
 
YRETCODE load (int msValidity)
 
virtual string loadAttribute (string attrName)
 
string logicalName (void)
 
YModulemodule (void)
 
virtual int muteValueCallbacks (void)
 
YFunctionnext (void)
 
YFunctionnextFunction (void)
 
virtual int registerValueCallback (YFunctionValueCallback callback)
 
int set_advertisedValue (const string &newval)
 
int set_logicalName (const string &newval)
 
void set_userData (void *data)
 
int setAdvertisedValue (const string &newval)
 
int setLogicalName (const string &newval)
 
void setUserData (void *data)
 
virtual int unmuteValueCallbacks (void)
 
void * userData (void)
 
virtual ~YFunction ()
 

Static Public Member Functions

static void _ClearCache (void)
 
static YFunctionFind (string func)
 
static YFunctionFindFunction (string func)
 
static YFunctionFirst (void)
 
static YFunctionFirstFunction (void)
 

Static Public Attributes

static const string ADVERTISEDVALUE_INVALID = YAPI_INVALID_STRING
 
static const string FRIENDLYNAME_INVALID = YAPI_INVALID_STRING
 
static const YFUN_DESCR FUNCTIONDESCRIPTOR_INVALID = Y_FUNCTIONDESCRIPTOR_INVALID
 
static const string FUNCTIONID_INVALID = YAPI_INVALID_STRING
 
static const string HARDWAREID_INVALID = YAPI_INVALID_STRING
 
static const string LOGICALNAME_INVALID = YAPI_INVALID_STRING
 

Protected Member Functions

YRETCODE _buildSetRequest (const string &changeattr, const string *changeval, string &request, string &errmsg)
 
string _escapeAttr (const string &changeval)
 
YRETCODE _getDescriptor (YFUN_DESCR &fundescr, string &errMsg)
 
YRETCODE _getDevice (YDevice *&dev, string &errMsg)
 
YRETCODE _load_unsafe (int msValidity)
 
YRETCODE _nextFunction (string &hwId)
 
int _parse (YJSONObject *j)
 
virtual int _parseAttr (YJSONObject *json_val)
 
YRETCODE _setAttr (string attrname, string newvalue)
 
 YFunction (const string &func)
 

Static Protected Member Functions

static void _AddToCache (const string &classname, const string &func, YFunction *obj)
 
static YFunction_FindFromCache (const string &classname, const string &func)
 
static void _UpdateTimedReportCallbackList (YFunction *func, bool add)
 
static void _UpdateValueCallbackList (YFunction *func, bool add)
 

Protected Attributes

string _advertisedValue
 
u64 _cacheExpiration
 
string _className
 
std::map< string, YDataStream * > _dataStreams
 
string _func
 
YFUN_DESCR _fundescr
 
string _funId
 
string _hwId
 
string _lastErrorMsg
 
YRETCODE _lastErrorType
 
string _logicalName
 
string _serial
 
yCRITICAL_SECTION _this_cs
 
void * _userData
 
YFunctionValueCallback _valueCallbackFunction
 

Static Protected Attributes

static std::map< string, YFunction * > _cache
 

Friends

YFunctionyFindFunction (const string &func)
 
YFunctionyFirstFunction (void)
 

Detailed Description

YFunction Class: Common function interface

This is the parent class for all public objects representing device functions documented in the high-level programming API. This abstract class does all the real job, but without knowledge of the specific function attributes.

Instantiating a child class of YFunction does not cause any communication. The instance simply keeps track of its function identifier, and will dynamically bind to a matching device at the time it is really being used to read or set an attribute. In order to allow true hot-plug replacement of one device by another, the binding stay dynamic through the life of the object.

The YFunction class implements a generic high-level cache for the attribute values of the specified function, pre-parsed from the REST API string.

Definition at line 1551 of file yocto_api.h.

Constructor & Destructor Documentation

YFunction::YFunction ( const string &  func)
protected

Definition at line 2313 of file yocto_api.cpp.

YFunction::~YFunction ( )
virtual

Definition at line 2328 of file yocto_api.cpp.

Member Function Documentation

void YFunction::_AddToCache ( const string &  classname,
const string &  func,
YFunction obj 
)
staticprotected

Definition at line 2345 of file yocto_api.cpp.

YRETCODE YFunction::_buildSetRequest ( const string &  changeattr,
const string *  changeval,
string &  request,
string &  errmsg 
)
protected

Definition at line 2919 of file yocto_api.cpp.

void YFunction::_ClearCache ( void  )
static

Definition at line 2350 of file yocto_api.cpp.

void YFunction::_clearDataStreamCache ( )

Definition at line 3117 of file yocto_api.cpp.

string YFunction::_decode_json_string ( const string &  json)

Definition at line 2871 of file yocto_api.cpp.

string YFunction::_download ( const string &  url)

Definition at line 3053 of file yocto_api.cpp.

string YFunction::_escapeAttr ( const string &  changeval)
protected

Definition at line 2891 of file yocto_api.cpp.

YDataStream * YFunction::_findDataStream ( YDataSet dataset,
const string &  def 
)

Definition at line 3105 of file yocto_api.cpp.

YFunction * YFunction::_FindFromCache ( const string &  classname,
const string &  func 
)
staticprotected

Definition at line 2338 of file yocto_api.cpp.

string YFunction::_get_json_path ( const string &  json,
const string &  path 
)

Definition at line 2852 of file yocto_api.cpp.

YRETCODE YFunction::_getDescriptor ( YFUN_DESCR fundescr,
string &  errMsg 
)
protected

Definition at line 2667 of file yocto_api.cpp.

YRETCODE YFunction::_getDevice ( YDevice *&  dev,
string &  errMsg 
)
protected

Definition at line 2688 of file yocto_api.cpp.

int YFunction::_invokeValueCallback ( string  value)
virtual
vector< string > YFunction::_json_get_array ( const string &  json)

Definition at line 2811 of file yocto_api.cpp.

string YFunction::_json_get_key ( const string &  json,
const string &  data 
)

Definition at line 2772 of file yocto_api.cpp.

string YFunction::_json_get_string ( const string &  json)

Definition at line 2798 of file yocto_api.cpp.

YRETCODE YFunction::_load_unsafe ( int  msValidity)
protected

Definition at line 3327 of file yocto_api.cpp.

YRETCODE YFunction::_nextFunction ( string &  hwId)
protected

Definition at line 2709 of file yocto_api.cpp.

int YFunction::_parse ( YJSONObject j)
protected

Definition at line 2960 of file yocto_api.cpp.

int YFunction::_parseAttr ( YJSONObject json_val)
protectedvirtual
int YFunction::_parseEx ( yJsonStateMachine j)
int YFunction::_parserHelper ( void  )
virtual

Reimplemented in YSensor.

Definition at line 2622 of file yocto_api.cpp.

string YFunction::_parseString ( yJsonStateMachine j)

Definition at line 2742 of file yocto_api.cpp.

string YFunction::_request ( const string &  request)

Definition at line 3046 of file yocto_api.cpp.

string YFunction::_requestEx ( int  tcpchan,
const string &  request,
yapiRequestProgressCallback  callback,
void *  context 
)

Definition at line 3010 of file yocto_api.cpp.

YRETCODE YFunction::_setAttr ( string  attrname,
string  newvalue 
)
protected

Definition at line 2968 of file yocto_api.cpp.

void YFunction::_throw ( YRETCODE  errType,
string  errMsg 
)

Definition at line 2656 of file yocto_api.cpp.

void YFunction::_UpdateTimedReportCallbackList ( YFunction func,
bool  add 
)
staticprotected

Definition at line 3531 of file yocto_api.cpp.

void YFunction::_UpdateValueCallbackList ( YFunction func,
bool  add 
)
staticprotected

Definition at line 3509 of file yocto_api.cpp.

YRETCODE YFunction::_upload ( const string &  path,
const string &  content 
)

Definition at line 3098 of file yocto_api.cpp.

YRETCODE YFunction::_uploadWithProgress ( const string &  path,
const string &  content,
yapiRequestProgressCallback  callback,
void *  context 
)

Definition at line 3071 of file yocto_api.cpp.

string YFunction::advertisedValue ( void  )
inline

Definition at line 1701 of file yocto_api.h.

void YFunction::clearCache ( )

Invalidates the cache. Invalidates the cache of the function attributes. Forces the next call to get_xxx() or loadxxx() to use values that come from the device.

Definition at line 3412 of file yocto_api.cpp.

string YFunction::describe ( void  )

Returns a short text that describes unambiguously the instance of the function in the form TYPE(NAME)=SERIAL&#46;FUNCTIONID. More precisely, TYPE is the type of the function, NAME it the name used for the first access to the function, SERIAL is the serial number of the module if the module is connected or "unresolved", and FUNCTIONID is the hardware identifier of the function if the module is connected. For example, this method returns Relay(MyCustomName.relay1)=RELAYLO1-123456.relay1 if the module is already connected or Relay(BadCustomeName.relay1)=unresolved if the module has not yet been connected. This method does not trigger any USB or TCP transaction and can therefore be used in a debugger.

Returns
a string that describes the function (ex: Relay(MyCustomName.relay1)=RELAYLO1-123456.relay1)

Definition at line 3131 of file yocto_api.cpp.

string YFunction::errMessage ( void  )
inline

Definition at line 1893 of file yocto_api.h.

string YFunction::errorMessage ( void  )
inline

Definition at line 1891 of file yocto_api.h.

YRETCODE YFunction::errorType ( void  )
inline

Definition at line 1877 of file yocto_api.h.

YRETCODE YFunction::errType ( void  )
inline

Definition at line 1879 of file yocto_api.h.

static YFunction* YFunction::Find ( string  func)
inlinestatic

Definition at line 1792 of file yocto_api.h.

YFunction * YFunction::FindFunction ( string  func)
static

Retrieves a function for a given identifier. The identifier can be specified using several formats:

  • FunctionLogicalName
  • ModuleSerialNumber.FunctionIdentifier
  • ModuleSerialNumber.FunctionLogicalName
  • ModuleLogicalName.FunctionIdentifier
  • ModuleLogicalName.FunctionLogicalName

This function does not require that the function is online at the time it is invoked. The returned object is nevertheless valid. Use the method YFunction.isOnline() to test if the function is indeed online at a given time. In case of ambiguity when looking for a function by logical name, no error is notified: the first instance found is returned. The search is performed first by hardware name, then by logical name.

If a call to this object's is_online() method returns FALSE although you are certain that the matching device is plugged, make sure that you did call registerHub() at application initialization time.

Parameters
func: a string that uniquely characterizes the function
Returns
a YFunction object allowing you to drive the function.

Definition at line 2512 of file yocto_api.cpp.

static YFunction* YFunction::First ( void  )
inlinestatic

Definition at line 1806 of file yocto_api.h.

YFunction * YFunction::FirstFunction ( void  )
static

comment from .yc definition

Definition at line 2637 of file yocto_api.cpp.

YFUN_DESCR YFunction::functionDescriptor ( void  )
inline

Definition at line 1952 of file yocto_api.h.

string YFunction::get_advertisedValue ( void  )

Returns a short string representing the current state of the function.

Returns
a string corresponding to a short string representing the current state of the function

On failure, throws an exception or returns Y_ADVERTISEDVALUE_INVALID.

Definition at line 2447 of file yocto_api.cpp.

string YFunction::get_errorMessage ( void  )

Returns the error message of the latest error with the function. This method is mostly useful when using the Yoctopuce library with exceptions disabled.

Returns
a string corresponding to the latest error message that occured while using the function object

Definition at line 3277 of file yocto_api.cpp.

YRETCODE YFunction::get_errorType ( void  )

Returns the numerical error code of the latest error with the function. This method is mostly useful when using the Yoctopuce library with exceptions disabled.

Returns
a number corresponding to the code of the latest error that occurred while using the function object

Definition at line 3264 of file yocto_api.cpp.

string YFunction::get_friendlyName ( void  )
virtual

Returns a global identifier of the function in the format MODULE_NAME&#46;FUNCTION_NAME. The returned string uses the logical names of the module and of the function if they are defined, otherwise the serial number of the module and the hardware identifier of the function (for example: MyCustomName.relay1)

Returns
a string that uniquely identifies the function using logical names (ex: MyCustomName.relay1)

On failure, throws an exception or returns Y_FRIENDLYNAME_INVALID.

Reimplemented in YModule.

Definition at line 3151 of file yocto_api.cpp.

YFUN_DESCR YFunction::get_functionDescriptor ( void  )

Returns a unique identifier of type YFUN_DESCR corresponding to the function. This identifier can be used to test if two instances of YFunction reference the same physical function on the same physical device.

Returns
an identifier of type YFUN_DESCR.

If the function has never been contacted, the returned value is Y_FUNCTIONDESCRIPTOR_INVALID.

Definition at line 3503 of file yocto_api.cpp.

string YFunction::get_functionId ( void  )

Returns the hardware identifier of the function, without reference to the module. For example relay1

Returns
a string that identifies the function (ex: relay1)

On failure, throws an exception or returns Y_FUNCTIONID_INVALID.

Definition at line 3229 of file yocto_api.cpp.

string YFunction::get_hardwareId ( void  )

Returns the unique hardware identifier of the function in the form SERIAL.FUNCTIONID. The unique hardware identifier is composed of the device serial number and of the hardware identifier of the function (for example RELAYLO1-123456.relay1).

Returns
a string that uniquely identifies the function (ex: RELAYLO1-123456.relay1)

On failure, throws an exception or returns Y_HARDWAREID_INVALID.

Definition at line 3194 of file yocto_api.cpp.

string YFunction::get_hubSerial ( )
string YFunction::get_logicalName ( void  )

Returns the logical name of the function.

Returns
a string corresponding to the logical name of the function

On failure, throws an exception or returns Y_LOGICALNAME_INVALID.

Definition at line 2386 of file yocto_api.cpp.

YModule * YFunction::get_module ( void  )

Gets the YModule object for the device on which the function is located. If the function cannot be located on any module, the returned instance of YModule is not shown as on-line.

Returns
an instance of YModule

Definition at line 3440 of file yocto_api.cpp.

void * YFunction::get_userData ( void  )

Returns the value of the userData attribute, as previously stored using method set_userData. This attribute is never touched directly by the API, and is at disposal of the caller to store a context.

Returns
the object stored previously by the caller.

Definition at line 3469 of file yocto_api.cpp.

bool YFunction::isOnline ( void  )

Checks if the function is currently reachable, without raising any error. If there is a cached value for the function in cache, that has not yet expired, the device is considered reachable. No exception is raised if there is an error while trying to contact the device hosting the function.

Returns
true if the function can be reached, and false otherwise

Definition at line 3291 of file yocto_api.cpp.

YRETCODE YFunction::load ( int  msValidity)

Preloads the function cache with a specified validity duration. By default, whenever accessing a device, all function attributes are kept in cache for the standard duration (5 ms). This method can be used to temporarily mark the cache as valid for a longer period, in order to reduce network traffic for instance.

Parameters
msValidity: an integer corresponding to the validity attributed to the loaded function parameters, in milliseconds
Returns
YAPI_SUCCESS when the call succeeds.

On failure, throws an exception or returns a negative error code.

Definition at line 3391 of file yocto_api.cpp.

string YFunction::loadAttribute ( string  attrName)
virtual

Returns the current value of a single function attribute, as a text string, as quickly as possible but without using the cached value.

Parameters
attrName: the name of the requested attribute
Returns
a string with the value of the the attribute

On failure, throws an exception or returns an empty string.

Definition at line 2613 of file yocto_api.cpp.

string YFunction::logicalName ( void  )
inline

Definition at line 1673 of file yocto_api.h.

YModule* YFunction::module ( void  )
inline

Definition at line 1939 of file yocto_api.h.

int YFunction::muteValueCallbacks ( void  )
virtual

Disables the propagation of every new advertised value to the parent hub. You can use this function to save bandwidth and CPU on computers with limited resources, or to prevent unwanted invocations of the HTTP callback. Remember to call the saveToFlash() method of the module if the modification must be kept.

Returns
YAPI_SUCCESS when the call succeeds.

On failure, throws an exception or returns a negative error code.

Definition at line 2583 of file yocto_api.cpp.

YFunction* YFunction::next ( void  )
inline

Definition at line 1799 of file yocto_api.h.

YFunction * YFunction::nextFunction ( void  )

comment from .yc definition

Definition at line 2627 of file yocto_api.cpp.

int YFunction::registerValueCallback ( YFunctionValueCallback  callback)
virtual

Registers the callback function that is invoked on every change of advertised value. The callback is invoked only during the execution of ySleep or yHandleEvents. This provides control over the time when the callback is triggered. For good responsiveness, remember to call one of these two functions periodically. To unregister a callback, pass a NULL pointer as argument.

Parameters
callback: the callback function to call, or a NULL pointer. The callback function should take two arguments: the function object of which the value has changed, and the character string describing the new advertised value.

Definition at line 2544 of file yocto_api.cpp.

int YFunction::set_advertisedValue ( const string &  newval)

Definition at line 2469 of file yocto_api.cpp.

int YFunction::set_logicalName ( const string &  newval)

Changes the logical name of the function. You can use yCheckLogicalName() prior to this call to make sure that your parameter is valid. Remember to call the saveToFlash() method of the module if the modification must be kept.

Parameters
newval: a string corresponding to the logical name of the function
Returns
YAPI_SUCCESS if the call succeeds.

On failure, throws an exception or returns a negative error code.

Definition at line 2420 of file yocto_api.cpp.

void YFunction::set_userData ( void *  data)

Stores a user context provided as argument in the userData attribute of the function. This attribute is never touched by the API, and is at disposal of the caller to store a context.

Parameters
data: any kind of object to be stored

Definition at line 3486 of file yocto_api.cpp.

int YFunction::setAdvertisedValue ( const string &  newval)
inline

Definition at line 1705 of file yocto_api.h.

int YFunction::setLogicalName ( const string &  newval)
inline

Definition at line 1689 of file yocto_api.h.

void YFunction::setUserData ( void *  data)
inline

Definition at line 1975 of file yocto_api.h.

int YFunction::unmuteValueCallbacks ( void  )
virtual

Re-enables the propagation of every new advertised value to the parent hub. This function reverts the effect of a previous call to muteValueCallbacks(). Remember to call the saveToFlash() method of the module if the modification must be kept.

Returns
YAPI_SUCCESS when the call succeeds.

On failure, throws an exception or returns a negative error code.

Definition at line 2598 of file yocto_api.cpp.

void* YFunction::userData ( void  )
inline

Definition at line 1964 of file yocto_api.h.

Friends And Related Function Documentation

YFunction* yFindFunction ( const string &  func)
friend
YFunction* yFirstFunction ( void  )
friend

Member Data Documentation

string YFunction::_advertisedValue
protected

Definition at line 1569 of file yocto_api.h.

std::map< string, YFunction * > YFunction::_cache
staticprotected

Definition at line 1585 of file yocto_api.h.

u64 YFunction::_cacheExpiration
protected

Definition at line 1571 of file yocto_api.h.

string YFunction::_className
protected

Definition at line 1558 of file yocto_api.h.

std::map<string,YDataStream*> YFunction::_dataStreams
protected

Definition at line 1564 of file yocto_api.h.

string YFunction::_func
protected

Definition at line 1559 of file yocto_api.h.

YFUN_DESCR YFunction::_fundescr
protected

Definition at line 1562 of file yocto_api.h.

string YFunction::_funId
protected

Definition at line 1573 of file yocto_api.h.

string YFunction::_hwId
protected

Definition at line 1574 of file yocto_api.h.

string YFunction::_lastErrorMsg
protected

Definition at line 1561 of file yocto_api.h.

YRETCODE YFunction::_lastErrorType
protected

Definition at line 1560 of file yocto_api.h.

string YFunction::_logicalName
protected

Definition at line 1568 of file yocto_api.h.

string YFunction::_serial
protected

Definition at line 1572 of file yocto_api.h.

yCRITICAL_SECTION YFunction::_this_cs
protected

Definition at line 1563 of file yocto_api.h.

void* YFunction::_userData
protected

Definition at line 1565 of file yocto_api.h.

YFunctionValueCallback YFunction::_valueCallbackFunction
protected

Definition at line 1570 of file yocto_api.h.

const string YFunction::ADVERTISEDVALUE_INVALID = YAPI_INVALID_STRING
static

Definition at line 1662 of file yocto_api.h.

const string YFunction::FRIENDLYNAME_INVALID = YAPI_INVALID_STRING
static

Definition at line 1652 of file yocto_api.h.

const YFUN_DESCR YFunction::FUNCTIONDESCRIPTOR_INVALID = Y_FUNCTIONDESCRIPTOR_INVALID
static

Definition at line 1649 of file yocto_api.h.

const string YFunction::FUNCTIONID_INVALID = YAPI_INVALID_STRING
static

Definition at line 1651 of file yocto_api.h.

const string YFunction::HARDWAREID_INVALID = YAPI_INVALID_STRING
static

Definition at line 1650 of file yocto_api.h.

const string YFunction::LOGICALNAME_INVALID = YAPI_INVALID_STRING
static

Definition at line 1661 of file yocto_api.h.


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


yoctopuce_altimeter
Author(s): Anja Sheppard
autogenerated on Mon Jun 10 2019 15:49:13