Main Page | Class Hierarchy | Class List | File List | Class Members | File Members | Related Pages | Examples

rdaDeviceServerBase Class Reference

An abstract class that provides the RDA connectivity for device servers implemented as its derived classes. More...

List of all members.

Public Member Functions

virtual void shutdownHook ()
 This virtual method is called by RDA prior to the server shutdown.

virtual bool clientConnectionHook (const rdaClientInfo &clientInfo)
 This virtual method is called by RDA when a new client wants to connect to the server.

Basic device access methods
Each device server must provide an implementation of these four abstract methods.

virtual rdaData * get (const rdaIOPoint &iop, const rdaData &ctx)=0
 Allows to read a value at the specified I/O point.

virtual void set (const rdaIOPoint &iop, const rdaData &ctx, const rdaData &value)=0
 Changes a value at the specified I/O point.

virtual void monitorOn (const rdaIOPoint &iop, const rdaData &ctx, rdaValueChangeListener *listener)=0
 Starts a subscription to value at the specified I/O point.

virtual void monitorOff (const rdaIOPoint &iop, rdaValueChangeListener *listener)=0
 Cancels a subscription identified by the I/O point and listener.

Asynchronous calls
Methods of this group are invoked when clients make asynchronous calls to devices that reside at this server.

virtual void get (const rdaIOPoint &iop, const rdaData &ctx, rdaResult *result)
 Allows to read a value at the specified I/O point.

virtual void set (const rdaIOPoint &iop, const rdaData &ctx, const rdaData &value, rdaResult *result)
 Changes a value at the specified I/O point.

virtual void cancel (rdaResult *result)
Administration calls
These methods are called remotely by administration clients.

virtual rdaData * getState ()
 This virtual method is called when an administration client calls the getState method of the admin::ServerAdmin interface.

virtual ServerStatus getStatus ()
 This method is called when an administration client calls the getStatus method of the admin::ServerAdmin interface.


Static Public Member Functions

rdaDeviceServerBase * theServer ()
 Returns a pointer to the single instance of the server.

void init (int argc, char **argv)
 Initializes the RDA.

void runServer ()
 Makes the server available for clients.

void shutDown ()
 Deactivates the server.

void shutDown (int signo)
 Deactivates the server.

const rdaClientInfo * getClientInfo ()
 Allows to obtain information about a remote client that made a device call in a device access method (get, set, monitorOn, monitorOff) implementation.

const char * getName ()
 Returns the name of this server.

rdaLogger * getGlobalLogger ()
 Returns the logger that is used by RDA to trace general activities in the server (initialization, fatal errors, shutdown).

rdaLogger * getClientsLogger ()
 Returns the logger that is used by RDA to trace cleint connections.

rdaLogger * getCallsLogger ()
 Returns the logger that is used by RDA to trace client calls.

rdaLogger * getSubscriptionsLogger ()
 Returns the logger that is used by RDA to trace subscription reports.


Protected Member Functions

 rdaDeviceServerBase (const char *serverName)
 Constructs a device server with the specified name.

Detailed Description

An abstract class that provides the RDA connectivity for device servers implemented as its derived classes.

device_server_base.gif

Device server developers must at least provide implementations for the four basic device access calls that are declared as pure virtual functions in this class: get(), set(), monitorOn(), monitorOff(). These methods are called whenever a corresponding method is called on an associated rdaDeviceHandle in a remote client.

The device access calls can throw the following two exceptions: Throwing any other exceptions then the above two is considered as a bug in the device server implementation. All such "unchecked" exceptions will be caught by the server side RDA and reported to clients by throwing an rdaInternalException.

See also:
rdaDeviceHandle for the description of the client side device access methods.
Examples:

DeviceServer.h.

Constructor & Destructor Documentation

rdaDeviceServerBase::rdaDeviceServerBase (  const char *  serverName  )  [protected]
 

Constructs a device server with the specified name.

The constructor prepares all the facilities required to make the server available for clients over the network, but does not activate the communications.

Access to the server can be enabled when it is fully constructed (all subclass constructors successfully completed) using the runServer() method of the class.

Parameters:
serverName the name under which the new server will be registered with the naming service when activated by the runServer() call.
Exceptions:
rdaInternalError thrown to indicate an attempt to create the server twice

Member Function Documentation

virtual bool rdaDeviceServerBase::clientConnectionHook (  const rdaClientInfo &  clientInfo  )  [virtual]
 

This virtual method is called by RDA when a new client wants to connect to the server.

The connection will be accepted if the method returns true, or refused if the return value is false. The rdaDeviceServerBase class provides a default implementation of the method which just returns true (accepts all connection requests). Derived classes can override the default implementation and provide their own access control mechanism.

Parameters:
clientInfo the information on client that wants to connect to the server.

virtual void rdaDeviceServerBase::get (  const rdaIOPoint &  iop,
const rdaData &  ctx,
rdaResult *  result
)  [virtual]
 

Allows to read a value at the specified I/O point.

This method is invoked when a client makes an asynchronous get call to a device that resides at this server. This class provides the default implementation of the method which does the following:

  • invokes the basic synchronous get method passing to it the iop and ctx parameters specified as the arguments to this call
  • reports results of the synchronous call (return value or exceptions) to the client via return methods of the result object.
Basically, it delegates the asynchronous call to the synchronous call. The method can be reimplemented in the servers which support true asynchronous I/O.
See also:
rdaDeviceHandle, rdaResult

virtual rdaData* rdaDeviceServerBase::get (  const rdaIOPoint &  iop,
const rdaData &  ctx
)  [pure virtual]
 

Allows to read a value at the specified I/O point.

This method is invoked when a client executes a get operation on a device that resides at this server.

Parameters:
iop the I/O point identifier
ctx the operation context as specified in the client call, or an empy rdaData object if context was not specified.
Returns:
pointer to a dynamically allocated rdaData object that contains the requested value. RDA "consumes" the pointer and will delete the data object when it is no more needed.

const rdaClientInfo* rdaDeviceServerBase::getClientInfo (   )  [static]
 

Allows to obtain information about a remote client that made a device call in a device access method (get, set, monitorOn, monitorOff) implementation.

If this method is invoked within the context of a device call, it will return a pointer to the object describing the calling client. This method returns NULL if it is invoked outside the context of a device call.

virtual rdaData* rdaDeviceServerBase::getState (   )  [virtual]
 

This virtual method is called when an administration client calls the getState method of the admin::ServerAdmin interface.

The default implementation of the method in the rdaDeviceServerBase class returns the state of the RDA server in a Data object which contains the following entries.

tag data type information
rda.numSubscriptions long The current number of subscriptions on the server
rda.maxSubscriptions long The maximum number of subscriptions that have ever been made on the server.
rda.maxClients short The maximum number of clients that have ever been simultaneously connected to this server.
rda.numGetCalls longlong The total number of "get" calls made by all clients to this server.
rda.numSetCalls longlong The total number of "set" calls made by all clients to this server.
rda.numMonCalls longlong The total number of "monitorOn" calls made by all clients to this server.
rda.numMofCalls longlong The total number of "monitorOff" calls made by all clients to this server.
rda.numReports longlong The total number of subscription reports sent by this server to all clients.
rda.numSessions longlong The total number of client sessions since the server startup, incremented each time a new client registers with the server.

If you want to add some information to the state data, first get the RDA server state by calling the superclass' method, then add to it your state variables. Here is an example implementation of this function from the Device Server Example.

class DeviceServer : public rdaDeviceServerBase
{
   ...
   virtual rdaData* getState()
   {
      //
      // Get the RDA server state
      //
      rdaData* result = rdaDeviceServerBase::getState();
      //
      // Add our state variable (updateTime) to the state data
      //
      result->insert("example.updateTime", updateTime);
      return result;
   }
   ...
};
Examples:
DeviceServer.h.

virtual ServerStatus rdaDeviceServerBase::getStatus (   )  [virtual]
 

This method is called when an administration client calls the getStatus method of the admin::ServerAdmin interface.

The default implementation of the method in the rdaDeviceServerBase class returns status of the RDA server. It can be overridden in subclasses so that the call will return the overall status of a device server. To do this, first evaluate the status at the subclass level, then compare it with the RDA status and return the higher severity value. Here is an example implementation of this function from the Device Server Example.

class DeviceServer : public rdaDeviceServerBase
{
   ...
   virtual ServerStatus getStatus()
   {
      //
      // Evaluate status of our server
      //
      ServerStatus myStatus;
      if (updateTime < 10) myStatus = STATUS_GREEN;       // OK
      else if (updateTime < 15) myStatus = STATUS_YELLOW; // heavy load
      else myStatus = STATUS_RED;                         // overloaded
      //
      // Get the status of the RDA server, compare it with our status,
      // and return the higher severity value.
      //
      ServerStatus result = rdaDeviceServerBase::getStatus();
      if (myStatus > result) result = myStatus;
      return result;
   }
   ...
};
Examples:
DeviceServer.h.

void rdaDeviceServerBase::init (  int  argc,
char **  argv
)  [static]
 

Initializes the RDA.

Must be called before any other RDA method with arguments to the main() as parameters.

Exceptions:
rdaInternalError thrown to indicate a fatal error in RDA.
Examples:
DeviceServer.cpp.

virtual void rdaDeviceServerBase::monitorOff (  const rdaIOPoint &  iop,
rdaValueChangeListener *  listener
)  [pure virtual]
 

Cancels a subscription identified by the I/O point and listener.

This call must not throw any exceptions.

virtual void rdaDeviceServerBase::monitorOn (  const rdaIOPoint &  iop,
const rdaData &  ctx,
rdaValueChangeListener *  listener
)  [pure virtual]
 

Starts a subscription to value at the specified I/O point.

This method is invoked when a client executes a monitorOn operation on a device that resides at this server.

Parameters:
iop the I/O point identifier
ctx the operation context as specified in the client call, or an empy rdaData object if context was not specified
listener the callback object that shall be notified on the value updates.

void rdaDeviceServerBase::runServer (   )  [static]
 

Makes the server available for clients.

Each device server must call this method when it is ready to accept client requests. The method registers the server with the naming service and enters event loop to receive incoming requests. The method only returns if the shutDown() method is called on the server.

Exceptions:
rdaInternalException thrown to indicate a recoverable error in the RDA runtime.
rdaInternalError thrown to indicate a fatal error in the RDA runtime.

virtual void rdaDeviceServerBase::set (  const rdaIOPoint &  iop,
const rdaData &  ctx,
const rdaData &  value,
rdaResult *  result
)  [virtual]
 

Changes a value at the specified I/O point.

This method is invoked when a client makes an asynchronous set call to a device that resides at this server. This class provides the default implementation of the method which does the following:

  • invokes the basic synchronous set method passing to it the iop, ctx and value parameters specified as the arguments to this call
  • reports results of the synchronous call (successfull completion or exceptions) to the client via return methods of the result object.
Basically, it delegates the asynchronous call to the synchronous call. The method can be reimplemented in the servers which support true asynchronous I/O.
See also:
rdaDeviceHandle, rdaResult

virtual void rdaDeviceServerBase::set (  const rdaIOPoint &  iop,
const rdaData &  ctx,
const rdaData &  value
)  [pure virtual]
 

Changes a value at the specified I/O point.

This method is invoked when a client executes a set operation on a device that resides at this server.

Parameters:
iop the I/O point identifier
ctx the operation context as specified in the client call, or an empy rdaData object if context was not specified
value the value to set.

void rdaDeviceServerBase::shutDown (  int  signo  )  [static]
 

Deactivates the server.

This method causes runServer() to return. It is intended for calling from within a signal handler to achieve clean server termination on signals like SIGINT, SIGHUP, and SIGTERM.

Parameters:
signo the terminating signal number.

void rdaDeviceServerBase::shutDown (   )  [static]
 

Deactivates the server.

This method causes runServer() to return. It can be called from a thread other then main (e.g., a poller) in order to achive clean server termination.

Examples:
DeviceServer.cpp, and Property.h.

virtual void rdaDeviceServerBase::shutdownHook (   )  [virtual]
 

This virtual method is called by RDA prior to the server shutdown.

The rdaDeviceServerBase class provides an empty implementation of this method; derived classes can override it if they need to perform any specific pre-shutdown cleanup in the server. This would typically include termination of I/O processes and threads (e.g., pollers) spawned by the server.

The documentation for this class was generated from the following file:
RDA-2.3 documentation - 27 Jun 2007 - N.Trofimov