libIEC61850  1.1.2
Open-source IEC 61850 MMS/GOOSE/SV server and client library
iec61850_server.h
Go to the documentation of this file.
1 /*
2  * iec61850_server.h
3  *
4  * IEC 61850 server API for libiec61850.
5  *
6  * Copyright 2013, 2014 Michael Zillgith
7  *
8  * This file is part of libIEC61850.
9  *
10  * libIEC61850 is free software: you can redistribute it and/or modify
11  * it under the terms of the GNU General Public License as published by
12  * the Free Software Foundation, either version 3 of the License, or
13  * (at your option) any later version.
14  *
15  * libIEC61850 is distributed in the hope that it will be useful,
16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18  * GNU General Public License for more details.
19  *
20  * You should have received a copy of the GNU General Public License
21  * along with libIEC61850. If not, see <http://www.gnu.org/licenses/>.
22  *
23  * See COPYING file for the complete license text.
24  *
25  */
26 
27 #ifndef IED_SERVER_API_H_
28 #define IED_SERVER_API_H_
29 
30 #ifdef __cplusplus
31 extern "C" {
32 #endif
33 
38 #include "mms_server.h"
39 #include "iec61850_dynamic_model.h"
40 #include "iec61850_model.h"
41 #include "hal_filesystem.h"
43 
47 typedef struct sIedServer* IedServer;
48 
52 typedef struct sClientConnection* ClientConnection;
53 
68 IedServer
69 IedServer_create(IedModel* iedModel);
70 
76 void
77 IedServer_destroy(IedServer self);
78 
85 void
86 IedServer_setLocalIpAddress(IedServer self, const char* localIpAddress);
87 
98 void
99 IedServer_setFilestoreBasepath(IedServer self, const char* basepath);
100 
107 void
108 IedServer_start(IedServer self, int tcpPort);
109 
115 void
116 IedServer_stop(IedServer self);
117 
128 void
129 IedServer_startThreadless(IedServer self, int tcpPort);
130 
144 int
145 IedServer_waitReady(IedServer self, unsigned int timeoutMs);
146 
156 void
157 IedServer_processIncomingData(IedServer self);
158 
167 void
168 IedServer_performPeriodicTasks(IedServer self);
169 
175 void
176 IedServer_stopThreadless(IedServer self);
177 
185 IedModel*
186 IedServer_getDataModel(IedServer self);
187 
195 bool
196 IedServer_isRunning(IedServer self);
197 
208 MmsServer
209 IedServer_getMmsServer(IedServer self);
210 
218 IsoServer
219 IedServer_getIsoServer(IedServer self);
220 
231 void
232 IedServer_enableGoosePublishing(IedServer self);
233 
242 void
243 IedServer_disableGoosePublishing(IedServer self);
244 
255 void
256 IedServer_setGooseInterfaceId(IedServer self, const char* interfaceId);
257 
278 void
279 IedServer_setAuthenticator(IedServer self, AcseAuthenticator authenticator, void* authenticatorParameter);
280 
281 
282 
292 const char*
293 ClientConnection_getPeerAddress(ClientConnection self);
294 
305 void*
306 ClientConnection_getSecurityToken(ClientConnection self);
307 
317 typedef void (*IedConnectionIndicationHandler) (IedServer self, ClientConnection connection, bool connected, void* parameter);
318 
326 void
327 IedServer_setConnectionIndicationHandler(IedServer self, IedConnectionIndicationHandler handler, void* parameter);
328 
329 
350 void
351 IedServer_lockDataModel(IedServer self);
352 
361 void
362 IedServer_unlockDataModel(IedServer self);
363 
376 MmsValue*
377 IedServer_getAttributeValue(IedServer self, DataAttribute* dataAttribute);
378 
390 bool
391 IedServer_getBooleanAttributeValue(IedServer self, const DataAttribute* dataAttribute);
392 
404 int32_t
405 IedServer_getInt32AttributeValue(IedServer self, const DataAttribute* dataAttribute);
406 
418 int64_t
419 IedServer_getInt64AttributeValue(IedServer self, const DataAttribute* dataAttribute);
420 
432 uint32_t
433 IedServer_getUInt32AttributeValue(IedServer self, const DataAttribute* dataAttribute);
434 
446 float
447 IedServer_getFloatAttributeValue(IedServer self, const DataAttribute* dataAttribute);
448 
460 uint64_t
461 IedServer_getUTCTimeAttributeValue(IedServer self, const DataAttribute* dataAttribute);
462 
478 uint32_t
479 IedServer_getBitStringAttributeValue(IedServer self, const DataAttribute* dataAttribute);
480 
492 const char*
493 IedServer_getStringAttributeValue(IedServer self, const DataAttribute* dataAttribute);
494 
495 
511 MmsValue*
512 IedServer_getFunctionalConstrainedData(IedServer self, DataObject* dataObject, FunctionalConstraint fc);
513 
530 void
531 IedServer_updateAttributeValue(IedServer self, DataAttribute* dataAttribute, MmsValue* value);
532 
545 void
546 IedServer_updateFloatAttributeValue(IedServer self, DataAttribute* dataAttribute, float value);
547 
560 void
561 IedServer_updateInt32AttributeValue(IedServer self, DataAttribute* dataAttribute, int32_t value);
562 
575 void
576 IedServer_udpateDbposValue(IedServer self, DataAttribute* dataAttribute, Dbpos value);
577 
590 void
591 IedServer_updateInt64AttributeValue(IedServer self, DataAttribute* dataAttribute, int64_t value);
592 
605 void
606 IedServer_updateUnsignedAttributeValue(IedServer self, DataAttribute* dataAttribute, uint32_t value);
607 
620 void
621 IedServer_updateBitStringAttributeValue(IedServer self, DataAttribute* dataAttribute, uint32_t value);
622 
635 void
636 IedServer_updateBooleanAttributeValue(IedServer self, DataAttribute* dataAttribute, bool value);
637 
650 void
651 IedServer_updateVisibleStringAttributeValue(IedServer self, DataAttribute* dataAttribute, char *value);
652 
665 void
666 IedServer_updateUTCTimeAttributeValue(IedServer self, DataAttribute* dataAttribute, uint64_t value);
667 
680 void
681 IedServer_updateTimestampAttributeValue(IedServer self, DataAttribute* dataAttribute, Timestamp* timestamp);
682 
697 void
698 IedServer_updateQuality(IedServer self, DataAttribute* dataAttribute, Quality quality);
699 
703 void
704 IedServer_setLogStorage(IedServer self, const char* logRef, LogStorage logStorage);
705 
722 void
723 IedServer_changeActiveSettingGroup(IedServer self, SettingGroupControlBlock* sgcb, uint8_t newActiveSg);
724 
733 uint8_t
734 IedServer_getActiveSettingGroup(IedServer self, SettingGroupControlBlock* sgcb);
735 
751 typedef bool (*ActiveSettingGroupChangedHandler) (void* parameter, SettingGroupControlBlock* sgcb,
752  uint8_t newActSg, ClientConnection connection);
753 
762 void
763 IedServer_setActiveSettingGroupChangedHandler(IedServer self, SettingGroupControlBlock* sgcb,
764  ActiveSettingGroupChangedHandler handler, void* parameter);
765 
783 typedef bool (*EditSettingGroupChangedHandler) (void* parameter, SettingGroupControlBlock* sgcb,
784  uint8_t newEditSg, ClientConnection connection);
785 
794 void
795 IedServer_setEditSettingGroupChangedHandler(IedServer self, SettingGroupControlBlock* sgcb,
796  EditSettingGroupChangedHandler handler, void* parameter);
797 
807 typedef void (*EditSettingGroupConfirmationHandler) (void* parameter, SettingGroupControlBlock* sgcb,
808  uint8_t editSg);
809 
818 void
819 IedServer_setEditSettingGroupConfirmationHandler(IedServer self, SettingGroupControlBlock* sgcb,
820  EditSettingGroupConfirmationHandler handler, void* parameter);
821 
833 typedef enum {
841 
845 typedef enum {
850 
867 typedef CheckHandlerResult (*ControlPerformCheckHandler) (void* parameter, MmsValue* ctlVal, bool test, bool interlockCheck,
868  ClientConnection connection);
869 
889 typedef ControlHandlerResult (*ControlWaitForExecutionHandler) (void* parameter, MmsValue* ctlVal, bool test, bool synchroCheck);
890 
908 typedef ControlHandlerResult (*ControlHandler) (void* parameter, MmsValue* ctlVal, bool test);
909 
923 void
924 IedServer_setControlHandler(IedServer self, DataObject* node, ControlHandler handler, void* parameter);
925 
940 void
941 IedServer_setPerformCheckHandler(IedServer self, DataObject* node, ControlPerformCheckHandler handler, void* parameter);
942 
958 void
959 IedServer_setWaitForExecutionHandler(IedServer self, DataObject* node, ControlWaitForExecutionHandler handler, void* parameter);
960 
970 #define IEC61850_SVCB_EVENT_ENABLE 1
971 
973 #define IEC61850_SVCB_EVENT_DISABLE 0
974 
982 typedef void (*SVCBEventHandler) (SVControlBlock* svcb, int event, void* parameter);
983 
992 void
993 IedServer_setSVCBHandler(IedServer self, SVControlBlock* svcb, SVCBEventHandler handler, void* parameter);
994 
1013 typedef void (*AttributeChangedHandler) (DataAttribute* dataAttribute, ClientConnection connection);
1014 
1029 void
1030 IedServer_observeDataAttribute(IedServer self, DataAttribute* dataAttribute,
1031  AttributeChangedHandler handler);
1032 
1033 /***************************************************************************
1034  * Access control
1035  **************************************************************************/
1036 
1055 typedef MmsDataAccessError
1056 (*WriteAccessHandler) (DataAttribute* dataAttribute, MmsValue* value, ClientConnection connection, void* parameter);
1057 
1073 void
1074 IedServer_handleWriteAccess(IedServer self, DataAttribute* dataAttribute,
1075  WriteAccessHandler handler, void* parameter);
1076 
1077 typedef enum {
1080 } AccessPolicy;
1081 
1090 void
1091 IedServer_setWriteAccessPolicy(IedServer self, FunctionalConstraint fc, AccessPolicy policy);
1092 
1097 #ifdef __cplusplus
1098 }
1099 #endif
1100 
1101 #endif /* IED_SERVER_API_H_ */
void IedServer_destroy(IedServer self)
Destroy an IedServer instance and release all resources (memory, TCP sockets)
Definition: iec61850_server.h:848
Definition: iec61850_server.h:837
void IedServer_setGooseInterfaceId(IedServer self, const char *interfaceId)
Set the ethernet interface to be used by GOOSE publishing.
void IedServer_start(IedServer self, int tcpPort)
Start handling client connections.
void IedServer_updateVisibleStringAttributeValue(IedServer self, DataAttribute *dataAttribute, char *value)
Update the value of an IEC 61850 visible string data attribute.
uint16_t Quality
Definition: iec61850_common.h:266
struct sIsoServer * IsoServer
Definition: iso_server.h:46
Definition: iec61850_server.h:834
void IedServer_updateBitStringAttributeValue(IedServer self, DataAttribute *dataAttribute, uint32_t value)
Update the value of an IEC 61850 bit string data attribute.
IedModel * IedServer_getDataModel(IedServer self)
Return the data model of the server.
void IedServer_unlockDataModel(IedServer self)
Unlock the MMS server data model and process pending client requests.
bool(* EditSettingGroupChangedHandler)(void *parameter, SettingGroupControlBlock *sgcb, uint8_t newEditSg, ClientConnection connection)
Callback handler that is invoked when the edit setting group is about to be changed by an external cl...
Definition: iec61850_server.h:783
CheckHandlerResult
result code for ControlPerformCheckHandler
Definition: iec61850_server.h:833
void IedServer_setConnectionIndicationHandler(IedServer self, IedConnectionIndicationHandler handler, void *parameter)
set a callback function that will be called on connection events (open or close). ...
void IedServer_updateQuality(IedServer self, DataAttribute *dataAttribute, Quality quality)
Update a quality ("q") IEC 61850 data attribute.
bool(* ActiveSettingGroupChangedHandler)(void *parameter, SettingGroupControlBlock *sgcb, uint8_t newActSg, ClientConnection connection)
Callback handler that is invoked when the active setting group is about to be changed by an external ...
Definition: iec61850_server.h:751
Definition: iec61850_server.h:846
void IedServer_updateUTCTimeAttributeValue(IedServer self, DataAttribute *dataAttribute, uint64_t value)
Update the value of an IEC 61850 UTC time (timestamp) data attribute.
void IedServer_updateInt32AttributeValue(IedServer self, DataAttribute *dataAttribute, int32_t value)
Update the value of an IEC 61850 integer32 data attribute.
Definition: iec61850_server.h:847
void(* IedConnectionIndicationHandler)(IedServer self, ClientConnection connection, bool connected, void *parameter)
User provided callback function that is invoked whenever a new client connects or an existing connect...
Definition: iec61850_server.h:317
bool(* AcseAuthenticator)(void *parameter, AcseAuthenticationParameter authParameter, void **securityToken, IsoApplicationReference *appReference)
Callback function to authenticate a client.
Definition: iso_connection_parameters.h:97
void IedServer_stopThreadless(IedServer self)
Stop handling client connections for non-threaded mode.
struct sMmsServer * MmsServer
Definition: mms_server.h:43
MmsValue * IedServer_getAttributeValue(IedServer self, DataAttribute *dataAttribute)
Get data attribute value.
void IedServer_lockDataModel(IedServer self)
Lock the MMS server data model.
uint8_t IedServer_getActiveSettingGroup(IedServer self, SettingGroupControlBlock *sgcb)
Get the active setting group number.
void IedServer_setActiveSettingGroupChangedHandler(IedServer self, SettingGroupControlBlock *sgcb, ActiveSettingGroupChangedHandler handler, void *parameter)
Set the callback handler for the SetActSG event.
void IedServer_processIncomingData(IedServer self)
handle incoming TCP data in non-threaded mode
MmsDataAccessError(* WriteAccessHandler)(DataAttribute *dataAttribute, MmsValue *value, ClientConnection connection, void *parameter)
callback handler to intercept/control client access to data attributes
Definition: iec61850_server.h:1056
const char * ClientConnection_getPeerAddress(ClientConnection self)
get the peer address of this connection as string
int32_t IedServer_getInt32AttributeValue(IedServer self, const DataAttribute *dataAttribute)
Get data attribute value of an integer data attribute.
Definition: iec61850_common.h:352
float IedServer_getFloatAttributeValue(IedServer self, const DataAttribute *dataAttribute)
Get data attribute value of a floating point data attribute.
void IedServer_setWriteAccessPolicy(IedServer self, FunctionalConstraint fc, AccessPolicy policy)
Change the default write access policy for functional constraint data with a specific FC...
struct sIedServer * IedServer
Definition: iec61850_server.h:47
Definition: iec61850_server.h:836
MmsValue * IedServer_getFunctionalConstrainedData(IedServer self, DataObject *dataObject, FunctionalConstraint fc)
Get the MmsValue object related to a FunctionalConstrainedData object.
void IedServer_updateInt64AttributeValue(IedServer self, DataAttribute *dataAttribute, int64_t value)
Update the value of an IEC 61850 integer64 data attribute (like BCR actVal)
void(* AttributeChangedHandler)(DataAttribute *dataAttribute, ClientConnection connection)
callback handler to monitor client access to data attributes
Definition: iec61850_server.h:1013
Definition: iec61850_server.h:835
void IedServer_stop(IedServer self)
Stop handling client connections.
void IedServer_setLocalIpAddress(IedServer self, const char *localIpAddress)
Set the local IP address to listen on.
ControlHandlerResult(* ControlWaitForExecutionHandler)(void *parameter, MmsValue *ctlVal, bool test, bool synchroCheck)
Control model callback to perform the dynamic tests (optional).
Definition: iec61850_server.h:889
uint32_t IedServer_getBitStringAttributeValue(IedServer self, const DataAttribute *dataAttribute)
Get data attribute value of a bit string data attribute as integer value.
Definition: iec61850_server.h:838
int IedServer_waitReady(IedServer self, unsigned int timeoutMs)
Wait until a server connection is ready (with timeout)
ControlHandlerResult
result codes for control handler (ControlWaitForExecutionHandler and ControlHandler) ...
Definition: iec61850_server.h:845
MmsServer IedServer_getMmsServer(IedServer self)
Get access to the underlying MmsServer instance.
void IedServer_disableGoosePublishing(IedServer self)
Disable all GOOSE control blocks.
void IedServer_updateUnsignedAttributeValue(IedServer self, DataAttribute *dataAttribute, uint32_t value)
Update the value of an IEC 61850 unsigned integer data attribute.
void IedServer_observeDataAttribute(IedServer self, DataAttribute *dataAttribute, AttributeChangedHandler handler)
Install an observer for a data attribute.
void IedServer_updateAttributeValue(IedServer self, DataAttribute *dataAttribute, MmsValue *value)
Update the MmsValue object of an IEC 61850 data attribute.
MmsDataAccessError
Definition: mms_value.h:47
void IedServer_setFilestoreBasepath(IedServer self, const char *basepath)
Set the virtual filestore basepath for the MMS file services.
void(* EditSettingGroupConfirmationHandler)(void *parameter, SettingGroupControlBlock *sgcb, uint8_t editSg)
Callback handler that is invoked when the edit setting group has been confirmed by an external client...
Definition: iec61850_server.h:807
void * ClientConnection_getSecurityToken(ClientConnection self)
Get the security token associated with this connection.
struct sClientConnection * ClientConnection
Definition: iec61850_server.h:52
CheckHandlerResult(* ControlPerformCheckHandler)(void *parameter, MmsValue *ctlVal, bool test, bool interlockCheck, ClientConnection connection)
Control model callback to perform the static tests (optional).
Definition: iec61850_server.h:867
AccessPolicy
Definition: iec61850_server.h:1077
Definition: iec61850_server.h:1078
void IedServer_changeActiveSettingGroup(IedServer self, SettingGroupControlBlock *sgcb, uint8_t newActiveSg)
Change active setting group.
uint32_t IedServer_getUInt32AttributeValue(IedServer self, const DataAttribute *dataAttribute)
Get data attribute value of an unsigned integer data attribute.
void IedServer_handleWriteAccess(IedServer self, DataAttribute *dataAttribute, WriteAccessHandler handler, void *parameter)
Install a WriteAccessHandler for a data attribute.
void IedServer_setLogStorage(IedServer self, const char *logRef, LogStorage logStorage)
void IedServer_updateTimestampAttributeValue(IedServer self, DataAttribute *dataAttribute, Timestamp *timestamp)
Update the value of an IEC 61850 UTC time (timestamp) data attribute.
void(* SVCBEventHandler)(SVControlBlock *svcb, int event, void *parameter)
callback handler for SVCB events.
Definition: iec61850_server.h:982
Dbpos
Definition: iec61850_common.h:315
IsoServer IedServer_getIsoServer(IedServer self)
get the IsoServer instance for this IedServer object
void IedServer_setEditSettingGroupConfirmationHandler(IedServer self, SettingGroupControlBlock *sgcb, EditSettingGroupConfirmationHandler handler, void *parameter)
Set the callback handler for the COnfEditSG event.
void IedServer_setControlHandler(IedServer self, DataObject *node, ControlHandler handler, void *parameter)
Set control handler for controllable data object.
void IedServer_updateBooleanAttributeValue(IedServer self, DataAttribute *dataAttribute, bool value)
Update the value of an IEC 61850 boolean data attribute.
void IedServer_enableGoosePublishing(IedServer self)
Enable all GOOSE control blocks.
Definition: iec61850_server.h:1079
void IedServer_setWaitForExecutionHandler(IedServer self, DataObject *node, ControlWaitForExecutionHandler handler, void *parameter)
Set a handler for a controllable data object to perform dynamic tests.
void IedServer_setAuthenticator(IedServer self, AcseAuthenticator authenticator, void *authenticatorParameter)
set the authenticator for this server
IedServer IedServer_create(IedModel *iedModel)
Create a new IedServer instance.
FunctionalConstraint
Definition: iec61850_common.h:202
void IedServer_udpateDbposValue(IedServer self, DataAttribute *dataAttribute, Dbpos value)
Update the value of an IEC 61850 Dbpos (double point/position) data attribute.
void IedServer_updateFloatAttributeValue(IedServer self, DataAttribute *dataAttribute, float value)
Update the value of an IEC 61850 float data attribute.
void IedServer_startThreadless(IedServer self, int tcpPort)
Start handling client connection for non-threaded mode.
void IedServer_setEditSettingGroupChangedHandler(IedServer self, SettingGroupControlBlock *sgcb, EditSettingGroupChangedHandler handler, void *parameter)
Set the callback handler for the SetEditSG event.
uint64_t IedServer_getUTCTimeAttributeValue(IedServer self, const DataAttribute *dataAttribute)
Get data attribute value of a UTC time data attribute.
bool IedServer_getBooleanAttributeValue(IedServer self, const DataAttribute *dataAttribute)
Get data attribute value of a boolean data attribute.
void IedServer_setPerformCheckHandler(IedServer self, DataObject *node, ControlPerformCheckHandler handler, void *parameter)
Set a handler for a controllable data object to perform operative tests.
void IedServer_setSVCBHandler(IedServer self, SVControlBlock *svcb, SVCBEventHandler handler, void *parameter)
Set a handler for SVCB control block events (enable/disable)
ControlHandlerResult(* ControlHandler)(void *parameter, MmsValue *ctlVal, bool test)
Control model callback to actually perform the control operation.
Definition: iec61850_server.h:908
const char * IedServer_getStringAttributeValue(IedServer self, const DataAttribute *dataAttribute)
Get data attribute value of a string type data attribute.
bool IedServer_isRunning(IedServer self)
Check if IedServer instance is listening for client connections.
void IedServer_performPeriodicTasks(IedServer self)
perform periodic background tasks in non-threaded mode
Definition: iec61850_server.h:839
struct sMmsValue MmsValue
Definition: mms_value.h:68
int64_t IedServer_getInt64AttributeValue(IedServer self, const DataAttribute *dataAttribute)
Get data attribute value of an integer data attribute.