libIEC61850  0.8.4
Open-source IEC 61850 MMS/GOOSE server and client library
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
iec61850_client.h
Go to the documentation of this file.
1 /*
2  * iec61850_client.h
3  *
4  * Copyright 2013, 2014 Michael Zillgith
5  *
6  * This file is part of libIEC61850.
7  *
8  * libIEC61850 is free software: you can redistribute it and/or modify
9  * it under the terms of the GNU General Public License as published by
10  * the Free Software Foundation, either version 3 of the License, or
11  * (at your option) any later version.
12  *
13  * libIEC61850 is distributed in the hope that it will be useful,
14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16  * GNU General Public License for more details.
17  *
18  * You should have received a copy of the GNU General Public License
19  * along with libIEC61850. If not, see <http://www.gnu.org/licenses/>.
20  *
21  * See COPYING file for the complete license text.
22  */
23 
24 #ifndef IEC61850_CLIENT_H_
25 #define IEC61850_CLIENT_H_
26 
27 #ifdef __cplusplus
28 extern "C" {
29 #endif
30 
31 #include "libiec61850_common_api.h"
32 #include "iec61850_common.h"
33 #include "goose_subscriber.h"
34 #include "mms_value.h"
35 #include "mms_client_connection.h"
36 #include "linked_list.h"
37 
44 typedef struct sClientDataSet* ClientDataSet;
45 
47 typedef struct sClientReport* ClientReport;
48 
50 typedef struct sClientReportControlBlock* ClientReportControlBlock;
51 
53 typedef struct sClientGooseControlBlock* ClientGooseControlBlock;
54 
62 typedef struct sIedConnection* IedConnection;
63 
65 typedef struct
66 {
67  int ctlNum;
68  int error;
71 
73 typedef enum
74 {
79 
81 typedef enum {
82  /* general errors */
83 
86 
89 
92 
95 
98 
101 
102  /* client side errors */
103 
106 
108 
111 
114 
115  /* service error - error reported by server */
116 
119 
122 
125 
128 
131 
132  /* unknown error */
135 
136 /**************************************************
137  * Connection creation and destruction
138  **************************************************/
139 
149 IedConnection
151 
160 void
161 IedConnection_destroy(IedConnection self);
162 
163 
173 void
174 IedConnection_setConnectTimeout(IedConnection self, uint32_t timeoutInMs);
175 
176 /**************************************************
177  * Association service
178  **************************************************/
179 
188 void
189 IedConnection_connect(IedConnection self, IedClientError* error, const char* hostname, int tcpPort);
190 
203 void
204 IedConnection_abort(IedConnection self, IedClientError* error);
205 
218 void
219 IedConnection_release(IedConnection self, IedClientError* error);
220 
228 void
229 IedConnection_close(IedConnection self);
230 
241 IedConnection_getState(IedConnection self);
242 
251 IedConnection_getLastApplError(IedConnection self);
252 
253 
254 typedef void (*IedConnectionClosedHandler) (void* parameter, IedConnection connection);
255 
263 void
265  void* parameter);
266 
278 IedConnection_getMmsConnection(IedConnection self);
279 
288 /*********************************************************
289  * GOOSE services handling (MMS part)
290  ********************************************************/
291 
293 #define GOCB_ELEMENT_GO_ENA 1
294 
296 #define GOCB_ELEMENT_GO_ID 2
297 
299 #define GOCB_ELEMENT_DATSET 4
300 
302 #define GOCB_ELEMENT_CONF_REV 8
303 
305 #define GOCB_ELEMENT_NDS_COMM 16
306 
308 #define GOCB_ELEMENT_DST_ADDRESS 32
309 
311 #define GOCB_ELEMENT_MIN_TIME 64
312 
314 #define GOCB_ELEMENT_MAX_TIME 128
315 
317 #define GOCB_ELEMENT_FIXED_OFFS 256
318 
320 #define GOCB_ELEMENT_ALL 511
321 
322 
323 /**************************************************
324  * ClientGooseControlBlock class
325  **************************************************/
326 
327 ClientGooseControlBlock
328 ClientGooseControlBlock_create(const char* dataAttributeReference);
329 
330 void
331 ClientGooseControlBlock_destroy(ClientGooseControlBlock self);
332 
333 bool
334 ClientGooseControlBlock_getGoEna(ClientGooseControlBlock self);
335 
336 void
337 ClientGooseControlBlock_setGoEna(ClientGooseControlBlock self, bool goEna);
338 
339 char*
340 ClientGooseControlBlock_getGoID(ClientGooseControlBlock self);
341 
342 void
343 ClientGooseControlBlock_setGoID(ClientGooseControlBlock self, const char* goID);
344 
345 char*
346 ClientGooseControlBlock_getDatSet(ClientGooseControlBlock self);
347 
348 void
349 ClientGooseControlBlock_setDatSet(ClientGooseControlBlock self, const char* datSet);
350 
351 uint32_t
352 ClientGooseControlBlock_getConfRev(ClientGooseControlBlock self);
353 
354 bool
355 ClientGooseControlBlock_getNdsComm(ClientGooseControlBlock self);
356 
357 uint32_t
358 ClientGooseControlBlock_getMinTime(ClientGooseControlBlock self);
359 
360 uint32_t
361 ClientGooseControlBlock_getMaxTime(ClientGooseControlBlock self);
362 
363 bool
364 ClientGooseControlBlock_getFixedOffs(ClientGooseControlBlock self);
365 
366 MmsValue* /* MMS_OCTET_STRING */
367 ClientGooseControlBlock_getDstAddress_addr(ClientGooseControlBlock self);
368 
369 void
370 ClientGooseControlBlock_setDstAddress_addr(ClientGooseControlBlock self, MmsValue* macAddr);
371 
372 uint8_t
373 ClientGooseControlBlock_getDstAddress_priority(ClientGooseControlBlock self);
374 
375 void
376 ClientGooseControlBlock_setDstAddress_priority(ClientGooseControlBlock self, uint8_t priorityValue);
377 
378 uint16_t
379 ClientGooseControlBlock_getDstAddress_vid(ClientGooseControlBlock self);
380 
381 void
382 ClientGooseControlBlock_setDstAddress_vid(ClientGooseControlBlock self, uint16_t vidValue);
383 
384 uint16_t
385 ClientGooseControlBlock_getDstAddress_appid(ClientGooseControlBlock self);
386 
387 void
388 ClientGooseControlBlock_setDstAddress_appid(ClientGooseControlBlock self, uint16_t appidValue);
389 
390 
391 /*********************************************************
392  * GOOSE services (access to GOOSE Control Blocks (GoCB))
393  ********************************************************/
394 
422 ClientGooseControlBlock
423 IedConnection_getGoCBValues(IedConnection self, IedClientError* error, const char* goCBReference, ClientGooseControlBlock updateGoCB);
424 
446 void
447 IedConnection_setGoCBValues(IedConnection self, IedClientError* error, ClientGooseControlBlock goCB,
448  uint32_t parametersMask, bool singleRequest);
449 
452 /********************************************
453  * Reporting services
454  ********************************************/
455 
495 ClientReportControlBlock
496 IedConnection_getRCBValues(IedConnection self, IedClientError* error, const char* rcbReference,
497  ClientReportControlBlock updateRcb);
498 
500 typedef enum {
503 
506 
509 
512 
515 
518 
522 
523 
524 /* Element encoding mask values for ClientReportControlBlock */
525 
527 #define RCB_ELEMENT_RPT_ID 1
528 
530 #define RCB_ELEMENT_RPT_ENA 2
531 
533 #define RCB_ELEMENT_RESV 4
534 
536 #define RCB_ELEMENT_DATSET 8
537 
539 #define RCB_ELEMENT_CONF_REV 16
540 
542 #define RCB_ELEMENT_OPT_FLDS 32
543 
545 #define RCB_ELEMENT_BUF_TM 64
546 
548 #define RCB_ELEMENT_SQ_NUM 128
549 
551 #define RCB_ELEMENT_TRG_OPS 256
552 
554 #define RCB_ELEMENT_INTG_PD 512
555 
557 #define RCB_ELEMENT_GI 1024
558 
560 #define RCB_ELEMENT_PURGE_BUF 2048
561 
563 #define RCB_ELEMENT_ENTRY_ID 4096
564 
566 #define RCB_ELEMENT_TIME_OF_ENTRY 8192
567 
569 #define RCB_ELEMENT_RESV_TMS 16384
570 
572 #define RCB_ELEMENT_OWNER 32768
573 
595 void
596 IedConnection_setRCBValues(IedConnection self, IedClientError* error, ClientReportControlBlock rcb,
597  uint32_t parametersMask, bool singleRequest);
598 
605 typedef void (*ReportCallbackFunction) (void* parameter, ClientReport report);
606 
626 void
627 IedConnection_installReportHandler(IedConnection self, const char* rcbReference, const char* rptId, ReportCallbackFunction handler,
628  void* handlerParameter);
629 
636 void
637 IedConnection_uninstallReportHandler(IedConnection self, const char* rcbReference);
638 
648 void
649 IedConnection_triggerGIReport(IedConnection self, IedClientError* error, const char* rcbReference);
650 
651 /****************************************
652  * Access to received reports
653  ****************************************/
654 
661 MmsValue*
662 ClientReport_getDataSetValues(ClientReport self);
663 
670 char*
671 ClientReport_getRcbReference(ClientReport self);
672 
679 char*
680 ClientReport_getRptId(ClientReport self);
681 
691 ClientReport_getReasonForInclusion(ClientReport self, int elementIndex);
692 
702 MmsValue*
703 ClientReport_getEntryId(ClientReport self);
704 
712 bool
713 ClientReport_hasTimestamp(ClientReport self);
714 
715 bool
716 ClientReport_hasSeqNum(ClientReport self);
717 
718 uint16_t
719 ClientReport_getSeqNum(ClientReport self);
720 
721 bool
722 ClientReport_hasDataSetName(ClientReport self);
723 
724 bool
725 ClientReport_hasReasonForInclusion(ClientReport self);
726 
727 bool
728 ClientReport_hasConfRev(ClientReport self);
729 
730 uint32_t
731 ClientReport_getConfRev(ClientReport self);
732 
733 bool
734 ClientReport_hasBufOvfl(ClientReport self);
735 
743 bool
744 ClientReport_hasDataReference(ClientReport self);
745 
759 const char*
760 ClientReport_getDataReference(ClientReport self, int elementIndex);
761 
762 
773 uint64_t
774 ClientReport_getTimestamp(ClientReport self);
775 
783 char*
785 
786 /**************************************************
787  * ClientReportControlBlock access class
788  **************************************************/
789 
790 ClientReportControlBlock
791 ClientReportControlBlock_create(const char* rcbReference);
792 
793 void
794 ClientReportControlBlock_destroy(ClientReportControlBlock self);
795 
796 char*
797 ClientReportControlBlock_getObjectReference(ClientReportControlBlock self);
798 
799 bool
800 ClientReportControlBlock_isBuffered(ClientReportControlBlock self);
801 
802 char*
803 ClientReportControlBlock_getRptId(ClientReportControlBlock self);
804 
805 void
806 ClientReportControlBlock_setRptId(ClientReportControlBlock self, const char* rptId);
807 
808 bool
809 ClientReportControlBlock_getRptEna(ClientReportControlBlock self);
810 
811 void
812 ClientReportControlBlock_setRptEna(ClientReportControlBlock self, bool rptEna);
813 
814 bool
815 ClientReportControlBlock_getResv(ClientReportControlBlock self);
816 
817 void
818 ClientReportControlBlock_setResv(ClientReportControlBlock self, bool resv);
819 
820 char*
821 ClientReportControlBlock_getDataSetReference(ClientReportControlBlock self);
822 
839 void
840 ClientReportControlBlock_setDataSetReference(ClientReportControlBlock self, const char* dataSetReference);
841 
842 uint32_t
843 ClientReportControlBlock_getConfRev(ClientReportControlBlock self);
844 
845 int
846 ClientReportControlBlock_getOptFlds(ClientReportControlBlock self);
847 
848 void
849 ClientReportControlBlock_setOptFlds(ClientReportControlBlock self, int optFlds);
850 
851 uint32_t
852 ClientReportControlBlock_getBufTm(ClientReportControlBlock self);
853 
854 void
855 ClientReportControlBlock_setBufTm(ClientReportControlBlock self, uint32_t bufTm);
856 
857 uint16_t
858 ClientReportControlBlock_getSqNum(ClientReportControlBlock self);
859 
860 int
861 ClientReportControlBlock_getTrgOps(ClientReportControlBlock self);
862 
863 void
864 ClientReportControlBlock_setTrgOps(ClientReportControlBlock self, int trgOps);
865 
866 uint32_t
867 ClientReportControlBlock_getIntgPd(ClientReportControlBlock self);
868 
869 void
870 ClientReportControlBlock_setIntgPd(ClientReportControlBlock self, uint32_t intgPd);
871 
872 bool
873 ClientReportControlBlock_getGI(ClientReportControlBlock self);
874 
875 void
876 ClientReportControlBlock_setGI(ClientReportControlBlock self, bool gi);
877 
878 bool
879 ClientReportControlBlock_getPurgeBuf(ClientReportControlBlock self);
880 
881 void
882 ClientReportControlBlock_setPurgeBuf(ClientReportControlBlock self, bool purgeBuf);
883 
884 int16_t
885 ClientReportControlBlock_getResvTms(ClientReportControlBlock self);
886 
887 void
888 ClientReportControlBlock_setResvTms(ClientReportControlBlock self, int16_t resvTms);
889 
890 MmsValue* /* <MMS_OCTET_STRING> */
891 ClientReportControlBlock_getEntryId(ClientReportControlBlock self);
892 
893 void
894 ClientReportControlBlock_setEntryId(ClientReportControlBlock self, MmsValue* entryId);
895 
896 uint64_t
897 ClientReportControlBlock_getEntryTime(ClientReportControlBlock self);
898 
899 MmsValue* /* <MMS_OCTET_STRING> */
900 ClientReportControlBlock_getOwner(ClientReportControlBlock self);
901 
902 
905 /****************************************
906  * Data model access services
907  ****************************************/
908 
925 MmsValue*
926 IedConnection_readObject(IedConnection self, IedClientError* error, const char* dataAttributeReference, FunctionalConstraint fc);
927 
937 void
938 IedConnection_writeObject(IedConnection self, IedClientError* error, const char* dataAttributeReference, FunctionalConstraint fc,
939  MmsValue* value);
940 
941 
950 bool
951 IedConnection_readBooleanValue(IedConnection self, IedClientError* error, const char* objectReference, FunctionalConstraint fc);
952 
961 float
962 IedConnection_readFloatValue(IedConnection self, IedClientError* error, const char* objectReference, FunctionalConstraint fc);
963 
976 char*
977 IedConnection_readStringValue(IedConnection self, IedClientError* error, const char* objectReference, FunctionalConstraint fc);
978 
989 int32_t
990 IedConnection_readInt32Value(IedConnection self, IedClientError* error, const char* objectReference, FunctionalConstraint fc);
991 
1002 uint32_t
1003 IedConnection_readUnsigned32Value(IedConnection self, IedClientError* error, const char* objectReference, FunctionalConstraint fc);
1004 
1019 Timestamp*
1020 IedConnection_readTimestampValue(IedConnection self, IedClientError* error, const char* objectReference, FunctionalConstraint fc,
1021  Timestamp* timeStamp);
1022 
1033 Quality
1034 IedConnection_readQualityValue(IedConnection self, IedClientError* error, const char* objectReference, FunctionalConstraint fc);
1035 
1045 void
1046 IedConnection_writeBooleanValue(IedConnection self, IedClientError* error, const char* objectReference,
1047  FunctionalConstraint fc, bool value);
1048 
1058 void
1059 IedConnection_writeInt32Value(IedConnection self, IedClientError* error, const char* objectReference,
1060  FunctionalConstraint fc, int32_t value);
1061 
1071 void
1072 IedConnection_writeUnsigned32Value(IedConnection self, IedClientError* error, const char* objectReference,
1073  FunctionalConstraint fc, uint32_t value);
1074 
1084 void
1085 IedConnection_writeFloatValue(IedConnection self, IedClientError* error, const char* objectReference,
1086  FunctionalConstraint fc, float value);
1087 
1088 void
1089 IedConnection_writeVisibleStringValue(IedConnection self, IedClientError* error, const char* objectReference,
1090  FunctionalConstraint fc, char* value);
1091 
1092 void
1093 IedConnection_writeOctetString(IedConnection self, IedClientError* error, const char* objectReference,
1094  FunctionalConstraint fc, uint8_t* value, int valueLength);
1095 
1098 /****************************************
1099  * Data set handling
1100  ****************************************/
1101 
1119 ClientDataSet
1120 IedConnection_readDataSetValues(IedConnection self, IedClientError* error, const char* dataSetReference, ClientDataSet dataSet);
1121 
1137 void
1138 IedConnection_createDataSet(IedConnection self, IedClientError* error, const char* dataSetReference, LinkedList /* char* */ dataSetElements);
1139 
1151 void
1152 IedConnection_deleteDataSet(IedConnection self, IedClientError* error, const char* dataSetReference);
1153 
1154 
1169 LinkedList /* <char*> */
1170 IedConnection_getDataSetDirectory(IedConnection self, IedClientError* error, const char* dataSetReference, bool* isDeletable);
1171 
1172 /********************************************************
1173  * Data set object (local representation of a data set)
1174  *******************************************************/
1175 
1184 void
1185 ClientDataSet_destroy(ClientDataSet self);
1186 
1201 MmsValue*
1202 ClientDataSet_getValues(ClientDataSet self);
1203 
1211 char*
1212 ClientDataSet_getReference(ClientDataSet self);
1213 
1221 int
1222 ClientDataSet_getDataSetSize(ClientDataSet self);
1223 
1226 /************************************
1227  * Control service functions
1228  ************************************/
1229 
1236 typedef struct sControlObjectClient* ControlObjectClient;
1237 
1238 typedef enum {
1244 } ControlModel;
1245 
1246 
1258 ControlObjectClient
1259 ControlObjectClient_create(const char* objectReference, IedConnection connection);
1260 
1261 void
1262 ControlObjectClient_destroy(ControlObjectClient self);
1263 
1264 char*
1265 ControlObjectClient_getObjectReference(ControlObjectClient self);
1266 
1268 ControlObjectClient_getControlModel(ControlObjectClient self);
1269 
1270 bool
1271 ControlObjectClient_operate(ControlObjectClient self, MmsValue* ctlVal, uint64_t operTime);
1272 
1273 bool
1274 ControlObjectClient_select(ControlObjectClient self);
1275 
1276 bool
1277 ControlObjectClient_selectWithValue(ControlObjectClient self, MmsValue* ctlVal);
1278 
1279 bool
1280 ControlObjectClient_cancel(ControlObjectClient self);
1281 
1282 void
1283 ControlObjectClient_setLastApplError(ControlObjectClient self, LastApplError lastAppIError);
1284 
1286 ControlObjectClient_getLastApplError(ControlObjectClient self);
1287 
1288 void
1289 ControlObjectClient_setTestMode(ControlObjectClient self);
1290 
1291 void
1292 ControlObjectClient_setOrigin(ControlObjectClient self, const char* orIdent, int orCat);
1293 
1294 void
1295 ControlObjectClient_enableInterlockCheck(ControlObjectClient self);
1296 
1297 void
1298 ControlObjectClient_enableSynchroCheck(ControlObjectClient self);
1299 
1300 
1312 typedef void (*CommandTerminationHandler) (void* parameter, ControlObjectClient controlClient);
1313 
1314 void
1316  void* handlerParameter);
1317 
1320 /*************************************
1321  * Model discovery services
1322  ************************************/
1323 
1340 void
1341 IedConnection_getDeviceModelFromServer(IedConnection self, IedClientError* error);
1342 
1353 LinkedList /*<char*>*/
1354 IedConnection_getLogicalDeviceList(IedConnection self, IedClientError* error);
1355 
1368 LinkedList /*<char*>*/
1369 IedConnection_getServerDirectory(IedConnection self, IedClientError* error, bool getFileNames);
1370 
1384 LinkedList /*<char*>*/
1385 IedConnection_getLogicalDeviceDirectory(IedConnection self, IedClientError* error, const char* logicalDeviceName);
1386 
1387 typedef enum {
1399 } ACSIClass;
1400 
1414 LinkedList /*<char*>*/
1415 IedConnection_getLogicalNodeVariables(IedConnection self, IedClientError* error,
1416  const char* logicalNodeReference);
1417 
1431 LinkedList /*<char*>*/
1432 IedConnection_getLogicalNodeDirectory(IedConnection self, IedClientError* error,
1433  const char* logicalNodeReference, ACSIClass acsiClass);
1434 
1448 LinkedList /*<char*>*/
1449 IedConnection_getDataDirectory(IedConnection self, IedClientError* error, const char* dataReference);
1450 
1465 LinkedList /*<char*>*/
1466 IedConnection_getDataDirectoryFC(IedConnection self, IedClientError* error, const char* dataReference);
1467 
1483 LinkedList
1484 IedConnection_getDataDirectoryByFC(IedConnection self, IedClientError* error, const char* dataReference, FunctionalConstraint fc);
1485 
1500 MmsVariableSpecification*
1501 IedConnection_getVariableSpecification(IedConnection self, IedClientError* error, const char* dataAttributeReference,
1503 
1512 typedef struct sFileDirectoryEntry* FileDirectoryEntry;
1513 
1514 FileDirectoryEntry
1515 FileDirectoryEntry_create(const char* fileName, uint32_t fileSize, uint64_t lastModified);
1516 
1517 void
1518 FileDirectoryEntry_destroy(FileDirectoryEntry self);
1519 
1520 char*
1521 FileDirectoryEntry_getFileName(FileDirectoryEntry self);
1522 
1523 uint32_t
1524 FileDirectoryEntry_getFileSize(FileDirectoryEntry self);
1525 
1526 uint64_t
1527 FileDirectoryEntry_getLastModified(FileDirectoryEntry self);
1528 
1529 
1548 LinkedList /*<FileDirectoryEntry>*/
1549 IedConnection_getFileDirectory(IedConnection self, IedClientError* error, const char* directoryName);
1550 
1565 typedef bool
1566 (*IedClientGetFileHandler) (void* parameter, uint8_t* buffer, uint32_t bytesRead);
1567 
1579 uint32_t
1580 IedConnection_getFile(IedConnection self, IedClientError* error, const char* fileName, IedClientGetFileHandler handler,
1581  void* handlerParameter);
1582 
1592 void
1593 IedConnection_deleteFile(IedConnection self, IedClientError* error, const char* fileName);
1594 
1595 
1600 #ifdef __cplusplus
1601 }
1602 #endif
1603 
1604 
1605 #endif /* IEC61850_CLIENT_H_ */