rdaValueChangeListener Class Reference

The listener interface for receiving notification of I/O value updates. More...

List of all members.

Public Member Functions
virtual const rdaClientInfo *	getClientInfo ()=0
	Returns information on the listening client.
virtual bool	isOnChange ()=0
	Returns true if the listener is onChange.
Immediate notification methods
Methods of this group are used to immediately report I/O values and errors to clients.
virtual void	valueUpdated (const rdaData &oldValue, const rdaData &newValue, bool hasChanged)=0
	Gets called when the value at the associated I/O point is updated.
virtual void	ioFailed (const rdaIOError &error)=0
	Gets called when an attempt to update the associated value fails due to an I/O error.
Store and flush methods
Methods of this group are used to report I/O values and errors to clients in the "store and flush" mode.
virtual void	valueUpdated (bool value, bool hasChanged)=0
	Gets called when the boolean value at the associated I/O point is updated.
virtual void	valueUpdated (signed char value, bool hasChanged)=0
	Gets called when the byte value at the associated I/O point is updated.
virtual void	valueUpdated (short value, bool hasChanged)=0
	Gets called when the short value at the associated I/O point is updated.
virtual void	valueUpdated (long value, bool hasChanged)=0
	Gets called when the long value at the associated I/O point is updated.
virtual void	valueUpdated (longlong value, bool hasChanged)=0
	Gets called when the longlong value at the associated I/O point is updated.
virtual void	valueUpdated (float value, bool hasChanged)=0
	Gets called when the float value at the associated I/O point is updated.
virtual void	valueUpdated (double value, bool hasChanged)=0
	Gets called when the double value at the associated I/O point is updated.
virtual void	valueUpdated (const char *value, bool hasChanged)=0
	Gets called when the string value at the associated I/O point is updated.
virtual void	valueUpdated (const bool *value, unsigned long size, bool hasChanged)=0
	Gets called when the boolean array value at the associated I/O point is updated.
virtual void	valueUpdated (const signed char *value, unsigned long size, bool hasChanged)=0
	Gets called when the byte array value at the associated I/O point is updated.
virtual void	valueUpdated (const short *value, unsigned long size, bool hasChanged)=0
	Gets called when the short array value at the associated I/O point is updated.
virtual void	valueUpdated (const long *value, unsigned long size, bool hasChanged)=0
	Gets called when the long array value at the associated I/O point is updated.
virtual void	valueUpdated (const longlong *value, unsigned long size, bool hasChanged)=0
	Gets called when the longlong array value at the associated I/O point is updated.
virtual void	valueUpdated (const float *value, unsigned long size, bool hasChanged)=0
	Gets called when the float array value at the associated I/O point is updated.
virtual void	valueUpdated (const double *value, unsigned long size, bool hasChanged)=0
	Gets called when the double array value at the associated I/O point is updated.
virtual void	valueUpdated (const char **value, unsigned long size, bool hasChanged)=0
	Gets called when the string array value at the associated I/O point is updated.
virtual void	valueUpdated (const rdaData &value, bool hasChanged)=0
	Gets called when the composite rdaData value at the associated I/O point is updated.
virtual void	ioFailed (const char *cat, int code, const char *msg, bool newError)=0
	Gets called when an attempt to update value at the associated I/O point fails due to an I/O error.
Static Public Member Functions
void	flush (const rdaData &stamp)
	Sends all reports stored in the subscription buffers to clients.

---

Detailed Description

The listener interface for receiving notification of I/O value updates.

Each rdaValueChangeListener is attached to exactly one I/O point in a device server; this association is established when the rdaDeviceServerBase::monitorOn() method is invoked on the server with this listener as an argument. The listener is then notified whenever the associated value is updated or an attempt to update the value fails due to an I/O error.

Each rdaValueChangeListener has an associated rdaReplyHandler object on the client side. When notification methods are called on rdaValueChangeListener objects, they generate subscription reports containing specified values or errors; the RDA delivers these reports to clients and invokes corresponding methods on the associated reply handlers. The RDA supports two report delivery modes:

• immediate notification
  Subscription reports generated by the immediate notification calls are immediately (during the call execution) submitted to the communications software which shall then deliver them to clients as soon as possible.

• store and flush
  Notification methods of the store and flush group generate reports and put them in subscription buffers - there is one such buffer for each connected client. Reports accumulated in the buffers will be sent to all clients when the static rdaValueChangeListener::flush method is invoked. Contents of each buffer will be handled at the communications level as a single packet, thus allowing to improve performance and achive better communucations use. Sending the same number of reports in the "store and flush" mode can be significantly (10 to 50 times) faster then in the immediate notification mode.

Immediate notification calls allow to report arbitrary complex I/O values and provide any supplementary information (see rdaIOError::getDetails) in the reported errors: the rdaData objects that are used to pass values and error details can contain any number of entries.

The "store and flush" methods allow to report only simple I/O values - such values that can be stored in a single data entry. The notification methods of this group are strongly typed and overloaded for each data type supported in the rdaDataEntry class. Whatever is passed as the value argument to this methods will be delivered to the client's reply handler in the "value" entry of the reported data. In addition, the reported data will contain copies of all entries passed in the stamp argument to the rdaValueChangeListener::flush method. The stamp data will also be available as details in each reported error - no other information can be passed as error details in this mode.

The choice of the report delivery mode depends on specific requirements to performance and value types in a concrete device server implementation. The immediate notification mode should be considered as a default option: it does not impose any limitations on the report format and value types and is sufficiently fast for most uses. The "store and flush" methods can be used when a large number of simple values sharing a common stamp data has to be reported to clients as quickly as possible.

Both report delivery modes can be simultaneously used in the same device server, and different notification calls can be freely mixed in the same or different threads. For example, one thread in a server can perform regular data acquisition synchronized with accelerator timing events and report results in the "store and flush" mode, while another thread in the same server can continously poll status properties and immediately notify clients on faults in the connected equipment - even when the data acquisition is in progress.

See also:

rdaDeviceServerBase

Examples:

Device.h, DeviceServer.h, and Property.h.

---

Member Function Documentation

void rdaValueChangeListener::flush (  const rdaData &  stamp  )  [static]

Sends all reports stored in the subscription buffers to clients. Contents of the stamp data will be appended to each reported value or error before passing it to the client side reply handler. Typically, this rdaData object will contain a time or cycle stamp for the reported values, but in principle it may be used to pass to the clients any supplementary information common to all reports stored in the buffers, or be empty if there is no such information. The stamp data should not contain entries with the "value" tag; if such an entry is discovered in the data, it will be ignored and never delivered to the clients. Exceptions: rdaInternalError  thrown if the call fails due to an internal RDA error.

virtual void rdaValueChangeListener::ioFailed (  const char *  cat, int  code, const char *  msg, bool  newError )  [pure virtual]

Gets called when an attempt to update value at the associated I/O point fails due to an I/O error. Constructs an rdaIOError object from the specified parameters, generates a subscription report containing the error, and adds it to the subscription buffer. The error details will be set from the stamp argument of the rdaValueChangeListener::flush call. Parameters: cat  the error category code  the error code msg  the error message newError  the flag that is true if there was no error in the previous update or if this error is different from the previous error; false otherwise. See also: rdaIOError for the exact meaning of the error category, code and message

virtual void rdaValueChangeListener::ioFailed (  const rdaIOError &  error  )  [pure virtual]

Gets called when an attempt to update the associated value fails due to an I/O error. Generates a subscription report containing the specified error and sends it to the client. Parameters: error  the rdaIOError object that describes the error. Exceptions: rdaInternalError  thrown if the call fails due to an internal RDA error.

virtual void rdaValueChangeListener::valueUpdated (  const rdaData &  value, bool  hasChanged )  [pure virtual]

Gets called when the composite rdaData value at the associated I/O point is updated. Generates a subscription report containing the specified value and adds it to the subscription buffer. Parameters: value  the rdaData object hasChanged  (currently ignored) the flag that is true if the array size or any of its elements has changed since the previous update; false otherwise.

virtual void rdaValueChangeListener::valueUpdated (  const char **  value, unsigned long  size, bool  hasChanged )  [pure virtual]

Gets called when the string array value at the associated I/O point is updated. Generates a subscription report containing the specified value and adds it to the subscription buffer. Parameters: value  the pointer to the value array size  the number of elements in the array hasChanged  the flag that is true if the array size or any of its elements has changed since the previous update; false otherwise.

virtual void rdaValueChangeListener::valueUpdated (  const double *  value, unsigned long  size, bool  hasChanged )  [pure virtual]

Gets called when the double array value at the associated I/O point is updated. Generates a subscription report containing the specified value and adds it to the subscription buffer. Parameters: value  the pointer to the value array size  the number of elements in the array hasChanged  the flag that is true if the array size or any of its elements has changed since the previous update; false otherwise.

virtual void rdaValueChangeListener::valueUpdated (  const float *  value, unsigned long  size, bool  hasChanged )  [pure virtual]

Gets called when the float array value at the associated I/O point is updated. Generates a subscription report containing the specified value and adds it to the subscription buffer. Parameters: value  the pointer to the value array size  the number of elements in the array hasChanged  the flag that is true if the array size or any of its elements has changed since the previous update; false otherwise.

virtual void rdaValueChangeListener::valueUpdated (  const longlong *  value, unsigned long  size, bool  hasChanged )  [pure virtual]

Gets called when the longlong array value at the associated I/O point is updated. Generates a subscription report containing the specified value and adds it to the subscription buffer. Parameters: value  the pointer to the value array size  the number of elements in the array hasChanged  the flag that is true if the array size or any of its elements has changed since the previous update; false otherwise.

virtual void rdaValueChangeListener::valueUpdated (  const long *  value, unsigned long  size, bool  hasChanged )  [pure virtual]

Gets called when the long array value at the associated I/O point is updated. Generates a subscription report containing the specified value and adds it to the subscription buffer. Parameters: value  the pointer to the value array size  the number of elements in the array hasChanged  the flag that is true if the array size or any of its elements has changed since the previous update; false otherwise.

virtual void rdaValueChangeListener::valueUpdated (  const short *  value, unsigned long  size, bool  hasChanged )  [pure virtual]

Gets called when the short array value at the associated I/O point is updated. Generates a subscription report containing the specified value and adds it to the subscription buffer. Parameters: value  the pointer to the value array size  the number of elements in the array hasChanged  the flag that is true if the array size or any of its elements has changed since the previous update; false otherwise.

virtual void rdaValueChangeListener::valueUpdated (  const signed char *  value, unsigned long  size, bool  hasChanged )  [pure virtual]

Gets called when the byte array value at the associated I/O point is updated. Generates a subscription report containing the specified value and adds it to the subscription buffer. Parameters: value  the pointer to the value array size  the number of elements in the array hasChanged  the flag that is true if the array size or any of its elements has changed since the previous update; false otherwise.

virtual void rdaValueChangeListener::valueUpdated (  const bool *  value, unsigned long  size, bool  hasChanged )  [pure virtual]

Gets called when the boolean array value at the associated I/O point is updated. Generates a subscription report containing the specified value and adds it to the subscription buffer. Parameters: value  the pointer to the value array size  the number of elements in the array hasChanged  the flag that is true if the array size or any of its elements has changed since the previous update; false otherwise.

virtual void rdaValueChangeListener::valueUpdated (  const char *  value, bool  hasChanged )  [pure virtual]

Gets called when the string value at the associated I/O point is updated. Generates a subscription report containing the specified value and adds it to the subscription buffer. Parameters: value  the pointer to the updated string value hasChanged  the flag that is true if the associated I/O value has changed since the previous update; false otherwise.

virtual void rdaValueChangeListener::valueUpdated (  double  value, bool  hasChanged )  [pure virtual]

Gets called when the double value at the associated I/O point is updated. Generates a subscription report containing the specified value and adds it to the subscription buffer. Parameters: value  the updated value hasChanged  the flag that is true if the associated I/O value has changed since the previous update; false otherwise.

virtual void rdaValueChangeListener::valueUpdated (  float  value, bool  hasChanged )  [pure virtual]

Gets called when the float value at the associated I/O point is updated. Generates a subscription report containing the specified value and adds it to the subscription buffer. Parameters: value  the updated value hasChanged  the flag that is true if the associated I/O value has changed since the previous update; false otherwise.

virtual void rdaValueChangeListener::valueUpdated (  longlong  value, bool  hasChanged )  [pure virtual]

Gets called when the longlong value at the associated I/O point is updated. Generates a subscription report containing the specified value and adds it to the subscription buffer. Parameters: value  the updated value hasChanged  the flag that is true if the associated I/O value has changed since the previous update; false otherwise.

virtual void rdaValueChangeListener::valueUpdated (  long  value, bool  hasChanged )  [pure virtual]

Gets called when the long value at the associated I/O point is updated. Generates a subscription report containing the specified value and adds it to the subscription buffer. Parameters: value  the updated value hasChanged  the flag that is true if the associated I/O value has changed since the previous update; false otherwise.

virtual void rdaValueChangeListener::valueUpdated (  short  value, bool  hasChanged )  [pure virtual]

Gets called when the short value at the associated I/O point is updated. Generates a subscription report containing the specified value and adds it to the subscription buffer. Parameters: value  the updated value hasChanged  the flag that is true if the associated I/O value has changed since the previous update; false otherwise.

virtual void rdaValueChangeListener::valueUpdated (  signed char  value, bool  hasChanged )  [pure virtual]

Gets called when the byte value at the associated I/O point is updated. Generates a subscription report containing the specified value and adds it to the subscription buffer. Parameters: value  the updated value hasChanged  the flag that is true if the associated I/O value has changed since the previous update; false otherwise.

virtual void rdaValueChangeListener::valueUpdated (  bool  value, bool  hasChanged )  [pure virtual]

Gets called when the boolean value at the associated I/O point is updated. Generates a subscription report containing the specified value and adds it to the subscription buffer. Parameters: value  the updated value hasChanged  the flag that is true if the associated I/O value has changed since the previous update; false otherwise.

virtual void rdaValueChangeListener::valueUpdated (  const rdaData &  oldValue, const rdaData &  newValue, bool  hasChanged )  [pure virtual]

Gets called when the value at the associated I/O point is updated. Generates a subscription report containing newValue and sends it to the client. Parameters: oldValue  the value before update or an empty rdaData, if old value is unknown newValue  the updated value hasChanged  is true if the new value is different from the old one; false otherwise. Exceptions: rdaInternalError  thrown if the call fails due to an internal RDA error.

---

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

• ValueChangeListener.h

---