libIEC61850  1.1.2
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 
119 void
120 MmsConnection_setFilestoreBasepath(MmsConnection self, const char* basepath);
121 
128 void
129 MmsConnection_setRequestTimeout(MmsConnection self, uint32_t timeoutInMs);
130 
137 void
138 MmsConnection_setConnectTimeout(MmsConnection self, uint32_t timeoutInMs);
139 
151 void
153  void* parameter);
154 
161 IsoConnectionParameters
162 MmsConnection_getIsoConnectionParameters(MmsConnection self);
163 
171 MmsConnection_getMmsConnectionParameters(MmsConnection self);
172 
179 typedef void (*MmsConnectionLostHandler) (MmsConnection connection, void* parameter);
180 
187 void
188 MmsConnection_setConnectionLostHandler(MmsConnection self, MmsConnectionLostHandler handler, void* handlerParameter);
189 
196 void
197 MmsConnection_setIsoConnectionParameters(MmsConnection self, IsoConnectionParameters* params);
198 
204 void
205 MmsConnection_destroy(MmsConnection self);
206 
207 /*******************************************************************************
208  * Blocking functions for connection establishment and data access
209  *******************************************************************************/
210 
211 
224 bool
225 MmsConnection_connect(MmsConnection self, MmsError* mmsError, const char* serverName, int serverPort);
226 
235 void
236 MmsConnection_close(MmsConnection self);
237 
249 void
250 MmsConnection_abort(MmsConnection self, MmsError* mmsError);
251 
263 void
264 MmsConnection_conclude(MmsConnection self, MmsError* mmsError);
265 
266 
277 LinkedList /* <char*> */
278 MmsConnection_getVMDVariableNames(MmsConnection self, MmsError* mmsError);
279 
291 LinkedList /* <char*> */
292 MmsConnection_getDomainNames(MmsConnection self, MmsError* mmsError);
293 
305 LinkedList /* <char*> */
306 MmsConnection_getDomainVariableNames(MmsConnection self, MmsError* mmsError, const char* domainId);
307 
319 LinkedList /* <char*> */
320 MmsConnection_getDomainVariableListNames(MmsConnection self, MmsError* mmsError, const char* domainId);
321 
333 LinkedList /* <char*> */
334 MmsConnection_getDomainJournals(MmsConnection self, MmsError* mmsError, const char* domainId);
335 
346 LinkedList /* <char*> */
348 
349 
362 MmsValue*
363 MmsConnection_readVariable(MmsConnection self, MmsError* mmsError, const char* domainId, const char* itemId);
364 
379 MmsValue*
380 MmsConnection_readArrayElements(MmsConnection self, MmsError* mmsError, const char* domainId, const char* itemId,
381  uint32_t startIndex, uint32_t numberOfElements);
382 
395 MmsValue*
396 MmsConnection_readMultipleVariables(MmsConnection self, MmsError* mmsError, const char* domainId,
397  LinkedList /*<char*>*/ items);
398 
413 MmsConnection_writeVariable(MmsConnection self, MmsError* mmsError,
414  const char* domainId, const char* itemId, MmsValue* value);
415 
435 MmsConnection_writeArrayElements(MmsConnection self, MmsError* mmsError,
436  const char* domainId, const char* itemId, int index, int numberOfElements,
437  MmsValue* value);
438 
456 void
457 MmsConnection_writeMultipleVariables(MmsConnection self, MmsError* mmsError, const char* domainId,
458  LinkedList /*<char*>*/ items, LinkedList /* <MmsValue*> */ values,
459  LinkedList* /* <MmsValue*> */ accessResults);
460 
477 void
478 MmsConnection_writeNamedVariableList(MmsConnection self, MmsError* mmsError, bool isAssociationSpecific,
479  const char* domainId, const char* itemId, LinkedList /* <MmsValue*> */values,
480  /* OUTPUT */LinkedList* /* <MmsValue*> */accessResults);
481 
492 MmsVariableSpecification*
493 MmsConnection_getVariableAccessAttributes(MmsConnection self, MmsError* mmsError,
494  const char* domainId, const char* itemId);
495 
512 MmsValue*
513 MmsConnection_readNamedVariableListValues(MmsConnection self, MmsError* mmsError, const char* domainId,
514  const char* listName, bool specWithResult);
515 
516 
529 MmsValue*
531  const char* listName, bool specWithResult);
532 
546 void
547 MmsConnection_defineNamedVariableList(MmsConnection self, MmsError* mmsError, const char* domainId,
548  const char* listName, LinkedList variableSpecs);
549 
550 
560 void
562  const char* listName, LinkedList variableSpecs);
563 
579 LinkedList /* <MmsVariableAccessSpecification*> */
580 MmsConnection_readNamedVariableListDirectory(MmsConnection self, MmsError* mmsError,
581  const char* domainId, const char* listName, bool* deletable);
582 
583 
584 
594 LinkedList /* <MmsVariableAccessSpecification*> */
596  const char* listName, bool* deletable);
597 
611 bool
612 MmsConnection_deleteNamedVariableList(MmsConnection self, MmsError* mmsError, const char* domainId, const char* listName);
613 
623 bool
625  const char* listName);
626 
639 MmsVariableAccessSpecification_create(char* domainId, char* itemId);
640 
658 MmsVariableAccessSpecification_createAlternateAccess(char* domainId, char* itemId, int32_t index,
659  char* componentName);
660 
666 void
668 
678 void
679 MmsConnection_setLocalDetail(MmsConnection self, int32_t localDetail);
680 
681 int32_t
682 MmsConnection_getLocalDetail(MmsConnection self);
683 
694 MmsConnection_identify(MmsConnection self, MmsError* mmsError);
695 
696 void
698 
711 void
712 MmsConnection_getServerStatus(MmsConnection self, MmsError* mmsError, int* vmdLogicalStatus, int* vmdPhysicalStatus,
713  bool extendedDerivation);
714 
715 /*******************************************************************************
716  * functions for MMS file services
717  *******************************************************************************/
718 
719 typedef void
720 (*MmsFileDirectoryHandler) (void* parameter, char* filename, uint32_t size, uint64_t lastModified);
721 
722 typedef void
723 (*MmsFileReadHandler) (void* parameter, int32_t frsmId, uint8_t* buffer, uint32_t bytesReceived);
724 
725 
734 int32_t
735 MmsConnection_fileOpen(MmsConnection self, MmsError* mmsError, const char* filename, uint32_t initialPosition,
736  uint32_t* fileSize, uint64_t* lastModified);
737 
749 bool
750 MmsConnection_fileRead(MmsConnection self, MmsError* mmsError, int32_t frsmId, MmsFileReadHandler handler, void* handlerParameter);
751 
759 void
760 MmsConnection_fileClose(MmsConnection self, MmsError* mmsError, int32_t frsmId);
761 
769 void
770 MmsConnection_fileDelete(MmsConnection self, MmsError* mmsError, const char* fileName);
771 
780 void
781 MmsConnection_fileRename(MmsConnection self, MmsError* mmsError, const char* currentFileName, const char* newFileName);
782 
783 
792 void
793 MmsConnection_obtainFile(MmsConnection self, MmsError* mmsError, const char* sourceFile, const char* destinationFile);
794 
811 bool
812 MmsConnection_getFileDirectory(MmsConnection self, MmsError* mmsError, const char* fileSpecification, const char* continueAfter,
813  MmsFileDirectoryHandler handler, void* handlerParameter);
814 
815 typedef struct sMmsJournalEntry* MmsJournalEntry;
816 
817 typedef struct sMmsJournalVariable* MmsJournalVariable;
818 
820  MmsValue* entryID; /* type MMS_OCTET_STRING */
821  MmsValue* occurenceTime; /* type MMS_BINARY_TIME */
822  LinkedList journalVariables;
823 };
824 
826  char* tag;
828 };
829 
843 void
844 MmsJournalEntry_destroy(MmsJournalEntry self);
845 
846 const MmsValue*
847 MmsJournalEntry_getEntryID(MmsJournalEntry self);
848 
849 const MmsValue*
850 MmsJournalEntry_getOccurenceTime(MmsJournalEntry self);
851 
852 const LinkedList /* <MmsJournalVariable> */
853 MmsJournalEntry_getJournalVariables(MmsJournalEntry self);
854 
855 const char*
856 MmsJournalVariable_getTag(MmsJournalVariable self);
857 
858 const MmsValue*
859 MmsJournalVariable_getValue(MmsJournalVariable self);
860 
861 
862 LinkedList
863 MmsConnection_readJournalTimeRange(MmsConnection self, MmsError* mmsError, const char* domainId, const char* itemId,
864  MmsValue* startingTime, MmsValue* endingTime, bool* moreFollows);
865 
866 LinkedList
867 MmsConnection_readJournalStartAfter(MmsConnection self, MmsError* mmsError, const char* domainId, const char* itemId,
868  MmsValue* timeSpecification, MmsValue* entrySpecification, bool* moreFollows);
869 
875 void
877 
880 #ifdef __cplusplus
881 }
882 #endif
883 
884 #endif /* MMS_CLIENT_CONNECTION_H_ */
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:825
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) ...
MmsDataAccessError MmsConnection_writeVariable(MmsConnection self, MmsError *mmsError, const char *domainId, const char *itemId, MmsValue *value)
Write a single variable to the server.
char * tag
Definition: mms_client_connection.h:826
Definition: mms_client_connection.h:819
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:720
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:821
LinkedList MmsConnection_getVariableListNamesAssociationSpecific(MmsConnection self, MmsError *mmsError)
Get the names of all named variable lists associated with this client connection. ...
Definition: mms_common.h:147
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:822
void MmsConnection_setFilestoreBasepath(MmsConnection self, const char *basepath)
Set the virtual filestore basepath for the MMS obtain file services.
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:820
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
void MmsConnection_writeNamedVariableList(MmsConnection self, MmsError *mmsError, bool isAssociationSpecific, const char *domainId, const char *itemId, LinkedList values, LinkedList *accessResults)
Write named variable list values to the server.
LinkedList MmsConnection_getDomainNames(MmsConnection self, MmsError *mmsError)
Get the domains names for all domains of the server.
MmsDataAccessError
Definition: mms_value.h:47
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 or VMD scope 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.
MmsDataAccessError MmsConnection_writeArrayElements(MmsConnection self, MmsError *mmsError, const char *domainId, const char *itemId, int index, int numberOfElements, MmsValue *value)
Write a single array element or a sub array to an array type variable.
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:179
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:723
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:827
MmsError
Definition: mms_common.h:38
struct sMmsValue MmsValue
Definition: mms_value.h:68