libIEC61850  0.8.3
Open-source IEC 61850 MMS/GOOSE server and client library
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Groups Pages
Macros | Typedefs | Enumerations | Functions
Client side report handling services, functions, and data types

Macros

#define RCB_ELEMENT_RPT_ID   1
 
#define RCB_ELEMENT_RPT_ENA   2
 
#define RCB_ELEMENT_RESV   4
 
#define RCB_ELEMENT_DATSET   8
 
#define RCB_ELEMENT_CONF_REV   16
 
#define RCB_ELEMENT_OPT_FLDS   32
 
#define RCB_ELEMENT_BUF_TM   64
 
#define RCB_ELEMENT_SQ_NUM   128
 
#define RCB_ELEMENT_TRG_OPS   256
 
#define RCB_ELEMENT_INTG_PD   512
 
#define RCB_ELEMENT_GI   1024
 
#define RCB_ELEMENT_PURGE_BUF   2048
 
#define RCB_ELEMENT_ENTRY_ID   4096
 
#define RCB_ELEMENT_TIME_OF_ENTRY   8192
 
#define RCB_ELEMENT_RESV_TMS   16384
 
#define RCB_ELEMENT_OWNER   32768
 

Typedefs

typedef void(* ReportCallbackFunction )(void *parameter, ClientReport report)
 Callback function for receiving reports. More...
 

Enumerations

enum  ReasonForInclusion {
  REASON_NOT_INCLUDED = 0, REASON_DATA_CHANGE = 1, REASON_QUALITY_CHANGE = 2, REASON_DATA_UPDATE = 3,
  REASON_INTEGRITY = 4, REASON_GI = 5, REASON_UNKNOWN = 6
}
 

Functions

ClientReportControlBlock IedConnection_getRCBValues (IedConnection self, IedClientError *error, char *rcbReference, ClientReportControlBlock updateRcb)
 Read access to attributes of a report control block (RCB) at the connected server. More...
 
void IedConnection_setRCBValues (IedConnection self, IedClientError *error, ClientReportControlBlock rcb, uint32_t parametersMask, bool singleRequest)
 Write access to attributes of a report control block (RCB) at the connected server. More...
 
void IedConnection_installReportHandler (IedConnection self, char *rcbReference, char *rptId, ReportCallbackFunction handler, void *handlerParameter)
 Install a report handler function for the specified report control block (RCB) More...
 
void IedConnection_uninstallReportHandler (IedConnection self, char *rcbReference)
 uninstall a report handler function for the specified report control block (RCB) More...
 
void IedConnection_triggerGIReport (IedConnection self, IedClientError *error, char *rcbReference)
 Trigger a general interrogation (GI) report for the specified report control block (RCB) More...
 
MmsValueClientReport_getDataSetValues (ClientReport self)
 return the received data set values of the report More...
 
char * ClientReport_getRcbReference (ClientReport self)
 return reference (name) of the server RCB associated with this ClientReport object More...
 
char * ClientReport_getRptId (ClientReport self)
 return RptId of the server RCB associated with this ClientReport object More...
 
ReasonForInclusion ClientReport_getReasonForInclusion (ClientReport self, int elementIndex)
 get the reason code (reason for inclusion) for a specific report data set element More...
 
MmsValueClientReport_getEntryId (ClientReport self)
 get the entry ID of the report More...
 
bool ClientReport_hasTimestamp (ClientReport self)
 determine if the last received report contains a timestamp More...
 
bool ClientReport_hasSeqNum (ClientReport self)
 
uint16_t ClientReport_getSeqNum (ClientReport self)
 
bool ClientReport_hasDataSetName (ClientReport self)
 
bool ClientReport_hasReasonForInclusion (ClientReport self)
 
bool ClientReport_hasConfRev (ClientReport self)
 
uint32_t ClientReport_getConfRev (ClientReport self)
 
bool ClientReport_hasBufOvfl (ClientReport self)
 
bool ClientReport_hasDataReference (ClientReport self)
 
uint64_t ClientReport_getTimestamp (ClientReport self)
 get the timestamp of the report More...
 
char * ReasonForInclusion_getValueAsString (ReasonForInclusion reasonCode)
 get the reason for inclusion of as a human readable string More...
 
ClientReportControlBlock ClientReportControlBlock_create (char *rcbReference)
 
void ClientReportControlBlock_destroy (ClientReportControlBlock self)
 
char * ClientReportControlBlock_getObjectReference (ClientReportControlBlock self)
 
bool ClientReportControlBlock_isBuffered (ClientReportControlBlock self)
 
char * ClientReportControlBlock_getRptId (ClientReportControlBlock self)
 
void ClientReportControlBlock_setRptId (ClientReportControlBlock self, char *rptId)
 
bool ClientReportControlBlock_getRptEna (ClientReportControlBlock self)
 
void ClientReportControlBlock_setRptEna (ClientReportControlBlock self, bool rptEna)
 
bool ClientReportControlBlock_getResv (ClientReportControlBlock self)
 
void ClientReportControlBlock_setResv (ClientReportControlBlock self, bool resv)
 
char * ClientReportControlBlock_getDataSetReference (ClientReportControlBlock self)
 
void ClientReportControlBlock_setDataSetReference (ClientReportControlBlock self, char *dataSetReference)
 set the data set to be observed by the RCB More...
 
uint32_t ClientReportControlBlock_getConfRev (ClientReportControlBlock self)
 
int ClientReportControlBlock_getOptFlds (ClientReportControlBlock self)
 
void ClientReportControlBlock_setOptFlds (ClientReportControlBlock self, int optFlds)
 
uint32_t ClientReportControlBlock_getBufTm (ClientReportControlBlock self)
 
void ClientReportControlBlock_setBufTm (ClientReportControlBlock self, uint32_t bufTm)
 
uint16_t ClientReportControlBlock_getSqNum (ClientReportControlBlock self)
 
int ClientReportControlBlock_getTrgOps (ClientReportControlBlock self)
 
void ClientReportControlBlock_setTrgOps (ClientReportControlBlock self, int trgOps)
 
uint32_t ClientReportControlBlock_getIntgPd (ClientReportControlBlock self)
 
void ClientReportControlBlock_setIntgPd (ClientReportControlBlock self, uint32_t intgPd)
 
bool ClientReportControlBlock_getGI (ClientReportControlBlock self)
 
void ClientReportControlBlock_setGI (ClientReportControlBlock self, bool gi)
 
bool ClientReportControlBlock_getPurgeBuf (ClientReportControlBlock self)
 
void ClientReportControlBlock_setPurgeBuf (ClientReportControlBlock self, bool purgeBuf)
 
int16_t ClientReportControlBlock_getResvTms (ClientReportControlBlock self)
 
void ClientReportControlBlock_setResvTms (ClientReportControlBlock self, int16_t resvTms)
 
MmsValueClientReportControlBlock_getEntryId (ClientReportControlBlock self)
 
void ClientReportControlBlock_setEntryId (ClientReportControlBlock self, MmsValue *entryId)
 
uint64_t ClientReportControlBlock_getEntryTime (ClientReportControlBlock self)
 
MmsValueClientReportControlBlock_getOwner (ClientReportControlBlock self)
 

Detailed Description

Macro Definition Documentation

#define RCB_ELEMENT_BUF_TM   64

include the bufTm (event buffering time) element into the setRCB request

#define RCB_ELEMENT_CONF_REV   16

include the configuration revision element into the setRCB request

#define RCB_ELEMENT_DATSET   8

include the data set element into the setRCB request

#define RCB_ELEMENT_ENTRY_ID   4096

include the entry ID element into the setRCB request (only available in buffered RCBs)

#define RCB_ELEMENT_GI   1024

include the GI (general interrogation) element into the setRCB request

#define RCB_ELEMENT_INTG_PD   512

include the integrity period element into the setRCB request

#define RCB_ELEMENT_OPT_FLDS   32

include the option fields element into the setRCB request

#define RCB_ELEMENT_OWNER   32768

include the owner element into the setRCB request

#define RCB_ELEMENT_PURGE_BUF   2048

include the purge buffer element into the setRCB request (only available in buffered RCBs)

#define RCB_ELEMENT_RESV   4

include the reservation element into the setRCB request (only available in unbuffered RCBs!)

#define RCB_ELEMENT_RESV_TMS   16384

include the reservation time element into the setRCB request (only available in buffered RCBs)

#define RCB_ELEMENT_RPT_ENA   2

include the report enable element into the setRCB request

#define RCB_ELEMENT_RPT_ID   1

include the report ID into the setRCB request

#define RCB_ELEMENT_SQ_NUM   128

include the sequence number element into the setRCB request (should be used!)

#define RCB_ELEMENT_TIME_OF_ENTRY   8192

include the time of entry element into the setRCB request (only available in buffered RCBs)

#define RCB_ELEMENT_TRG_OPS   256

include the trigger options element into the setRCB request

Typedef Documentation

typedef void(* ReportCallbackFunction)(void *parameter, ClientReport report)

Callback function for receiving reports.

Parameters
parametera user provided parameter that is handed to the callback function
reporta ClientReport instance that holds the informations contained in the received report

Enumeration Type Documentation

Describes the reason for the inclusion of the element in the report

Enumerator
REASON_NOT_INCLUDED 

the element is not included in the received report

REASON_DATA_CHANGE 

the element is included due to a change of the data value

REASON_QUALITY_CHANGE 

the element is included due to a change in the quality of data

REASON_DATA_UPDATE 

the element is included due to an update of the data value

REASON_INTEGRITY 

the element is included due to a periodic integrity report task

REASON_GI 

the element is included due to a general interrogation by the client

REASON_UNKNOWN 

the reason for inclusion is unknown

Function Documentation

uint32_t ClientReport_getConfRev ( ClientReport  self)
MmsValue* ClientReport_getDataSetValues ( ClientReport  self)

return the received data set values of the report

Parameters
selfthe ClientReport instance
Returns
an MmsValue array instance containing the data set values
MmsValue* ClientReport_getEntryId ( ClientReport  self)

get the entry ID of the report

Returns the entryId of the report if included in the report. Otherwise returns NULL.

Parameters
selfthe ClientReport instance
Returns
entryId or NULL
char* ClientReport_getRcbReference ( ClientReport  self)

return reference (name) of the server RCB associated with this ClientReport object

Parameters
selfthe ClientReport instance
Returns
report control block reference as string
ReasonForInclusion ClientReport_getReasonForInclusion ( ClientReport  self,
int  elementIndex 
)

get the reason code (reason for inclusion) for a specific report data set element

Parameters
selfthe ClientReport instance
elementIndexindex of the data set element (starting with 0)
Returns
reason code for the inclusion of the specified element
char* ClientReport_getRptId ( ClientReport  self)

return RptId of the server RCB associated with this ClientReport object

Parameters
selfthe ClientReport instance
Returns
report control block reference as string
uint16_t ClientReport_getSeqNum ( ClientReport  self)
uint64_t ClientReport_getTimestamp ( ClientReport  self)

get the timestamp of the report

Returns the timestamp of the report if included in the report. Otherwise the value is undefined. Use the ClientReport_hasTimestamp function first to figure out if the timestamp is valid

Parameters
selfthe ClientReport instance
Returns
the timestamp as milliseconds since 1.1.1970 UTC
bool ClientReport_hasBufOvfl ( ClientReport  self)
bool ClientReport_hasConfRev ( ClientReport  self)
bool ClientReport_hasDataReference ( ClientReport  self)
bool ClientReport_hasDataSetName ( ClientReport  self)
bool ClientReport_hasReasonForInclusion ( ClientReport  self)
bool ClientReport_hasSeqNum ( ClientReport  self)
bool ClientReport_hasTimestamp ( ClientReport  self)

determine if the last received report contains a timestamp

Parameters
selfthe ClientReport instance
Returns
true if the report contains a timestamp, false otherwise
ClientReportControlBlock ClientReportControlBlock_create ( char *  rcbReference)
void ClientReportControlBlock_destroy ( ClientReportControlBlock  self)
uint32_t ClientReportControlBlock_getBufTm ( ClientReportControlBlock  self)
uint32_t ClientReportControlBlock_getConfRev ( ClientReportControlBlock  self)
char* ClientReportControlBlock_getDataSetReference ( ClientReportControlBlock  self)
MmsValue* ClientReportControlBlock_getEntryId ( ClientReportControlBlock  self)
uint64_t ClientReportControlBlock_getEntryTime ( ClientReportControlBlock  self)
bool ClientReportControlBlock_getGI ( ClientReportControlBlock  self)
uint32_t ClientReportControlBlock_getIntgPd ( ClientReportControlBlock  self)
char* ClientReportControlBlock_getObjectReference ( ClientReportControlBlock  self)
int ClientReportControlBlock_getOptFlds ( ClientReportControlBlock  self)
MmsValue* ClientReportControlBlock_getOwner ( ClientReportControlBlock  self)
bool ClientReportControlBlock_getPurgeBuf ( ClientReportControlBlock  self)
bool ClientReportControlBlock_getResv ( ClientReportControlBlock  self)
int16_t ClientReportControlBlock_getResvTms ( ClientReportControlBlock  self)
bool ClientReportControlBlock_getRptEna ( ClientReportControlBlock  self)
char* ClientReportControlBlock_getRptId ( ClientReportControlBlock  self)
uint16_t ClientReportControlBlock_getSqNum ( ClientReportControlBlock  self)
int ClientReportControlBlock_getTrgOps ( ClientReportControlBlock  self)
bool ClientReportControlBlock_isBuffered ( ClientReportControlBlock  self)
void ClientReportControlBlock_setBufTm ( ClientReportControlBlock  self,
uint32_t  bufTm 
)
void ClientReportControlBlock_setDataSetReference ( ClientReportControlBlock  self,
char *  dataSetReference 
)

set the data set to be observed by the RCB

The data set reference is a mixture of MMS and IEC 61850 syntax! In general the reference has the form: LDName/LNName$DataSetName

e.g. "simpleIOGenericIO/LLN0$Events"

It is standard that data sets are defined in LN0 logical nodes. But this is not mandatory.

Note: As a result of changing the data set the server will increase the confRev attribute of the RCB.

Parameters
selfthe RCB instance
dataSetReferencethe reference of the data set
void ClientReportControlBlock_setEntryId ( ClientReportControlBlock  self,
MmsValue entryId 
)
void ClientReportControlBlock_setGI ( ClientReportControlBlock  self,
bool  gi 
)
void ClientReportControlBlock_setIntgPd ( ClientReportControlBlock  self,
uint32_t  intgPd 
)
void ClientReportControlBlock_setOptFlds ( ClientReportControlBlock  self,
int  optFlds 
)
void ClientReportControlBlock_setPurgeBuf ( ClientReportControlBlock  self,
bool  purgeBuf 
)
void ClientReportControlBlock_setResv ( ClientReportControlBlock  self,
bool  resv 
)
void ClientReportControlBlock_setResvTms ( ClientReportControlBlock  self,
int16_t  resvTms 
)
void ClientReportControlBlock_setRptEna ( ClientReportControlBlock  self,
bool  rptEna 
)
void ClientReportControlBlock_setRptId ( ClientReportControlBlock  self,
char *  rptId 
)
void ClientReportControlBlock_setTrgOps ( ClientReportControlBlock  self,
int  trgOps 
)
ClientReportControlBlock IedConnection_getRCBValues ( IedConnection  self,
IedClientError error,
char *  rcbReference,
ClientReportControlBlock  updateRcb 
)

Read access to attributes of a report control block (RCB) at the connected server.

The requested RCB has to be specified by its object reference. E.g.

"simpleIOGernericIO/LLN0.RP.EventsRCB01"

or

"simpleIOGenericIO/LLN0.BR.EventsBRCB01"

Report control blocks have either "RP" or "BR" as part of their name following the logical node part. "RP" is part of the name of unbuffered RCBs whilst "BR" is part of the name of buffered RCBs.

This function is used to perform the actual read service. To access the received values the functions of ClientReportControlBlock have to be used.

If called with a NULL argument for the updateRcb parameter a new ClientReportControlBlock instance is created and populated with the values received by the server. It is up to the user to release this object by calling the ClientReportControlBlock_destroy function when the object is no longer needed. If called with a reference to an existing ClientReportControlBlock instance the values of the attributes will be updated and no new instance will be created.

Note: This function maps to a single MMS read request to retrieve the complete RCB at once.

Parameters
connectionthe connection object
errorthe error code if an error occurs
rcbReferenceobject reference of the report control block
updateRcba reference to an existing ClientReportControlBlock instance or NULL
Returns
new ClientReportControlBlock instance or the instance provided by the user with the updateRcb parameter.
void IedConnection_installReportHandler ( IedConnection  self,
char *  rcbReference,
char *  rptId,
ReportCallbackFunction  handler,
void *  handlerParameter 
)

Install a report handler function for the specified report control block (RCB)

It is important that you provide a ClientDataSet instance that is already populated with an MmsValue object of type MMS_STRUCTURE that contains the data set entries as structure elements. This is required because otherwise the report handler is not able to correctly parse the report message from the server.

This function will replace a formerly set report handler function for the specified RCB.

Parameters
connectionthe connection object
rcbReferenceobject reference of the report control block
rptIda string that identifies the report. If the rptId is not available then the rcbReference is used to identify the report.
handleruser provided callback function to be invoked when a report is received.
handlerParameteruser provided parameter that will be passed to the callback function
void IedConnection_setRCBValues ( IedConnection  self,
IedClientError error,
ClientReportControlBlock  rcb,
uint32_t  parametersMask,
bool  singleRequest 
)

Write access to attributes of a report control block (RCB) at the connected server.

The requested RCB has to be specified by its object reference (see also IedConnection_getRCBValues). The object reference for the referenced RCB is contained in the provided ClientReportControlBlock instance.

The parametersMask parameter specifies which attributes of the remote RCB have to be set by this request. You can specify multiple attributes by ORing the defined bit values.

The singleRequest parameter specifies the mapping to the corresponding MMS write request. Standard compliant servers should accept both variants. But some server accept only one variant. Then the value of this parameter will be of relevance.

Parameters
connectionthe connection object
errorthe error code if an error occurs
rcbobject reference of the ClientReportControlBlock instance that actually holds the parameter values to be written.
parametersMaskspecifies the parameters contained in the setRCBValues request.
singleRequestspecifies if the setRCBValues services is mapped to a single MMS write request containing multiple variables or to multiple MMS write requests.
void IedConnection_triggerGIReport ( IedConnection  self,
IedClientError error,
char *  rcbReference 
)

Trigger a general interrogation (GI) report for the specified report control block (RCB)

The RCB must have been enabled and GI set as trigger option before this command can be performed.

Parameters
connectionthe connection object
errorthe error code if an error occurs
rcbReferenceobject reference of the report control block
void IedConnection_uninstallReportHandler ( IedConnection  self,
char *  rcbReference 
)

uninstall a report handler function for the specified report control block (RCB)

char* ReasonForInclusion_getValueAsString ( ReasonForInclusion  reasonCode)

get the reason for inclusion of as a human readable string

Parameters
reasonCode
Returns
the reason for inclusion as static human readable string