iec61850_server.h

Go to the documentation of this file.

/*
 *  iec61850_server.h
 *
 *  IEC 61850 server API for libiec61850.
 *
 *  Copyright 2013-2023 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 IED_SERVER_API_H_
#define IED_SERVER_API_H_
 
#ifdef __cplusplus
extern "C" {
#endif
 
#include "mms_server.h"
#include "iec61850_dynamic_model.h"
#include "iec61850_model.h"
#include "hal_filesystem.h"
#include "iso_connection_parameters.h"
#include "iec61850_config_file_parser.h"
 
#define IEC61850_REPORTSETTINGS_RPT_ID 1
#define IEC61850_REPORTSETTINGS_BUF_TIME 2
#define IEC61850_REPORTSETTINGS_DATSET 4
#define IEC61850_REPORTSETTINGS_TRG_OPS 8
#define IEC61850_REPORTSETTINGS_OPT_FIELDS 16
#define IEC61850_REPORTSETTINGS_INTG_PD 32
 
typedef struct sIedServerConfig* IedServerConfig;
 
struct sIedServerConfig
{
    int reportBufferSize;
 
    int reportBufferSizeURCBs;
 
    char* fileServiceBasepath;
 
    bool enableFileService;
 
    bool enableDynamicDataSetService;
 
    int maxAssociationSpecificDataSets;
 
    int maxDomainSpecificDataSets;
 
    int maxDataSetEntries;
 
    bool enableLogService;
 
    bool useIntegratedGoosePublisher;
 
    uint8_t edition;
 
    int maxMmsConnections;
 
    bool enableEditSG;
 
    bool enableResvTmsForSGCB;
 
    bool enableResvTmsForBRCB;
 
    bool enableOwnerForRCB;
 
    bool syncIntegrityReportTimes;
 
    uint8_t reportSettingsWritable;
};
 
LIB61850_API IedServerConfig
IedServerConfig_create(void);
 
LIB61850_API void
IedServerConfig_destroy(IedServerConfig self);
 
LIB61850_API void
IedServerConfig_setEdition(IedServerConfig self, uint8_t edition);
 
LIB61850_API uint8_t
IedServerConfig_getEdition(IedServerConfig self);
 
LIB61850_API void
IedServerConfig_setReportBufferSize(IedServerConfig self, int reportBufferSize);
 
LIB61850_API int
IedServerConfig_getReportBufferSize(IedServerConfig self);
 
LIB61850_API void
IedServerConfig_setReportBufferSizeForURCBs(IedServerConfig self, int reportBufferSize);
 
LIB61850_API int
IedServerConfig_getReportBufferSizeForURCBs(IedServerConfig self);
 
LIB61850_API void
IedServerConfig_setMaxMmsConnections(IedServerConfig self, int maxConnections);
 
LIB61850_API int
IedServerConfig_getMaxMmsConnections(IedServerConfig self);
 
LIB61850_API void
IedServerConfig_setSyncIntegrityReportTimes(IedServerConfig self, bool enable);
 
LIB61850_API bool
IedServerConfig_getSyncIntegrityReportTimes(IedServerConfig self);
 
LIB61850_API void
IedServerConfig_setFileServiceBasePath(IedServerConfig self, const char* basepath);
 
LIB61850_API const char*
IedServerConfig_getFileServiceBasePath(IedServerConfig self);
 
LIB61850_API void
IedServerConfig_enableFileService(IedServerConfig self, bool enable);
 
LIB61850_API bool
IedServerConfig_isFileServiceEnabled(IedServerConfig self);
 
LIB61850_API void
IedServerConfig_enableDynamicDataSetService(IedServerConfig self, bool enable);
 
LIB61850_API bool
IedServerConfig_isDynamicDataSetServiceEnabled(IedServerConfig self);
 
LIB61850_API void
IedServerConfig_setMaxAssociationSpecificDataSets(IedServerConfig self, int maxDataSets);
 
LIB61850_API int
IedServerConfig_getMaxAssociationSpecificDataSets(IedServerConfig self);
 
LIB61850_API void
IedServerConfig_setMaxDomainSpecificDataSets(IedServerConfig self, int maxDataSets);
 
LIB61850_API int
IedServerConfig_getMaxDomainSpecificDataSets(IedServerConfig self);
 
LIB61850_API void
IedServerConfig_setMaxDataSetEntries(IedServerConfig self, int maxDataSetEntries);
 
LIB61850_API int
IedServerConfig_getMaxDatasSetEntries(IedServerConfig self);
 
LIB61850_API void
IedServerConfig_enableLogService(IedServerConfig self, bool enable);
 
LIB61850_API void
IedServerConfig_enableEditSG(IedServerConfig self, bool enable);
 
LIB61850_API void
IedServerConfig_enableResvTmsForSGCB(IedServerConfig self, bool enable);
 
LIB61850_API void
IedServerConfig_enableResvTmsForBRCB(IedServerConfig self, bool enable);
 
LIB61850_API  bool
IedServerConfig_isResvTmsForBRCBEnabled(IedServerConfig self);
 
LIB61850_API void
IedServerConfig_enableOwnerForRCB(IedServerConfig self, bool enable);
 
LIB61850_API  bool
IedServerConfig_isOwnerForRCBEnabled(IedServerConfig self);
 
LIB61850_API void
IedServerConfig_useIntegratedGoosePublisher(IedServerConfig self, bool enable);
 
LIB61850_API bool
IedServerConfig_isLogServiceEnabled(IedServerConfig self);
 
LIB61850_API void
IedServerConfig_setReportSetting(IedServerConfig self, uint8_t setting, bool isDyn);
 
LIB61850_API bool
IedServerConfig_getReportSetting(IedServerConfig self, uint8_t setting);
 
typedef struct sIedServer* IedServer;
 
typedef struct sClientConnection* ClientConnection;
 
LIB61850_API IedServer
IedServer_create(IedModel* dataModel);
 
LIB61850_API IedServer
IedServer_createWithTlsSupport(IedModel* dataModel, TLSConfiguration tlsConfiguration);
 
LIB61850_API IedServer
IedServer_createWithConfig(IedModel* dataModel, TLSConfiguration tlsConfiguration, IedServerConfig serverConfiguration);
 
LIB61850_API void
IedServer_destroy(IedServer self);
 
LIB61850_API bool
IedServer_addAccessPoint(IedServer self, const char* ipAddr, int tcpPort, TLSConfiguration tlsConfiguration);
 
LIB61850_API void
IedServer_setLocalIpAddress(IedServer self, const char* localIpAddress);
 
LIB61850_API void
IedServer_setServerIdentity(IedServer self, const char* vendor, const char* model, const char* revision);
 
LIB61850_API void
IedServer_setFilestoreBasepath(IedServer self, const char* basepath);
 
LIB61850_API void
IedServer_start(IedServer self, int tcpPort);
 
LIB61850_API void
IedServer_stop(IedServer self);
 
LIB61850_API void
IedServer_startThreadless(IedServer self, int tcpPort);
 
LIB61850_API int
IedServer_waitReady(IedServer self, unsigned int timeoutMs);
 
LIB61850_API void
IedServer_processIncomingData(IedServer self);
 
LIB61850_API void
IedServer_performPeriodicTasks(IedServer self);
 
LIB61850_API void
IedServer_stopThreadless(IedServer self);
 
LIB61850_API IedModel*
IedServer_getDataModel(IedServer self);
 
LIB61850_API bool
IedServer_isRunning(IedServer self);
 
LIB61850_API int
IedServer_getNumberOfOpenConnections(IedServer self);
 
LIB61850_API MmsServer
IedServer_getMmsServer(IedServer self);
 
LIB61850_API void
IedServer_enableGoosePublishing(IedServer self);
 
LIB61850_API void
IedServer_disableGoosePublishing(IedServer self);
 
LIB61850_API void
IedServer_setGooseInterfaceId(IedServer self, const char* interfaceId);
 
LIB61850_API void
IedServer_setGooseInterfaceIdEx(IedServer self, LogicalNode* ln, const char* gcbName, const char* interfaceId);
 
LIB61850_API void
IedServer_useGooseVlanTag(IedServer self, LogicalNode* ln, const char* gcbName, bool useVlanTag);
 
LIB61850_API void
IedServer_setTimeQuality(IedServer self, bool leapSecondKnown, bool clockFailure, bool clockNotSynchronized, int subsecondPrecision);
 
LIB61850_API void
IedServer_setAuthenticator(IedServer self, AcseAuthenticator authenticator, void* authenticatorParameter);
 
LIB61850_API const char*
ClientConnection_getPeerAddress(ClientConnection self);
 
LIB61850_API const char*
ClientConnection_getLocalAddress(ClientConnection self);
 
LIB61850_API void*
ClientConnection_getSecurityToken(ClientConnection self);
 
typedef void (*IedConnectionIndicationHandler) (IedServer self, ClientConnection connection, bool connected, void* parameter);
 
LIB61850_API void
IedServer_setConnectionIndicationHandler(IedServer self, IedConnectionIndicationHandler handler, void* parameter);
 
 
LIB61850_API void
IedServer_lockDataModel(IedServer self);
 
LIB61850_API void
IedServer_unlockDataModel(IedServer self);
 
LIB61850_API MmsValue*
IedServer_getAttributeValue(IedServer self, DataAttribute* dataAttribute);
 
LIB61850_API bool
IedServer_getBooleanAttributeValue(IedServer self, const DataAttribute* dataAttribute);
 
LIB61850_API int32_t
IedServer_getInt32AttributeValue(IedServer self, const DataAttribute* dataAttribute);
 
LIB61850_API int64_t
IedServer_getInt64AttributeValue(IedServer self, const DataAttribute* dataAttribute);
 
LIB61850_API uint32_t
IedServer_getUInt32AttributeValue(IedServer self, const DataAttribute* dataAttribute);
 
LIB61850_API float
IedServer_getFloatAttributeValue(IedServer self, const DataAttribute* dataAttribute);
 
LIB61850_API uint64_t
IedServer_getUTCTimeAttributeValue(IedServer self, const DataAttribute* dataAttribute);
 
LIB61850_API uint32_t
IedServer_getBitStringAttributeValue(IedServer self, const DataAttribute* dataAttribute);
 
LIB61850_API const char*
IedServer_getStringAttributeValue(IedServer self, const DataAttribute* dataAttribute);
 
LIB61850_API MmsValue*
IedServer_getFunctionalConstrainedData(IedServer self, DataObject* dataObject, FunctionalConstraint fc);
 
LIB61850_API void
IedServer_updateAttributeValue(IedServer self, DataAttribute* dataAttribute, MmsValue* value);
 
LIB61850_API void
IedServer_updateFloatAttributeValue(IedServer self, DataAttribute* dataAttribute, float value);
 
LIB61850_API void
IedServer_updateInt32AttributeValue(IedServer self, DataAttribute* dataAttribute, int32_t value);
 
LIB61850_API void
IedServer_updateDbposValue(IedServer self, DataAttribute* dataAttribute, Dbpos value);
 
LIB61850_API void
IedServer_updateInt64AttributeValue(IedServer self, DataAttribute* dataAttribute, int64_t value);
 
LIB61850_API void
IedServer_updateUnsignedAttributeValue(IedServer self, DataAttribute* dataAttribute, uint32_t value);
 
LIB61850_API void
IedServer_updateBitStringAttributeValue(IedServer self, DataAttribute* dataAttribute, uint32_t value);
 
LIB61850_API void
IedServer_updateBooleanAttributeValue(IedServer self, DataAttribute* dataAttribute, bool value);
 
LIB61850_API void
IedServer_updateVisibleStringAttributeValue(IedServer self, DataAttribute* dataAttribute, char *value);
 
LIB61850_API void
IedServer_updateUTCTimeAttributeValue(IedServer self, DataAttribute* dataAttribute, uint64_t value);
 
LIB61850_API void
IedServer_updateTimestampAttributeValue(IedServer self, DataAttribute* dataAttribute, Timestamp* timestamp);
 
LIB61850_API void
IedServer_updateQuality(IedServer self, DataAttribute* dataAttribute, Quality quality);
 
LIB61850_API void
IedServer_setLogStorage(IedServer self, const char* logRef, LogStorage logStorage);
 
LIB61850_API void
IedServer_changeActiveSettingGroup(IedServer self, SettingGroupControlBlock* sgcb, uint8_t newActiveSg);
 
LIB61850_API uint8_t
IedServer_getActiveSettingGroup(IedServer self, SettingGroupControlBlock* sgcb);
 
typedef bool (*ActiveSettingGroupChangedHandler) (void* parameter, SettingGroupControlBlock* sgcb,
        uint8_t newActSg, ClientConnection connection);
 
LIB61850_API void
IedServer_setActiveSettingGroupChangedHandler(IedServer self, SettingGroupControlBlock* sgcb,
        ActiveSettingGroupChangedHandler handler, void* parameter);
 
typedef bool (*EditSettingGroupChangedHandler) (void* parameter, SettingGroupControlBlock* sgcb,
        uint8_t newEditSg, ClientConnection connection);
 
LIB61850_API void
IedServer_setEditSettingGroupChangedHandler(IedServer self, SettingGroupControlBlock* sgcb,
        EditSettingGroupChangedHandler handler, void* parameter);
 
typedef void (*EditSettingGroupConfirmationHandler) (void* parameter, SettingGroupControlBlock* sgcb,
        uint8_t editSg);
 
LIB61850_API void
IedServer_setEditSettingGroupConfirmationHandler(IedServer self, SettingGroupControlBlock* sgcb,
        EditSettingGroupConfirmationHandler handler, void* parameter);
 
typedef enum {
    CONTROL_ACCEPTED = -1, 
    CONTROL_WAITING_FOR_SELECT = 0, 
    CONTROL_HARDWARE_FAULT = 1, 
    CONTROL_TEMPORARILY_UNAVAILABLE = 2, 
    CONTROL_OBJECT_ACCESS_DENIED = 3, 
    CONTROL_OBJECT_UNDEFINED = 4, 
    CONTROL_VALUE_INVALID = 11 
} CheckHandlerResult;
 
typedef enum {
    CONTROL_RESULT_FAILED = 0, 
    CONTROL_RESULT_OK = 1,     
    CONTROL_RESULT_WAITING = 2 
} ControlHandlerResult;
 
typedef void* ControlAction;
 
LIB61850_API void
ControlAction_setError(ControlAction self, ControlLastApplError error);
 
LIB61850_API void
ControlAction_setAddCause(ControlAction self, ControlAddCause addCause);
 
LIB61850_API int
ControlAction_getOrCat(ControlAction self);
 
LIB61850_API uint8_t*
ControlAction_getOrIdent(ControlAction self, int* orIdentSize);
 
LIB61850_API int
ControlAction_getCtlNum(ControlAction self);
 
LIB61850_API bool
ControlAction_getSynchroCheck(ControlAction self);
 
LIB61850_API bool
ControlAction_getInterlockCheck(ControlAction self);
 
LIB61850_API bool
ControlAction_isSelect(ControlAction self);
 
LIB61850_API ClientConnection
ControlAction_getClientConnection(ControlAction self);
 
LIB61850_API DataObject*
ControlAction_getControlObject(ControlAction self);
 
LIB61850_API uint64_t
ControlAction_getControlTime(ControlAction self);
 
typedef CheckHandlerResult (*ControlPerformCheckHandler) (ControlAction action, void* parameter, MmsValue* ctlVal, bool test, bool interlockCheck);
 
typedef ControlHandlerResult (*ControlWaitForExecutionHandler) (ControlAction action, void* parameter, MmsValue* ctlVal, bool test, bool synchroCheck);
 
typedef ControlHandlerResult (*ControlHandler) (ControlAction action, void* parameter, MmsValue* ctlVal, bool test);
 
typedef enum {
    SELECT_STATE_REASON_SELECTED, 
    SELECT_STATE_REASON_CANCELED, 
    SELECT_STATE_REASON_TIMEOUT,  
    SELECT_STATE_REASON_OPERATED, 
    SELECT_STATE_REASON_OPERATE_FAILED, 
    SELECT_STATE_REASON_DISCONNECTED 
} SelectStateChangedReason;
 
typedef void (*ControlSelectStateChangedHandler) (ControlAction action, void* parameter, bool isSelected, SelectStateChangedReason reason);
 
LIB61850_API void
IedServer_setControlHandler(IedServer self, DataObject* node, ControlHandler handler, void* parameter);
 
LIB61850_API void
IedServer_setPerformCheckHandler(IedServer self, DataObject* node, ControlPerformCheckHandler handler, void* parameter);
 
LIB61850_API void
IedServer_setWaitForExecutionHandler(IedServer self, DataObject* node, ControlWaitForExecutionHandler handler, void* parameter);
 
 
LIB61850_API void
IedServer_setSelectStateChangedHandler(IedServer self, DataObject* node, ControlSelectStateChangedHandler handler, void* parameter);
 
LIB61850_API void
IedServer_updateCtlModel(IedServer self, DataObject* ctlObject, ControlModel value);
 
typedef enum {
    RCB_EVENT_GET_PARAMETER, /* << parameter read by client (not implemented) */
    RCB_EVENT_SET_PARAMETER, /* << parameter set by client */
    RCB_EVENT_UNRESERVED,    /* << RCB reservation canceled */
    RCB_EVENT_RESERVED,      /* << RCB reserved */
    RCB_EVENT_ENABLE,        /* << RCB enabled */
    RCB_EVENT_DISABLE,       /* << RCB disabled */
    RCB_EVENT_GI,            /* << GI report triggered */
    RCB_EVENT_PURGEBUF,      /* << Purge buffer procedure executed */
    RCB_EVENT_OVERFLOW,      /* << Report buffer overflow */
    RCB_EVENT_REPORT_CREATED /* << A new report was created and inserted into the buffer */
} IedServer_RCBEventType;
 
typedef void (*IedServer_RCBEventHandler) (void* parameter, ReportControlBlock* rcb, ClientConnection connection, IedServer_RCBEventType event, const char* parameterName, MmsDataAccessError serviceError);
 
LIB61850_API void
IedServer_setRCBEventHandler(IedServer self, IedServer_RCBEventHandler handler, void* parameter);
 
#define IEC61850_SVCB_EVENT_ENABLE 1
 
#define IEC61850_SVCB_EVENT_DISABLE 0
 
typedef void (*SVCBEventHandler) (SVControlBlock* svcb, int event, void* parameter);
 
LIB61850_API void
IedServer_setSVCBHandler(IedServer self, SVControlBlock* svcb, SVCBEventHandler handler, void* parameter);
 
typedef struct sMmsGooseControlBlock* MmsGooseControlBlock;
 
#define IEC61850_GOCB_EVENT_ENABLE 1
 
#define IEC61850_GOCB_EVENT_DISABLE 0
 
typedef void (*GoCBEventHandler) (MmsGooseControlBlock goCb, int event, void* parameter);
 
LIB61850_API void
IedServer_setGoCBHandler(IedServer self, GoCBEventHandler handler, void* parameter);
 
LIB61850_API char*
MmsGooseControlBlock_getName(MmsGooseControlBlock self);
 
LIB61850_API LogicalNode*
MmsGooseControlBlock_getLogicalNode(MmsGooseControlBlock self);
 
LIB61850_API DataSet*
MmsGooseControlBlock_getDataSet(MmsGooseControlBlock self);
 
LIB61850_API bool
MmsGooseControlBlock_getGoEna(MmsGooseControlBlock self);
 
LIB61850_API int
MmsGooseControlBlock_getMinTime(MmsGooseControlBlock self);
 
LIB61850_API int
MmsGooseControlBlock_getMaxTime(MmsGooseControlBlock self);
 
LIB61850_API bool
MmsGooseControlBlock_getFixedOffs(MmsGooseControlBlock self);
 
LIB61850_API bool
MmsGooseControlBlock_getNdsCom(MmsGooseControlBlock self);
 
/***************************************************************************
 * Access control
 **************************************************************************/
 
typedef MmsDataAccessError
(*WriteAccessHandler) (DataAttribute* dataAttribute, MmsValue* value, ClientConnection connection, void* parameter);
 
LIB61850_API void
IedServer_handleWriteAccess(IedServer self, DataAttribute* dataAttribute,
        WriteAccessHandler handler, void* parameter);
 
LIB61850_API void
IedServer_handleWriteAccessForComplexAttribute(IedServer self, DataAttribute* dataAttribute,
        WriteAccessHandler handler, void* parameter);
 
typedef enum {
    ACCESS_POLICY_ALLOW,
    ACCESS_POLICY_DENY
} AccessPolicy;
 
LIB61850_API void
IedServer_setWriteAccessPolicy(IedServer self, FunctionalConstraint fc, AccessPolicy policy);
 
typedef MmsDataAccessError
(*ReadAccessHandler) (LogicalDevice* ld, LogicalNode* ln, DataObject* dataObject, FunctionalConstraint fc, ClientConnection connection, void* parameter);
 
LIB61850_API void
IedServer_setReadAccessHandler(IedServer self, ReadAccessHandler handler, void* parameter);
 
#ifdef __cplusplus
}
#endif
 
#endif /* IED_SERVER_API_H_ */