embeded-gateway/library/include/libiec61850/mms_server.h

/*
 *  mms_server.h
 *
 *  Copyright 2013-2023 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_SERVER_H_
#define MMS_SERVER_H_

/** \addtogroup mms_server_api_group
 *  @{
 */

#ifdef __cplusplus
extern "C" {
#endif

#include "mms_value.h"
#include "iso_connection_parameters.h"

typedef enum {
	MMS_SERVER_NEW_CONNECTION,
	MMS_SERVER_CONNECTION_CLOSED,
	MMS_SERVER_CONNECTION_TICK
} MmsServerEvent;

typedef struct sMmsServer* MmsServer;

typedef struct sMmsServerConnection* MmsServerConnection;

typedef enum {
    MMS_DOMAIN_SPECIFIC,
    MMS_ASSOCIATION_SPECIFIC,
    MMS_VMD_SPECIFIC
} MmsVariableListType;

LIB61850_INTERNAL void
MmsServer_setLocalIpAddress(MmsServer self, const char* localIpAddress);

LIB61850_INTERNAL bool
MmsServer_isRunning(MmsServer self);

typedef enum {
    MMS_VARLIST_CREATE,
    MMS_VARLIST_DELETE,
    MMS_VARLIST_READ,
    MMS_VARLIST_WRITE,
    MMS_VARLIST_GET_DIRECTORY
} MmsVariableListAccessType;

/**
 * \brief callback handler that is called for each named variable list access
 *
 * \param parameter a user provided parameter
 * \param accessType the kind of access (create, delete, read, write, get directory)
 * \param listType the type (scope) of the named variable list (either domain, association or VMD specific)
 * \param domain the MMS domain the list is belonging to (is NULL for association or VMD specific lists!)
 * \param listName the name
 * \param connection client connection that is accessing the named variable list
 *
 * \return MMS_ERROR_NONE if the request is accepted, otherwise the MmsError value that has to be sent back to the client
 */
typedef MmsError (*MmsNamedVariableListAccessHandler)(void* parameter, MmsVariableListAccessType accessType, MmsVariableListType listType, MmsDomain* domain,
        char* listName, MmsServerConnection connection);

/**
 * \brief Install callback handler that is called when a named variable list is accessed by a client
 *
 * \param self the MmsServer instance to operate on
 * \param handler the callback handler function
 * \param parameter user provided parameter that is passed to the callback handler
 */
LIB61850_INTERNAL void
MmsServer_installVariableListAccessHandler(MmsServer self, MmsNamedVariableListAccessHandler handler, void* parameter);

/**
 * \brief callback handler that is called for each received read journal request
 * 
 * \param parameter a user provided parameter
 * \param domain the MMS domain the journal is belonging to
 * \param logName the name of the journal
 * \param connection client connection that is accessing the journal
 */
typedef bool (*MmsReadJournalHandler)(void* parameter, MmsDomain* domain, const char* logName, MmsServerConnection connection);

/**
 * \brief Install callback handler that is called when a journal is accessed by a client
 *
 * \param self the MmsServer instance to operate on
 * \param handler the callback handler function
 * \param parameter user provided parameter that is passed to the callback handler
 */
LIB61850_INTERNAL void
MmsServer_installReadJournalHandler(MmsServer self, MmsReadJournalHandler handler, void* parameter);

typedef enum {
    MMS_GETNAMELIST_DOMAINS,
    MMS_GETNAMELIST_JOURNALS,
    MMS_GETNAMELIST_DATASETS,
    MMS_GETNAMELIST_DATA
} MmsGetNameListType;

typedef bool (*MmsGetNameListHandler)(void* parameter, MmsGetNameListType nameListType, MmsDomain* domain, MmsServerConnection connection);

LIB61850_INTERNAL void
MmsServer_installGetNameListHandler(MmsServer self, MmsGetNameListHandler handler, void* parameter);

/**
 * \brief ObtainFile service callback handler
 *
 * This is invoked when the obtainFile service is requested by the client. It can be used to accept or deny the
 * write access to the file system based on the client connection.
 *
 * \param parameter user provided parameter that is passed to the callback handler
 * \param connection the connection that requested the service
 * \param sourceFilename the source file name on the client side system
 * \param destinationFilename the target file name on the server side system
 */
typedef bool (*MmsObtainFileHandler)(void* parameter, MmsServerConnection connection, const char* sourceFilename, const char* destinationFilename);

/**
 * \brief Install callback handler that is invoked when the file upload (obtainFile service) is invoked by the client
 *
 * This handler can be used to apply access restrictions on the file upload (obtainFile) service
 *
 * \param self the MmsServer instance to operate on
 * \param handler the callback handler function
 * \param parameter user provided parameter that is passed to the callback handler
 */
LIB61850_INTERNAL void
MmsServer_installObtainFileHandler(MmsServer self, MmsObtainFileHandler handler, void* parameter);

/**
 * \brief Get file complete (obtainFile service terminated) callback handler
 *
 * This handler can be used to invoke some actions after a file upload is complete.
 *
 * \param parameter user provided parameter that is passed to the callback handler
 * \param connection the connection that requested the service
 * \param destinationFilename the target file name on the server side system
 */
typedef void (*MmsGetFileCompleteHandler)(void* parameter, MmsServerConnection connection, const char* destinationFilename);

/**
 * \brief Install callback handler that is invoked when the file upload (obtainFile service) is completed and the
 *        file has been uploaded.
 *
 * \param self the MmsServer instance
 * \param handler the callback handler function
 * \param parameter user provided parameter that is passed to the callback handler
 */
LIB61850_INTERNAL void
MmsServer_installGetFileCompleteHandler(MmsServer self, MmsGetFileCompleteHandler handler, void* parameter);


typedef  enum {
    MMS_FILE_ACCESS_TYPE_READ_DIRECTORY,
    MMS_FILE_ACCESS_TYPE_OPEN,
    MMS_FILE_ACCESS_TYPE_OBTAIN,
    MMS_FILE_ACCESS_TYPE_DELETE,
    MMS_FILE_ACCESS_TYPE_RENAME
} MmsFileServiceType;

/**
 * \brief MmsFileAccessHandler callback function. Use to monitor and control file access
 *
 * \param parameter user provided parameter that is passed to the callback handler
 * \param connection the connection that requested the service
 * \param service the requested file service
 * \param localFilename the requested file or directory name at the server
 * \param otherFilename a second file name parameter (e.g. source file of the ObtainFile or new file of rename file)
 *
 * \return MMS_ERROR_NONE when the request is accepted, otherwise use the appropriate error code (e.g. MMS_ERROR_FILE_FILE_ACCESS_DENIED)
 */
typedef MmsError (*MmsFileAccessHandler) (void* parameter, MmsServerConnection connection, MmsFileServiceType service,
                                          const char* localFilename, const char* otherFilename);


/**
 * \brief Install a callback handler this is invoked when the client requests a file server. This function can be
 *        used to monitor and control file access
 *
 * \param self the MmsServer instance
 * \param handler the callback handler function
 * \param parameter user provided parameter that is passed to the callback handler
 */
LIB61850_API void
MmsServer_installFileAccessHandler(MmsServer self, MmsFileAccessHandler handler, void* parameter);

/**
 * \brief Set the virtual filestore basepath for the MMS file services
 *
 * All external file service accesses will be mapped to paths relative to the base directory.
 * NOTE: This function is only available when the CONFIG_SET_FILESTORE_BASEPATH_AT_RUNTIME
 * option in stack_config.h is set.
 *
 * \param self the MmsServer instance
 * \param basepath the new virtual filestore basepath
 */
LIB61850_INTERNAL void
MmsServer_setFilestoreBasepath(MmsServer self, const char* basepath);

/**
 * \brief Set the maximum number of TCP client connections
 *
 * \param[in] maxConnections the maximum number of TCP client connections to accept
 */
LIB61850_INTERNAL void
MmsServer_setMaxConnections(MmsServer self, int maxConnections);

/**
 * \brief Enable/disable MMS file services at runtime
 *
 * NOTE: requires CONFIG_MMS_SERVER_CONFIG_SERVICES_AT_RUNTIME = 1 in stack configuration
 *
 * \param[in] self the MmsServer instance
 * \param[in] enable true to enable file services, false to disable
 */
LIB61850_INTERNAL void
MmsServer_enableFileService(MmsServer self, bool enable);

/**
 * \brief Enable/disable dynamic named variable list (data set) service
 *
 * NOTE: requires CONFIG_MMS_SERVER_CONFIG_SERVICES_AT_RUNTIME = 1 in stack configuration
 *
 * \param[in] self the MmsServer instance
 * \param[in] enable true to enable named variable list services, false to disable
 */
LIB61850_INTERNAL void
MmsServer_enableDynamicNamedVariableListService(MmsServer self, bool enable);

/**
 * \brief Set the maximum number of association specific data sets (per connection)
 *
 * \param[in] self the MmsServer instance
 * \param[in] maxDataSets maximum number association specific data sets
 */
LIB61850_INTERNAL void
MmsServer_setMaxAssociationSpecificDataSets(MmsServer self, int maxDataSets);

/**
 * \brief Set the maximum number of domain specific data sets
 *
 * \param[in] self the MmsServer instance
 * \param[in] maxDataSets maximum number domain specific data sets
 */
LIB61850_INTERNAL void
MmsServer_setMaxDomainSpecificDataSets(MmsServer self, int maxDataSets);

/**
 * \brief Set the maximum number of data set entries (for dynamic data sets)
 *
 * \param[in] self the MmsServer instance
 * \param[in] maxDataSetEntries maximum number of dynamic data set entries
 */
LIB61850_INTERNAL void
MmsServer_setMaxDataSetEntries(MmsServer self, int maxDataSetEntries);

/**
 * \brief Enable/disable journal service
 *
 * NOTE: requires CONFIG_MMS_SERVER_CONFIG_SERVICES_AT_RUNTIME = 1 in stack configuration
 *
 * \param[in] self the MmsServer instance
 * \param[in] enable true to enable journal service, false to disable
 */
LIB61850_INTERNAL void
MmsServer_enableJournalService(MmsServer self, bool enable);





/***************************************************
 * Functions for MMS identify service
 ***************************************************/

/**
 * \brief set the values that the server will give as response for an MMS identify request
 *
 * With this function the VMD identity attributes can be set programmatically. If not set by this
 * function the default values form stack_config.h are used.
 *
 * \param self the MmsServer instance to operate on
 * \param vendorName the vendor name attribute of the VMD
 * \param modelName the model name attribute of the VMD
 * \param revision the revision attribute of the VMD
 */
LIB61850_INTERNAL void
MmsServer_setServerIdentity(MmsServer self, char* vendorName, char* modelName, char* revision);

/**
 * \brief get the vendor name attribute of the VMD identity
 *
 * \param self the MmsServer instance to operate on
 * \return the vendor name attribute of the VMD as C string
 */
LIB61850_INTERNAL char*
MmsServer_getVendorName(MmsServer self);

/**
 * \brief get the model name attribute of the VMD identity
 *
 * \param self the MmsServer instance to operate on
 * \return the model name attribute of the VMD as C string
 */
LIB61850_INTERNAL char*
MmsServer_getModelName(MmsServer self);

/**
 * \brief get the revision attribute of the VMD identity
 *
 * \param self the MmsServer instance to operate on
 * \return the revision attribute of the VMD as C string
 */
LIB61850_INTERNAL char*
MmsServer_getRevision(MmsServer self);

/***************************************************
 * Functions for MMS status service
 ***************************************************/

#define MMS_LOGICAL_STATE_STATE_CHANGES_ALLOWED 0
#define MMS_LOGICAL_STATE_NO_STATE_CHANGES_ALLOWED 1
#define MMS_LOGICAL_STATE_LIMITED_SERVICES_PERMITTED 2
#define MMS_LOGICAL_STATE_SUPPORT_SERVICES_ALLOWED 3

#define MMS_PHYSICAL_STATE_OPERATIONAL 0
#define MMS_PHYSICAL_STATE_PARTIALLY_OPERATIONAL 1
#define MMS_PHYSICAL_STATE_INOPERATIONAL 2
#define MMS_PHYSICAL_STATE_NEEDS_COMMISSIONING 3

/**
 * \brief User provided handler that is invoked on a MMS status request
 *
 * The extendedDerivation parameter indicates that the client requests the server to perform
 * self diagnosis tests before answering the request.
 *
 * \param parameter is a user provided parameter
 * \param mmsServer is the MmsServer instance
 * \param connection is the MmsServerConnection instance that received the MMS status request
 * \param extendedDerivation indicates if the request contains the extendedDerivation parameter
 */
typedef void (*MmsStatusRequestListener)(void* parameter, MmsServer mmsServer, MmsServerConnection connection, bool extendedDerivation);

/**
 * \brief set the VMD state values for the VMD status service
 *
 * \param self the MmsServer instance to operate on
 * \param vmdLogicalStatus the logical status attribute of the VMD
 * \param vmdPhysicalStatus the physical status attribute of the VMD
 */
LIB61850_INTERNAL void
MmsServer_setVMDStatus(MmsServer self, int vmdLogicalStatus, int vmdPhysicalStatus);

/**
 * \brief get the logical status attribute of the VMD
 *
 * \param self the MmsServer instance to operate on
 */
LIB61850_INTERNAL int
MmsServer_getVMDLogicalStatus(MmsServer self);

/**
 * \brief get the physical status attribute of the VMD
 *
 * \param self the MmsServer instance to operate on
 */
LIB61850_INTERNAL int
MmsServer_getVMDPhysicalStatus(MmsServer self);

/**
 * \brief set the MmsStatusRequestListener for this MmsServer
 *
 * With this function the API user can register a listener that is invoked whenever a
 * MMS status request is received from a client. Inside of the handler the user can
 * provide new status values with the MmsServer_setVMDStatus function.
 *
 * \param self the MmsServer instance to operate on
 * \param listener the listener that is called when a MMS status request is received
 * \param parameter a user provided parameter that is handed over to the listener
 */
LIB61850_INTERNAL void
MmsServer_setStatusRequestListener(MmsServer self, MmsStatusRequestListener listener, void* parameter);

LIB61850_INTERNAL char*
MmsServerConnection_getClientAddress(MmsServerConnection self);

LIB61850_INTERNAL char*
MmsServerConnection_getLocalAddress(MmsServerConnection self);

LIB61850_INTERNAL void*
MmsServerConnection_getSecurityToken(MmsServerConnection self);

LIB61850_INTERNAL void
MmsServer_ignoreClientRequests(MmsServer self, bool enable);;

/**@}*/

#ifdef __cplusplus
}
#endif

#endif /* MMS_SERVER_H_ */