You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
214 lines
6.9 KiB
C
214 lines
6.9 KiB
C
/*
|
|
* goose_subscriber.h
|
|
*
|
|
* Copyright 2013-2018 Michael Zillgith
|
|
*
|
|
* This file is part of libIEC61850.
|
|
*
|
|
* libIEC61850 is free software: you can redistribute it and/or modify
|
|
* it under the terms of the GNU General Public License as published by
|
|
* the Free Software Foundation, either version 3 of the License, or
|
|
* (at your option) any later version.
|
|
*
|
|
* libIEC61850 is distributed in the hope that it will be useful,
|
|
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
* GNU General Public License for more details.
|
|
*
|
|
* You should have received a copy of the GNU General Public License
|
|
* along with libIEC61850. If not, see <http://www.gnu.org/licenses/>.
|
|
*
|
|
* See COPYING file for the complete license text.
|
|
*/
|
|
|
|
#ifndef GOOSE_SUBSCRIBER_H_
|
|
#define GOOSE_SUBSCRIBER_H_
|
|
|
|
#include "libiec61850_common_api.h"
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/**
|
|
* \defgroup goose_api_group IEC 61850 GOOSE subscriber API
|
|
*/
|
|
/**@{*/
|
|
|
|
#include "mms_value.h"
|
|
|
|
typedef struct sGooseSubscriber* GooseSubscriber;
|
|
|
|
/**
|
|
* \brief user provided callback function that will be invoked when a GOOSE message is received.
|
|
*
|
|
* \param subscriber the subscriber object that invoked the callback function,
|
|
* \param parameter a user provided parameter that will be passed to the callback function
|
|
*/
|
|
typedef void (*GooseListener)(GooseSubscriber subscriber, void* parameter);
|
|
|
|
/**
|
|
* \brief 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.
|
|
*
|
|
* \param goCbRef a string containing the object reference of the GOOSE Control Block (GoCB) in MMS notation the
|
|
* GOOSE publisher uses.
|
|
* \param dataSetValues the MmsValue object where the data set values will be written or NULL.
|
|
*/
|
|
LIB61850_API GooseSubscriber
|
|
GooseSubscriber_create(char* goCbRef, MmsValue* dataSetValues);
|
|
|
|
/* char*
|
|
GooseSubscriber_getGoCbRef(GooseSubscriber self);
|
|
*/
|
|
|
|
/**
|
|
* \brief 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.
|
|
*
|
|
* \param self GooseSubscriber instance to operate on.
|
|
* \param the APPID value the subscriber should use to filter messages
|
|
*/
|
|
LIB61850_API void
|
|
GooseSubscriber_setAppId(GooseSubscriber self, uint16_t appId);
|
|
|
|
/**
|
|
* \brief 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.
|
|
*
|
|
*/
|
|
LIB61850_API bool
|
|
GooseSubscriber_isValid(GooseSubscriber self);
|
|
|
|
LIB61850_API void
|
|
GooseSubscriber_destroy(GooseSubscriber self);
|
|
|
|
/**
|
|
* \brief set a callback function that will be invoked when a GOOSE message has been received.
|
|
*
|
|
* \param self GooseSubscriber instance to operate on.
|
|
* \param listener user provided callback function
|
|
* \param parameter a user provided parameter that will be passed to the callback function
|
|
*/
|
|
LIB61850_API void
|
|
GooseSubscriber_setListener(GooseSubscriber self, GooseListener listener, void* parameter);
|
|
|
|
/**
|
|
* \brief 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
|
|
*
|
|
* \param self GooseSubscriber instance to operate on.
|
|
*
|
|
* \return the state number of the last received GOOSE message
|
|
*/
|
|
LIB61850_API uint32_t
|
|
GooseSubscriber_getStNum(GooseSubscriber self);
|
|
|
|
/**
|
|
* \brief 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.
|
|
*
|
|
* \param self GooseSubscriber instance to operate on.
|
|
*
|
|
* \return the sequence number of the last received GOOSE message
|
|
*/
|
|
LIB61850_API uint32_t
|
|
GooseSubscriber_getSqNum(GooseSubscriber self);
|
|
|
|
/**
|
|
* \brief returns the test flag of the last received GOOSE message
|
|
*
|
|
* IMPORTANT: Goose messages with test=TRUE have to be ignored to be standard compliant!
|
|
*
|
|
* \param self GooseSubscriber instance to operate on.
|
|
*
|
|
* \return the state of the test flag of the last received GOOSE message.
|
|
*/
|
|
LIB61850_API bool
|
|
GooseSubscriber_isTest(GooseSubscriber self);
|
|
|
|
/**
|
|
* \brief returns the confRev value of the last received GOOSE message
|
|
*
|
|
* \param self GooseSubscriber instance to operate on.
|
|
*
|
|
* \return the confRev value of the last received GOOSE message. If the message does not contain such
|
|
* a value the result is always 0
|
|
*/
|
|
LIB61850_API uint32_t
|
|
GooseSubscriber_getConfRev(GooseSubscriber self);
|
|
|
|
/**
|
|
* \brief 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!
|
|
*
|
|
* \param self GooseSubscriber instance to operate on.
|
|
*
|
|
* \return the state of the ndsCom flag of the last received GOOSE message.
|
|
*
|
|
*/
|
|
LIB61850_API bool
|
|
GooseSubscriber_needsCommission(GooseSubscriber self);
|
|
|
|
/**
|
|
* \brief Get the TimeAllowedToLive value of the last received message.
|
|
*
|
|
* \param self GooseSubscriber instance to operate on.
|
|
*
|
|
* \return the TimeAllowedToLive value of the last received GOOSE message in milliseconds.
|
|
*/
|
|
LIB61850_API uint32_t
|
|
GooseSubscriber_getTimeAllowedToLive(GooseSubscriber self);
|
|
|
|
/**
|
|
* \brief Get the timestamp of the last received message.
|
|
*
|
|
* \param self GooseSubscriber instance to operate on.
|
|
*
|
|
* \return the timestamp value of the last received GOOSE message in milliseconds since epoch (1.1.1970 UTC).
|
|
*/
|
|
LIB61850_API uint64_t
|
|
GooseSubscriber_getTimestamp(GooseSubscriber self);
|
|
|
|
/**
|
|
* \brief 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.
|
|
*
|
|
* \param self GooseSubscriber instance to operate on.
|
|
*
|
|
* \return MmsValue instance of the report data set
|
|
*/
|
|
LIB61850_API MmsValue*
|
|
GooseSubscriber_getDataSetValues(GooseSubscriber self);
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
|
|
/**@}*/
|
|
|
|
#endif /* GOOSE_SUBSCRIBER_H_ */
|