libIEC61850  0.8.3
Open-source IEC 61850 MMS/GOOSE server and client library
 All Classes Files Functions Variables Typedefs Enumerations Enumerator 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, 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(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, char* goID);
344 
345 char*
346 ClientGooseControlBlock_getDatSet(ClientGooseControlBlock self);
347 
348 void
349 ClientGooseControlBlock_setDatSet(ClientGooseControlBlock self, 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, 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, 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 
623 void
624 IedConnection_installReportHandler(IedConnection self, char* rcbReference, char* rptId, ReportCallbackFunction handler,
625  void* handlerParameter);
626 
630 void
631 IedConnection_uninstallReportHandler(IedConnection self, char* rcbReference);
632 
642 void
643 IedConnection_triggerGIReport(IedConnection self, IedClientError* error, char* rcbReference);
644 
645 /****************************************
646  * Access to received reports
647  ****************************************/
648 
655 MmsValue*
656 ClientReport_getDataSetValues(ClientReport self);
657 
664 char*
665 ClientReport_getRcbReference(ClientReport self);
666 
673 char*
674 ClientReport_getRptId(ClientReport self);
675 
685 ClientReport_getReasonForInclusion(ClientReport self, int elementIndex);
686 
696 MmsValue*
697 ClientReport_getEntryId(ClientReport self);
698 
706 bool
707 ClientReport_hasTimestamp(ClientReport self);
708 
709 bool
710 ClientReport_hasSeqNum(ClientReport self);
711 
712 uint16_t
713 ClientReport_getSeqNum(ClientReport self);
714 
715 bool
716 ClientReport_hasDataSetName(ClientReport self);
717 
718 bool
719 ClientReport_hasReasonForInclusion(ClientReport self);
720 
721 bool
722 ClientReport_hasConfRev(ClientReport self);
723 
724 uint32_t
725 ClientReport_getConfRev(ClientReport self);
726 
727 bool
728 ClientReport_hasBufOvfl(ClientReport self);
729 
730 bool
731 ClientReport_hasDataReference(ClientReport self);
732 
733 
744 uint64_t
745 ClientReport_getTimestamp(ClientReport self);
746 
754 char*
756 
757 /**************************************************
758  * ClientReportControlBlock access class
759  **************************************************/
760 
761 ClientReportControlBlock
762 ClientReportControlBlock_create(char* rcbReference);
763 
764 void
765 ClientReportControlBlock_destroy(ClientReportControlBlock self);
766 
767 char*
768 ClientReportControlBlock_getObjectReference(ClientReportControlBlock self);
769 
770 bool
771 ClientReportControlBlock_isBuffered(ClientReportControlBlock self);
772 
773 char*
774 ClientReportControlBlock_getRptId(ClientReportControlBlock self);
775 
776 void
777 ClientReportControlBlock_setRptId(ClientReportControlBlock self, char* rptId);
778 
779 bool
780 ClientReportControlBlock_getRptEna(ClientReportControlBlock self);
781 
782 void
783 ClientReportControlBlock_setRptEna(ClientReportControlBlock self, bool rptEna);
784 
785 bool
786 ClientReportControlBlock_getResv(ClientReportControlBlock self);
787 
788 void
789 ClientReportControlBlock_setResv(ClientReportControlBlock self, bool resv);
790 
791 char*
792 ClientReportControlBlock_getDataSetReference(ClientReportControlBlock self);
793 
810 void
811 ClientReportControlBlock_setDataSetReference(ClientReportControlBlock self, char* dataSetReference);
812 
813 uint32_t
814 ClientReportControlBlock_getConfRev(ClientReportControlBlock self);
815 
816 int
817 ClientReportControlBlock_getOptFlds(ClientReportControlBlock self);
818 
819 void
820 ClientReportControlBlock_setOptFlds(ClientReportControlBlock self, int optFlds);
821 
822 uint32_t
823 ClientReportControlBlock_getBufTm(ClientReportControlBlock self);
824 
825 void
826 ClientReportControlBlock_setBufTm(ClientReportControlBlock self, uint32_t bufTm);
827 
828 uint16_t
829 ClientReportControlBlock_getSqNum(ClientReportControlBlock self);
830 
831 int
832 ClientReportControlBlock_getTrgOps(ClientReportControlBlock self);
833 
834 void
835 ClientReportControlBlock_setTrgOps(ClientReportControlBlock self, int trgOps);
836 
837 uint32_t
838 ClientReportControlBlock_getIntgPd(ClientReportControlBlock self);
839 
840 void
841 ClientReportControlBlock_setIntgPd(ClientReportControlBlock self, uint32_t intgPd);
842 
843 bool
844 ClientReportControlBlock_getGI(ClientReportControlBlock self);
845 
846 void
847 ClientReportControlBlock_setGI(ClientReportControlBlock self, bool gi);
848 
849 bool
850 ClientReportControlBlock_getPurgeBuf(ClientReportControlBlock self);
851 
852 void
853 ClientReportControlBlock_setPurgeBuf(ClientReportControlBlock self, bool purgeBuf);
854 
855 int16_t
856 ClientReportControlBlock_getResvTms(ClientReportControlBlock self);
857 
858 void
859 ClientReportControlBlock_setResvTms(ClientReportControlBlock self, int16_t resvTms);
860 
861 MmsValue* /* <MMS_OCTET_STRING> */
862 ClientReportControlBlock_getEntryId(ClientReportControlBlock self);
863 
864 void
865 ClientReportControlBlock_setEntryId(ClientReportControlBlock self, MmsValue* entryId);
866 
867 uint64_t
868 ClientReportControlBlock_getEntryTime(ClientReportControlBlock self);
869 
870 MmsValue* /* <MMS_OCTET_STRING> */
871 ClientReportControlBlock_getOwner(ClientReportControlBlock self);
872 
873 
876 /****************************************
877  * Data model access services
878  ****************************************/
879 
896 MmsValue*
897 IedConnection_readObject(IedConnection self, IedClientError* error, const char* dataAttributeReference, FunctionalConstraint fc);
898 
908 void
909 IedConnection_writeObject(IedConnection self, IedClientError* error, const char* dataAttributeReference, FunctionalConstraint fc,
910  MmsValue* value);
911 
912 
921 bool
922 IedConnection_readBooleanValue(IedConnection self, IedClientError* error, const char* objectReference, FunctionalConstraint fc);
923 
932 float
933 IedConnection_readFloatValue(IedConnection self, IedClientError* error, const char* objectReference, FunctionalConstraint fc);
934 
947 char*
948 IedConnection_readStringValue(IedConnection self, IedClientError* error, const char* objectReference, FunctionalConstraint fc);
949 
960 int32_t
961 IedConnection_readInt32Value(IedConnection self, IedClientError* error, const char* objectReference, FunctionalConstraint fc);
962 
973 uint32_t
974 IedConnection_readUnsigned32Value(IedConnection self, IedClientError* error, const char* objectReference, FunctionalConstraint fc);
975 
990 Timestamp*
991 IedConnection_readTimestampValue(IedConnection self, IedClientError* error, const char* objectReference, FunctionalConstraint fc,
992  Timestamp* timeStamp);
993 
1004 Quality
1005 IedConnection_readQualityValue(IedConnection self, IedClientError* error, const char* objectReference, FunctionalConstraint fc);
1006 
1016 void
1017 IedConnection_writeBooleanValue(IedConnection self, IedClientError* error, const char* objectReference,
1018  FunctionalConstraint fc, bool value);
1019 
1029 void
1030 IedConnection_writeInt32Value(IedConnection self, IedClientError* error, const char* objectReference,
1031  FunctionalConstraint fc, int32_t value);
1032 
1042 void
1043 IedConnection_writeUnsigned32Value(IedConnection self, IedClientError* error, const char* objectReference,
1044  FunctionalConstraint fc, uint32_t value);
1045 
1055 void
1056 IedConnection_writeFloatValue(IedConnection self, IedClientError* error, const char* objectReference,
1057  FunctionalConstraint fc, float value);
1058 
1059 void
1060 IedConnection_writeVisibleStringValue(IedConnection self, IedClientError* error, const char* objectReference,
1061  FunctionalConstraint fc, char* value);
1062 
1063 void
1064 IedConnection_writeOctetString(IedConnection self, IedClientError* error, const char* objectReference,
1065  FunctionalConstraint fc, uint8_t* value, int valueLength);
1066 
1069 /****************************************
1070  * Data set handling
1071  ****************************************/
1072 
1090 ClientDataSet
1091 IedConnection_readDataSetValues(IedConnection self, IedClientError* error, const char* dataSetReference, ClientDataSet dataSet);
1092 
1108 void
1109 IedConnection_createDataSet(IedConnection self, IedClientError* error, const char* dataSetReference, LinkedList /* char* */ dataSetElements);
1110 
1122 void
1123 IedConnection_deleteDataSet(IedConnection self, IedClientError* error, const char* dataSetReference);
1124 
1125 
1140 LinkedList /* <char*> */
1141 IedConnection_getDataSetDirectory(IedConnection self, IedClientError* error, const char* dataSetReference, bool* isDeletable);
1142 
1143 /********************************************************
1144  * Data set object (local representation of a data set)
1145  *******************************************************/
1146 
1155 void
1156 ClientDataSet_destroy(ClientDataSet self);
1157 
1172 MmsValue*
1173 ClientDataSet_getValues(ClientDataSet self);
1174 
1182 char*
1183 ClientDataSet_getReference(ClientDataSet self);
1184 
1192 int
1193 ClientDataSet_getDataSetSize(ClientDataSet self);
1194 
1197 /************************************
1198  * Control service functions
1199  ************************************/
1200 
1207 typedef struct sControlObjectClient* ControlObjectClient;
1208 
1209 typedef enum {
1215 } ControlModel;
1216 
1217 
1218 
1219 ControlObjectClient
1220 ControlObjectClient_create(char* dataAttributeReference, IedConnection connection);
1221 
1222 void
1223 ControlObjectClient_destroy(ControlObjectClient self);
1224 
1225 char*
1226 ControlObjectClient_getObjectReference(ControlObjectClient self);
1227 
1229 ControlObjectClient_getControlModel(ControlObjectClient self);
1230 
1231 bool
1232 ControlObjectClient_operate(ControlObjectClient self, MmsValue* ctlVal, uint64_t operTime);
1233 
1234 bool
1235 ControlObjectClient_select(ControlObjectClient self);
1236 
1237 bool
1238 ControlObjectClient_selectWithValue(ControlObjectClient self, MmsValue* ctlVal);
1239 
1240 bool
1241 ControlObjectClient_cancel(ControlObjectClient self);
1242 
1243 void
1244 ControlObjectClient_setLastApplError(ControlObjectClient self, LastApplError lastAppIError);
1245 
1247 ControlObjectClient_getLastApplError(ControlObjectClient self);
1248 
1249 void
1250 ControlObjectClient_setTestMode(ControlObjectClient self);
1251 
1252 void
1253 ControlObjectClient_setOrigin(ControlObjectClient self, const char* orIdent, int orCat);
1254 
1255 void
1256 ControlObjectClient_enableInterlockCheck(ControlObjectClient self);
1257 
1258 void
1259 ControlObjectClient_enableSynchroCheck(ControlObjectClient self);
1260 
1261 
1273 typedef void (*CommandTerminationHandler) (void* parameter, ControlObjectClient controlClient);
1274 
1275 void
1277  void* handlerParameter);
1278 
1281 /*************************************
1282  * Model discovery services
1283  ************************************/
1284 
1301 void
1302 IedConnection_getDeviceModelFromServer(IedConnection self, IedClientError* error);
1303 
1314 LinkedList /*<char*>*/
1315 IedConnection_getLogicalDeviceList(IedConnection self, IedClientError* error);
1316 
1329 LinkedList /*<char*>*/
1330 IedConnection_getServerDirectory(IedConnection self, IedClientError* error, bool getFileNames);
1331 
1345 LinkedList /*<char*>*/
1346 IedConnection_getLogicalDeviceDirectory(IedConnection self, IedClientError* error, const char* logicalDeviceName);
1347 
1348 typedef enum {
1360 } ACSIClass;
1361 
1375 LinkedList /*<char*>*/
1376 IedConnection_getLogicalNodeVariables(IedConnection self, IedClientError* error,
1377  const char* logicalNodeReference);
1378 
1392 LinkedList /*<char*>*/
1393 IedConnection_getLogicalNodeDirectory(IedConnection self, IedClientError* error,
1394  const char* logicalNodeReference, ACSIClass acsiClass);
1395 
1409 LinkedList /*<char*>*/
1410 IedConnection_getDataDirectory(IedConnection self, IedClientError* error, const char* dataReference);
1411 
1426 LinkedList /*<char*>*/
1427 IedConnection_getDataDirectoryFC(IedConnection self, IedClientError* error, const char* dataReference);
1428 
1444 LinkedList
1445 IedConnection_getDataDirectoryByFC(IedConnection self, IedClientError* error, const char* dataReference, FunctionalConstraint fc);
1446 
1461 MmsVariableSpecification*
1462 IedConnection_getVariableSpecification(IedConnection self, IedClientError* error, const char* dataAttributeReference,
1464 
1473 typedef struct sFileDirectoryEntry* FileDirectoryEntry;
1474 
1475 FileDirectoryEntry
1476 FileDirectoryEntry_create(const char* fileName, uint32_t fileSize, uint64_t lastModified);
1477 
1478 void
1479 FileDirectoryEntry_destroy(FileDirectoryEntry self);
1480 
1481 char*
1482 FileDirectoryEntry_getFileName(FileDirectoryEntry self);
1483 
1484 uint32_t
1485 FileDirectoryEntry_getFileSize(FileDirectoryEntry self);
1486 
1487 uint64_t
1488 FileDirectoryEntry_getLastModified(FileDirectoryEntry self);
1489 
1490 
1509 LinkedList /*<FileDirectoryEntry>*/
1510 IedConnection_getFileDirectory(IedConnection self, IedClientError* error, const char* directoryName);
1511 
1526 typedef bool
1527 (*IedClientGetFileHandler) (void* parameter, uint8_t* buffer, uint32_t bytesRead);
1528 
1540 uint32_t
1541 IedConnection_getFile(IedConnection self, IedClientError* error, const char* fileName, IedClientGetFileHandler handler,
1542  void* handlerParameter);
1543 
1553 void
1554 IedConnection_deleteFile(IedConnection self, IedClientError* error, const char* fileName);
1555 
1556 
1561 #ifdef __cplusplus
1562 }
1563 #endif
1564 
1565 
1566 #endif /* IEC61850_CLIENT_H_ */