mms_client_connection.h

Go to the documentation of this file.

/*
 *  mms_client_connection.h
 *
 *  Copyright 2013-2016 Michael Zillgith
 *
 *      This file is part of libIEC61850.
 *
 *      libIEC61850 is free software: you can redistribute it and/or modify
 *      it under the terms of the GNU General Public License as published by
 *      the Free Software Foundation, either version 3 of the License, or
 *      (at your option) any later version.
 *
 *      libIEC61850 is distributed in the hope that it will be useful,
 *      but WITHOUT ANY WARRANTY; without even the implied warranty of
 *      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *      GNU General Public License for more details.
 *
 *      You should have received a copy of the GNU General Public License
 *      along with libIEC61850.  If not, see <http://www.gnu.org/licenses/>.
 *
 *      See COPYING file for the complete license text.
 */

#ifndef MMS_CLIENT_CONNECTION_H_
#define MMS_CLIENT_CONNECTION_H_

#ifdef __cplusplus
extern "C" {
#endif

#include "libiec61850_common_api.h"

#include "mms_common.h"
#include "mms_type_spec.h"
#include "mms_value.h"
#include "iso_connection_parameters.h"
#include "linked_list.h"

#include "tls_api.h"

typedef struct sMmsConnectionParameters {
        int maxServOutstandingCalling;
        int maxServOutstandingCalled;
        int dataStructureNestingLevel;
        int maxPduSize; /* local detail */
        uint8_t servicesSupported[11];
} MmsConnectionParameters;

typedef struct {
    char* vendorName;
    char* modelName;
    char* revision;
} MmsServerIdentity;

typedef void (*MmsInformationReportHandler) (void* parameter, char* domainName,
        char* variableListName, MmsValue* value, bool isVariableListName);

typedef struct sMmsConnection* MmsConnection;


/*******************************************************************************
 * Connection management functions
 *******************************************************************************/

MmsConnection
MmsConnection_create(void);

MmsConnection
MmsConnection_createSecure(TLSConfiguration tlsConfig);

typedef void (*MmsRawMessageHandler) (void* parameter, uint8_t* message, int messageLength, bool received);

void
MmsConnection_setRawMessageHandler(MmsConnection self, MmsRawMessageHandler handler, void* parameter);

void
MmsConnection_setFilestoreBasepath(MmsConnection self, const char* basepath);

void
MmsConnection_setRequestTimeout(MmsConnection self, uint32_t timeoutInMs);

void
MmsConnection_setConnectTimeout(MmsConnection self, uint32_t timeoutInMs);

void
MmsConnection_setInformationReportHandler(MmsConnection self, MmsInformationReportHandler handler,
        void* parameter);

IsoConnectionParameters
MmsConnection_getIsoConnectionParameters(MmsConnection self);

MmsConnectionParameters
MmsConnection_getMmsConnectionParameters(MmsConnection self);

typedef void (*MmsConnectionLostHandler) (MmsConnection connection, void* parameter);

void
MmsConnection_setConnectionLostHandler(MmsConnection self, MmsConnectionLostHandler handler, void* handlerParameter);

void
MmsConnection_setIsoConnectionParameters(MmsConnection self, IsoConnectionParameters* params);

void
MmsConnection_destroy(MmsConnection self);

/*******************************************************************************
 * Blocking functions for connection establishment and data access
 *******************************************************************************/


bool
MmsConnection_connect(MmsConnection self, MmsError* mmsError, const char* serverName, int serverPort);

void
MmsConnection_close(MmsConnection self);

void
MmsConnection_abort(MmsConnection self, MmsError* mmsError);

void
MmsConnection_conclude(MmsConnection self, MmsError* mmsError);


LinkedList /* <char*> */
MmsConnection_getVMDVariableNames(MmsConnection self, MmsError* mmsError);

LinkedList /* <char*> */
MmsConnection_getDomainNames(MmsConnection self, MmsError* mmsError);

LinkedList /* <char*> */
MmsConnection_getDomainVariableNames(MmsConnection self, MmsError* mmsError, const char* domainId);

LinkedList /* <char*> */
MmsConnection_getDomainVariableListNames(MmsConnection self, MmsError* mmsError, const char* domainId);

LinkedList /* <char*> */
MmsConnection_getDomainJournals(MmsConnection self, MmsError* mmsError, const char* domainId);

LinkedList /* <char*> */
MmsConnection_getVariableListNamesAssociationSpecific(MmsConnection self, MmsError* mmsError);


MmsValue*
MmsConnection_readVariable(MmsConnection self, MmsError* mmsError, const char* domainId, const char* itemId);

MmsValue*
MmsConnection_readArrayElements(MmsConnection self, MmsError* mmsError, const char* domainId, const char* itemId,
                uint32_t startIndex, uint32_t numberOfElements);

MmsValue*
MmsConnection_readMultipleVariables(MmsConnection self, MmsError* mmsError, const char* domainId,
                LinkedList /*<char*>*/ items);

MmsDataAccessError
MmsConnection_writeVariable(MmsConnection self, MmsError* mmsError,
        const char* domainId, const char* itemId, MmsValue* value);

MmsDataAccessError
MmsConnection_writeArrayElements(MmsConnection self, MmsError* mmsError,
        const char* domainId, const char* itemId, int index, int numberOfElements,
        MmsValue* value);

void
MmsConnection_writeMultipleVariables(MmsConnection self, MmsError* mmsError, const char* domainId,
        LinkedList /*<char*>*/ items, LinkedList /* <MmsValue*> */ values,
        LinkedList* /* <MmsValue*> */ accessResults);

void
MmsConnection_writeNamedVariableList(MmsConnection self, MmsError* mmsError, bool isAssociationSpecific,
        const char* domainId, const char* itemId, LinkedList /* <MmsValue*> */values,
        /* OUTPUT */LinkedList* /* <MmsValue*> */accessResults);

MmsVariableSpecification*
MmsConnection_getVariableAccessAttributes(MmsConnection self, MmsError* mmsError,
        const char* domainId, const char* itemId);

MmsValue*
MmsConnection_readNamedVariableListValues(MmsConnection self, MmsError* mmsError, const char* domainId,
        const char* listName,   bool specWithResult);


MmsValue*
MmsConnection_readNamedVariableListValuesAssociationSpecific(MmsConnection self, MmsError* mmsError,
        const char* listName,   bool specWithResult);

void
MmsConnection_defineNamedVariableList(MmsConnection self, MmsError* mmsError, const char* domainId,
        const char* listName,   LinkedList variableSpecs);


void
MmsConnection_defineNamedVariableListAssociationSpecific(MmsConnection self, MmsError* mmsError,
        const char* listName,   LinkedList variableSpecs);

LinkedList /* <MmsVariableAccessSpecification*> */
MmsConnection_readNamedVariableListDirectory(MmsConnection self, MmsError* mmsError,
        const char* domainId, const char* listName, bool* deletable);



LinkedList /* <MmsVariableAccessSpecification*> */
MmsConnection_readNamedVariableListDirectoryAssociationSpecific(MmsConnection self, MmsError* mmsError,
        const char* listName, bool* deletable);

bool
MmsConnection_deleteNamedVariableList(MmsConnection self, MmsError* mmsError, const char* domainId, const char* listName);

bool
MmsConnection_deleteAssociationSpecificNamedVariableList(MmsConnection self, MmsError* mmsError,
        const char* listName);

MmsVariableAccessSpecification*
MmsVariableAccessSpecification_create(char* domainId, char* itemId);

MmsVariableAccessSpecification*
MmsVariableAccessSpecification_createAlternateAccess(char* domainId, char* itemId, int32_t index,
                char* componentName);

void
MmsVariableAccessSpecification_destroy(MmsVariableAccessSpecification* self);

void
MmsConnection_setLocalDetail(MmsConnection self, int32_t localDetail);

int32_t
MmsConnection_getLocalDetail(MmsConnection self);

MmsServerIdentity*
MmsConnection_identify(MmsConnection self, MmsError* mmsError);

void
MmsServerIdentity_destroy(MmsServerIdentity* self);

void
MmsConnection_getServerStatus(MmsConnection self, MmsError* mmsError, int* vmdLogicalStatus, int* vmdPhysicalStatus,
        bool extendedDerivation);

/*******************************************************************************
 * functions for MMS file services
 *******************************************************************************/

typedef void
(*MmsFileDirectoryHandler) (void* parameter, char* filename, uint32_t size, uint64_t lastModified);

typedef void
(*MmsFileReadHandler) (void* parameter, int32_t frsmId, uint8_t* buffer, uint32_t bytesReceived);


int32_t
MmsConnection_fileOpen(MmsConnection self, MmsError* mmsError, const char* filename, uint32_t initialPosition,
        uint32_t* fileSize, uint64_t* lastModified);

bool
MmsConnection_fileRead(MmsConnection self, MmsError* mmsError, int32_t frsmId, MmsFileReadHandler handler, void* handlerParameter);

void
MmsConnection_fileClose(MmsConnection self, MmsError* mmsError, int32_t frsmId);

void
MmsConnection_fileDelete(MmsConnection self, MmsError* mmsError, const char* fileName);

void
MmsConnection_fileRename(MmsConnection self, MmsError* mmsError, const char* currentFileName, const char* newFileName);


void
MmsConnection_obtainFile(MmsConnection self, MmsError* mmsError, const char* sourceFile, const char* destinationFile);

bool
MmsConnection_getFileDirectory(MmsConnection self, MmsError* mmsError, const char* fileSpecification, const char* continueAfter,
        MmsFileDirectoryHandler handler, void* handlerParameter);

typedef struct sMmsJournalEntry* MmsJournalEntry;

typedef struct sMmsJournalVariable* MmsJournalVariable;

struct sMmsJournalEntry {
    MmsValue* entryID; /* type MMS_OCTET_STRING */
    MmsValue* occurenceTime; /* type MMS_BINARY_TIME */
    LinkedList journalVariables;
};

struct sMmsJournalVariable {
    char* tag;
    MmsValue* value;
};

void
MmsJournalEntry_destroy(MmsJournalEntry self);

const MmsValue*
MmsJournalEntry_getEntryID(MmsJournalEntry self);

const MmsValue*
MmsJournalEntry_getOccurenceTime(MmsJournalEntry self);

const LinkedList /* <MmsJournalVariable> */
MmsJournalEntry_getJournalVariables(MmsJournalEntry self);

const char*
MmsJournalVariable_getTag(MmsJournalVariable self);

const MmsValue*
MmsJournalVariable_getValue(MmsJournalVariable self);


LinkedList
MmsConnection_readJournalTimeRange(MmsConnection self, MmsError* mmsError, const char* domainId, const char* itemId,
        MmsValue* startingTime, MmsValue* endingTime, bool* moreFollows);

LinkedList
MmsConnection_readJournalStartAfter(MmsConnection self, MmsError* mmsError, const char* domainId, const char* itemId,
        MmsValue* timeSpecification, MmsValue* entrySpecification, bool* moreFollows);

void
MmsServerIdentity_destroy(MmsServerIdentity* self);

#ifdef __cplusplus
}
#endif

#endif /* MMS_CLIENT_CONNECTION_H_ */