libIEC61850  1.0.1
Open-source IEC 61850 MMS/GOOSE/SV server and client library
mms_client_connection.h
Go to the documentation of this file.
1 /*
2  * mms_client_connection.h
3  *
4  * Copyright 2013-2016 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 MMS_CLIENT_CONNECTION_H_
25 #define MMS_CLIENT_CONNECTION_H_
26 
27 #ifdef __cplusplus
28 extern "C" {
29 #endif
30 
36 #include "libiec61850_common_api.h"
37 
38 #include "mms_common.h"
39 #include "mms_type_spec.h"
40 #include "mms_value.h"
42 #include "linked_list.h"
43 
47 typedef struct sMmsConnectionParameters {
51  int maxPduSize; /* local detail */
52  uint8_t servicesSupported[11];
54 
55 typedef struct {
56  char* vendorName;
57  char* modelName;
58  char* revision;
60 
61 typedef void (*MmsInformationReportHandler) (void* parameter, char* domainName,
62  char* variableListName, MmsValue* value, bool isVariableListName);
63 
67 typedef struct sMmsConnection* MmsConnection;
68 
69 
70 /*******************************************************************************
71  * Connection management functions
72  *******************************************************************************/
73 
79 MmsConnection
81 
93 typedef void (*MmsRawMessageHandler) (void* parameter, uint8_t* message, int messageLength, bool received);
94 
106 void
107 MmsConnection_setRawMessageHandler(MmsConnection self, MmsRawMessageHandler handler, void* parameter);
108 
115 void
116 MmsConnection_setRequestTimeout(MmsConnection self, uint32_t timeoutInMs);
117 
124 void
125 MmsConnection_setConnectTimeout(MmsConnection self, uint32_t timeoutInMs);
126 
138 void
140  void* parameter);
141 
148 IsoConnectionParameters
149 MmsConnection_getIsoConnectionParameters(MmsConnection self);
150 
158 MmsConnection_getMmsConnectionParameters(MmsConnection self);
159 
166 typedef void (*MmsConnectionLostHandler) (MmsConnection connection, void* parameter);
167 
174 void
175 MmsConnection_setConnectionLostHandler(MmsConnection self, MmsConnectionLostHandler handler, void* handlerParameter);
176 
183 void
184 MmsConnection_setIsoConnectionParameters(MmsConnection self, IsoConnectionParameters* params);
185 
191 void
192 MmsConnection_destroy(MmsConnection self);
193 
194 /*******************************************************************************
195  * Blocking functions for connection establishment and data access
196  *******************************************************************************/
197 
198 
211 bool
212 MmsConnection_connect(MmsConnection self, MmsError* mmsError, const char* serverName, int serverPort);
213 
222 void
223 MmsConnection_close(MmsConnection self);
224 
236 void
237 MmsConnection_abort(MmsConnection self, MmsError* mmsError);
238 
250 void
251 MmsConnection_conclude(MmsConnection self, MmsError* mmsError);
252 
253 
264 LinkedList /* <char*> */
265 MmsConnection_getVMDVariableNames(MmsConnection self, MmsError* mmsError);
266 
278 LinkedList /* <char*> */
279 MmsConnection_getDomainNames(MmsConnection self, MmsError* mmsError);
280 
292 LinkedList /* <char*> */
293 MmsConnection_getDomainVariableNames(MmsConnection self, MmsError* mmsError, const char* domainId);
294 
306 LinkedList /* <char*> */
307 MmsConnection_getDomainVariableListNames(MmsConnection self, MmsError* mmsError, const char* domainId);
308 
320 LinkedList /* <char*> */
321 MmsConnection_getDomainJournals(MmsConnection self, MmsError* mmsError, const char* domainId);
322 
333 LinkedList /* <char*> */
335 
336 
349 MmsValue*
350 MmsConnection_readVariable(MmsConnection self, MmsError* mmsError, const char* domainId, const char* itemId);
351 
366 MmsValue*
367 MmsConnection_readArrayElements(MmsConnection self, MmsError* mmsError, const char* domainId, const char* itemId,
368  uint32_t startIndex, uint32_t numberOfElements);
369 
382 MmsValue*
383 MmsConnection_readMultipleVariables(MmsConnection self, MmsError* mmsError, const char* domainId,
384  LinkedList /*<char*>*/ items);
385 
395 void
396 MmsConnection_writeVariable(MmsConnection self, MmsError* mmsError,
397  const char* domainId, const char* itemId, MmsValue* value);
398 
416 void
417 MmsConnection_writeMultipleVariables(MmsConnection self, MmsError* mmsError, const char* domainId,
418  LinkedList /*<char*>*/ items, LinkedList /* <MmsValue*> */ values,
419  LinkedList* /* <MmsValue*> */ accessResults);
420 
431 MmsVariableSpecification*
432 MmsConnection_getVariableAccessAttributes(MmsConnection self, MmsError* mmsError,
433  const char* domainId, const char* itemId);
434 
451 MmsValue*
452 MmsConnection_readNamedVariableListValues(MmsConnection self, MmsError* mmsError, const char* domainId,
453  const char* listName, bool specWithResult);
454 
455 
468 MmsValue*
470  const char* listName, bool specWithResult);
471 
485 void
486 MmsConnection_defineNamedVariableList(MmsConnection self, MmsError* mmsError, const char* domainId,
487  const char* listName, LinkedList variableSpecs);
488 
489 
499 void
501  const char* listName, LinkedList variableSpecs);
502 
518 LinkedList /* <MmsVariableAccessSpecification*> */
519 MmsConnection_readNamedVariableListDirectory(MmsConnection self, MmsError* mmsError,
520  const char* domainId, const char* listName, bool* deletable);
521 
522 
523 
533 LinkedList /* <MmsVariableAccessSpecification*> */
535  const char* listName, bool* deletable);
536 
550 bool
551 MmsConnection_deleteNamedVariableList(MmsConnection self, MmsError* mmsError, const char* domainId, const char* listName);
552 
562 bool
564  const char* listName);
565 
578 MmsVariableAccessSpecification_create(char* domainId, char* itemId);
579 
597 MmsVariableAccessSpecification_createAlternateAccess(char* domainId, char* itemId, int32_t index,
598  char* componentName);
599 
605 void
607 
617 void
618 MmsConnection_setLocalDetail(MmsConnection self, int32_t localDetail);
619 
620 int32_t
621 MmsConnection_getLocalDetail(MmsConnection self);
622 
633 MmsConnection_identify(MmsConnection self, MmsError* mmsError);
634 
635 void
637 
650 void
651 MmsConnection_getServerStatus(MmsConnection self, MmsError* mmsError, int* vmdLogicalStatus, int* vmdPhysicalStatus,
652  bool extendedDerivation);
653 
654 /*******************************************************************************
655  * functions for MMS file services
656  *******************************************************************************/
657 
658 typedef void
659 (*MmsFileDirectoryHandler) (void* parameter, char* filename, uint32_t size, uint64_t lastModified);
660 
661 typedef void
662 (*MmsFileReadHandler) (void* parameter, int32_t frsmId, uint8_t* buffer, uint32_t bytesReceived);
663 
664 
673 int32_t
674 MmsConnection_fileOpen(MmsConnection self, MmsError* mmsError, const char* filename, uint32_t initialPosition,
675  uint32_t* fileSize, uint64_t* lastModified);
676 
688 bool
689 MmsConnection_fileRead(MmsConnection self, MmsError* mmsError, int32_t frsmId, MmsFileReadHandler handler, void* handlerParameter);
690 
698 void
699 MmsConnection_fileClose(MmsConnection self, MmsError* mmsError, int32_t frsmId);
700 
708 void
709 MmsConnection_fileDelete(MmsConnection self, MmsError* mmsError, const char* fileName);
710 
719 void
720 MmsConnection_fileRename(MmsConnection self, MmsError* mmsError, const char* currentFileName, const char* newFileName);
721 
722 
731 void
732 MmsConnection_obtainFile(MmsConnection self, MmsError* mmsError, const char* sourceFile, const char* destinationFile);
733 
750 bool
751 MmsConnection_getFileDirectory(MmsConnection self, MmsError* mmsError, const char* fileSpecification, const char* continueAfter,
752  MmsFileDirectoryHandler handler, void* handlerParameter);
753 
754 typedef struct sMmsJournalEntry* MmsJournalEntry;
755 
756 typedef struct sMmsJournalVariable* MmsJournalVariable;
757 
759  MmsValue* entryID; /* type MMS_OCTET_STRING */
760  MmsValue* occurenceTime; /* type MMS_BINARY_TIME */
761  LinkedList journalVariables;
762 };
763 
765  char* tag;
767 };
768 
782 void
783 MmsJournalEntry_destroy(MmsJournalEntry self);
784 
785 const MmsValue*
786 MmsJournalEntry_getEntryID(MmsJournalEntry self);
787 
788 const MmsValue*
789 MmsJournalEntry_getOccurenceTime(MmsJournalEntry self);
790 
791 const LinkedList /* <MmsJournalVariable> */
792 MmsJournalEntry_getJournalVariables(MmsJournalEntry self);
793 
794 const char*
795 MmsJournalVariable_getTag(MmsJournalVariable self);
796 
797 const MmsValue*
798 MmsJournalVariable_getValue(MmsJournalVariable self);
799 
800 
801 LinkedList
802 MmsConnection_readJournalTimeRange(MmsConnection self, MmsError* mmsError, const char* domainId, const char* itemId,
803  MmsValue* startingTime, MmsValue* endingTime, bool* moreFollows);
804 
805 LinkedList
806 MmsConnection_readJournalStartAfter(MmsConnection self, MmsError* mmsError, const char* domainId, const char* itemId,
807  MmsValue* timeSpecification, MmsValue* entrySpecification, bool* moreFollows);
808 
814 void
816 
819 #ifdef __cplusplus
820 }
821 #endif
822 
823 #endif /* MMS_CLIENT_CONNECTION_H_ */
void MmsConnection_writeVariable(MmsConnection self, MmsError *mmsError, const char *domainId, const char *itemId, MmsValue *value)
Write a single variable to the server.
MmsServerIdentity * MmsConnection_identify(MmsConnection self, MmsError *mmsError)
get the identity of the connected server
MmsConnectionParameters MmsConnection_getMmsConnectionParameters(MmsConnection self)
Get the MMS specific connection parameters for an MmsConnection instance.
const MmsValue * MmsJournalVariable_getValue(MmsJournalVariable self)
void(* MmsInformationReportHandler)(void *parameter, char *domainName, char *variableListName, MmsValue *value, bool isVariableListName)
Definition: mms_client_connection.h:61
void MmsConnection_close(MmsConnection self)
Close the connection - not recommended.
MmsValue * MmsConnection_readArrayElements(MmsConnection self, MmsError *mmsError, const char *domainId, const char *itemId, uint32_t startIndex, uint32_t numberOfElements)
Read an element of a single array variable from the server.
int32_t MmsConnection_fileOpen(MmsConnection self, MmsError *mmsError, const char *filename, uint32_t initialPosition, uint32_t *fileSize, uint64_t *lastModified)
open a file for read
Definition: mms_client_connection.h:764
void MmsConnection_obtainFile(MmsConnection self, MmsError *mmsError, const char *sourceFile, const char *destinationFile)
Send an obtainFile request to the server (used to initiate file download to server) ...
char * tag
Definition: mms_client_connection.h:765
Definition: mms_client_connection.h:758
void MmsConnection_conclude(MmsConnection self, MmsError *mmsError)
Uses the MMS conclude service to close the connection to the server.
void MmsConnection_setConnectionLostHandler(MmsConnection self, MmsConnectionLostHandler handler, void *handlerParameter)
Install a callback function that will be called by the client stack if the MMS connection to the serv...
void MmsConnection_setRawMessageHandler(MmsConnection self, MmsRawMessageHandler handler, void *parameter)
Set the callback handler to intercept the raw MMS messages of the connection.
struct sMmsConnection * MmsConnection
Definition: mms_client_connection.h:67
IsoConnectionParameters MmsConnection_getIsoConnectionParameters(MmsConnection self)
Get the ISO connection parameters for an MmsConnection instance.
void(* MmsFileDirectoryHandler)(void *parameter, char *filename, uint32_t size, uint64_t lastModified)
Definition: mms_client_connection.h:659
char * vendorName
Definition: mms_client_connection.h:56
int maxServOutstandingCalled
Definition: mms_client_connection.h:49
void MmsJournalEntry_destroy(MmsJournalEntry self)
Destroy a single MmsJournalEntry instance.
void MmsConnection_setConnectTimeout(MmsConnection self, uint32_t timeoutInMs)
Set the connect timeout in ms for this connection instance.
void MmsConnection_destroy(MmsConnection self)
Destroy an MmsConnection instance and release all resources.
void MmsServerIdentity_destroy(MmsServerIdentity *self)
Destroy (free) an MmsServerIdentity object.
void MmsConnection_getServerStatus(MmsConnection self, MmsError *mmsError, int *vmdLogicalStatus, int *vmdPhysicalStatus, bool extendedDerivation)
get the VMD status of the connected server (is MMS status service)
void MmsConnection_setLocalDetail(MmsConnection self, int32_t localDetail)
Get the MMS local detail parameter (local detail means maximum MMS PDU size).
bool MmsConnection_deleteNamedVariableList(MmsConnection self, MmsError *mmsError, const char *domainId, const char *listName)
Delete a named variable list at the server.
void MmsVariableAccessSpecification_destroy(MmsVariableAccessSpecification *self)
Delete the MmsVariableAccessSpecification data structure.
MmsValue * occurenceTime
Definition: mms_client_connection.h:760
LinkedList MmsConnection_getVariableListNamesAssociationSpecific(MmsConnection self, MmsError *mmsError)
Get the names of all named variable lists associated with this client connection. ...
Definition: mms_common.h:146
MmsVariableSpecification * MmsConnection_getVariableAccessAttributes(MmsConnection self, MmsError *mmsError, const char *domainId, const char *itemId)
Get the variable access attributes of a MMS named variable of the server.
int dataStructureNestingLevel
Definition: mms_client_connection.h:50
const char * MmsJournalVariable_getTag(MmsJournalVariable self)
char * revision
Definition: mms_client_connection.h:58
int32_t MmsConnection_getLocalDetail(MmsConnection self)
void MmsConnection_fileDelete(MmsConnection self, MmsError *mmsError, const char *fileName)
delete the file with the specified name
int maxPduSize
Definition: mms_client_connection.h:51
bool MmsConnection_connect(MmsConnection self, MmsError *mmsError, const char *serverName, int serverPort)
Connect to an MMS server.
LinkedList journalVariables
Definition: mms_client_connection.h:761
void MmsConnection_fileRename(MmsConnection self, MmsError *mmsError, const char *currentFileName, const char *newFileName)
rename the file with the specified name
MmsValue * MmsConnection_readVariable(MmsConnection self, MmsError *mmsError, const char *domainId, const char *itemId)
Read a single variable from the server.
MmsValue * MmsConnection_readNamedVariableListValuesAssociationSpecific(MmsConnection self, MmsError *mmsError, const char *listName, bool specWithResult)
Read the values of a association specific named variable list.
bool MmsConnection_fileRead(MmsConnection self, MmsError *mmsError, int32_t frsmId, MmsFileReadHandler handler, void *handlerParameter)
read the next data block from the file
void MmsConnection_setInformationReportHandler(MmsConnection self, MmsInformationReportHandler handler, void *parameter)
Install a handler function for MMS information reports (unsolicited messages from the server)...
MmsValue * MmsConnection_readMultipleVariables(MmsConnection self, MmsError *mmsError, const char *domainId, LinkedListitems)
Read multiple variables of a domain from the server with one request message.
const MmsValue * MmsJournalEntry_getEntryID(MmsJournalEntry self)
LinkedList MmsConnection_getDomainVariableNames(MmsConnection self, MmsError *mmsError, const char *domainId)
Get the names of all variables present in a MMS domain of the server.
MmsValue * entryID
Definition: mms_client_connection.h:759
Definition: mms_client_connection.h:47
LinkedList MmsConnection_readNamedVariableListDirectoryAssociationSpecific(MmsConnection self, MmsError *mmsError, const char *listName, bool *deletable)
Read the entry list of an association specific named variable list at the server. ...
MmsVariableAccessSpecification * MmsVariableAccessSpecification_createAlternateAccess(char *domainId, char *itemId, int32_t index, char *componentName)
Create a new MmsVariableSpecification that can be used to define named variable lists.
void MmsConnection_setIsoConnectionParameters(MmsConnection self, IsoConnectionParameters *params)
Set the ISO connection parameters for a MmsConnection instance.
void(* MmsRawMessageHandler)(void *parameter, uint8_t *message, int messageLength, bool received)
Callback function to intercept raw MMS messages.
Definition: mms_client_connection.h:93
LinkedList MmsConnection_getDomainNames(MmsConnection self, MmsError *mmsError)
Get the domains names for all domains of the server.
Definition: mms_client_connection.h:55
void MmsConnection_fileClose(MmsConnection self, MmsError *mmsError, int32_t frsmId)
close the file with the specified frsmID
void MmsConnection_defineNamedVariableListAssociationSpecific(MmsConnection self, MmsError *mmsError, const char *listName, LinkedList variableSpecs)
Define a new association specific named variable list at the server.
void MmsConnection_abort(MmsConnection self, MmsError *mmsError)
Uses the MMS/ACSE abort service to close the connection to the server.
MmsConnection MmsConnection_create(void)
Create a new MmsConnection instance.
bool MmsConnection_getFileDirectory(MmsConnection self, MmsError *mmsError, const char *fileSpecification, const char *continueAfter, MmsFileDirectoryHandler handler, void *handlerParameter)
get the file directory of the server.
void MmsConnection_writeMultipleVariables(MmsConnection self, MmsError *mmsError, const char *domainId, LinkedListitems, LinkedListvalues, LinkedList *accessResults)
Write multiple variables to the server.
LinkedList MmsConnection_getDomainVariableListNames(MmsConnection self, MmsError *mmsError, const char *domainId)
Get the names of all named variable lists present in a MMS domain of the server.
MmsValue * MmsConnection_readNamedVariableListValues(MmsConnection self, MmsError *mmsError, const char *domainId, const char *listName, bool specWithResult)
Read the values of a domain specific named variable list.
const LinkedList MmsJournalEntry_getJournalVariables(MmsJournalEntry self)
LinkedList MmsConnection_readJournalStartAfter(MmsConnection self, MmsError *mmsError, const char *domainId, const char *itemId, MmsValue *timeSpecification, MmsValue *entrySpecification, bool *moreFollows)
LinkedList MmsConnection_getVMDVariableNames(MmsConnection self, MmsError *mmsError)
Get the names of all VMD scope variables of the server.
void MmsConnection_defineNamedVariableList(MmsConnection self, MmsError *mmsError, const char *domainId, const char *listName, LinkedList variableSpecs)
Define a new VMD or domain scoped named variable list at the server.
bool MmsConnection_deleteAssociationSpecificNamedVariableList(MmsConnection self, MmsError *mmsError, const char *listName)
Delete an association specific named variable list at the server.
LinkedList MmsConnection_readJournalTimeRange(MmsConnection self, MmsError *mmsError, const char *domainId, const char *itemId, MmsValue *startingTime, MmsValue *endingTime, bool *moreFollows)
int maxServOutstandingCalling
Definition: mms_client_connection.h:48
const MmsValue * MmsJournalEntry_getOccurenceTime(MmsJournalEntry self)
void(* MmsConnectionLostHandler)(MmsConnection connection, void *parameter)
User provided handler function that will be called if the connection to the server is lost...
Definition: mms_client_connection.h:166
LinkedList MmsConnection_getDomainJournals(MmsConnection self, MmsError *mmsError, const char *domainId)
Get the names of all journals present in a MMS domain of the server.
MmsVariableAccessSpecification * MmsVariableAccessSpecification_create(char *domainId, char *itemId)
Create a new MmsVariableSpecification that can be used to define named variable lists.
char * modelName
Definition: mms_client_connection.h:57
void MmsConnection_setRequestTimeout(MmsConnection self, uint32_t timeoutInMs)
Set the request timeout in ms for this connection.
void(* MmsFileReadHandler)(void *parameter, int32_t frsmId, uint8_t *buffer, uint32_t bytesReceived)
Definition: mms_client_connection.h:662
LinkedList MmsConnection_readNamedVariableListDirectory(MmsConnection self, MmsError *mmsError, const char *domainId, const char *listName, bool *deletable)
Read the entry list of a named variable list at the server.
MmsValue * value
Definition: mms_client_connection.h:766
MmsError
Definition: mms_common.h:38
struct sMmsValue MmsValue
Definition: mms_value.h:68