Client side report handling services, functions, and data types

Macros
#define	REASON_NOT_INCLUDED   IEC61850_REASON_NOT_INCLUDED
#define	REASON_DATA_CHANGE   IEC61850_REASON_DATA_CHANGE
#define	REASON_QUALITY_CHANGE   IEC61850_REASON_QUALITY_CHANGE
#define	REASON_DATA_UPDATE   IEC61850_REASON_DATA_UPDATE
#define	REASON_INTEGRITY   IEC61850_REASON_INTEGRITY
#define	REASON_GI   IEC61850_REASON_GI
#define	REASON_UNKNOWN   IEC61850_REASON_UNKNOWN
#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 {   IEC61850_REASON_NOT_INCLUDED = 0, IEC61850_REASON_DATA_CHANGE = 1, IEC61850_REASON_QUALITY_CHANGE = 2, IEC61850_REASON_DATA_UPDATE = 3,   IEC61850_REASON_INTEGRITY = 4, IEC61850_REASON_GI = 5, IEC61850_REASON_UNKNOWN = 6 }

Functions
ClientReportControlBlock	IedConnection_getRCBValues (IedConnection self, IedClientError *error, const 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, const char *rcbReference, const char *rptId, ReportCallbackFunction handler, void *handlerParameter)
	Install a report handler function for the specified report control block (RCB) More...
void	IedConnection_uninstallReportHandler (IedConnection self, const char *rcbReference)
	uninstall a report handler function for the specified report control block (RCB) More...
void	IedConnection_triggerGIReport (IedConnection self, IedClientError *error, const char *rcbReference)
	Trigger a general interrogation (GI) report for the specified report control block (RCB) More...
const char *	ClientReport_getDataSetName (ClientReport self)
	Get the name of the report data set. More...
MmsValue *	ClientReport_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...
MmsValue *	ClientReport_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)
	Indicates if the report contains the bufOvfl (buffer overflow) flag. More...
bool	ClientReport_getBufOvfl (ClientReport self)
	Get the value of the bufOvfl flag. More...
bool	ClientReport_hasDataReference (ClientReport self)
	Indicates if the report contains data references for the reported data set members. More...
const char *	ClientReport_getDataReference (ClientReport self, int elementIndex)
	get the data-reference of the element of the report data set More...
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 (const char *rcbReference)
void	ClientReportControlBlock_destroy (ClientReportControlBlock self)
char *	ClientReportControlBlock_getObjectReference (ClientReportControlBlock self)
bool	ClientReportControlBlock_isBuffered (ClientReportControlBlock self)
const char *	ClientReportControlBlock_getRptId (ClientReportControlBlock self)
void	ClientReportControlBlock_setRptId (ClientReportControlBlock self, const 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)
const char *	ClientReportControlBlock_getDataSetReference (ClientReportControlBlock self)
void	ClientReportControlBlock_setDataSetReference (ClientReportControlBlock self, const 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)
MmsValue *	ClientReportControlBlock_getEntryId (ClientReportControlBlock self)
void	ClientReportControlBlock_setEntryId (ClientReportControlBlock self, MmsValue *entryId)
uint64_t	ClientReportControlBlock_getEntryTime (ClientReportControlBlock self)
MmsValue *	ClientReportControlBlock_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

#define REASON_DATA_CHANGE   IEC61850_REASON_DATA_CHANGE

#define REASON_DATA_UPDATE   IEC61850_REASON_DATA_UPDATE

#define REASON_GI   IEC61850_REASON_GI

#define REASON_INTEGRITY   IEC61850_REASON_INTEGRITY

#define REASON_NOT_INCLUDED   IEC61850_REASON_NOT_INCLUDED

#define REASON_QUALITY_CHANGE   IEC61850_REASON_QUALITY_CHANGE

#define REASON_UNKNOWN   IEC61850_REASON_UNKNOWN

Typedef Documentation

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

Callback function for receiving reports.

Parameters

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

Enumeration Type Documentation

enum ReasonForInclusion

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

Enumerator
IEC61850_REASON_NOT_INCLUDED	the element is not included in the received report
IEC61850_REASON_DATA_CHANGE	the element is included due to a change of the data value
IEC61850_REASON_QUALITY_CHANGE	the element is included due to a change in the quality of data
IEC61850_REASON_DATA_UPDATE	the element is included due to an update of the data value
IEC61850_REASON_INTEGRITY	the element is included due to a periodic integrity report task
IEC61850_REASON_GI	the element is included due to a general interrogation by the client
IEC61850_REASON_UNKNOWN	the reason for inclusion is unknown

Function Documentation

bool ClientReport_getBufOvfl

(

ClientReport

self

)

Get the value of the bufOvfl flag.

Parameters

self	the ClientReport instance

Returns

true if bufOvfl is set, false otherwise

uint32_t ClientReport_getConfRev

(

ClientReport

self

)

const char* ClientReport_getDataReference	(	ClientReport	self,
		int	elementIndex
	)

get the data-reference of the element of the report data set

This function will only return a non-NULL value if the received report contains data-references. This can be determined by the ClientReport_hasDataReference function. NOTE: The returned string is allocated and hold by the ClientReport instance and is only valid until the ClientReport instance exists!

Parameters

self	the ClientReport instance
elementIndex	index of the data set element (starting with 0)
the	data reference as string as provided by the report or NULL if the data reference is not available

const char* ClientReport_getDataSetName

(

ClientReport

self

)

Get the name of the report data set.

NOTE: the returned string is only valid as long as the ClientReport instance exists!

Parameters

self	the ClientReport instance

Returns

report data set name as 0 terminated string

MmsValue* ClientReport_getDataSetValues

(

ClientReport

self

)

return the received data set values of the report

Parameters

self	the 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

self	the ClientReport instance

Returns

entryId or NULL

char* ClientReport_getRcbReference

(

ClientReport

self

)

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

Parameters

self	the 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

self	the ClientReport instance
elementIndex	index 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

self	the 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

self	the ClientReport instance

Returns

the timestamp as milliseconds since 1.1.1970 UTC

bool ClientReport_hasBufOvfl

(

ClientReport

self

)

Indicates if the report contains the bufOvfl (buffer overflow) flag.

Parameters

self	the ClientReport instance

Returns

true if the report contains the bufOvfl flag, false otherwise

bool ClientReport_hasConfRev

(

ClientReport

self

)

bool ClientReport_hasDataReference

(

ClientReport

self

)

Indicates if the report contains data references for the reported data set members.

Parameters

self	the ClientReport instance

Returns

true if the report contains data-references, false otherwise

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

self	the ClientReport instance

Returns

true if the report contains a timestamp, false otherwise

ClientReportControlBlock ClientReportControlBlock_create

(

const char *

rcbReference

)

void ClientReportControlBlock_destroy

(

ClientReportControlBlock

self

)

uint32_t ClientReportControlBlock_getBufTm

(

ClientReportControlBlock

self

)

uint32_t ClientReportControlBlock_getConfRev

(

ClientReportControlBlock

self

)

const 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

)

const 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,
		const 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

self	the RCB instance
dataSetReference	the 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,
		const char *	rptId
	)

void ClientReportControlBlock_setTrgOps	(	ClientReportControlBlock	self,
		int	trgOps
	)

ClientReportControlBlock IedConnection_getRCBValues	(	IedConnection	self,
		IedClientError *	error,
		const 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.

"simpleIOGenericIO/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

connection	the connection object
error	the error code if an error occurs
rcbReference	object reference of the report control block
updateRcb	a 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,
		const char *	rcbReference,
		const char *	rptId,
		ReportCallbackFunction	handler,
		void *	handlerParameter
	)

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

This function will replace a report handler set earlier for the specified RCB. The report handler will be called whenever a report for the specified RCB is received. Please note that this function should be called whenever the RCB data set is changed or updated. Otherwise the internal data structures storing the received data set values will not be updated correctly.

When replacing a report handler you only have to call this function. There is no separate call to IedConnection_uninstallReportHandler() required.

Parameters

self	the connection object
rcbReference	object reference of the report control block
rptId	a string that identifies the report. If the rptId is not available then the rcbReference is used to identify the report.
handler	user provided callback function to be invoked when a report is received.
handlerParameter	user 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

connection	the connection object
error	the error code if an error occurs
rcb	object reference of the ClientReportControlBlock instance that actually holds the parameter values to be written.
parametersMask	specifies the parameters contained in the setRCBValues request.
singleRequest	specifies 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,
		const 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.

Deprecated:

Use ClientReportControlBlock_setGI instead

Parameters

connection	the connection object
error	the error code if an error occurs
rcbReference	object reference of the report control block

void IedConnection_uninstallReportHandler	(	IedConnection	self,
		const char *	rcbReference
	)

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

Parameters

self	the connection object
rcbReference	object reference of the report control block

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