libiec61850  1.5.3
Typedefs | Enumerations | Functions
Client side control service functions

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
parameterthe user parameter that is passed to the callback function
controlClientthe 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
invokeIdinvoke ID of the command sent by the client
parameterthe user parameter that is passed to the callback function
errthe error code when an error occurred, or IED_ERROR_OK
typecontrol action type that caused the callback
successtrue, when the command was successful, false otherwise

Enumeration Type Documentation

◆ 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
selfthe 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
selfthe control object instance to use
[out]errerror code
handlerthe user provided callback handler
parameteruser 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
selfthe control object instance to use
ctlModelthe 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
objectReferencethe reference of the controllable data object
connectionthe 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
objectReferencethe reference of the controllable data object
connectionthe connection instance where the control object has to be reached
ctlModelthe control model used by the controllable data object
controlObjectSpecspecification 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
selfthe 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
selfthe 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
selfthe 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
selfthe 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
selfthe 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
selfthe control object instance to use
ctlValthe control value (for APC the value may be either AnalogueValue (MMS_STRUCT) or MMS_FLOAT/MMS_INTEGER
operTimethe 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
selfthe control object instance to use
[out]errerror code
ctlValthe control value (for APC the value may be either AnalogueValue (MMS_STRUCT) or MMS_FLOAT/MMS_INTEGER
operTimethe 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.
handlerthe user provided callback handler
parameteruser 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
selfthe 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
selfthe control object instance to use
[out]errerror code
handlerthe user provided callback handler
parameteruser 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
selfthe control object instance to use
ctlValthe 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
selfthe control object instance to use
[out]errerror code
ctlValthe control value (for APC the value may be either AnalogueValue (MMS_STRUCT) or MMS_FLOAT/MMS_INTEGER
handlerthe user provided callback handler
parameteruser 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
selfthe ControlObjectClient instance
handlerthe callback function to be used
handlerParametera 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
selfthe control object instance to use
ctlModelthe 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
selfthe ControlObjectClient instance
valueif 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
selfthe ControlObjectClient instance
orIdentoriginator identification can be an arbitrary string
orCatoriginator 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
selfthe ControlObjectClient instance
valueif 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
selfthe control object instance to use
valuevalue 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
selfthe ControlObjectClient instance
useContantTenable this behavior with true, disable with false