rdaDeviceHandle Class Reference

Allows to set, get and monitor property values in a remote device. More...

List of all members.

Public Member Functions
Device info
Methods of this group allow to obtain information on the associated device.
virtual const char *	getDeviceName () const=0
	Returns the device name.
virtual const char *	getClassName () const=0
	Returns the device class name.
Synchronous calls
Methods of this group allow to set and get property values in the synchronous (blocking) mode.
virtual rdaData *	get (const char *propName)=0 throw (rdaBadParameter, rdaTimeOut, rdaNoConnection, rdaIOError, rdaInternalException, rdaInternalError)
	Returns the value of the device property.
virtual rdaData *	get (const char *propName, const rdaData &context)=0 throw (rdaBadParameter,rdaTimeOut, rdaNoConnection, rdaIOError, rdaInternalException, rdaInternalError)
	Returns the value of the device property within the specified context.
virtual rdaData *	get (const char *propName, const char *cycleSelector)=0 throw (rdaBadParameter, rdaTimeOut, rdaNoConnection, rdaIOError, rdaInternalException, rdaInternalError)
	Returns the value of the device property for the specified cycle.
virtual rdaData *	get (const char *propName, const char *cycleSelector, const rdaData &context)=0 throw (rdaBadParameter, rdaTimeOut, rdaNoConnection, rdaIOError, rdaInternalException, rdaInternalError)
	Returns the value of the device property for the specified cycle and within the specified context.
virtual void	set (const char *propName, const rdaData &value)=0 throw (rdaBadParameter, rdaTimeOut, rdaNoConnection, rdaIOError, rdaInternalException, rdaInternalError)
	Sets the value of the device property.
virtual void	set (const char *propName, const rdaData &value, const rdaData &context)=0 throw (rdaBadParameter, rdaTimeOut, rdaNoConnection, rdaIOError, rdaInternalException, rdaInternalError)
	Sets the value of the device property within the specified context.
virtual void	set (const char *propName, const char *cycleSelector, const rdaData &value)=0 throw (rdaBadParameter, rdaTimeOut, rdaNoConnection, rdaIOError, rdaInternalException, rdaInternalError)
	Sets the value of the device property for the specified cycle.
virtual void	set (const char *propName, const char *cycleSelector, const rdaData &value, const rdaData &context)=0 throw (rdaBadParameter, rdaTimeOut, rdaNoConnection, rdaIOError, rdaInternalException, rdaInternalError)
	Sets the value of the device property for the specified cycle and within the specified context.
Asynchronous calls
Methods of this group allow to set and get property values in the asynchronous (non-blocking) mode.
virtual void	get (const char *propName, rdaReplyHandler *replyHandler)=0 throw (rdaBadParameter, rdaNoConnection, rdaInternalException, rdaInternalError)
	Sends to the device a request to read the property value.
virtual void	get (const char *propName, rdaReplyHandler *replyHandler, const rdaData &context)=0 throw (rdaBadParameter, rdaNoConnection, rdaInternalException, rdaInternalError)
	Sends to the device a request to read the property value within the specified context.
virtual void	get (const char *propName, const char *cycleSelector, rdaReplyHandler *replyHandler)=0 throw (rdaBadParameter, rdaNoConnection, rdaInternalException, rdaInternalError)
	Sends to the device a request to read the property value for the specified cycle.
virtual void	get (const char *propName, const char *cycleSelector, rdaReplyHandler *replyHandler, const rdaData &context)=0 throw (rdaBadParameter, rdaNoConnection, rdaInternalException, rdaInternalError)
	Sends to the device a request to read the property value for the specified cycle and within the specified contex.
virtual void	set (const char *propName, const rdaData &value, rdaReplyHandler *replyHandler)=0 throw (rdaBadParameter, rdaNoConnection, rdaInternalException, rdaInternalError)
	Sends to the device a request to set the property value.
virtual void	set (const char *propName, const rdaData &value, rdaReplyHandler *replyHandler, const rdaData &context)=0 throw (rdaBadParameter, rdaNoConnection, rdaInternalException, rdaInternalError)
	Sends to the device a request to set the property value within the specified context.
virtual void	set (const char *propName, const char *cycleSelector, const rdaData &value, rdaReplyHandler *replyHandler)=0 throw (rdaBadParameter, rdaNoConnection, rdaInternalException, rdaInternalError)
	Sends to the device a request to set the property value for the specified cycle.
virtual void	set (const char *propName, const char *cycleSelector, const rdaData &value, rdaReplyHandler *replyHandler, const rdaData &context)=0 throw (rdaBadParameter, rdaNoConnection, rdaInternalException, rdaInternalError)
	Sends to the device a request to set the property value for the specified cycle and within the specified context.
Subscription
Methods of this group allow to subscribe on a device property value.
virtual rdaRequest *	monitorOn (const char *propName, bool onChange, rdaReplyHandler *replyHandler)=0 throw (rdaBadParameter, rdaTimeOut, rdaNoConnection, rdaIOError, rdaInternalException, rdaInternalError)
	Starts a subscription on the property value.
virtual rdaRequest *	monitorOn (const char *propName, bool onChange, rdaReplyHandler *replyHandler, const rdaData &context)=0 throw (rdaBadParameter, rdaTimeOut, rdaNoConnection, rdaIOError, rdaInternalException, rdaInternalError)
	Starts a subscription on the property value within the specified context.
virtual rdaRequest *	monitorOn (const char *propName, const char *cycleSelector, bool onChange, rdaReplyHandler *replyHandler)=0 throw (rdaBadParameter, rdaTimeOut, rdaNoConnection, rdaIOError, rdaInternalException, rdaInternalError)
	Starts a subscription on the property value for the specified cycle.
virtual rdaRequest *	monitorOn (const char *propName, const char *cycleSelector, bool onChange, rdaReplyHandler *replyHandler, const rdaData &context)=0 throw (rdaBadParameter, rdaTimeOut, rdaNoConnection, rdaIOError, rdaInternalException, rdaInternalError)
	Starts a subscription on the property value for the specified cycle and within the specified context.
virtual void	monitorOff (rdaRequest *request)=0 throw (rdaBadParameter, rdaTimeOut)
	Cancels a subscription initiated by the specified request.

---

Detailed Description

Allows to set, get and monitor property values in a remote device.

An object of this class acts as a proxy which represents a remote device to the local client, and delegates device calls, made by the client, to the device server.

The class provides several groups of the device access methods.

• <A HREF="#sync>synchronous calls
  Methods of this group allow to set and get device property values in the synchronous (blocking) mode. When a client makes a synchronous call, it blocks while the call is being executed in the device server. Here is an example of using the synchronous device calls.
• <A HREF="#async>asynchronous calls
  Methods of this group create a request to set or get a device property value, send it to the device server, and return. Results of the requested operation will be delivered to the callback object which is specified as an argument in each asynchronous call. Here is an example of using the asynchronous device calls.
• <A HREF="#sub>subscription
  Using methods of this group, a client can subscribe on a device property value, and receive regular updates of the value via the specified callback object. Here is a subscription example.

The class also provides a <A HREF="#info>group of methods that allow to obtain some information on the associated device.

Examples:

GetAsync.cpp, GetSync.cpp, and Monitor.cpp.

---

Member Function Documentation

virtual void rdaDeviceHandle::get (  const char *  propName, const char *  cycleSelector, rdaReplyHandler *  replyHandler, const rdaData &  context )  throw (rdaBadParameter, rdaNoConnection, rdaInternalException, rdaInternalError) [pure virtual]

Sends to the device a request to read the property value for the specified cycle and within the specified contex. The call returns when the request has been sent to the device. The operation results will be delivered to the replyHandler object, see rdaReplyHandler for the description of callback methods which can be invoked in this phase. Parameters: propName  the property name cycleSelector  the cycle identifier context  the operation context replyHandler  the "callback" object that will be notified on the operation results.

virtual void rdaDeviceHandle::get (  const char *  propName, const char *  cycleSelector, rdaReplyHandler *  replyHandler )  throw (rdaBadParameter, rdaNoConnection, rdaInternalException, rdaInternalError) [pure virtual]

Sends to the device a request to read the property value for the specified cycle. The call returns when the request has been sent to the device. The operation results will be delivered to the replyHandler object, see rdaReplyHandler for the description of callback methods which can be invoked in this phase. Parameters: propName  the property name cycleSelector  the cycle identifier replyHandler  the "callback" object that will be notified on the operation results.

virtual void rdaDeviceHandle::get (  const char *  propName, rdaReplyHandler *  replyHandler, const rdaData &  context )  throw (rdaBadParameter, rdaNoConnection, rdaInternalException, rdaInternalError) [pure virtual]

Sends to the device a request to read the property value within the specified context. The call returns when the request has been sent to the device. The operation results will be delivered to the replyHandler object, see rdaReplyHandler for the description of callback methods which can be invoked in this phase. Parameters: propName  the property name context  the operation context replyHandler  the "callback" object that will be notified on the operation results.

virtual void rdaDeviceHandle::get (  const char *  propName, rdaReplyHandler *  replyHandler )  throw (rdaBadParameter, rdaNoConnection, rdaInternalException, rdaInternalError) [pure virtual]

Sends to the device a request to read the property value. The call returns when the request has been sent to the device. The operation results will be delivered to the replyHandler object, see rdaReplyHandler for the description of callback methods which can be invoked in this phase. Parameters: propName  the property name replyHandler  the "callback" object that will be notified on the operation results.

virtual rdaData* rdaDeviceHandle::get (  const char *  propName, const char *  cycleSelector, const rdaData &  context )  throw (rdaBadParameter, rdaTimeOut, rdaNoConnection, rdaIOError, rdaInternalException, rdaInternalError) [pure virtual]

Returns the value of the device property for the specified cycle and within the specified context. Parameters: propName  the property name cycleSelector  the cycle identifier context  the operation context Returns: a pointer to the rdaData object that contains the requested value. The data object is dynamically allocated and must be released by the caller when it is no longer needed

virtual rdaData* rdaDeviceHandle::get (  const char *  propName, const char *  cycleSelector )  throw (rdaBadParameter, rdaTimeOut, rdaNoConnection, rdaIOError, rdaInternalException, rdaInternalError) [pure virtual]

Returns the value of the device property for the specified cycle. Parameters: propName  the property name cycleSelector  the cycle identifier Returns: a pointer to the rdaData object that contains the requested value. The data object is dynamically allocated and must be released by the caller when it is no longer needed

virtual rdaData* rdaDeviceHandle::get (  const char *  propName, const rdaData &  context )  throw (rdaBadParameter,rdaTimeOut, rdaNoConnection, rdaIOError, rdaInternalException, rdaInternalError) [pure virtual]

Returns the value of the device property within the specified context. Parameters: propName  the property name context  the operation context Returns: a pointer to the rdaData object that contains the requested value. The data object is dynamically allocated and must be released by the caller when it is no longer needed

virtual rdaData* rdaDeviceHandle::get (  const char *  propName  )  throw (rdaBadParameter, rdaTimeOut, rdaNoConnection, rdaIOError, rdaInternalException, rdaInternalError) [pure virtual]

Returns the value of the device property. Parameters: propName  the property name Returns: a pointer to the rdaData object that contains the requested value. The data object is dynamically allocated and must be released by the caller when it is no longer needed Examples: GetAsync.cpp, and GetSync.cpp.

virtual void rdaDeviceHandle::monitorOff (  rdaRequest *  request  )  throw (rdaBadParameter, rdaTimeOut) [pure virtual]

Cancels a subscription initiated by the specified request. This is a blocking call that propagates down to the device server. In case of timeout, the subscription remains active in the client and may or may not be removed in the server. You can retry the call to definitely remove the server side monitor. A successful monitorOff call deletes the subscription request object and invalidates the request pointer. An attempt to use the invalid request pointer in a monitorOff call will result in the rdaBadParameter exception. In principle, each monitorOn call should have a matching monitorOff: this allows to optimize resource utilization on the client and server side. However, an uncancelled subscription does not result in an irreversible resource leak: all monitors installed by a client will be automatically removed in the servers when the client terminates. Examples: Monitor.cpp.

virtual rdaRequest* rdaDeviceHandle::monitorOn (  const char *  propName, const char *  cycleSelector, bool  onChange, rdaReplyHandler *  replyHandler, const rdaData &  context )  throw (rdaBadParameter, rdaTimeOut, rdaNoConnection, rdaIOError, rdaInternalException, rdaInternalError) [pure virtual]

Starts a subscription on the property value for the specified cycle and within the specified context. If a monitorOn call completes successfully then the rdaReplyHandler object specified as an argument to the call will be notified each time the subscribed value is updated or an attempt to update the value fails due to an I/O error (see rdaReplyHandler for the description of callback methods that can be invoked as a result of this call). If "on-change" mode has been specified in the call then only the value which is different from the previous one will be reported to the client. monitorOn is a blocking call that propagates down to the device server. On the server side, it installs a "monitor" on the specified value. Each monitor takes some resources (CPU time, memory, I/O bandwidth) in the server. The call fails if the monitor cannot be installed due to lack of the resources. On success, the call returns a pointer to the subscription request object that has been sent to the server. The subscription can be cancelled using the monitorOff call with this pointer as an argument. Parameters: propName  the property name cycleSelector  the cycle identifier onChange  the subscription mode: "on-change", if true replyHandler  the "callback" that will receive subscription reports context  the operation context.

virtual rdaRequest* rdaDeviceHandle::monitorOn (  const char *  propName, const char *  cycleSelector, bool  onChange, rdaReplyHandler *  replyHandler )  throw (rdaBadParameter, rdaTimeOut, rdaNoConnection, rdaIOError, rdaInternalException, rdaInternalError) [pure virtual]

Starts a subscription on the property value for the specified cycle. If a monitorOn call completes successfully then the rdaReplyHandler object specified as an argument to the call will be notified each time the subscribed value is updated or an attempt to update the value fails due to an I/O error (see rdaReplyHandler for the description of callback methods that can be invoked as a result of this call). If "on-change" mode has been specified in the call then only the value which is different from the previous one will be reported to the client. monitorOn is a blocking call that propagates down to the device server. On the server side, it installs a "monitor" on the specified value. Each monitor takes some resources (CPU time, memory, I/O bandwidth) in the server. The call fails if the monitor cannot be installed due to lack of the resources. On success, the call returns a pointer to the subscription request object that has been sent to the server. The subscription can be cancelled using the monitorOff call with this pointer as an argument. Parameters: propName  the property name cycleSelector  the cycle identifier onChange  the subscription mode: "on-change", if true replyHandler  the "callback" object that will receive subscription reports.

virtual rdaRequest* rdaDeviceHandle::monitorOn (  const char *  propName, bool  onChange, rdaReplyHandler *  replyHandler, const rdaData &  context )  throw (rdaBadParameter, rdaTimeOut, rdaNoConnection, rdaIOError, rdaInternalException, rdaInternalError) [pure virtual]

Starts a subscription on the property value within the specified context. If a monitorOn call completes successfully then the rdaReplyHandler object specified as an argument to the call will be notified each time the subscribed value is updated or an attempt to update the value fails due to an I/O error (see rdaReplyHandler for the description of callback methods that can be invoked as a result of this call). If "on-change" mode has been specified in the call then only the value which is different from the previous one will be reported to the client. monitorOn is a blocking call that propagates down to the device server. On the server side, it installs a "monitor" on the specified value. Each monitor takes some resources (CPU time, memory, I/O bandwidth) in the server. The call fails if the monitor cannot be installed due to lack of the resources. On success, the call returns a pointer to the subscription request object that has been sent to the server. The subscription can be cancelled using the monitorOff call with this pointer as an argument. Parameters: propName  the property name onChange  the subscription mode: "on-change", if true replyHandler  the "callback" object that will receive subscription reports context  the operation context.

virtual rdaRequest* rdaDeviceHandle::monitorOn (  const char *  propName, bool  onChange, rdaReplyHandler *  replyHandler )  throw (rdaBadParameter, rdaTimeOut, rdaNoConnection, rdaIOError, rdaInternalException, rdaInternalError) [pure virtual]

Starts a subscription on the property value. If a monitorOn call completes successfully then the rdaReplyHandler object specified as an argument to the call will be notified each time the subscribed value is updated or an attempt to update the value fails due to an I/O error (see rdaReplyHandler for the description of callback methods that can be invoked as a result of this call). If "on-change" mode has been specified in the call then only the value which is different from the previous one will be reported to the client. monitorOn is a blocking call that propagates down to the device server. On the server side, it installs a "monitor" on the specified value. Each monitor takes some resources (CPU time, memory, I/O bandwidth) in the server. The call fails if the monitor cannot be installed due to lack of the resources. On success, the call returns a pointer to the subscription request object that has been sent to the server. The subscription can be cancelled using the monitorOff call with this pointer as an argument. Parameters: propName  the property name onChange  the subscription mode: "on-change", if true replyHandler  the "callback" object that will receive subscription reports. Examples: Monitor.cpp.

virtual void rdaDeviceHandle::set (  const char *  propName, const char *  cycleSelector, const rdaData &  value, rdaReplyHandler *  replyHandler, const rdaData &  context )  throw (rdaBadParameter, rdaNoConnection, rdaInternalException, rdaInternalError) [pure virtual]

Sends to the device a request to set the property value for the specified cycle and within the specified context. The call returns when the request has been sent to the device. The operation results will be reported to the replyHandler object, see rdaReplyHandler for the description of callback methods which can be invoked in this phase. Parameters: propName  the property name cycleSelector  the cycle identifier value  the value to set context  the operation context replyHandler  the "callback" object that will be notified on the operation results.

virtual void rdaDeviceHandle::set (  const char *  propName, const char *  cycleSelector, const rdaData &  value, rdaReplyHandler *  replyHandler )  throw (rdaBadParameter, rdaNoConnection, rdaInternalException, rdaInternalError) [pure virtual]

Sends to the device a request to set the property value for the specified cycle. The call returns when the request has been sent to the device. The operation results will be reported to the replyHandler object, see rdaReplyHandler for the description of callback methods which can be invoked in this phase. Parameters: propName  the property name cycleSelector  the cycle identifier value  the value to set replyHandler  the "callback" object that will be notified on the operation results.

virtual void rdaDeviceHandle::set (  const char *  propName, const rdaData &  value, rdaReplyHandler *  replyHandler, const rdaData &  context )  throw (rdaBadParameter, rdaNoConnection, rdaInternalException, rdaInternalError) [pure virtual]

Sends to the device a request to set the property value within the specified context. The call returns when the request has been sent to the device. The operation results will be reported to the replyHandler object, see rdaReplyHandler for the description of callback methods which can be invoked in this phase. Parameters: propName  the property name cycleSelector  the cycle identifier value  the value to set context  the operation context replyHandler  the "callback" object that will be notified on the operation results.

virtual void rdaDeviceHandle::set (  const char *  propName, const rdaData &  value, rdaReplyHandler *  replyHandler )  throw (rdaBadParameter, rdaNoConnection, rdaInternalException, rdaInternalError) [pure virtual]

Sends to the device a request to set the property value. The call returns when the request has been sent to the device. The operation results will be reported to the replyHandler object, see rdaReplyHandler for the description of callback methods which can be invoked in this phase. Parameters: propName  the property name cycleSelector  the cycle identifier value  the value to set replyHandler  the "callback" object that will be notified on the operation results.

virtual void rdaDeviceHandle::set (  const char *  propName, const char *  cycleSelector, const rdaData &  value, const rdaData &  context )  throw (rdaBadParameter, rdaTimeOut, rdaNoConnection, rdaIOError, rdaInternalException, rdaInternalError) [pure virtual]

Sets the value of the device property for the specified cycle and within the specified context. This call returns when the value has been set in the device. Parameters: propName  the property name cycleSelector  the cycle identifier value  the value to set context  the operation context

virtual void rdaDeviceHandle::set (  const char *  propName, const char *  cycleSelector, const rdaData &  value )  throw (rdaBadParameter, rdaTimeOut, rdaNoConnection, rdaIOError, rdaInternalException, rdaInternalError) [pure virtual]

Sets the value of the device property for the specified cycle. This call returns when the value has been set in the device. Parameters: propName  the property name cycleSelector  the cycle identifier value  the value to set

virtual void rdaDeviceHandle::set (  const char *  propName, const rdaData &  value, const rdaData &  context )  throw (rdaBadParameter, rdaTimeOut, rdaNoConnection, rdaIOError, rdaInternalException, rdaInternalError) [pure virtual]

Sets the value of the device property within the specified context. This call returns when the value has been set in the device. Parameters: propName  the property name value  the value to set context  the operation context

virtual void rdaDeviceHandle::set (  const char *  propName, const rdaData &  value )  throw (rdaBadParameter, rdaTimeOut, rdaNoConnection, rdaIOError, rdaInternalException, rdaInternalError) [pure virtual]

Sets the value of the device property. This call returns when the value has been set in the device. Parameters: propName  the property name value  the value to set

---

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

• DeviceHandle.h

---