Typedefs
typedef struct sControlObjectClient *	ControlObjectClient

typedef void(*	ControlObjectClient_ControlActionHandler) (uint32_t invokeId, void *parameter, IedClientError err, ControlActionType type, bool success)
	A callback handler that is invoked when a command termination message is received. More...

typedef void(*	CommandTerminationHandler) (void *parameter, ControlObjectClient controlClient)
	A callback handler that is invoked when a command termination message is received. More...

Enumerations
enum	ControlActionType { CONTROL_ACTION_TYPE_SELECT = 0 , CONTROL_ACTION_TYPE_OPERATE = 1 , CONTROL_ACTION_TYPE_CANCEL = 2 }

Functions
LIB61850_API ControlObjectClient	ControlObjectClient_create (const char *objectReference, IedConnection connection)
	Create a new client control object. More...

LIB61850_API ControlObjectClient	ControlObjectClient_createEx (const char objectReference, IedConnection connection, ControlModel ctlModel, MmsVariableSpecification controlObjectSpec)
	Create a new client control object - doesn't send requests to the server (doesn't block) More...

LIB61850_API void	ControlObjectClient_destroy (ControlObjectClient self)
	Destroy the client control object instance and release all related resources. More...

LIB61850_API const char *	ControlObjectClient_getObjectReference (ControlObjectClient self)
	Get the object reference of the control data object. More...

LIB61850_API ControlModel	ControlObjectClient_getControlModel (ControlObjectClient self)
	Get the current control model (local representation) applied to the control object. More...

LIB61850_API void	ControlObjectClient_setControlModel (ControlObjectClient self, ControlModel ctlModel)
	Set the applied control model. More...

LIB61850_API void	ControlObjectClient_changeServerControlModel (ControlObjectClient self, ControlModel ctlModel)
	Change the control model of the server. More...

LIB61850_API MmsType	ControlObjectClient_getCtlValType (ControlObjectClient self)
	Get the type of ctlVal. More...

LIB61850_API IedClientError	ControlObjectClient_getLastError (ControlObjectClient self)
	Get the error code of the last synchronous control action (operate, select, select-with-value, cancel) More...

LIB61850_API bool	ControlObjectClient_operate (ControlObjectClient self, MmsValue *ctlVal, uint64_t operTime)
	Send an operate command to the server. More...

LIB61850_API bool	ControlObjectClient_select (ControlObjectClient self)
	Send a select command to the server. More...

LIB61850_API bool	ControlObjectClient_selectWithValue (ControlObjectClient self, MmsValue *ctlVal)
	Send an select with value command to the server. More...

LIB61850_API bool	ControlObjectClient_cancel (ControlObjectClient self)
	Send a cancel command to the server. More...

LIB61850_API uint32_t	ControlObjectClient_operateAsync (ControlObjectClient self, IedClientError err, MmsValue ctlVal, uint64_t operTime, ControlObjectClient_ControlActionHandler handler, void *parameter)
	Send an operate command to the server - async version. More...

LIB61850_API uint32_t	ControlObjectClient_selectAsync (ControlObjectClient self, IedClientError err, ControlObjectClient_ControlActionHandler handler, void parameter)
	Send a select command to the server - async version. More...

LIB61850_API uint32_t	ControlObjectClient_selectWithValueAsync (ControlObjectClient self, IedClientError err, MmsValue ctlVal, ControlObjectClient_ControlActionHandler handler, void *parameter)
	Send a select-with-value command to the server - async version. More...

LIB61850_API uint32_t	ControlObjectClient_cancelAsync (ControlObjectClient self, IedClientError err, ControlObjectClient_ControlActionHandler handler, void parameter)
	Send a cancel command to the server - async version. More...

LIB61850_API LastApplError	ControlObjectClient_getLastApplError (ControlObjectClient self)
	Get the last received control application error. More...

LIB61850_API void	ControlObjectClient_setTestMode (ControlObjectClient self, bool value)
	Send commands in test mode. More...

LIB61850_API void	ControlObjectClient_setOrigin (ControlObjectClient self, const char *orIdent, int orCat)
	Set the origin parameter for control commands. More...

LIB61850_API void	ControlObjectClient_useConstantT (ControlObjectClient self, bool useConstantT)
	Use a constant T parameter for all command (select, operate, cancel) of a single control sequence. More...

LIB61850_API DEPRECATED void	ControlObjectClient_enableInterlockCheck (ControlObjectClient self)

LIB61850_API DEPRECATED void	ControlObjectClient_enableSynchroCheck (ControlObjectClient self)

LIB61850_API DEPRECATED void	ControlObjectClient_setCtlNum (ControlObjectClient self, uint8_t ctlNum)

LIB61850_API void	ControlObjectClient_setInterlockCheck (ControlObjectClient self, bool value)
	Set the value of the interlock check flag when a control command is sent. More...

LIB61850_API void	ControlObjectClient_setSynchroCheck (ControlObjectClient self, bool value)
	Set the value of the synchro check flag when a control command is sent. More...

LIB61850_API void	ControlObjectClient_setCommandTerminationHandler (ControlObjectClient self, CommandTerminationHandler handler, void *handlerParameter)
	Set the command termination callback handler for this control object. More...

Detailed Description

Typedef Documentation

◆ CommandTerminationHandler

typedef void(* CommandTerminationHandler) (void *parameter, ControlObjectClient controlClient)

A callback handler that is invoked when a command termination message is received.

This callback is invoked whenever a CommandTermination+ or CommandTermination- message is received. To distinguish between a CommandTermination+ and CommandTermination- please use the ControlObjectClient_getLastApplError function.

In case of CommandTermination+ the return value of ControlObjectClient_getLastApplError has error=CONTROL_ERROR_NO_ERROR and addCause=ADD_CAUSE_UNKNOWN set. When addCause is different from ADD_CAUSE_UNKNOWN then the client received a CommandTermination- message.

NOTE: Do not call ControlObjectClient_destroy inside of this callback! Doing so will cause a dead-lock.

Parameters

parameter	the user parameter that is passed to the callback function
controlClient	the ControlObjectClient instance

◆ ControlObjectClient

typedef struct sControlObjectClient* ControlObjectClient

◆ ControlObjectClient_ControlActionHandler

typedef void(* ControlObjectClient_ControlActionHandler) (uint32_t invokeId, void *parameter, IedClientError err, ControlActionType type, bool success)

A callback handler that is invoked when a command termination message is received.

This callback is invoked whenever a CommandTermination+ or CommandTermination- message is received. To distinguish between a CommandTermination+ and CommandTermination- please use the ControlObjectClient_getLastApplError function.

NOTE: Do not call ControlObjectClient_destroy inside of this callback! Doing so will cause a dead-lock.

Parameters

invokeId	invoke ID of the command sent by the client
parameter	the user parameter that is passed to the callback function
err	the error code when an error occurred, or IED_ERROR_OK
type	control action type that caused the callback
success	true, when the command was successful, false otherwise

Enumeration Type Documentation

◆ ControlActionType

enum ControlActionType

Cause of the ControlObjectClient_ControlActionHandler invocation

Enumerator
CONTROL_ACTION_TYPE_SELECT
CONTROL_ACTION_TYPE_OPERATE	< callback was invoked because of a select command
CONTROL_ACTION_TYPE_CANCEL	< callback was invoked because of an operate command

Function Documentation

◆ ControlObjectClient_cancel()

LIB61850_API bool ControlObjectClient_cancel ( ControlObjectClient self )

Send a cancel command to the server.

The cancel command can be used to stop an ongoing operation (when the server and application support this) and to cancel a former select command.

Parameters

self	the control object instance to use

Returns: true if operation has been successful, false otherwise.

◆ ControlObjectClient_cancelAsync()

LIB61850_API uint32_t ControlObjectClient_cancelAsync	(	ControlObjectClient	self,
		IedClientError *	err,
		ControlObjectClient_ControlActionHandler	handler,
		void *	parameter
	)

Send a cancel command to the server - async version.

The cancel command can be used to stop an ongoing operation (when the server and application support this) and to cancel a former select command.

Parameters

	self	the control object instance to use
[out]	err	error code
	handler	the user provided callback handler
	parameter	user provided parameter that is passed to the callback handler

Returns: the invoke ID of the request

◆ ControlObjectClient_changeServerControlModel()

LIB61850_API void ControlObjectClient_changeServerControlModel	(	ControlObjectClient	self,
		ControlModel	ctlModel
	)

Change the control model of the server.

NOTE: Not supported by all servers. Information can be found in the PIXIT of the server. Also sets the applied control model for this client control instance.

Parameters

self	the control object instance to use
ctlModel	the new control model

◆ ControlObjectClient_create()

LIB61850_API ControlObjectClient ControlObjectClient_create	(	const char *	objectReference,
		IedConnection	connection
	)

Create a new client control object.

A client control object is used to handle all client side functions of a controllable data object. A controllable data object is an instance of a controllable CDC like e.g. SPC, DPC, APC, ...

NOTE: This function will synchronously request information about the control object (like ctlModel) from the server. The function will block until these requests return or time-out.

Parameters

objectReference	the reference of the controllable data object
connection	the connection instance where the control object has to be reached

Returns: the newly created instance or NULL if the creation failed

◆ ControlObjectClient_createEx()

LIB61850_API ControlObjectClient ControlObjectClient_createEx	(	const char *	objectReference,
		IedConnection	connection,
		ControlModel	ctlModel,
		MmsVariableSpecification *	controlObjectSpec
	)

Create a new client control object - doesn't send requests to the server (doesn't block)

A client control object is used to handle all client side functions of a controllable data object. A controllable data object is an instance of a controllable CDC like e.g. SPC, DPC, APC, ...

Parameters

objectReference	the reference of the controllable data object
connection	the connection instance where the control object has to be reached
ctlModel	the control model used by the controllable data object
controlObjectSpec	specification of the controllable data objects - used to derive required information to handle the control object

◆ ControlObjectClient_destroy()

LIB61850_API void ControlObjectClient_destroy ( ControlObjectClient self )

Destroy the client control object instance and release all related resources.

Parameters

self	the control object instance to use

◆ ControlObjectClient_enableInterlockCheck()

LIB61850_API DEPRECATED void ControlObjectClient_enableInterlockCheck ( ControlObjectClient self )

Deprecated:: use ControlObjectClient_setInterlockCheck instead

◆ ControlObjectClient_enableSynchroCheck()

LIB61850_API DEPRECATED void ControlObjectClient_enableSynchroCheck ( ControlObjectClient self )

Deprecated:: use ControlObjectClient_setSynchroCheck instead

◆ ControlObjectClient_getControlModel()

LIB61850_API ControlModel ControlObjectClient_getControlModel ( ControlObjectClient self )

Get the current control model (local representation) applied to the control object.

Parameters

self	the control object instance to use

Returns: the current applied control model (ControlModel)

◆ ControlObjectClient_getCtlValType()

LIB61850_API MmsType ControlObjectClient_getCtlValType ( ControlObjectClient self )

Get the type of ctlVal.

This type is required for the ctlVal parameter of the ControlObjectClient_operate and ControlObjectClient_selectWithValue functions.

Parameters

self	the control object instance to use

Returns: MmsType required for the ctlVal value.

◆ ControlObjectClient_getLastApplError()

LIB61850_API LastApplError ControlObjectClient_getLastApplError ( ControlObjectClient self )

Get the last received control application error.

NOTE: this is the content of the "LastApplError" message received from the server.

Returns: the value of the last received application error

◆ ControlObjectClient_getLastError()

LIB61850_API IedClientError ControlObjectClient_getLastError ( ControlObjectClient self )

Get the error code of the last synchronous control action (operate, select, select-with-value, cancel)

Parameters

self	the control object instance to use

Returns: the client error code

◆ ControlObjectClient_getObjectReference()

LIB61850_API const char* ControlObjectClient_getObjectReference ( ControlObjectClient self )

Get the object reference of the control data object.

Parameters

self	the control object instance to use

Returns: the object reference (string is valid only as long as the ControlObjectClient instance exists).

◆ ControlObjectClient_operate()

LIB61850_API bool ControlObjectClient_operate	(	ControlObjectClient	self,
		MmsValue *	ctlVal,
		uint64_t	operTime
	)

Send an operate command to the server.

Parameters

self	the control object instance to use
ctlVal	the control value (for APC the value may be either AnalogueValue (MMS_STRUCT) or MMS_FLOAT/MMS_INTEGER
operTime	the time when the command has to be executed (for time activated control). The value represents the local time of the server in milliseconds since epoch. If this value is 0 the command will be executed instantly.

Returns: true if operation has been successful, false otherwise.

◆ ControlObjectClient_operateAsync()

LIB61850_API uint32_t ControlObjectClient_operateAsync	(	ControlObjectClient	self,
		IedClientError *	err,
		MmsValue *	ctlVal,
		uint64_t	operTime,
		ControlObjectClient_ControlActionHandler	handler,
		void *	parameter
	)

Send an operate command to the server - async version.

Parameters

	self	the control object instance to use
[out]	err	error code
	ctlVal	the control value (for APC the value may be either AnalogueValue (MMS_STRUCT) or MMS_FLOAT/MMS_INTEGER
	operTime	the time when the command has to be executed (for time activated control). The value represents the local time of the server in milliseconds since epoch. If this value is 0 the command will be executed instantly.
	handler	the user provided callback handler
	parameter	user provided parameter that is passed to the callback handler

Returns: the invoke ID of the request

◆ ControlObjectClient_select()

LIB61850_API bool ControlObjectClient_select ( ControlObjectClient self )

Send a select command to the server.

The select command is only used for the control model "select-before-operate with normal security" (CONTROL_MODEL_SBO_NORMAL). The select command has to be sent before the operate command can be used.

Parameters

self	the control object instance to use

Returns: true if operation has been successful, false otherwise.

◆ ControlObjectClient_selectAsync()

LIB61850_API uint32_t ControlObjectClient_selectAsync	(	ControlObjectClient	self,
		IedClientError *	err,
		ControlObjectClient_ControlActionHandler	handler,
		void *	parameter
	)

Send a select command to the server - async version.

The select command is only used for the control model "select-before-operate with normal security" (CONTROL_MODEL_SBO_NORMAL). The select command has to be sent before the operate command can be used.

Parameters

	self	the control object instance to use
[out]	err	error code
	handler	the user provided callback handler
	parameter	user provided parameter that is passed to the callback handler

Returns: the invoke ID of the request

◆ ControlObjectClient_selectWithValue()

LIB61850_API bool ControlObjectClient_selectWithValue	(	ControlObjectClient	self,
		MmsValue *	ctlVal
	)

Send an select with value command to the server.

The select-with-value command is only used for the control model "select-before-operate with enhanced security" (CONTROL_MODEL_SBO_ENHANCED). The select-with-value command has to be sent before the operate command can be used.

Parameters

self	the control object instance to use
ctlVal	the control value (for APC the value may be either AnalogueValue (MMS_STRUCT) or MMS_FLOAT/MMS_INTEGER

Returns: true if select has been successful, false otherwise.

◆ ControlObjectClient_selectWithValueAsync()

LIB61850_API uint32_t ControlObjectClient_selectWithValueAsync	(	ControlObjectClient	self,
		IedClientError *	err,
		MmsValue *	ctlVal,
		ControlObjectClient_ControlActionHandler	handler,
		void *	parameter
	)

Send a select-with-value command to the server - async version.

The select-with-value command is only used for the control model "select-before-operate with enhanced security" (CONTROL_MODEL_SBO_ENHANCED). The select-with-value command has to be sent before the operate command can be used.

Parameters

	self	the control object instance to use
[out]	err	error code
	ctlVal	the control value (for APC the value may be either AnalogueValue (MMS_STRUCT) or MMS_FLOAT/MMS_INTEGER
	handler	the user provided callback handler
	parameter	user provided parameter that is passed to the callback handler

Returns: the invoke ID of the request

◆ ControlObjectClient_setCommandTerminationHandler()

LIB61850_API void ControlObjectClient_setCommandTerminationHandler	(	ControlObjectClient	self,
		CommandTerminationHandler	handler,
		void *	handlerParameter
	)

Set the command termination callback handler for this control object.

This callback is invoked whenever a CommandTermination+ or CommandTermination- message is received. To distinguish between a CommandTermination+ and CommandTermination- please use the ControlObjectClient_getLastApplError function. In case of CommandTermination+ the return value of ControlObjectClient_getLastApplError has error=CONTROL_ERROR_NO_ERROR and addCause=ADD_CAUSE_UNKNOWN set. When addCause is different from ADD_CAUSE_UNKNOWN then the client received a CommandTermination- message.

Parameters

self	the ControlObjectClient instance
handler	the callback function to be used
handlerParameter	a user parameter that is passed to the handler

◆ ControlObjectClient_setControlModel()

LIB61850_API void ControlObjectClient_setControlModel	(	ControlObjectClient	self,
		ControlModel	ctlModel
	)

Set the applied control model.

NOTE: This function call will not change the server control model.

Parameters

self	the control object instance to use
ctlModel	the new control model to apply

◆ ControlObjectClient_setCtlNum()

LIB61850_API DEPRECATED void ControlObjectClient_setCtlNum	(	ControlObjectClient	self,
		uint8_t	ctlNum
	)

Deprecated:: Do not use (ctlNum is handled automatically by the library)! Intended for test purposes only.

◆ ControlObjectClient_setInterlockCheck()

LIB61850_API void ControlObjectClient_setInterlockCheck	(	ControlObjectClient	self,
		bool	value
	)

Set the value of the interlock check flag when a control command is sent.

Parameters

self	the ControlObjectClient instance
value	if true the server will perform a interlock check if supported

◆ ControlObjectClient_setOrigin()

LIB61850_API void ControlObjectClient_setOrigin	(	ControlObjectClient	self,
		const char *	orIdent,
		int	orCat
	)

Set the origin parameter for control commands.

The origin parameter is used to identify the client/application that sent a control command. It is intended for later analysis.

Parameters

self	the ControlObjectClient instance
orIdent	originator identification can be an arbitrary string
orCat	originator category (see Originator categories (orCat))

◆ ControlObjectClient_setSynchroCheck()

LIB61850_API void ControlObjectClient_setSynchroCheck	(	ControlObjectClient	self,
		bool	value
	)

Set the value of the synchro check flag when a control command is sent.

Parameters

self	the ControlObjectClient instance
value	if true the server will perform a synchro check if supported

◆ ControlObjectClient_setTestMode()

LIB61850_API void ControlObjectClient_setTestMode	(	ControlObjectClient	self,
		bool	value
	)

Send commands in test mode.

When the server supports test mode the commands that are sent with the test flag set are not executed (will have no effect on the attached physical process).

Parameters

self	the control object instance to use
value	value if the test flag (true = test mode).

◆ ControlObjectClient_useConstantT()

LIB61850_API void ControlObjectClient_useConstantT	(	ControlObjectClient	self,
		bool	useConstantT
	)

Use a constant T parameter for all command (select, operate, cancel) of a single control sequence.

NOTE: Some non-standard compliant servers may require this to accept oper/cancel requests

Parameters

self	the ControlObjectClient instance
useContantT	enable this behavior with true, disable with false

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ CommandTerminationHandler

◆ ControlObjectClient

◆ ControlObjectClient_ControlActionHandler

Enumeration Type Documentation

◆ ControlActionType

Function Documentation

◆ ControlObjectClient_cancel()

◆ ControlObjectClient_cancelAsync()

◆ ControlObjectClient_changeServerControlModel()

◆ ControlObjectClient_create()

◆ ControlObjectClient_createEx()

◆ ControlObjectClient_destroy()

◆ ControlObjectClient_enableInterlockCheck()

◆ ControlObjectClient_enableSynchroCheck()

◆ ControlObjectClient_getControlModel()

◆ ControlObjectClient_getCtlValType()

◆ ControlObjectClient_getLastApplError()

◆ ControlObjectClient_getLastError()

◆ ControlObjectClient_getObjectReference()

◆ ControlObjectClient_operate()

◆ ControlObjectClient_operateAsync()

◆ ControlObjectClient_select()

◆ ControlObjectClient_selectAsync()

◆ ControlObjectClient_selectWithValue()

◆ ControlObjectClient_selectWithValueAsync()

◆ ControlObjectClient_setCommandTerminationHandler()

◆ ControlObjectClient_setControlModel()

◆ ControlObjectClient_setCtlNum()

◆ ControlObjectClient_setInterlockCheck()

◆ ControlObjectClient_setOrigin()

◆ ControlObjectClient_setSynchroCheck()

◆ ControlObjectClient_setTestMode()

◆ ControlObjectClient_useConstantT()