Tango Core Classes Reference
9.3.4
|
Easy to use interface to Tango device attribute. More...
#include "tango.h"
Public Member Functions | |
Constructors | |
AttributeProxy (string &name) | |
Create a AttributeProxy object. More... | |
AttributeProxy (const char *name) | |
Create a AttributeProxy object. More... | |
Miscellaneous methods | |
virtual string | name () |
Get attribute name. More... | |
virtual DeviceProxy * | get_device_proxy () |
Get associated DeviceProxy instance. More... | |
virtual string | status () |
Get device status. More... | |
virtual DevState | state () |
Get device state. More... | |
virtual int | ping () |
Ping the device. More... | |
Synchronous methods | |
virtual AttributeInfoEx | get_config () |
Get attribute configuration. More... | |
virtual void | set_config (AttributeInfo &ai) |
Set attribute configuration. More... | |
virtual void | set_config (AttributeInfoEx &ai) |
Set extended attribute configuration. More... | |
virtual DeviceAttribute | read () |
Read attribute value. More... | |
virtual void | write (DeviceAttribute &da) |
Write attribute value. More... | |
virtual DeviceAttribute | write_read (DeviceAttribute &da) |
Write the Read attribute value. More... | |
virtual vector< DeviceAttributeHistory > * | history (int depth) |
Get attribute history from polling buffer. More... | |
Asynchronous methods | |
virtual long | read_asynch () |
Read attribute value asynchronously in polling model. More... | |
virtual DeviceAttribute * | read_reply (long id) |
Get asynchronous read attribute call reply. More... | |
virtual DeviceAttribute * | read_reply (long id, long to) |
Get asynchronous read attribute call reply with timeout. More... | |
virtual long | write_asynch (DeviceAttribute &da) |
Write attribute value asynchrnously in polling model. More... | |
virtual void | write_reply (long id) |
Get asynchronous write attribute call reply. More... | |
virtual void | write_reply (long id, long to) |
Get asynchronous write attribute call reply with timeout. More... | |
virtual void | read_asynch (CallBack &cb) |
Read attribute asynchronously in callback model. More... | |
virtual void | write_asynch (DeviceAttribute &da, CallBack &cb) |
Write attribute asynchronously in callback model. More... | |
Polling related methods | |
virtual bool | is_polled () |
Check if the attribute is polled. More... | |
virtual int | get_poll_period () |
Get attribute polling period. More... | |
virtual void | poll (int period) |
Set attribute polling period. More... | |
virtual void | stop_poll () |
Stop attribute polling. More... | |
Event related methods | |
virtual int | subscribe_event (EventType event, CallBack *cb) |
Subscribe to attribute event. More... | |
virtual int | subscribe_event (EventType event, CallBack *cb, bool stateless) |
Stateless subscription to attribute event. More... | |
virtual int | subscribe_event (EventType event, int event_queue_size, bool stateless=false) |
Stateless subscription to attribute event with event queue. More... | |
virtual void | unsubscribe_event (int ev_id) |
Unsubsribe to attribute event. More... | |
virtual void | get_events (int event_id, CallBack *cb) |
Get events from event queue (pull model) More... | |
virtual void | get_events (int event_id, EventDataList &event_list) |
Get events from event queue (pull model) More... | |
virtual void | get_events (int event_id, AttrConfEventDataList &event_list) |
Get events from event queue (pull model) More... | |
virtual int | event_queue_size (int event_id) |
Get events number in queue. More... | |
virtual TimeVal | get_last_event_date (int event_id) |
Get last event date. More... | |
virtual bool | is_event_queue_empty (int event_id) |
Check if the event queue is empty. More... | |
Property related methods | |
virtual void | get_property (string &prop_name, DbData &db) |
Get single attribute property. More... | |
virtual void | get_property (vector< string > &prop_names, DbData &db) |
Get multiple attribute property. More... | |
virtual void | get_property (DbData &db) |
Get attribute property(ies) More... | |
virtual void | put_property (DbData &db) |
Put attribute property(ies) More... | |
virtual void | delete_property (string &prop_name) |
Delete a single attribute property. More... | |
virtual void | delete_property (vector< string > &prop_names) |
Delete a list of attribute property. More... | |
virtual void | delete_property (DbData &db) |
Delete attribute property(ies) More... | |
Easy to use interface to Tango device attribute.
The high level object which provides the client with an easy-to-use interface to TANGO device attributes. AttributeProxy is a handle to the real attribute (hence the name Proxy) and is not the real attribute (of course). The AttributeProxy manages timeouts, stateless connections (new AttributeProxy() nearly always works), and reconnection if the device server is restarted.
AttributeProxy::AttributeProxy | ( | string & | name | ) |
Create a AttributeProxy object.
Create an AttributeProxy to an attribute of the specified name. The constructor will connect to the TANGO database, query for the device to which the attribute belongs to network address and build a connection to this device. If the device to which the attribute belongs to is defined in the TANGO database but the device server is not running, AttributeProxy will try to build a connection every time the client tries to access the attribute. If an alias name is defined for the attribute, this alias name can be used to create the AttributeProxy instance. If a device name alias is defined for the device, it can be used instead of the three fields device name. If the device to which the attribute belongs to is not defined in the database, an exception is thrown. Examples :
[in] | name | The attribute name |
AttributeProxy::AttributeProxy | ( | const char * | name | ) |
|
virtual |
Delete attribute property(ies)
Delete property(ies) for an attribute. Properties to delete are specified using the DbData type. Refer to DbDevice::get_property() and DbData sections for details.
[in] | db | The properties name |
NonDbDevice,ConnectionFailed,CommunicationFailed,DevFailed | from database |
|
virtual |
Delete a single attribute property.
Delete a single property for an attribute. The property to delete is specified as a string. Refer to DbDevice:: delete_property() and DbData sections for details on the DbData type.
[in] | prop_name | The property name |
NonDbDevice,ConnectionFailed,CommunicationFailed,DevFailed | from database |
|
virtual |
Delete a list of attribute property.
Delete a list of properties for an attribute. The properties to delete are specified as a vector of strings. Refer to DbDevice::get_property() and DbData sections for details on the DbData type.
[in] | prop_names | The properties name |
NonDbDevice,ConnectionFailed,CommunicationFailed,DevFailed | from database |
|
inlinevirtual |
Get events number in queue.
Returns the number of stored events in the event reception buffer. After every call to DeviceProxy:get_events(), the event queue size is 0. During event subscription the client must have chosen the pull model for this event. event_id is the event identifier returned by the AttributeProxy::subscribe_event()method.
[in] | event_id | The event identifier |
EventSystemFailed |
|
virtual |
Get attribute configuration.
Return the attribute configuration
ConnectionFailed,CommunnicationFailed,DevFailed | from device |
|
inlinevirtual |
Get associated DeviceProxy instance.
Returns the DeviceProxy instance used to communicate with the device to which the attributes belongs
|
inlinevirtual |
Get events from event queue (pull model)
The method extracts all waiting attribute configuration events from the event reception buffer. The returned event_list is a vector of AttrConfEventData pointers. The AttrConfEventData object contains the event information as for the callback methods. During event subscription the client must have chosen the pull model for this event. event_id is the event identifier returned by the AttributeProxy::subscribe_event()method.
[in] | event_id | The event identifier |
[out] | event_list | The event list |
EventSystemFailed |
|
inlinevirtual |
Get events from event queue (pull model)
The method extracts all waiting events from the event reception buffer and executes the callback method cb for every event. During event subscription the client must have chosen the pull model for this event. event_id is the event identifier returned by the AttributeProxy::subscribe_event()method.
[in] | event_id | The event identifier |
[in] | cb | The event callback |
EventSystemFailed |
|
inlinevirtual |
Get events from event queue (pull model)
The method extracts all waiting events from the event reception buffer. The returned event_list is a vector of EventData pointers. The EventData object contains the event information as for the callback methods. During event subscription the client must have chosen the pull model for this event. event_id is the event identifier returned by the AttributeProxy::subscribe_event()method.
[in] | event_id | The event identifier |
[out] | event_list | The event list |
EventSystemFailed |
|
inlinevirtual |
Get last event date.
Returns the arrival time of the last event stored in the event reception buffer. After every call to AttributeProxy:get_events(), the event reception buffer is empty. In this case an exception will be returned. During event subscription the client must have chosen the pull model for this event. event_id is the event identifier returned by the AttributeProxy::subscribe_event()method.
[in] | event_id | The event identifier |
EventSystemFailed |
|
virtual |
Get attribute polling period.
Returns the attribute polling period in mS. If the attribute is not polled, it returns 0.
|
virtual |
Get attribute property(ies)
Get property(ies) for the attribute. Properties to get are specified using the DbData type. Refer to DbDevice:: get_property() and DbData sections for details.
[in,out] | db | Properties value |
NonDbDevice,ConnectionFailed,CommunicationFailed,DevFailed | from database |
|
virtual |
Get single attribute property.
Get a single property for the attribute. The property to get is specified as a string. Refer to DbDevice:: get_property() and DbData sections for details on the DbData type.
[in] | prop_name | The property name |
[out] | db | Property value |
NonDbDevice,ConnectionFailed,CommunicationFailed,DevFailed | from database |
|
virtual |
Get multiple attribute property.
Get a list of properties for the attribute. The properties to get are specified as a vector of strings. Refer to DbDevice::get_property() and DbData sections for details on the DbData type.
[in] | prop_names | The property names |
[out] | db | Properties value |
NonDbDevice,ConnectionFailed,CommunicationFailed,DevFailed | from database |
|
virtual |
Get attribute history from polling buffer.
Retrieve attribute history from the attribute polling buffer. The argument is the wanted history depth. This method returns a vector of DeviceAttributeHistory types. This method allocates memory for the vector of DeviceAttributeHistory returned to the caller. It is the caller responsibility to delete this memory. See Tango book chapter on Advanced Feature for all details regarding polling.
[in] | depth | The required history depth |
ConnectionFailed,CommunnicationFailed,NonSupportedFeature,DevFailed | from device |
|
inlinevirtual |
Check if the event queue is empty.
Returns true when the event reception buffer is empty. During event subscription the client must have chosen the pull model for this event. event_id is the event identifier returned by the AttributeProxy::subscribe_event()method.
[in] | event_id | The event identifier |
EventSystemFailed |
|
virtual |
Check if the attribute is polled.
Returns true if the attribute is polled. Otherwise, returns false.
|
inlinevirtual |
Get attribute name.
Returns the attribute name
|
virtual |
Ping the device.
A method which sends a ping to the device to which the attribute belongs and returns the time elapsed in microseconds. Example :
ConnectionFailed,CommunnicationFailed |
|
virtual |
Set attribute polling period.
Add the attribute to the list of polled attributes. The polling period is specified by "period" (in mS). If the attribute is already polled, this method will update the polling period according to "period".
[in] | period | The polling period |
|
virtual |
Put attribute property(ies)
Put property(ies) for an attribute. Properties to put are specified using the DbData type. Refer to DbDevice:: put_property() and DbData sections for details.
[in,out] | db | Properties value |
NonDbDevice,ConnectionFailed,CommunicationFailed,DevFailed | from database |
|
virtual |
Read attribute value.
Read the attribute. To extract the value you have to use the operator of the class DeviceAttribute which corresponds to the data type of the attribute. NOTE: There is no automatic type conversion from the attribute native type to user type e.g. if an attribute returns a short you cannot extract it as a double (this will return 0) you have to extract it as a short.
ConnectionFailed,CommunnicationFailed,DevFailed | from device |
|
inlinevirtual |
Read attribute value asynchronously in polling model.
Read the attribute asynchronously (polling model). This call returns an asynchronous call identifier which is needed to get the attribute value.
ConnectionFailed |
|
inlinevirtual |
Read attribute asynchronously in callback model.
Read the attribute asynchronously using the callback model. The argument is a reference to a callback object. This callback object should be an instance of a user class inheriting from the Tango::CallBack class with the attr_read() method overloaded.
[in] | cb | The callback object |
ConnectionFailed |
|
inlinevirtual |
Get asynchronous read attribute call reply.
Check if the answer of an asynchronous read is arrived (polling model). id is the asynchronous call identifier. If the reply is arrived and if it is a valid reply, it is returned to the caller in a DeviceAttribute object. If the reply is an exception, it is re-thrown by this call. An exception is also thrown in case of the reply is not yet arrived. To extract attribute value, you have to use the operator of the class DeviceAttribute which corresponds to the data type of the attribute. NOTE: There is no automatic type conversion from the attribute native type to user type e.g. if an attribute returns a short you cannot extract it as a double, you have to extract it as a short. Memory has been allocated for the DeviceAttribute object returned to the caller. This is the caller responsibility to delete this memory.
[in] | id | The asynchronous identifier |
AsynCall,AsynReplyNotArrived,CommunicationFailed,DevFailed | from device |
|
inlinevirtual |
Get asynchronous read attribute call reply with timeout.
Check if the answer of an asynchronous read is arrived (polling model). id is the asynchronous call identifier. If the reply is arrived and if it is a valid reply, it is returned to the caller in a DeviceAttribute object. If the reply is an exception, it is re-thrown by this call. If the reply is not yet arrived, the call will wait (blocking the process) for the time specified in timeout. If after timeout milliseconds, the reply is still not there, an exception is thrown. If timeout is set to 0, the call waits until the reply arrived. To extract attribute value, you have to use the operator of the class DeviceAttribute which corresponds to the data type of the attribute. NOTE: There is no automatic type conversion from the attribute native type to user type e.g. if an attribute returns a short you cannot extract it as a double, you have to extract it as a short. Memory has been allocated for the DeviceAttribute object returned to the caller. This is the caller responsibility to delete this memory.
[in] | id | The asynchronous identifier |
[in] | to | The timeout value |
AsynCall,AsynReplyNotArrived,CommunicationFailed,DevFailed | from device |
|
virtual |
Set attribute configuration.
Change the attribute configuration.
[in] | ai | The new attribute configuration data |
ConnectionFailed,CommunnicationFailed,DevFailed | from device |
|
virtual |
Set extended attribute configuration.
Change the attribute configuration.
[in] | ai | The new extended attribute configuration data |
ConnectionFailed,CommunnicationFailed,DevFailed | from device |
|
virtual |
Get device state.
A method which returns the state of the device to which the attribute belongs to. This state is returned as a Tango::DevState type. Example :
ConnectionFailed,CommunnicationFailed |
|
virtual |
Get device status.
A method which return the status of the device to which the attribute belongs to. The status is returned as a string. Example :
ConnectionFailed,CommunnicationFailed |
|
virtual |
Stop attribute polling.
Remove attribute from the list of polled attributes.
|
virtual |
Subscribe to attribute event.
The client call to subscribe for event reception in the pushmodel. The client implements a callbackmethod which is triggered when the event is received either by polling or a dedicated thread. Filtering is done based on the reason specified and the event type. For example when reading the state and the reason specified is "change" the event will be fired only when the state changes. Events consist of an attribute name and the event reason. A standard set of reasons are implemented by the system, additional device specific reasons an be implemented by device servers programmers. cb is a pointer to a class inheriting fromthe Tango CallBack class and implementing a push_event() method. The lifetime of the pointed to object must at least be equal to the time when events are requested because only the pointer is stored into the event machinery. The subscribe_event() call returns an event id which has to be specified when unsubscribing from this event.
[in] | event | The event type (reason) |
[in] | cb | The event callback |
EventSystemFailed |
|
virtual |
Stateless subscription to attribute event.
This subscribe event method has the same functionality as described in the last section. It adds an additional flag called stateless. When the stateless flag is set to false, an exception will be thrown when the event subscription encounters a problem. With the stateless flag set to true, the event subscription will always succeed, even if the corresponding device server is not running. The keep alive thread will try every 10 seconds to subscribe for the specified event. At every subscription retry, a callback is executed which contains the corresponding exception.
[in] | event | The event type (reason) |
[in] | cb | The event callback |
[in] | stateless | The stateless flag |
EventSystemFailed |
|
virtual |
Stateless subscription to attribute event with event queue.
The client call to subscribe for event reception in the pull model. Instead of a callback method the client has to specify the size of the event reception buffer. The event reception buffer is implemented as a round robin buffer. This way the client can set-up different ways to receive events.
All other parameters are similar to the descriptions given in the last two sections.
[in] | event | The event type (reason) |
[in] | event_queue_size | The event queue size |
[in] | stateless | The stateless flag |
EventSystemFailed |
|
inlinevirtual |
Unsubsribe to attribute event.
Unsubscribe a client from receiving the event specified by event_id. event_id is the event identifier returned by the AttributeProxy::subscribe_event() method.
[in] | ev_id | The event identifier |
EventSystemFailed |
|
virtual |
Write attribute value.
Write the attribute. To insert the value to write you have to use the operator of the class DeviceAttribute which corresponds to the data type of the attribute. NOTE: There is no automatic type conversion from the user type to the attribute native type e.g. if an attribute expects a short you cannot insert it as a double (this will throw an exception) you have to insert it as a short.
[in] | da | The new attribute value |
ConnectionFailed,CommunnicationFailed,DevUnlocked,DevFailed | from device |
|
inlinevirtual |
Write attribute value asynchrnously in polling model.
Write the attribute asynchronously (polling model). To insert the value to write you have to use the operator of the class DeviceAttribute which corresponds to the data type of the attribute. NOTE: There is no automatic type conversion from the user type to the attribute native type e.g. if an attribute expects a short you cannot insert it as a double (this will throw an exception) you have to insert it as a short. This call returns an asynchronous call identifier which is needed to get the server reply.
[in] | da | The attribute value |
ConnectionFailed |
|
inlinevirtual |
Write attribute asynchronously in callback model.
Write the attribute asynchronously using the callback model. The argument is a reference to a callback object. This callback object should be an instance of a user class inheriting from the Tango::CallBack class with the attr_written() method overloaded.
[in] | da | The new attribute value |
[in] | cb | The callback object |
ConnectionFailed |
|
virtual |
Write the Read attribute value.
Write then read a single attribute in a single network call. By default (serialisation by device), the execution of this call in the server can’t be interrupted by other clients. To insert/extract the value to write/read you have to use the operator of the class DeviceAttribute which corresponds to the data type of the attribute. NOTE: There is no automatic type conversion from the user type to the attribute native type e.g. if an attribute expects a short you cannot insert it as a double (this will throw an exception) you have to insert it as a short.
[in] | da | The new attribute value |
ConnectionFailed,CommunnicationFailed,DevUnlocked,DevFailed | from device |
|
inlinevirtual |
Get asynchronous write attribute call reply.
Check if the answer of an asynchronous write is arrived (polling model). id is the asynchronous call identifier. If the reply is arrived and if it is a valid reply, the call returned. If the reply is an exception, it is re-thrown by this call. An exception is also thrown in case of the reply is not yet arrived.
[in] | id | The asynchronous identifier |
AsynCall,AsynReplyNotArrived,CommunicationFailed,DevFailed | from device |
|
inlinevirtual |
Get asynchronous write attribute call reply with timeout.
Check if the answer of an asynchronous write is arrived (polling model). id is the asynchronous call identifier. If the reply is arrived and if it is a valid reply, the call returned. If the reply is an exception, it is re-thrown by this call. If the reply is not yet arrived, the call will wait (blocking the process) for the time specified in timeout. If after timeout milliseconds, the reply is still not there, an exception is thrown. If timeout is set to 0, the call waits until the reply arrived.
[in] | id | The asynchronous identifier |
[in] | to | The timeout value |
AsynCall,AsynReplyNotArrived,CommunicationFailed,DevFailed | from device |