libIEC61850  0.8.2
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 
719 uint64_t
720 ClientReport_getTimestamp(ClientReport self);
721 
729 char*
731 
732 /**************************************************
733  * ClientReportControlBlock access class
734  **************************************************/
735 
736 ClientReportControlBlock
737 ClientReportControlBlock_create(char* rcbReference);
738 
739 void
740 ClientReportControlBlock_destroy(ClientReportControlBlock self);
741 
742 char*
743 ClientReportControlBlock_getObjectReference(ClientReportControlBlock self);
744 
745 bool
746 ClientReportControlBlock_isBuffered(ClientReportControlBlock self);
747 
748 char*
749 ClientReportControlBlock_getRptId(ClientReportControlBlock self);
750 
751 void
752 ClientReportControlBlock_setRptId(ClientReportControlBlock self, char* rptId);
753 
754 bool
755 ClientReportControlBlock_getRptEna(ClientReportControlBlock self);
756 
757 void
758 ClientReportControlBlock_setRptEna(ClientReportControlBlock self, bool rptEna);
759 
760 bool
761 ClientReportControlBlock_getResv(ClientReportControlBlock self);
762 
763 void
764 ClientReportControlBlock_setResv(ClientReportControlBlock self, bool resv);
765 
766 char*
767 ClientReportControlBlock_getDataSetReference(ClientReportControlBlock self);
768 
785 void
786 ClientReportControlBlock_setDataSetReference(ClientReportControlBlock self, char* dataSetReference);
787 
788 uint32_t
789 ClientReportControlBlock_getConfRev(ClientReportControlBlock self);
790 
791 int
792 ClientReportControlBlock_getOptFlds(ClientReportControlBlock self);
793 
794 void
795 ClientReportControlBlock_setOptFlds(ClientReportControlBlock self, int optFlds);
796 
797 uint32_t
798 ClientReportControlBlock_getBufTm(ClientReportControlBlock self);
799 
800 void
801 ClientReportControlBlock_setBufTm(ClientReportControlBlock self, uint32_t bufTm);
802 
803 uint16_t
804 ClientReportControlBlock_getSqNum(ClientReportControlBlock self);
805 
806 int
807 ClientReportControlBlock_getTrgOps(ClientReportControlBlock self);
808 
809 void
810 ClientReportControlBlock_setTrgOps(ClientReportControlBlock self, int trgOps);
811 
812 uint32_t
813 ClientReportControlBlock_getIntgPd(ClientReportControlBlock self);
814 
815 void
816 ClientReportControlBlock_setIntgPd(ClientReportControlBlock self, uint32_t intgPd);
817 
818 bool
819 ClientReportControlBlock_getGI(ClientReportControlBlock self);
820 
821 void
822 ClientReportControlBlock_setGI(ClientReportControlBlock self, bool gi);
823 
824 bool
825 ClientReportControlBlock_getPurgeBuf(ClientReportControlBlock self);
826 
827 void
828 ClientReportControlBlock_setPurgeBuf(ClientReportControlBlock self, bool purgeBuf);
829 
830 int16_t
831 ClientReportControlBlock_getResvTms(ClientReportControlBlock self);
832 
833 void
834 ClientReportControlBlock_setResvTms(ClientReportControlBlock self, int16_t resvTms);
835 
836 MmsValue* /* <MMS_OCTET_STRING> */
837 ClientReportControlBlock_getEntryId(ClientReportControlBlock self);
838 
839 void
840 ClientReportControlBlock_setEntryId(ClientReportControlBlock self, MmsValue* entryId);
841 
842 uint64_t
843 ClientReportControlBlock_getEntryTime(ClientReportControlBlock self);
844 
845 MmsValue* /* <MMS_OCTET_STRING> */
846 ClientReportControlBlock_getOwner(ClientReportControlBlock self);
847 
848 
851 /****************************************
852  * Data model access services
853  ****************************************/
854 
871 MmsValue*
872 IedConnection_readObject(IedConnection self, IedClientError* error, const char* dataAttributeReference, FunctionalConstraint fc);
873 
883 void
884 IedConnection_writeObject(IedConnection self, IedClientError* error, const char* dataAttributeReference, FunctionalConstraint fc,
885  MmsValue* value);
886 
887 
896 bool
897 IedConnection_readBooleanValue(IedConnection self, IedClientError* error, const char* objectReference, FunctionalConstraint fc);
898 
907 float
908 IedConnection_readFloatValue(IedConnection self, IedClientError* error, const char* objectReference, FunctionalConstraint fc);
909 
922 char*
923 IedConnection_readStringValue(IedConnection self, IedClientError* error, const char* objectReference, FunctionalConstraint fc);
924 
935 int32_t
936 IedConnection_readInt32Value(IedConnection self, IedClientError* error, const char* objectReference, FunctionalConstraint fc);
937 
948 uint32_t
949 IedConnection_readUnsigned32Value(IedConnection self, IedClientError* error, const char* objectReference, FunctionalConstraint fc);
950 
965 Timestamp*
966 IedConnection_readTimestampValue(IedConnection self, IedClientError* error, const char* objectReference, FunctionalConstraint fc,
967  Timestamp* timeStamp);
968 
979 Quality
980 IedConnection_readQualityValue(IedConnection self, IedClientError* error, const char* objectReference, FunctionalConstraint fc);
981 
991 void
992 IedConnection_writeBooleanValue(IedConnection self, IedClientError* error, const char* objectReference,
993  FunctionalConstraint fc, bool value);
994 
1004 void
1005 IedConnection_writeInt32Value(IedConnection self, IedClientError* error, const char* objectReference,
1006  FunctionalConstraint fc, int32_t value);
1007 
1017 void
1018 IedConnection_writeUnsigned32Value(IedConnection self, IedClientError* error, const char* objectReference,
1019  FunctionalConstraint fc, uint32_t value);
1020 
1030 void
1031 IedConnection_writeFloatValue(IedConnection self, IedClientError* error, const char* objectReference,
1032  FunctionalConstraint fc, float value);
1033 
1034 void
1035 IedConnection_writeVisibleStringValue(IedConnection self, IedClientError* error, const char* objectReference,
1036  FunctionalConstraint fc, char* value);
1037 
1038 void
1039 IedConnection_writeOctetString(IedConnection self, IedClientError* error, const char* objectReference,
1040  FunctionalConstraint fc, uint8_t* value, int valueLength);
1041 
1044 /****************************************
1045  * Data set handling
1046  ****************************************/
1047 
1065 ClientDataSet
1066 IedConnection_readDataSetValues(IedConnection self, IedClientError* error, const char* dataSetReference, ClientDataSet dataSet);
1067 
1083 void
1084 IedConnection_createDataSet(IedConnection self, IedClientError* error, const char* dataSetReference, LinkedList /* char* */ dataSetElements);
1085 
1097 void
1098 IedConnection_deleteDataSet(IedConnection self, IedClientError* error, const char* dataSetReference);
1099 
1100 
1115 LinkedList /* <char*> */
1116 IedConnection_getDataSetDirectory(IedConnection self, IedClientError* error, const char* dataSetReference, bool* isDeletable);
1117 
1118 /********************************************************
1119  * Data set object (local representation of a data set)
1120  *******************************************************/
1121 
1130 void
1131 ClientDataSet_destroy(ClientDataSet self);
1132 
1147 MmsValue*
1148 ClientDataSet_getValues(ClientDataSet self);
1149 
1157 char*
1158 ClientDataSet_getReference(ClientDataSet self);
1159 
1167 int
1168 ClientDataSet_getDataSetSize(ClientDataSet self);
1169 
1172 /************************************
1173  * Control service functions
1174  ************************************/
1175 
1182 typedef struct sControlObjectClient* ControlObjectClient;
1183 
1184 typedef enum {
1190 } ControlModel;
1191 
1192 
1193 
1194 ControlObjectClient
1195 ControlObjectClient_create(char* dataAttributeReference, IedConnection connection);
1196 
1197 void
1198 ControlObjectClient_destroy(ControlObjectClient self);
1199 
1200 char*
1201 ControlObjectClient_getObjectReference(ControlObjectClient self);
1202 
1204 ControlObjectClient_getControlModel(ControlObjectClient self);
1205 
1206 bool
1207 ControlObjectClient_operate(ControlObjectClient self, MmsValue* ctlVal, uint64_t operTime);
1208 
1209 bool
1210 ControlObjectClient_select(ControlObjectClient self);
1211 
1212 bool
1213 ControlObjectClient_selectWithValue(ControlObjectClient self, MmsValue* ctlVal);
1214 
1215 bool
1216 ControlObjectClient_cancel(ControlObjectClient self);
1217 
1218 void
1219 ControlObjectClient_setLastApplError(ControlObjectClient self, LastApplError lastAppIError);
1220 
1222 ControlObjectClient_getLastApplError(ControlObjectClient self);
1223 
1224 void
1225 ControlObjectClient_setTestMode(ControlObjectClient self);
1226 
1227 void
1228 ControlObjectClient_setOrigin(ControlObjectClient self, const char* orIdent, int orCat);
1229 
1230 void
1231 ControlObjectClient_enableInterlockCheck(ControlObjectClient self);
1232 
1233 void
1234 ControlObjectClient_enableSynchroCheck(ControlObjectClient self);
1235 
1236 
1248 typedef void (*CommandTerminationHandler) (void* parameter, ControlObjectClient controlClient);
1249 
1250 void
1252  void* handlerParameter);
1253 
1256 /*************************************
1257  * Model discovery services
1258  ************************************/
1259 
1276 void
1277 IedConnection_getDeviceModelFromServer(IedConnection self, IedClientError* error);
1278 
1289 LinkedList /*<char*>*/
1290 IedConnection_getLogicalDeviceList(IedConnection self, IedClientError* error);
1291 
1304 LinkedList /*<char*>*/
1305 IedConnection_getServerDirectory(IedConnection self, IedClientError* error, bool getFileNames);
1306 
1320 LinkedList /*<char*>*/
1321 IedConnection_getLogicalDeviceDirectory(IedConnection self, IedClientError* error, const char* logicalDeviceName);
1322 
1323 typedef enum {
1335 } ACSIClass;
1336 
1350 LinkedList /*<char*>*/
1351 IedConnection_getLogicalNodeVariables(IedConnection self, IedClientError* error,
1352  const char* logicalNodeReference);
1353 
1367 LinkedList /*<char*>*/
1368 IedConnection_getLogicalNodeDirectory(IedConnection self, IedClientError* error,
1369  const char* logicalNodeReference, ACSIClass acsiClass);
1370 
1384 LinkedList /*<char*>*/
1385 IedConnection_getDataDirectory(IedConnection self, IedClientError* error, const char* dataReference);
1386 
1401 LinkedList /*<char*>*/
1402 IedConnection_getDataDirectoryFC(IedConnection self, IedClientError* error, const char* dataReference);
1403 
1419 LinkedList
1420 IedConnection_getDataDirectoryByFC(IedConnection self, IedClientError* error, const char* dataReference, FunctionalConstraint fc);
1421 
1436 MmsVariableSpecification*
1437 IedConnection_getVariableSpecification(IedConnection self, IedClientError* error, const char* dataAttributeReference,
1439 
1448 typedef struct sFileDirectoryEntry* FileDirectoryEntry;
1449 
1450 FileDirectoryEntry
1451 FileDirectoryEntry_create(const char* fileName, uint32_t fileSize, uint64_t lastModified);
1452 
1453 void
1454 FileDirectoryEntry_destroy(FileDirectoryEntry self);
1455 
1456 char*
1457 FileDirectoryEntry_getFileName(FileDirectoryEntry self);
1458 
1459 uint32_t
1460 FileDirectoryEntry_getFileSize(FileDirectoryEntry self);
1461 
1462 uint64_t
1463 FileDirectoryEntry_getLastModified(FileDirectoryEntry self);
1464 
1465 
1484 LinkedList /*<FileDirectoryEntry>*/
1485 IedConnection_getFileDirectory(IedConnection self, IedClientError* error, const char* directoryName);
1486 
1501 typedef bool
1502 (*IedClientGetFileHandler) (void* parameter, uint8_t* buffer, uint32_t bytesRead);
1503 
1515 uint32_t
1516 IedConnection_getFile(IedConnection self, IedClientError* error, const char* fileName, IedClientGetFileHandler handler,
1517  void* handlerParameter);
1518 
1528 void
1529 IedConnection_deleteFile(IedConnection self, IedClientError* error, const char* fileName);
1530 
1531 
1536 #ifdef __cplusplus
1537 }
1538 #endif
1539 
1540 
1541 #endif /* IEC61850_CLIENT_H_ */