Main Page | Namespace List | Class Hierarchy | Alphabetical List | Data Structures | File List | Namespace Members | Data Fields | Globals

dcs::fee::FeeClientLibInterface Class Reference

#include <FeeClientLibInterface.hpp>

Inheritance diagram for dcs::fee::FeeClientLibInterface:

dcs::fee::FeeClientLibImp

Detailed Description

This virtual class presentes the interface of the FeeClient - library.

It has to be derived in an child class and the pure virtual functions have to be implemented in order to use the interface. In addition the user has to provide a handler routine for each FeeService, he subscribes to. This handler gives updated service values to the user. And the names of the FeeServers have to be given to the library. After this registration the user can start the FeeClient and send commands to a dedicated FeeServer.

See also:
registerFeeServerName for more information about registering FeeServers

registerServiceName for more information about registering FeeServices

startFeeClient for more information about starting the FeeClient

messageHandler for more information on how to receive messages.

acknowledgeHandler for more information on how to receive ACK data.

sendCommand for more information about sending commands.

stopFeeClient for more information about stopping the FeeClient.

clearFeeClient for more information about cleaning up.

Author:
Sebastian Bablok (Sebastian.Bablok@ift.uib.no)
Date:
2005-10-05


Public Member Functions

 FeeClientLibInterface ()
virtual ~FeeClientLibInterface ()
virtual void acknowledgeHandler (char *serverName, unsigned int size, char *data, unsigned int id, FlagBits flags, short errorCode, short ackState)=0
virtual void messageHandler (const MessageStruct msg)=0
bool registerFeeServerName (const char *serverName)
bool registerServiceName (const char *serviceName, void(*serviceHandler)(float fVal))
int startFeeClient ()
unsigned int sendCommand (char *serverName, unsigned int size, char *data, FlagBits flags)
bool stopFeeClient ()
int clearFeeClient ()
bool deactivateIDinList (int id)
bool checkIDinList (int id)

Private Member Functions

bool isNewFeeServerName (const char *feeServerName)
bool isNewServiceName (const char *feeServiceName)
void insertIDtoList (int id)
void lockListMutex ()
void unlockListMutex ()
void clearFeeServerVector ()
void clearServiceVector ()

Private Attributes

FeeClientCorempFeeClient
std::vector< char * > mServerNames
std::vector< FeeServiceStruct * > mServiceNames
std::map< int, bool > mIDList
pthread_mutex_t mListMutex


Constructor & Destructor Documentation

FeeClientLibInterface::FeeClientLibInterface  ) 
 

Constructor for the client interface.

FeeClientLibInterface::~FeeClientLibInterface  )  [virtual]
 

Destructor for the client interface.


Member Function Documentation

virtual void dcs::fee::FeeClientLibInterface::acknowledgeHandler char *  serverName,
unsigned int  size,
char *  data,
unsigned int  id,
FlagBits  flags,
short  errorCode,
short  ackState
[pure virtual]
 

This handler routine informs about new acknowledge from a FeeServer and offers the received data.

It has to be implemented in the derived classes to get the ACK.
NOTE: First the ackState has to be checked, it is possible, that some of the parameters are NULL, depending on the state.
[pure virtual]

Structure of the FlageBits:

NO_FLAGS 0x0000 // dec 0 CHECKSUM_FLAG 0x0002 // dec 2 FEESERVER_UPDATE_FLAG 0x0004 // dec 4 FEESERVER_RESTART_FLAG 0x0008 // dec 8 FEESERVER_REBOOT_FLAG 0x0010 // dec 16 FEESERVER_SHUTDOWN_FLAG 0x0020 // dec 32 FEESERVER_EXIT_FLAG 0x0040 // dec 64 FEESERVER_SET_DEADBAND_FLAG 0x0080 // dec 128 FEESERVER_GET_DEADBAND_FLAG 0x0100 // dec 256 FEESERVER_SET_ISSUE_TIMEOUT_FLAG 0x0200 // dec 512 FEESERVER_GET_ISSUE_TIMEOUT_FLAG 0x0400 // dec 1024 FEESERVER_SET_UPDATERATE_FLAG 0x0800 // dec 2048 FEESERVER_GET_UPDATERATE_FLAG 0x1000 // dec 4096 FEESERVER_SET_LOGLEVEL_FLAG 0x2000 // dec 8192 FEESERVER_GET_CONFIGURATION_FLAG 0x4000 // dec 16384 --------------------------------------------------------------------

Data structure in case of an ACK to a getter command:
FEESERVER_GET_DEADBAND_FLAG:
(gets deadband of a specified service value)
-> { deadband[sizeof(float))] | servicename of deadband[rest of data] }

FEESERVER_GET_ISSUE_TIMEOUT_FLAG:
(gets timeout for execution of commands inside the control engine in ms)

-> { issue timeout [sizeof(unsigned long)] }

FEESERVER_GET_UPDATERATE_FLAG:
(gets update rate of the deadband checker for service values in ms)

-> { update rate [sizeof(unsigned short)] }

FEESERVER_GET_CONFIGURATION_FLAG:
(this structure has not implemented yet, but it consists of a summary of the above menmtioned configuration settings.)

Parameters:
serverName name of the Server, which has received this ack
size the size of the received acknowledge data
data pointer to the acknowledge data (pass by pointer)
id the id of the corresponding command to this ack
flags informs about the received flags of the ack data, NOTE: these are not necessarily the same like the command
errorCode passes a possible error code inside the FeePacket header to the handler.
ackState passes the state of the Acknowledge:
FEE_OK - Link available, FeePacket valid
FEE_ACK_CORRUPTED - Link available, FeePacket to small -> their is NO DATA
FEE_CHECKSUM_FAILED - Link available, FeePacket checksum failed, but data available
FEE_ACK_LINK_DOWN - no Link available, NO DATA
See also:
feepacket_flags.h for more information

fee_errors.h for more information

Implemented in dcs::fee::FeeClientLibImp.

bool FeeClientLibInterface::checkIDinList int  id  ) 
 

Removes an ACK ID from the pending ID map.

If its value is false, the ACK is already regarded as lost. In that case only a message will be written to the message channel and the ACK shall be discarded.
This function is not part of the interface and should only be called by an FeeAckInfo object.

Parameters:
id the ID, which shall be checked and removed from the map
Returns:
true, if the ID is expected, false, if the ID is not in the map or its value is false (ACK already regarded as lost -> discard ACK then).

int FeeClientLibInterface::clearFeeClient  ) 
 

Function to clear all registered FeeServers and FeeServices.

This can only to executed, if the FeeClient is not in the running state.

Returns:
the amount of services + FeeServers, which are deleted. A negative number (FEE_CLIENT_WRONG_STATE) is returned, if the FeeClient is in the wrong state.

void FeeClientLibInterface::clearFeeServerVector  )  [private]
 

Clears the local vector of FeeServer names.

void FeeClientLibInterface::clearServiceVector  )  [private]
 

Clears the local vector of FeeService structs.

bool FeeClientLibInterface::deactivateIDinList int  id  ) 
 

Sets a pending ACK ID to false -> timeout, ACK no longer expected.


This function belonmgs as well to the interface and should not be called by the Lib itself, only by the implementation. The Lib does not include a timeout mechsnism for now.

Parameters:
id the ID to deactivate
Returns:
true, if ID is in list and its value true; false, if ID is not in map or its value is already false.

void FeeClientLibInterface::insertIDtoList int  id  )  [private]
 

Function to insert an ID in the map of pending ACK IDs.

If this ID already exists, its value is set to true, which indicates that it will be accepted when an ACK with the corresponding ID arrives. If the value has been false before, the ACK has been regarded as lost; if the value has been true before, a message will be written to the message channel (possible reasons: the FeeClientLib has not been notified about a timeout for this ID, or a collision might occur, when the mssing ACK arrives in between). If an ACK arrives with an ID corresponding to a false value, a message will be send to the message channel as well.

Parameters:
id the ID to insert into map

bool FeeClientLibInterface::isNewFeeServerName const char *  feeServerName  )  [private]
 

Checks, if a given FeeServer name is already in the local vector.

Parameters:
feeServerName the new name, which shall be checked
Returns:
false, if the name already exists in the local vector.

bool FeeClientLibInterface::isNewServiceName const char *  feeServiceName  )  [private]
 

Checks, if a given FeeService name is already in the local vector.

Parameters:
feeServiceName the new name, which shall be checked
Returns:
false, if the name already exists in the local vector.

void FeeClientLibInterface::lockListMutex  )  [private]
 

Function to lock the ID list mutex.

virtual void dcs::fee::FeeClientLibInterface::messageHandler const MessageStruct  msg  )  [pure virtual]
 

This handler routine informs about new received log message (remote and local).

It has to be implemented in the derived classes, the message can be retrieved via the parameter msg.
[pure virtual]

Parameters:
msg this message struct contains the current log message for this handler routine. (pass by value)

Implemented in dcs::fee::FeeClientLibImp.

bool FeeClientLibInterface::registerFeeServerName const char *  serverName  ) 
 

This function registers a FeeServer name to which the FeeClient should connect to.

This is only possible during init state, registering afterwards will return an error. If the name already exists in the local vector, no additional copy is included.

Parameters:
serverName FeeServer name, for the FeeClient to connect to.
Returns:
false, if the FeeClient has already been connected to the FeeServers (or if serverName is NULL).

bool FeeClientLibInterface::registerServiceName const char *  serviceName,
void(*  serviceHandler)(float fVal)
 

This function registers a FeeService to which the FeeClient should connect to.

It needs the name of the desired service and has to register the corresponding handler function. This is only possible during init state, registering afterwards will return an error. If the name already exists in the local vector, no additional copy is included.

Parameters:
serviceName FeeServer name, for the FeeClient to connect to.
serviceHandler() function pointer to the corresponding handler, the float value, it accepts, is the new value of an updated service.
NOTE: This function has to be implemented by the user of the FeeClient - library and its pointer passed to registerServiceName(...). Each time the value of this service is updated, the new value is passed to the user via this function.
Returns:
false, if the FeeClient has already been connected to the FeeServers (or if serviceName or function pointer is NULL).

unsigned int FeeClientLibInterface::sendCommand char *  serverName,
unsigned int  size,
char *  data,
FlagBits  flags
 

Function to send a command to a specified FeeServer.

If no FlagBits for FeeServer (core) commands are set, this data is delivered to the ControlEngine and executed there. Commands to the FeeServer core (see FlagBits) never reach the ControlEngine and have a defined structure (see below).

Structure of the FlageBits:

NO_FLAGS 0x0000 // dec 0 CHECKSUM_FLAG 0x0002 // dec 2 FEESERVER_UPDATE_FLAG 0x0004 // dec 4 (experts only!) FEESERVER_RESTART_FLAG 0x0008 // dec 8 FEESERVER_REBOOT_FLAG 0x0010 // dec 16 FEESERVER_SHUTDOWN_FLAG 0x0020 // dec 32 FEESERVER_EXIT_FLAG 0x0040 // dec 64 FEESERVER_SET_DEADBAND_FLAG 0x0080 // dec 128 FEESERVER_GET_DEADBAND_FLAG 0x0100 // dec 256 FEESERVER_SET_ISSUE_TIMEOUT_FLAG 0x0200 // dec 512 FEESERVER_GET_ISSUE_TIMEOUT_FLAG 0x0400 // dec 1024 FEESERVER_SET_UPDATERATE_FLAG 0x0800 // dec 2048 FEESERVER_GET_UPDATERATE_FLAG 0x1000 // dec 4096 FEESERVER_SET_LOGLEVEL_FLAG 0x2000 // dec 8192 FEESERVER_GET_CONFIGURATION_FLAG 0x4000 // dec 16384 --------------------------------------------------------------------

Structure of the FlageBits:
FEESERVER_UPDATE_FLAG:
(this command should be executed only by experts, it updates the whole FeeServer with a new binary)
-> { binary of the new FeeServer [sizeof(data)] }

FEESERVER_SET_DEADBAND_FLAG:
(sets deadband of a specified service value)

-> { deadband[sizeof(float))] | servicename of deadband[rest of data] }

FEESERVER_GET_DEADBAND_FLAG:
(requests deadband of a specified service value)

-> { servicename of deadband [sizeof(data)] }

FEESERVER_SET_ISSUE_TIMEOUT_FLAG:
(sets timeout for execution of commands inside the control engine in ms)

-> { issue timeout [sizeof(unsigned long)] }

FEESERVER_SET_UPDATERATE_FLAG:
(sets update rate of the deadband checker for service values in ms)

-> { update rate [sizeof(unsigned short)] }

FEESERVER_SET_LOGLEVEL_FLAG:
(sets log level in the specified FeeServer (MSG_ALARM is always on), see LogLevels for further details)

-> { log level [sizeof(unsigned int)] }
(all other flags do not contain any command data; there ack may, depending on the command).
NOTE: A "0" (FEE_CLIENT_NOT_STARTED) is returned, if the FeeRootclient has already been started.

Parameters:
serverName name of the Server, to which the command shall be sent
size the size of the to sent command data
data pointer to the to sent command data
flags which should be set for this command packet
Returns:
the id of the command is returned to the interface to identify the corresponding acknowledge afterwards. A "0" (FEE_CLIENT_NOT_STARTED) is returned, if the FeeClient has not been started yet.
NOTE: FEE_CLIENT_NOT_STARTED is also returned, if the given server name is NULL.
See also:
feepacket_flags.h for more information

fee_loglevels.h for detailed description of log levels

int FeeClientLibInterface::startFeeClient  ) 
 

Starts the FeeClient.

It subscibes to all registered FeeServers and their registered service. The amount of subscribed services is returned.
NOTE: The amount contains an ACK and a message channel per FeeSever + registered services.
NOTE: A negative number (FEE_CLIENT_WRONG_STATE) is returned, if the FeeClient has already been started.

Returns:
the amount of services, the FeeClient has subscribed to. A negative number (FEE_CLIENT_WRONG_STATE) is returned, if the FeeClient is in the wrong state.

bool FeeClientLibInterface::stopFeeClient  ) 
 

Function to stop the FeeClient.

Only the subscribed channels are deregistered, but the corresponding container are NOT cleared. A new call of startFeeClient() will result in the same connections. It is possible to register additional FeeServices and FeeServer before restarting the FeeClient.
To empty the corresponding containers (clear all subscribed FeeServices and FeeServers) call clearFeeClient() after stopping the FeeClient. It is only possible to stop the FeeClient, if it is in running state.

Returns:
false, if FeeClient is in the wrong state

void FeeClientLibInterface::unlockListMutex  )  [private]
 

Function to unlock the ID list mutex.


Field Documentation

std::map<int, bool> dcs::fee::FeeClientLibInterface::mIDList [private]
 

List of pending packet IDs.

This container contains a list of IDs for which an ACK is expected.

pthread_mutex_t dcs::fee::FeeClientLibInterface::mListMutex [private]
 

Mutex variable to protect the map from concurrent access.

FeeClientCore* dcs::fee::FeeClientLibInterface::mpFeeClient [private]
 

The pointer to the FeeClientCore.

std::vector<char* > dcs::fee::FeeClientLibInterface::mServerNames [private]
 

Vector of FeeServer names for subscribing to at the end of init process.

std::vector<FeeServiceStruct* > dcs::fee::FeeClientLibInterface::mServiceNames [private]
 

Vector of FeeServiceStructs for subscribing to at the end of init process.

The FeeServiceStruct contains the FeeService name and the pointer to its handler function.


The documentation for this class was generated from the following files:
Generated on Thu Mar 29 19:21:15 2007 for Fee Client Library by doxygen 1.3.5