IEC 61850 GOOSE subscriber API

Typedefs
typedef struct sGooseSubscriber *	GooseSubscriber
typedef void(*	GooseListener) (GooseSubscriber subscriber, void *parameter)
	user provided callback function that will be invoked when a GOOSE message is received. More...
typedef struct sGooseReceiver *	GooseReceiver

Functions
GooseSubscriber	GooseSubscriber_create (char *goCbRef, MmsValue *dataSetValues)
	create a new GOOSE subscriber instance. More...
void	GooseSubscriber_setAppId (GooseSubscriber self, uint16_t appId)
	set the APPID used by the subscriber to filter relevant messages. More...
bool	GooseSubscriber_isValid (GooseSubscriber self)
	Check if subscriber state is valid. More...
void	GooseSubscriber_destroy (GooseSubscriber self)
void	GooseSubscriber_setListener (GooseSubscriber self, GooseListener listener, void *parameter)
	set a callback function that will be invoked when a GOOSE message has been received. More...
uint32_t	GooseSubscriber_getStNum (GooseSubscriber self)
	return the state number (stNum) of the last received GOOSE message. More...
uint32_t	GooseSubscriber_getSqNum (GooseSubscriber self)
	return the sequence number (sqNum) of the last received GOOSE message. More...
bool	GooseSubscriber_isTest (GooseSubscriber self)
	returns the test flag of the last received GOOSE message More...
uint32_t	GooseSubscriber_getConfRev (GooseSubscriber self)
	returns the confRev value of the last received GOOSE message More...
bool	GooseSubscriber_needsCommission (GooseSubscriber self)
	returns the value of the ndsCom (needs commission) flag of the last received GOOSE message. More...
uint32_t	GooseSubscriber_getTimeAllowedToLive (GooseSubscriber self)
	Get the TimeAllowedToLive value of the last received message. More...
uint64_t	GooseSubscriber_getTimestamp (GooseSubscriber self)
	Get the timestamp of the last received message. More...
MmsValue *	GooseSubscriber_getDataSetValues (GooseSubscriber self)
	get the data set values received with the last report More...
GooseReceiver	GooseReceiver_create (void)
	Create a new receiver instance. More...
void	GooseReceiver_setInterfaceId (GooseReceiver self, const char *interfaceId)
	sets the interface for the GOOSE receiver More...
void	GooseReceiver_addSubscriber (GooseReceiver self, GooseSubscriber subscriber)
	Add a subscriber to this receiver instance. More...
void	GooseReceiver_removeSubscriber (GooseReceiver self, GooseSubscriber subscriber)
	Remove a subscriber from this receiver instance. More...
void	GooseReceiver_start (GooseReceiver self)
	start the GOOSE receiver in a separate thread More...
void	GooseReceiver_stop (GooseReceiver self)
	stop the GOOSE receiver running in a separate thread More...
bool	GooseReceiver_isRunning (GooseReceiver self)
	Check if GOOSE receiver is running. More...
void	GooseReceiver_destroy (GooseReceiver self)
	Free all resource of the GooseReceiver and all installed GooseSubscribers. More...
EthernetSocket	GooseReceiver_startThreadless (GooseReceiver self)
void	GooseReceiver_stopThreadless (GooseReceiver self)
bool	GooseReceiver_tick (GooseReceiver self)
	Parse GOOSE messages if they are available. More...

Detailed Description

Typedef Documentation

typedef void(* GooseListener) (GooseSubscriber subscriber, void *parameter)

user provided callback function that will be invoked when a GOOSE message is received.

Parameters

subscriber	the subscriber object that invoked the callback function,
parameter	a user provided parameter that will be passed to the callback function

typedef struct sGooseReceiver* GooseReceiver

typedef struct sGooseSubscriber* GooseSubscriber

Function Documentation

void GooseReceiver_addSubscriber	(	GooseReceiver	self,
		GooseSubscriber	subscriber
	)

Add a subscriber to this receiver instance.

NOTE: Do not call this function while the receiver is running (after GooseReceiver_start has been called)!

Parameters

self	the GooseReceiver instance
subscriber	the GooseSubscriber instance to add

GooseReceiver GooseReceiver_create

(

void

)

Create a new receiver instance.

A GooseReceiver instance is used to handle all GOOSE messages received on a specific network interface.

Returns

the new GooseReceiver instance

void GooseReceiver_destroy

(

GooseReceiver

self

)

Free all resource of the GooseReceiver and all installed GooseSubscribers.

Parameters

self	the GooseReceiver instance

bool GooseReceiver_isRunning

(

GooseReceiver

self

)

Check if GOOSE receiver is running.

Can be used to check if GooseReceiver_start has been successful.

Parameters

self	the GooseReceiver instance

Returns

true if GOOSE receiver is running, false otherwise

void GooseReceiver_removeSubscriber	(	GooseReceiver	self,
		GooseSubscriber	subscriber
	)

Remove a subscriber from this receiver instance.

NOTE: Do not call this function while the receiver is running (after GooseReceiver_start has been called)!

Parameters

self	the GooseReceiver instance
subscriber	the GooseSubscriber instance to remove

void GooseReceiver_setInterfaceId	(	GooseReceiver	self,
		const char *	interfaceId
	)

sets the interface for the GOOSE receiver

Parameters

self	the GooseReceiver instance
interfaceId

void GooseReceiver_start

(

GooseReceiver

self

)

start the GOOSE receiver in a separate thread

Parameters

self	the GooseReceiver instance

EthernetSocket GooseReceiver_startThreadless

(

GooseReceiver

self

)

void GooseReceiver_stop

(

GooseReceiver

self

)

stop the GOOSE receiver running in a separate thread

This function is used to stop the receiver thread started with GooseReceiver_start

Parameters

self	the GooseReceiver instance

void GooseReceiver_stopThreadless

(

GooseReceiver

self

)

bool GooseReceiver_tick

(

GooseReceiver

self

)

Parse GOOSE messages if they are available.

Call after reception of ethernet frame and periodically to to house keeping tasks

Parameters

self	the receiver object

Returns

true if a message was available and has been parsed, false otherwise

GooseSubscriber GooseSubscriber_create	(	char *	goCbRef,
		MmsValue *	dataSetValues
	)

create a new GOOSE subscriber instance.

A new GOOSE subscriber will be created and connected to a specific GOOSE control block reference.

The parameter goCbRef has to be given in MMS like notation (as it also will appear in the GOOSE message sent by the publisher). An example could be "simpleIOGenericIO/LLN0$GO$gcbEvents".

The data set values contained in a GOOSE message will be written to the optionally provided MmsValue instance. The MmsValue object has to be of type MMS_ARRAY. The array elements need to be of the same type as the data set elements. It is intended that the provided MmsValue instance has been created by the IedConnection_getDataSet() method before.

If NULL is given as dataSetValues it will be created the first time when a appropriate GOOSE message is received.

Parameters

goCbRef	a string containing the object reference of the GOOSE Control Block (GoCB) in MMS notation the GOOSE publisher uses.
dataSetValues	the MmsValue object where the data set values will be written or NULL.

void GooseSubscriber_destroy

(

GooseSubscriber

self

)

uint32_t GooseSubscriber_getConfRev

(

GooseSubscriber

self

)

returns the confRev value of the last received GOOSE message

Parameters

self	GooseSubscriber instance to operate on.

Returns

the confRev value of the last received GOOSE message. If the message does not contain such a value the result is always 0

MmsValue* GooseSubscriber_getDataSetValues

(

GooseSubscriber

self

)

get the data set values received with the last report

Note: To prevent data corruption. The MmsValue instance received should only be used inside of the callback function, when the GOOSE receiver is running in a separate thread.

Parameters

self	GooseSubscriber instance to operate on.

Returns

MmsValue instance of the report data set

uint32_t GooseSubscriber_getSqNum

(

GooseSubscriber

self

)

return the sequence number (sqNum) of the last received GOOSE message.

The sequence number is increased for every consecutive GOOSE message without state change. When a state change occurs (stNum is increased) then the sequence number (sqNum) will be reset.

Parameters

self	GooseSubscriber instance to operate on.

Returns

the sequence number of the last received GOOSE message

uint32_t GooseSubscriber_getStNum

(

GooseSubscriber

self

)

return the state number (stNum) of the last received GOOSE message.

The state number is increased if any of the values in the GOOSE data set changed due to a valid trigger condition

Parameters

self	GooseSubscriber instance to operate on.

Returns

the state number of the last received GOOSE message

uint32_t GooseSubscriber_getTimeAllowedToLive

(

GooseSubscriber

self

)

Get the TimeAllowedToLive value of the last received message.

Parameters

self	GooseSubscriber instance to operate on.

Returns

the TimeAllowedToLive value of the last received GOOSE message in milliseconds.

uint64_t GooseSubscriber_getTimestamp

(

GooseSubscriber

self

)

Get the timestamp of the last received message.

Parameters

self	GooseSubscriber instance to operate on.

Returns

the timestamp value of the last received GOOSE message in milliseconds since epoch (1.1.1970 UTC).

bool GooseSubscriber_isTest

(

GooseSubscriber

self

)

returns the test flag of the last received GOOSE message

IMPORTANT: Goose messages with test=TRUE have to be ignored to be standard compliant!

Parameters

self	GooseSubscriber instance to operate on.

Returns

the state of the test flag of the last received GOOSE message.

bool GooseSubscriber_isValid

(

GooseSubscriber

self

)

Check if subscriber state is valid.

A GOOSE subscriber is valid if TimeAllowedToLive timeout is not elapsed and GOOSE message were received with correct state and sequence ID.

bool GooseSubscriber_needsCommission

(

GooseSubscriber

self

)

returns the value of the ndsCom (needs commission) flag of the last received GOOSE message.

IMPORTANT: Goose messages with ndsCom=TRUE have to be ignored to be standard compliant!

Parameters

self	GooseSubscriber instance to operate on.

Returns

the state of the ndsCom flag of the last received GOOSE message.

void GooseSubscriber_setAppId	(	GooseSubscriber	self,
		uint16_t	appId
	)

set the APPID used by the subscriber to filter relevant messages.

If APPID is set the subscriber will ignore all messages with other APPID values.

Parameters

self	GooseSubscriber instance to operate on.
the	APPID value the subscriber should use to filter messages

void GooseSubscriber_setListener	(	GooseSubscriber	self,
		GooseListener	listener,
		void *	parameter
	)

set a callback function that will be invoked when a GOOSE message has been received.

Parameters

self	GooseSubscriber instance to operate on.
listener	user provided callback function
parameter	a user provided parameter that will be passed to the callback function