Server side control model handling

Typedefs
typedef CheckHandlerResult(*	ControlPerformCheckHandler) (void *parameter, MmsValue *ctlVal, bool test, bool interlockCheck, ClientConnection connection)
	Control model callback to perform the static tests (optional). More...
typedef ControlHandlerResult(*	ControlWaitForExecutionHandler) (void *parameter, MmsValue *ctlVal, bool test, bool synchroCheck)
	Control model callback to perform the dynamic tests (optional). More...
typedef ControlHandlerResult(*	ControlHandler) (void *parameter, MmsValue *ctlVal, bool test)
	Control model callback to actually perform the control operation. More...

Enumerations
enum	CheckHandlerResult {   CONTROL_ACCEPTED = -1, CONTROL_HARDWARE_FAULT = 1, CONTROL_TEMPORARILY_UNAVAILABLE = 2, CONTROL_OBJECT_ACCESS_DENIED = 3,   CONTROL_OBJECT_UNDEFINED = 4, CONTROL_VALUE_INVALID = 11 }
	result code for ControlPerformCheckHandler More...
enum	ControlHandlerResult { CONTROL_RESULT_FAILED = 0, CONTROL_RESULT_OK = 1, CONTROL_RESULT_WAITING = 2 }
	result codes for control handler (ControlWaitForExecutionHandler and ControlHandler) More...

Functions
void	IedServer_setControlHandler (IedServer self, DataObject *node, ControlHandler handler, void *parameter)
	Set control handler for controllable data object. More...
void	IedServer_setPerformCheckHandler (IedServer self, DataObject *node, ControlPerformCheckHandler handler, void *parameter)
	Set a handler for a controllable data object to perform operative tests. More...
void	IedServer_setWaitForExecutionHandler (IedServer self, DataObject *node, ControlWaitForExecutionHandler handler, void *parameter)
	Set a handler for a controllable data object to perform dynamic tests. More...

Detailed Description

Typedef Documentation

typedef ControlHandlerResult(* ControlHandler) (void *parameter, MmsValue *ctlVal, bool test)

Control model callback to actually perform the control operation.

User provided callback function for the control model. It will be invoked when a control operation happens (Oper). Here the user should perform the control operation (e.g. by setting an digital output or switching a relay). NOTE: Since version 0.7.9 this function is intended to return immediately. If the operation cannot be performed immediately the function SHOULD return CONTROL_RESULT_WAITING and the handler will be invoked again later.

Parameters

parameter	the parameter that was specified when setting the control handler
ctlVal	the control value of the control operation.
test	indicates if the operate request is a test operation

Returns

CONTROL_RESULT_OK if the control action bas been successful, CONTROL_RESULT_FAILED otherwise, CONTROL_RESULT_WAITING if the test is not yet finished

typedef CheckHandlerResult(* ControlPerformCheckHandler) (void *parameter, MmsValue *ctlVal, bool test, bool interlockCheck, ClientConnection connection)

Control model callback to perform the static tests (optional).

User provided callback function for the control model. It will be invoked after a control operation has been invoked by the client. This callback function is intended to perform the static tests. It should check if the interlock conditions are met if the interlockCheck parameter is true. This handler can also be check if the client has the required permissions to execute the operation and allow or deny the operation accordingly.

Parameters

parameter	the parameter that was specified when setting the control handler
ctlVal	the control value of the control operation.
test	indicates if the operate request is a test operation
interlockCheck	the interlockCheck parameter provided by the client
connection	the connection object of the client connection that invoked the control operation

Returns

CONTROL_ACCEPTED if the static tests had been successful, one of the error codes otherwise

typedef ControlHandlerResult(* ControlWaitForExecutionHandler) (void *parameter, MmsValue *ctlVal, bool test, bool synchroCheck)

Control model callback to perform the dynamic tests (optional).

User provided callback function for the control model. It will be invoked after a control operation has been invoked by the client. This callback function is intended to perform the dynamic tests. It should check if the synchronization conditions are met if the synchroCheck parameter is set to true. NOTE: Since version 0.7.9 this function is intended to return immediately. If the operation cannot be performed immediately the function SHOULD return CONTROL_RESULT_WAITING and the handler will be invoked again later.

Parameters

parameter	the parameter that was specified when setting the control handler
ctlVal	the control value of the control operation.
test	indicates if the operate request is a test operation
synchroCheck	the synchroCheck parameter provided by the client

Returns

CONTROL_RESULT_OK if the dynamic tests had been successful, CONTROL_RESULT_FAILED otherwise, CONTROL_RESULT_WAITING if the test is not yet finished

Enumeration Type Documentation

enum CheckHandlerResult

result code for ControlPerformCheckHandler

Enumerator
CONTROL_ACCEPTED
CONTROL_HARDWARE_FAULT	check passed
CONTROL_TEMPORARILY_UNAVAILABLE	check failed due to hardware fault
CONTROL_OBJECT_ACCESS_DENIED	control is already selected or operated
CONTROL_OBJECT_UNDEFINED	check failed due to access control reason - access denied for this client or state
CONTROL_VALUE_INVALID	object not visible in this security context ???

enum ControlHandlerResult

result codes for control handler (ControlWaitForExecutionHandler and ControlHandler)

Enumerator
CONTROL_RESULT_FAILED
CONTROL_RESULT_OK	check or operation failed
CONTROL_RESULT_WAITING	check or operation was successful

Function Documentation

void IedServer_setControlHandler	(	IedServer	self,
		DataObject *	node,
		ControlHandler	handler,
		void *	parameter
	)

Set control handler for controllable data object.

This functions sets a user provided control handler for a data object. The data object has to be an instance of a controllable CDC (Common Data Class) like e.g. SPC, DPC or APC. The control handler is a callback function that will be called by the IEC server when a client invokes a control operation on the data object.

Parameters

self	the instance of IedServer to operate on.
node	the controllable data object handle
handler	a callback function of type ControlHandler
parameter	a user provided parameter that is passed to the control handler.

void IedServer_setPerformCheckHandler	(	IedServer	self,
		DataObject *	node,
		ControlPerformCheckHandler	handler,
		void *	parameter
	)

Set a handler for a controllable data object to perform operative tests.

This functions sets a user provided handler that should perform the operative tests for a control operation. Setting this handler is not required. If not set the server assumes that the checks will always be successful. The handler has to return true upon a successful test of false if the test fails. In the later case the control operation will be aborted.

Parameters

self	the instance of IedServer to operate on.
node	the controllable data object handle
handler	a callback function of type ControlHandler
parameter	a user provided parameter that is passed to the control handler.

void IedServer_setWaitForExecutionHandler	(	IedServer	self,
		DataObject *	node,
		ControlWaitForExecutionHandler	handler,
		void *	parameter
	)

Set a handler for a controllable data object to perform dynamic tests.

This functions sets a user provided handler that should perform the dynamic tests for a control operation. Setting this handler is not required. If not set the server assumes that the checks will always be successful. The handler has to return true upon a successful test of false if the test fails. In the later case the control operation will be aborted. If this handler is set than the server will start a new thread before calling the handler. This thread will also be used to execute the ControlHandler.

Parameters

self	the instance of IedServer to operate on.
node	the controllable data object handle
handler	a callback function of type ControlHandler
parameter	a user provided parameter that is passed to the control handler.