libIEC61850  1.0.1
Open-source IEC 61850 MMS/GOOSE/SV server and client library
mms_server.h
Go to the documentation of this file.
1 /*
2  * mms_server.h
3  *
4  * Copyright 2013, 2014 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_SERVER_H_
25 #define MMS_SERVER_H_
26 
31 #ifdef __cplusplus
32 extern "C" {
33 #endif
34 
35 #include "mms_device_model.h"
36 #include "mms_value.h"
37 #include "iso_server.h"
38 
39 typedef enum {
42 
43 typedef struct sMmsServer* MmsServer;
44 
45 typedef struct sMmsServerConnection* MmsServerConnection;
46 
47 typedef enum {
52 
53 typedef MmsValue* (*MmsReadVariableHandler)(void* parameter, MmsDomain* domain,
54  char* variableId, MmsServerConnection connection);
55 
56 typedef MmsDataAccessError (*MmsReadAccessHandler) (void* parameter, MmsDomain* domain,
57  char* variableId, MmsServerConnection connection);
58 
59 typedef MmsDataAccessError (*MmsWriteVariableHandler)(void* parameter,
60  MmsDomain* domain, char* variableId, MmsValue* value,
61  MmsServerConnection connection);
62 
63 typedef void (*MmsConnectionHandler)(void* parameter,
64  MmsServerConnection connection, MmsServerEvent event);
65 
66 MmsServer
67 MmsServer_create(IsoServer isoServer, MmsDevice* device);
68 
69 void
70 MmsServer_destroy(MmsServer self);
71 
72 void
74  void* parameter);
75 
76 void
77 MmsServer_installReadAccessHandler(MmsServer self, MmsReadAccessHandler, void* parameter);
78 
79 void
81  void* parameter);
82 
86 void
88  void* parameter);
89 
90 void
91 MmsServer_setClientAuthenticator(MmsServer self, AcseAuthenticator authenticator, void* authenticatorParameter);
92 
93 MmsDevice*
94 MmsServer_getDevice(MmsServer self);
95 
96 MmsValue*
97 MmsServer_getValueFromCache(MmsServer self, MmsDomain* domain, char* itemId);
98 
99 bool
100 MmsServer_isLocked(MmsServer self);
101 
114 typedef MmsError (*MmsNamedVariableListChangedHandler)(void* parameter, bool create, MmsVariableListType listType, MmsDomain* domain,
115  char* listName, MmsServerConnection connection);
116 
124 void
126 
138 typedef bool (*MmsObtainFileHandler)(void* parameter, MmsServerConnection connection, const char* sourceFilename, const char* destinationFilename);
139 
149 void
150 MmsServer_installObtainFileHandler(MmsServer self, MmsObtainFileHandler handler, void* parameter);
151 
161 typedef void (*MmsGetFileCompleteHandler)(void* parameter, MmsServerConnection connection, const char* destinationFilename);
162 
171 void
172 MmsServer_installGetFileCompleteHandler(MmsServer self, MmsGetFileCompleteHandler handler, void* parameter);
173 
183 void
184 MmsServer_lockModel(MmsServer self);
185 
194 void
195 MmsServer_unlockModel(MmsServer self);
196 
197 void
198 MmsServer_insertIntoCache(MmsServer self, MmsDomain* domain, char* itemId,
199  MmsValue* value);
200 
201 void
202 MmsServer_setDevice(MmsServer self, MmsDevice* device);
203 
204 /***************************************************
205  * Functions for multi-threaded operation mode
206  ***************************************************/
207 
214 void
215 MmsServer_startListening(MmsServer self, int tcpPort);
216 
222 void
223 MmsServer_stopListening(MmsServer self);
224 
225 /***************************************************
226  * Functions for threadless operation mode
227  ***************************************************/
228 
235 void
236 MmsServer_startListeningThreadless(MmsServer self, int tcpPort);
237 
245 int
246 MmsServer_waitReady(MmsServer self, unsigned int timeoutMs);
247 
256 void
257 MmsServer_handleIncomingMessages(MmsServer self);
258 
264 void
265 MmsServer_handleBackgroundTasks(MmsServer self);
266 
272 void
273 MmsServer_stopListeningThreadless(MmsServer self);
274 
275 
276 /***************************************************
277  * Functions for MMS identify service
278  ***************************************************/
279 
291 void
292 MmsServer_setServerIdentity(MmsServer self, char* vendorName, char* modelName, char* revision);
293 
300 char*
301 MmsServer_getVendorName(MmsServer self);
302 
309 char*
310 MmsServer_getModelName(MmsServer self);
311 
318 char*
319 MmsServer_getRevision(MmsServer self);
320 
321 /***************************************************
322  * Functions for MMS status service
323  ***************************************************/
324 
325 #define MMS_LOGICAL_STATE_STATE_CHANGES_ALLOWED 0
326 #define MMS_LOGICAL_STATE_NO_STATE_CHANGES_ALLOWED 1
327 #define MMS_LOGICAL_STATE_LIMITED_SERVICES_PERMITTED 2
328 #define MMS_LOGICAL_STATE_SUPPORT_SERVICES_ALLOWED 3
329 
330 #define MMS_PHYSICAL_STATE_OPERATIONAL 0
331 #define MMS_PHYSICAL_STATE_PARTIALLY_OPERATIONAL 1
332 #define MMS_PHYSICAL_STATE_INOPERATIONAL 2
333 #define MMS_PHYSICAL_STATE_NEEDS_COMMISSIONING 3
334 
346 typedef void (*MmsStatusRequestListener)(void* parameter, MmsServer mmsServer, MmsServerConnection connection, bool extendedDerivation);
347 
355 void
356 MmsServer_setVMDStatus(MmsServer self, int vmdLogicalStatus, int vmdPhysicalStatus);
357 
363 int
364 MmsServer_getVMDLogicalStatus(MmsServer self);
365 
371 int
372 MmsServer_getVMDPhysicalStatus(MmsServer self);
373 
385 void
386 MmsServer_setStatusRequestListener(MmsServer self, MmsStatusRequestListener listener, void* parameter);
387 
388 char*
389 MmsServerConnection_getClientAddress(MmsServerConnection self);
390 
392 MmsServerConnection_getIsoConnection(MmsServerConnection self);
393 
396 #ifdef __cplusplus
397 }
398 #endif
399 
400 #endif /* MMS_SERVER_H_ */
void MmsServer_installReadAccessHandler(MmsServer self, MmsReadAccessHandler, void *parameter)
void MmsServer_lockModel(MmsServer self)
lock the cached server data model
bool MmsServer_isLocked(MmsServer self)
void MmsServer_startListeningThreadless(MmsServer self, int tcpPort)
Start a new server in non-threaded operation mode.
MmsDataAccessError(* MmsWriteVariableHandler)(void *parameter, MmsDomain *domain, char *variableId, MmsValue *value, MmsServerConnection connection)
Definition: mms_server.h:59
int MmsServer_getVMDPhysicalStatus(MmsServer self)
get the physical status attribute of the VMD
MmsDevice * MmsServer_getDevice(MmsServer self)
struct sIsoServer * IsoServer
Definition: iso_server.h:46
void MmsServer_installReadHandler(MmsServer self, MmsReadVariableHandler, void *parameter)
char * MmsServer_getModelName(MmsServer self)
get the model name attribute of the VMD identity
Definition: mms_server.h:40
struct sMmsServerConnection * MmsServerConnection
Definition: mms_server.h:45
Definition: mms_server.h:40
char * MmsServer_getVendorName(MmsServer self)
get the vendor name attribute of the VMD identity
struct sIsoConnection * IsoConnection
Definition: iso_server.h:54
void MmsServer_unlockModel(MmsServer self)
unlock the cached server data model
void MmsServer_setVMDStatus(MmsServer self, int vmdLogicalStatus, int vmdPhysicalStatus)
set the VMD state values for the VMD status service
Definition: mms_server.h:49
void MmsServer_setServerIdentity(MmsServer self, char *vendorName, char *modelName, char *revision)
set the values that the server will give as response for an MMS identify request
int MmsServer_waitReady(MmsServer self, unsigned int timeoutMs)
Wait for the server to come ready in non-threaded operation mode.
void MmsServer_startListening(MmsServer self, int tcpPort)
Start a new server thread and listen for incoming connections.
struct sMmsServer * MmsServer
Definition: mms_server.h:43
MmsServerEvent
Definition: mms_server.h:39
MmsDataAccessError(* MmsReadAccessHandler)(void *parameter, MmsDomain *domain, char *variableId, MmsServerConnection connection)
Definition: mms_server.h:56
void(* MmsStatusRequestListener)(void *parameter, MmsServer mmsServer, MmsServerConnection connection, bool extendedDerivation)
User provided handler that is invoked on a MMS status request.
Definition: mms_server.h:346
IsoConnection MmsServerConnection_getIsoConnection(MmsServerConnection self)
bool(* MmsObtainFileHandler)(void *parameter, MmsServerConnection connection, const char *sourceFilename, const char *destinationFilename)
ObtainFile service callback handler.
Definition: mms_server.h:138
MmsVariableListType
Definition: mms_server.h:47
char * MmsServerConnection_getClientAddress(MmsServerConnection self)
int MmsServer_getVMDLogicalStatus(MmsServer self)
get the logical status attribute of the VMD
MmsValue *(* MmsReadVariableHandler)(void *parameter, MmsDomain *domain, char *variableId, MmsServerConnection connection)
Definition: mms_server.h:53
void MmsServer_insertIntoCache(MmsServer self, MmsDomain *domain, char *itemId, MmsValue *value)
bool(* AcseAuthenticator)(void *parameter, AcseAuthenticationParameter authParameter, void **securityToken)
Callback function to authenticate a client.
Definition: iso_connection_parameters.h:92
MmsError(* MmsNamedVariableListChangedHandler)(void *parameter, bool create, MmsVariableListType listType, MmsDomain *domain, char *listName, MmsServerConnection connection)
callback handler that is called whenever a named variable list changes
Definition: mms_server.h:114
void MmsServer_handleIncomingMessages(MmsServer self)
Handle client connections (for non-threaded operation mode)
Definition: mms_server.h:48
void MmsServer_installVariableListChangedHandler(MmsServer self, MmsNamedVariableListChangedHandler handler, void *parameter)
Install callback handler that is called when a named variable list changes (is created or deleted) ...
void(* MmsGetFileCompleteHandler)(void *parameter, MmsServerConnection connection, const char *destinationFilename)
Get file complete (obtainFile service terminated) callback handler.
Definition: mms_server.h:161
Definition: mms_server.h:50
void MmsServer_installGetFileCompleteHandler(MmsServer self, MmsGetFileCompleteHandler handler, void *parameter)
Install callback handler that is invoked when the file upload (obtainFile service) is completed and t...
void(* MmsConnectionHandler)(void *parameter, MmsServerConnection connection, MmsServerEvent event)
Definition: mms_server.h:63
void MmsServer_setStatusRequestListener(MmsServer self, MmsStatusRequestListener listener, void *parameter)
set the MmsStatusRequestListener for this MmsServer
MmsDataAccessError
Definition: mms_value.h:47
void MmsServer_installWriteHandler(MmsServer self, MmsWriteVariableHandler, void *parameter)
MmsValue * MmsServer_getValueFromCache(MmsServer self, MmsDomain *domain, char *itemId)
void MmsServer_installObtainFileHandler(MmsServer self, MmsObtainFileHandler handler, void *parameter)
Install callback handler that is invoked when the file upload (obtainFile service) is invoked by the ...
void MmsServer_installConnectionHandler(MmsServer self, MmsConnectionHandler, void *parameter)
void MmsServer_setDevice(MmsServer self, MmsDevice *device)
MmsServer MmsServer_create(IsoServer isoServer, MmsDevice *device)
void MmsServer_stopListeningThreadless(MmsServer self)
Stop the server (for non-threaded operation mode)
Definition: mms_device_model.h:38
void MmsServer_setClientAuthenticator(MmsServer self, AcseAuthenticator authenticator, void *authenticatorParameter)
void MmsServer_handleBackgroundTasks(MmsServer self)
Handle MmsServer background task.
void MmsServer_destroy(MmsServer self)
char * MmsServer_getRevision(MmsServer self)
get the revision attribute of the VMD identity
MmsError
Definition: mms_common.h:38
void MmsServer_stopListening(MmsServer self)
Stop server thread an all open connection threads.
struct sMmsValue MmsValue
Definition: mms_value.h:68