libIEC61850  1.0.0
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_start(IedServer self, int tcpPort);
87 
93 void
94 IedServer_stop(IedServer self);
95 
106 void
107 IedServer_startThreadless(IedServer self, int tcpPort);
108 
109 int
110 IedServer_waitReady(IedServer self, unsigned int timeoutMs);
111 
121 void
122 IedServer_processIncomingData(IedServer self);
123 
132 void
133 IedServer_performPeriodicTasks(IedServer self);
134 
140 void
141 IedServer_stopThreadless(IedServer self);
142 
150 IedModel*
151 IedServer_getDataModel(IedServer self);
152 
160 bool
161 IedServer_isRunning(IedServer self);
162 
173 MmsServer
174 IedServer_getMmsServer(IedServer self);
175 
183 IsoServer
184 IedServer_getIsoServer(IedServer self);
185 
196 void
197 IedServer_enableGoosePublishing(IedServer self);
198 
207 void
208 IedServer_disableGoosePublishing(IedServer self);
209 
220 void
221 IedServer_setGooseInterfaceId(IedServer self, const char* interfaceId);
222 
243 void
244 IedServer_setAuthenticator(IedServer self, AcseAuthenticator authenticator, void* authenticatorParameter);
245 
246 
247 
257 const char*
258 ClientConnection_getPeerAddress(ClientConnection self);
259 
270 void*
271 ClientConnection_getSecurityToken(ClientConnection self);
272 
282 typedef void (*IedConnectionIndicationHandler) (IedServer self, ClientConnection connection, bool connected, void* parameter);
283 
291 void
292 IedServer_setConnectionIndicationHandler(IedServer self, IedConnectionIndicationHandler handler, void* parameter);
293 
294 
315 void
316 IedServer_lockDataModel(IedServer self);
317 
326 void
327 IedServer_unlockDataModel(IedServer self);
328 
341 MmsValue*
342 IedServer_getAttributeValue(IedServer self, DataAttribute* dataAttribute);
343 
355 bool
356 IedServer_getBooleanAttributeValue(IedServer self, const DataAttribute* dataAttribute);
357 
369 int32_t
370 IedServer_getInt32AttributeValue(IedServer self, const DataAttribute* dataAttribute);
371 
383 int64_t
384 IedServer_getInt64AttributeValue(IedServer self, const DataAttribute* dataAttribute);
385 
397 uint32_t
398 IedServer_getUInt32AttributeValue(IedServer self, const DataAttribute* dataAttribute);
399 
411 float
412 IedServer_getFloatAttributeValue(IedServer self, const DataAttribute* dataAttribute);
413 
425 uint64_t
426 IedServer_getUTCTimeAttributeValue(IedServer self, const DataAttribute* dataAttribute);
427 
443 uint32_t
444 IedServer_getBitStringAttributeValue(IedServer self, const DataAttribute* dataAttribute);
445 
457 const char*
458 IedServer_getStringAttributeValue(IedServer self, const DataAttribute* dataAttribute);
459 
460 
476 MmsValue*
477 IedServer_getFunctionalConstrainedData(IedServer self, DataObject* dataObject, FunctionalConstraint fc);
478 
495 void
496 IedServer_updateAttributeValue(IedServer self, DataAttribute* dataAttribute, MmsValue* value);
497 
510 void
511 IedServer_updateFloatAttributeValue(IedServer self, DataAttribute* dataAttribute, float value);
512 
525 void
526 IedServer_updateInt32AttributeValue(IedServer self, DataAttribute* dataAttribute, int32_t value);
527 
540 void
541 IedServer_updateInt64AttributeValue(IedServer self, DataAttribute* dataAttribute, int64_t value);
542 
555 void
556 IedServer_updateUnsignedAttributeValue(IedServer self, DataAttribute* dataAttribute, uint32_t value);
557 
570 void
571 IedServer_updateBitStringAttributeValue(IedServer self, DataAttribute* dataAttribute, uint32_t value);
572 
585 void
586 IedServer_updateBooleanAttributeValue(IedServer self, DataAttribute* dataAttribute, bool value);
587 
600 void
601 IedServer_updateVisibleStringAttributeValue(IedServer self, DataAttribute* dataAttribute, char *value);
602 
615 void
616 IedServer_updateUTCTimeAttributeValue(IedServer self, DataAttribute* dataAttribute, uint64_t value);
617 
630 void
631 IedServer_updateTimestampAttributeValue(IedServer self, DataAttribute* dataAttribute, Timestamp* timestamp);
632 
647 void
648 IedServer_updateQuality(IedServer self, DataAttribute* dataAttribute, Quality quality);
649 
653 void
654 IedServer_setLogStorage(IedServer self, const char* logRef, LogStorage logStorage);
655 
672 void
673 IedServer_changeActiveSettingGroup(IedServer self, SettingGroupControlBlock* sgcb, uint8_t newActiveSg);
674 
683 uint8_t
684 IedServer_getActiveSettingGroup(IedServer self, SettingGroupControlBlock* sgcb);
685 
701 typedef bool (*ActiveSettingGroupChangedHandler) (void* parameter, SettingGroupControlBlock* sgcb,
702  uint8_t newActSg, ClientConnection connection);
703 
712 void
713 IedServer_setActiveSettingGroupChangedHandler(IedServer self, SettingGroupControlBlock* sgcb,
714  ActiveSettingGroupChangedHandler handler, void* parameter);
715 
733 typedef bool (*EditSettingGroupChangedHandler) (void* parameter, SettingGroupControlBlock* sgcb,
734  uint8_t newEditSg, ClientConnection connection);
735 
744 void
745 IedServer_setEditSettingGroupChangedHandler(IedServer self, SettingGroupControlBlock* sgcb,
746  EditSettingGroupChangedHandler handler, void* parameter);
747 
757 typedef void (*EditSettingGroupConfirmationHandler) (void* parameter, SettingGroupControlBlock* sgcb,
758  uint8_t editSg);
759 
768 void
769 IedServer_setEditSettingGroupConfirmationHandler(IedServer self, SettingGroupControlBlock* sgcb,
770  EditSettingGroupConfirmationHandler handler, void* parameter);
771 
783 typedef enum {
790 
794 typedef enum {
799 
816 typedef CheckHandlerResult (*ControlPerformCheckHandler) (void* parameter, MmsValue* ctlVal, bool test, bool interlockCheck,
817  ClientConnection connection);
818 
838 typedef ControlHandlerResult (*ControlWaitForExecutionHandler) (void* parameter, MmsValue* ctlVal, bool test, bool synchroCheck);
839 
857 typedef ControlHandlerResult (*ControlHandler) (void* parameter, MmsValue* ctlVal, bool test);
858 
872 void
873 IedServer_setControlHandler(IedServer self, DataObject* node, ControlHandler handler, void* parameter);
874 
889 void
890 IedServer_setPerformCheckHandler(IedServer self, DataObject* node, ControlPerformCheckHandler handler, void* parameter);
891 
907 void
908 IedServer_setWaitForExecutionHandler(IedServer self, DataObject* node, ControlWaitForExecutionHandler handler, void* parameter);
909 
919 #define IEC61850_SVCB_EVENT_ENABLE 1
920 
922 #define IEC61850_SVCB_EVENT_DISABLE 0
923 
931 typedef void (*SVCBEventHandler) (SVControlBlock* svcb, int event, void* parameter);
932 
941 void
942 IedServer_setSVCBHandler(IedServer self, SVControlBlock* svcb, SVCBEventHandler handler, void* parameter);
943 
962 typedef void (*AttributeChangedHandler) (DataAttribute* dataAttribute, ClientConnection connection);
963 
978 void
979 IedServer_observeDataAttribute(IedServer self, DataAttribute* dataAttribute,
980  AttributeChangedHandler handler);
981 
982 /***************************************************************************
983  * Access control
984  **************************************************************************/
985 
1004 typedef MmsDataAccessError
1005 (*WriteAccessHandler) (DataAttribute* dataAttribute, MmsValue* value, ClientConnection connection, void* parameter);
1006 
1022 void
1023 IedServer_handleWriteAccess(IedServer self, DataAttribute* dataAttribute,
1024  WriteAccessHandler handler, void* parameter);
1025 
1026 typedef enum {
1029 } AccessPolicy;
1030 
1039 void
1040 IedServer_setWriteAccessPolicy(IedServer self, FunctionalConstraint fc, AccessPolicy policy);
1041 
1046 #ifdef __cplusplus
1047 }
1048 #endif
1049 
1050 #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:797
Definition: iec61850_server.h:787
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:784
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:733
CheckHandlerResult
result code for ControlPerformCheckHandler
Definition: iec61850_server.h:783
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:701
Definition: iec61850_server.h:795
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:796
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:282
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:1005
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:786
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:962
Definition: iec61850_server.h:785
bool(* AcseAuthenticator)(void *parameter, AcseAuthenticationParameter authParameter, void **securityToken)
Callback function to authenticate a client.
Definition: iso_connection_parameters.h:92
void IedServer_stop(IedServer self)
Stop handling client connections.
ControlHandlerResult(* ControlWaitForExecutionHandler)(void *parameter, MmsValue *ctlVal, bool test, bool synchroCheck)
Control model callback to perform the dynamic tests (optional).
Definition: iec61850_server.h:838
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:788
int IedServer_waitReady(IedServer self, unsigned int timeoutMs)
ControlHandlerResult
result codes for control handler (ControlWaitForExecutionHandler and ControlHandler) ...
Definition: iec61850_server.h:794
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(* 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:757
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:816
AccessPolicy
Definition: iec61850_server.h:1026
Definition: iec61850_server.h:1027
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:931
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:1028
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_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:857
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
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.