Functions and callbacks to handle control model related operations on the server side. More...

Typedefs
typedef void *	ControlAction

typedef CheckHandlerResult(*	ControlPerformCheckHandler) (ControlAction action, void parameter, MmsValue ctlVal, bool test, bool interlockCheck)
	Control model callback to perform the static tests (optional). More...

typedef ControlHandlerResult(*	ControlWaitForExecutionHandler) (ControlAction action, void parameter, MmsValue ctlVal, bool test, bool synchroCheck)
	Control model callback to perform the dynamic tests (optional). More...

typedef ControlHandlerResult(*	ControlHandler) (ControlAction action, void parameter, MmsValue ctlVal, bool test)
	Control model callback to actually perform the control operation. More...

typedef void(*	ControlSelectStateChangedHandler) (ControlAction action, void *parameter, bool isSelected, SelectStateChangedReason reason)
	Control model callback that is called when the select state of a control changes. More...

Enumerations
enum	CheckHandlerResult { CONTROL_ACCEPTED = -1 , CONTROL_WAITING_FOR_SELECT = 0 , 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...

enum	SelectStateChangedReason { SELECT_STATE_REASON_SELECTED , SELECT_STATE_REASON_CANCELED , SELECT_STATE_REASON_TIMEOUT , SELECT_STATE_REASON_OPERATED , SELECT_STATE_REASON_OPERATE_FAILED , SELECT_STATE_REASON_DISCONNECTED }
	Reason why a select state of a control object changed. More...

Functions
LIB61850_API void	ControlAction_setError (ControlAction self, ControlLastApplError error)
	Sets the error code for the next command termination or application error message. More...

LIB61850_API void	ControlAction_setAddCause (ControlAction self, ControlAddCause addCause)
	Sets the add cause for the next command termination or application error message. More...

LIB61850_API int	ControlAction_getOrCat (ControlAction self)
	Gets the originator category provided by the client. More...

LIB61850_API uint8_t *	ControlAction_getOrIdent (ControlAction self, int *orIdentSize)
	Gets the originator identifier provided by the client. More...

LIB61850_API int	ControlAction_getCtlNum (ControlAction self)
	Get the ctlNum attribute send by the client. More...

LIB61850_API bool	ControlAction_getSynchroCheck (ControlAction self)
	Gets the synchroCheck bit provided by the client. More...

LIB61850_API bool	ControlAction_getInterlockCheck (ControlAction self)
	Gets the interlockCheck bit provided by the client. More...

LIB61850_API bool	ControlAction_isSelect (ControlAction self)
	Check if the control callback is called by a select or operate command. More...

LIB61850_API ClientConnection	ControlAction_getClientConnection (ControlAction self)
	Gets the client object associated with the client that caused the control action. More...

LIB61850_API DataObject *	ControlAction_getControlObject (ControlAction self)
	Gets the control object that is subject to this action. More...

LIB61850_API uint64_t	ControlAction_getControlTime (ControlAction self)
	Gets the time of the control (attribute "operTm"), if it's a timeActivatedControl, returns 0, if it's not. More...

LIB61850_API Timestamp *	ControlAction_getT (ControlAction self)
	Gets the time (attribute "T") of the last received control action (Oper or Select) More...

LIB61850_API void	IedServer_setControlHandler (IedServer self, DataObject node, ControlHandler handler, void parameter)
	Set control handler for controllable data object. More...

LIB61850_API void	IedServer_setPerformCheckHandler (IedServer self, DataObject node, ControlPerformCheckHandler handler, void parameter)
	Set a handler for a controllable data object to perform operative tests. More...

LIB61850_API void	IedServer_setWaitForExecutionHandler (IedServer self, DataObject node, ControlWaitForExecutionHandler handler, void parameter)
	Set a handler for a controllable data object to perform dynamic tests. More...

LIB61850_API void	IedServer_setSelectStateChangedHandler (IedServer self, DataObject node, ControlSelectStateChangedHandler handler, void parameter)
	Set a callback handler for a controllable data object to track select state changes. More...

LIB61850_API void	IedServer_updateCtlModel (IedServer self, DataObject *ctlObject, ControlModel value)
	Update the control model for the specified controllable data object with the given value and update "ctlModel" attribute value. More...

Detailed Description

Functions and callbacks to handle control model related operations on the server side.

Typedef Documentation

◆ ControlAction

typedef void* ControlAction

◆ ControlHandler

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

Control model callback to actually perform the control operation.

Note: Signature changed in version 1.4!

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

action	the control action parameter that provides access to additional context information
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

◆ ControlPerformCheckHandler

typedef CheckHandlerResult(* ControlPerformCheckHandler) (ControlAction action, void *parameter, MmsValue *ctlVal, bool test, bool interlockCheck)

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

Note: Signature changed in version 1.4!

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

action	the control action parameter that provides access to additional context information
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

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

◆ ControlSelectStateChangedHandler

typedef void(* ControlSelectStateChangedHandler) (ControlAction action, void *parameter, bool isSelected, SelectStateChangedReason reason)

Control model callback that is called when the select state of a control changes.

Note: New in version 1.5

Parameters

action	the control action parameter that provides access to additional context information
parameter	the parameter that was specified when setting the control handler
isSelected	true when the control is selected, false otherwise
reason	reason why the select state changed

◆ ControlWaitForExecutionHandler

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

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

Note: Signature changed in version 1.4!

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

action	the control action parameter that provides access to additional context information
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

◆ CheckHandlerResult

enum CheckHandlerResult

result code for ControlPerformCheckHandler

Enumerator
CONTROL_ACCEPTED	check passed
CONTROL_WAITING_FOR_SELECT	select operation in progress - handler will be called again later
CONTROL_HARDWARE_FAULT	check failed due to hardware fault
CONTROL_TEMPORARILY_UNAVAILABLE	control is already selected or operated
CONTROL_OBJECT_ACCESS_DENIED	check failed due to access control reason - access denied for this client or state
CONTROL_OBJECT_UNDEFINED	object not visible in this security context ???
CONTROL_VALUE_INVALID	ctlVal out of range

◆ ControlHandlerResult

enum ControlHandlerResult

result codes for control handler (ControlWaitForExecutionHandler and ControlHandler)

Enumerator
CONTROL_RESULT_FAILED	check or operation failed
CONTROL_RESULT_OK	check or operation was successful
CONTROL_RESULT_WAITING	check or operation is in progress

◆ SelectStateChangedReason

enum SelectStateChangedReason

Reason why a select state of a control object changed.

Enumerator
SELECT_STATE_REASON_SELECTED	control has been selected
SELECT_STATE_REASON_CANCELED	cancel received for the control
SELECT_STATE_REASON_TIMEOUT	unselected due to timeout (sboTimeout)
SELECT_STATE_REASON_OPERATED	unselected due to successful operate
SELECT_STATE_REASON_OPERATE_FAILED	unselected due to failed operate
SELECT_STATE_REASON_DISCONNECTED	unselected due to disconnection of selecting client

Function Documentation

◆ ControlAction_getClientConnection()

LIB61850_API ClientConnection ControlAction_getClientConnection ( ControlAction self )

Gets the client object associated with the client that caused the control action.

Parameters

self	the control action instance

Returns: client connection instance

◆ ControlAction_getControlObject()

LIB61850_API DataObject* ControlAction_getControlObject ( ControlAction self )

Gets the control object that is subject to this action.

Parameters

self	the control action instance

Returns: the controllable data object instance

◆ ControlAction_getControlTime()

LIB61850_API uint64_t ControlAction_getControlTime ( ControlAction self )

Gets the time of the control (attribute "operTm"), if it's a timeActivatedControl, returns 0, if it's not.

Parameters

self	the control action instance

Returns: the controllable data object instance

◆ ControlAction_getCtlNum()

LIB61850_API int ControlAction_getCtlNum ( ControlAction self )

Get the ctlNum attribute send by the client.

Parameters

self	the control action instance

Returns: the ctlNum value

◆ ControlAction_getInterlockCheck()

LIB61850_API bool ControlAction_getInterlockCheck ( ControlAction self )

Gets the interlockCheck bit provided by the client.

Parameters

self	the control action instance

Returns: the interlockCheck bit

◆ ControlAction_getOrCat()

LIB61850_API int ControlAction_getOrCat ( ControlAction self )

Gets the originator category provided by the client.

Parameters

self	the control action instance

Returns: the originator category

◆ ControlAction_getOrIdent()

LIB61850_API uint8_t* ControlAction_getOrIdent	(	ControlAction	self,
		int *	orIdentSize
	)

Gets the originator identifier provided by the client.

Parameters

self	the control action instance

Returns: the originator identifier

◆ ControlAction_getSynchroCheck()

LIB61850_API bool ControlAction_getSynchroCheck ( ControlAction self )

Gets the synchroCheck bit provided by the client.

Parameters

self	the control action instance

Returns: the synchroCheck bit

◆ ControlAction_getT()

LIB61850_API Timestamp* ControlAction_getT ( ControlAction self )

Gets the time (attribute "T") of the last received control action (Oper or Select)

Parameters

self	the control action instance

Returns: the time of the last received control action

◆ ControlAction_isSelect()

LIB61850_API bool ControlAction_isSelect ( ControlAction self )

Check if the control callback is called by a select or operate command.

Parameters

self	the control action instance

Returns: true, when called by select, false for operate

◆ ControlAction_setAddCause()

LIB61850_API void ControlAction_setAddCause	(	ControlAction	self,
		ControlAddCause	addCause
	)

Sets the add cause for the next command termination or application error message.

Parameters

self	the control action instance
addCause	the additional cause

◆ ControlAction_setError()

LIB61850_API void ControlAction_setError	(	ControlAction	self,
		ControlLastApplError	error
	)

Sets the error code for the next command termination or application error message.

Parameters

self	the control action instance
error	the error code

◆ IedServer_setControlHandler()

LIB61850_API 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.

◆ IedServer_setPerformCheckHandler()

LIB61850_API 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.

◆ IedServer_setSelectStateChangedHandler()

LIB61850_API void IedServer_setSelectStateChangedHandler	(	IedServer	self,
		DataObject *	node,
		ControlSelectStateChangedHandler	handler,
		void *	parameter
	)

Set a callback handler for a controllable data object to track select state changes.

The callback is called whenever the select state of a control changes. Reason for changes can be:

a successful select or select-with-value by a client
select timeout
operate or failed operate
cancel request by a client
the client that selected the control has been disconnected

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 callback handler.

◆ IedServer_setWaitForExecutionHandler()

LIB61850_API 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.

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.

◆ IedServer_updateCtlModel()

LIB61850_API void IedServer_updateCtlModel	(	IedServer	self,
		DataObject *	ctlObject,
		ControlModel	value
	)

Update the control model for the specified controllable data object with the given value and update "ctlModel" attribute value.

Note: The corresponding control structures for the control model have to be present in the data model!

Parameters

self	the instance of IedServer to operate on.
ctlObject	the controllable data object handle
value	the new control model value

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ ControlAction

◆ ControlHandler

◆ ControlPerformCheckHandler

◆ ControlSelectStateChangedHandler

◆ ControlWaitForExecutionHandler

Enumeration Type Documentation

◆ CheckHandlerResult

◆ ControlHandlerResult

◆ SelectStateChangedReason

Function Documentation

◆ ControlAction_getClientConnection()

◆ ControlAction_getControlObject()

◆ ControlAction_getControlTime()

◆ ControlAction_getCtlNum()

◆ ControlAction_getInterlockCheck()

◆ ControlAction_getOrCat()

◆ ControlAction_getOrIdent()

◆ ControlAction_getSynchroCheck()

◆ ControlAction_getT()

◆ ControlAction_isSelect()

◆ ControlAction_setAddCause()

◆ ControlAction_setError()

◆ IedServer_setControlHandler()

◆ IedServer_setPerformCheckHandler()

◆ IedServer_setSelectStateChangedHandler()

◆ IedServer_setWaitForExecutionHandler()

◆ IedServer_updateCtlModel()