/* * 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 . * * 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_ */