libIEC61850
Open-source IEC 61850 MMS server and client library
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Groups Pages
Data Structures | Typedefs | Enumerations | Functions
IEC 61850 MMS client API

Data Structures

struct  MmsConnectionParameters
 
struct  MmsVariableSpecification
 

Typedefs

typedef void(* MmsInformationReportHandler )(void *parameter, char *domainName, char *variableListName, MmsValue *value)
 
typedef struct sMmsConnection * MmsConnection
 

Enumerations

enum  MmsClientError { MMS_CE_NO_ERROR, MMS_CE_REQUEST_FAILED, MMS_CE_REQUEST_TIMEOUT, MMS_CE_INVOKE_ID_MISMATCH }
 

Functions

MmsConnection MmsConnection_create ()
 
void MmsConnection_setInformationReportHandler (MmsConnection self, MmsInformationReportHandler handler, void *parameter)
 
void MmsConnection_setConnectionParameters (MmsConnection self, MmsConnectionParameters params)
 
void MmsConnection_setIsoConnectionParameters (MmsConnection self, IsoConnectionParameters *params)
 
void MmsConnection_destroy (MmsConnection self)
 
MmsClientError MmsConnection_getError (MmsConnection self)
 
MmsIndication MmsConnection_connect (MmsConnection self, char *serverName, int serverPort)
 
LinkedList MmsConnection_getDomainNames (MmsConnection self)
 
LinkedList MmsConnection_getDomainVariableNames (MmsConnection self, char *domainId)
 
LinkedList MmsConnection_getDomainVariableListNames (MmsConnection self, char *domainId)
 
LinkedList MmsConnection_getVariableListNamesAssociationSpecific (MmsConnection self)
 
MmsValue * MmsConnection_readVariable (MmsConnection self, char *domainId, char *itemId)
 
MmsValue * MmsConnection_readArrayElements (MmsConnection self, char *domainId, char *itemId, uint32_t startIndex, uint32_t numberOfElements)
 
MmsValue * MmsConnection_readMultipleVariables (MmsConnection self, char *domainId, LinkedListitems)
 
MmsIndication MmsConnection_writeVariable (MmsConnection self, char *domainId, char *itemId, MmsValue *value)
 
MmsTypeSpecification * MmsConnection_getVariableAccessAttributes (MmsConnection self, char *domainId, char *itemId)
 
MmsValue * MmsConnection_readNamedVariableListValues (MmsConnection self, char *domainId, char *listName, bool specWithResult)
 
MmsValue * MmsConnection_readNamedVariableListValuesAssociationSpecific (MmsConnection self, char *listName, bool specWithResult)
 
MmsIndication MmsConnection_defineNamedVariableList (MmsConnection self, char *domainId, char *listName, LinkedList variableSpecs)
 
MmsIndication MmsConnection_defineNamedVariableListAssociationSpecific (MmsConnection self, char *listName, LinkedList variableSpecs)
 
LinkedList MmsConnection_readNamedVariableListDirectory (MmsConnection self, char *domainId, char *listName, bool *deletable)
 
LinkedList MmsConnection_readAssociationSpecificNamedVariableListDirectory (MmsConnection self, char *listName)
 
MmsIndication MmsConnection_deleteNamedVariableList (MmsConnection self, char *domainId, char *listName)
 
MmsIndication MmsConnection_deleteAssociationSpecificNamedVariableList (MmsConnection self, char *listName)
 
MmsVariableSpecificationMmsVariableSpecification_create (char *domainId, char *itemId)
 
MmsVariableSpecificationMmsVariableSpecification_createAlternateAccess (char *domainId, char *itemId, int32_t index, char *componentName)
 
void MmsConnection_setLocalDetail (MmsConnection self, int32_t localDetail)
 
int32_t MmsConnection_getLocalDetail (MmsConnection self)
 

Detailed Description

Typedef Documentation

typedef struct sMmsConnection* MmsConnection

Opaque handle for MMS client connection instance.

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

Enumeration Type Documentation

Detailed MMS Client error codes

Enumerator
MMS_CE_NO_ERROR 
MMS_CE_REQUEST_FAILED 
MMS_CE_REQUEST_TIMEOUT 
MMS_CE_INVOKE_ID_MISMATCH 

Function Documentation

MmsIndication MmsConnection_connect ( MmsConnection  self,
char *  serverName,
int  serverPort 
)

Connect to a MMS server. This will open a new TCP connection and send a MMS initiate request.

Parameters
selfMmsConnection instance to operate on
serverNamehostname or IP address of the server to connect
serverPortTCP port number of the server to connect (usually 102)
Returns
MMS_OK on success. MMS_ERROR if the connection attempt failed.
MmsConnection MmsConnection_create ( )

Create a new MmsConnection instance

Returns
the newly created instance.
MmsIndication MmsConnection_defineNamedVariableList ( MmsConnection  self,
char *  domainId,
char *  listName,
LinkedList  variableSpecs 
)

Define a new named variable list at the server.

Parameters
selfMmsConnection instance to operate on
domainIdthe domain name of the domain for the new variable list
listNamethe name of the named variable list
variableSpecsa list of variable specifications for the new variable lsit
Returns
MMS_OK on success. MMS_ERROR if the write attempt failed.
MmsIndication MmsConnection_defineNamedVariableListAssociationSpecific ( MmsConnection  self,
char *  listName,
LinkedList  variableSpecs 
)

Define a new association specific named variable list at the server.

Parameters
selfMmsConnection instance to operate on
listNamethe name of the named variable list
variableSpecslist of variable specifications for the new variable lsit
Returns
MMS_OK on success. MMS_ERROR if the write attempt failed.
MmsIndication MmsConnection_deleteAssociationSpecificNamedVariableList ( MmsConnection  self,
char *  listName 
)

Delete an association specific named variable list at the server.

Parameters
selfMmsConnection instance to operate on
listNamethe name of the named variable list
Returns
MMS_OK on success. MMS_ERROR if the request failed.
MmsIndication MmsConnection_deleteNamedVariableList ( MmsConnection  self,
char *  domainId,
char *  listName 
)

Delete a named variable list at the server.

Parameters
selfMmsConnection instance to operate on
domainIdthe domain name of the domain of the variable list
listNamethe name of the named variable list
Returns
MMS_OK on success. MMS_ERROR if the request failed.
void MmsConnection_destroy ( MmsConnection  self)

Destroy a MmsConnection instance and release all resources

Parameters
selfMmsConnection instance to operate on
LinkedList MmsConnection_getDomainNames ( MmsConnection  self)

Get the domains names for all domains of the server.

This will result in a VMD specific GetNameList request.

Parameters
selfMmsConnection instance to operate on
Returns
the list of domain names or NULL if the request failed.
LinkedList MmsConnection_getDomainVariableListNames ( MmsConnection  self,
char *  domainId 
)

Get the names of all named variable lists present in a MMS domain of the server.

This will result in a domain specific GetNameList request.

Parameters
selfMmsConnection instance to operate on
domainIdthe domain name for the domain specific request
Returns
the domain specific named variable list names or NULL if the request failed.
LinkedList MmsConnection_getDomainVariableNames ( MmsConnection  self,
char *  domainId 
)

Get the names of all variables present in a MMS domain of the server.

This will result in a domain specific GetNameList request.

Parameters
selfMmsConnection instance to operate on
domainIdthe domain name for the domain specific request
Returns
the of domain specific variable names or NULL if the request failed.
MmsClientError MmsConnection_getError ( MmsConnection  self)

Get a detailed description of the last error occurred.

Parameters
selfMmsConnection instance to operate on
int32_t MmsConnection_getLocalDetail ( MmsConnection  self)
MmsTypeSpecification* MmsConnection_getVariableAccessAttributes ( MmsConnection  self,
char *  domainId,
char *  itemId 
)

Get the variable access attributes of a MMS named variable of the server

Parameters
selfMmsConnection instance to operate on
domainIdthe domain name of the variable
itemIdname of the variable
Returns
Returns a MmsTypeSpecification object or NULL if the request failed.
LinkedList MmsConnection_getVariableListNamesAssociationSpecific ( MmsConnection  self)

Get the names of all named variable lists associated with this client connection.

This will result in an association specific GetNameList request.

Parameters
selfMmsConnection instance to operate on
Returns
the association specific named variable list names or NULL if the request failed.
MmsValue* MmsConnection_readArrayElements ( MmsConnection  self,
char *  domainId,
char *  itemId,
uint32_t  startIndex,
uint32_t  numberOfElements 
)

Read an element of a single array variable from the server.

Parameters
selfMmsConnection instance to operate on
domainIdthe domain name of the variable to be read
itemIdname of the variable to be read
startIndexindex of element to read or start index if a element range is to be read
numberOfElementsNumber of elements to read or 0 if a single element is to be read
Returns
Returns a MmsValue object or NULL if the request failed. The MmsValue object is either a simple or complex type if numberOfElements is 0, or an array containing the selected array elements of numberOfElements > 0.
LinkedList MmsConnection_readAssociationSpecificNamedVariableListDirectory ( MmsConnection  self,
char *  listName 
)

Read the entry list of an association specific named variable list at the server.

Parameters
selfMmsConnection instance to operate on
listNamethe name of the named variable list
Returns
List of names of the variable list entries or NULL if the request failed
MmsValue* MmsConnection_readMultipleVariables ( MmsConnection  self,
char *  domainId,
LinkedListitems   
)

Read multiple variables of a domain from the server with one request message.

Parameters
selfMmsConnection instance to operate on
domainIdthe domain name of the requested variables. : LinkedList<char*> is the list of item IDs of the requested variables.
Returns
Returns a MmsValue object or NULL if the request failed. The MmsValue object is is of type MMS_ARRAY and contains the variable values of simple or complex type in the order as they appeared in the item ID list.
LinkedList MmsConnection_readNamedVariableListDirectory ( MmsConnection  self,
char *  domainId,
char *  listName,
bool *  deletable 
)

Read the entry list of a named variable list at the server.

Parameters
selfMmsConnection instance to operate on
domainIdthe domain name of the domain of the variable list
listNamethe name of the named variable list
deletableTHIS IS A OUTPUT PARAMETER - indicates if the variable list is deletable by the client. The user may provide a NULL pointer if the value doesn't matter.
Returns
List of names of the variable list entries or NULL if the request failed
MmsValue* MmsConnection_readNamedVariableListValues ( MmsConnection  self,
char *  domainId,
char *  listName,
bool  specWithResult 
)

Read the values of a domain specific named variable list

Parameters
selfMmsConnection instance to operate on
domainIdthe domain name of the requested variables.
listNamethe name of the named variable list
specWithResultif specWithResult is set to true, a IEC 61850 compliant request will be sent.
Returns
Returns a MmsValue object or NULL if the request failed. The MmsValue object is is of type MMS_ARRAY and contains the variable values of simple or complex type in the order as they appeared in named variable list definition.
MmsValue* MmsConnection_readNamedVariableListValuesAssociationSpecific ( MmsConnection  self,
char *  listName,
bool  specWithResult 
)

Read the values of a association specific named variable list

Parameters
selfMmsConnection instance to operate on
listNamethe name of the named variable list
specWithResultif specWithResult is set to true, a IEC 61850 compliant request will be sent.
Returns
Returns a MmsValue object or NULL if the request failed. The MmsValue object is is of type MMS_ARRAY and contains the variable values of simple or complex type in the order as they appeared in named variable list definition.
MmsValue* MmsConnection_readVariable ( MmsConnection  self,
char *  domainId,
char *  itemId 
)

Read a single variable from the server.

Parameters
selfMmsConnection instance to operate on
domainIdthe domain name of the variable to be read
itemIdname of the variable to be read
Returns
Returns a MmsValue object or NULL if the request failed. The MmsValue object can either be a simple value or a complex value or array.
void MmsConnection_setConnectionParameters ( MmsConnection  self,
MmsConnectionParameters  params 
)

Set the connection parameters for a MmsConnection instance

Parameters
selfMmsConnection instance to operate on
paramsthe parameters to use
void MmsConnection_setInformationReportHandler ( MmsConnection  self,
MmsInformationReportHandler  handler,
void *  parameter 
)

Install a handler function for MMS information reports (unsolicited messages from the server). The handler function will be called whenever the client receives an MMS information report message. Note that the API user is responsible to properly free the passed MmsValue object.

Parameters
selfMmsConnection instance to operate on
handlerthe handler function to install for this client connection
parametera user specified parameter that will be passed to the handler function on each invocation.
void MmsConnection_setIsoConnectionParameters ( MmsConnection  self,
IsoConnectionParameters *  params 
)

Set the ISO connection parameters for a MmsConnection instance

Parameters
selfMmsConnection instance to operate on
paramsthe ISO client parameters to use
void MmsConnection_setLocalDetail ( MmsConnection  self,
int32_t  localDetail 
)

Get the MMS local detail parameter (local detail means maximum MMS PDU size). This defaults to

  1. This function should not be called after a successful connection attempt.
Parameters
localDetailthe maximum size of the MMS PDU that we will accept.
MmsIndication MmsConnection_writeVariable ( MmsConnection  self,
char *  domainId,
char *  itemId,
MmsValue *  value 
)

Write a single variable to the server.

Parameters
selfMmsConnection instance to operate on
domainIdthe domain name of the variable to be written
itemIdname of the variable to be written
valuevalue of the variable to be written
Returns
MMS_OK on success. MMS_ERROR if the write attempt failed.
MmsVariableSpecification* MmsVariableSpecification_create ( char *  domainId,
char *  itemId 
)

Create a new MmsVariableSpecification that can be used to define named variable lists. The created object can be deleted with free(). If the parameter strings were dynamically allocated the deallocation is in the responsibility of the user.

Parameters
domainIdthe MMS domain name of the variable
itemIdthe name for the MMS variable
Returns
reference to the new MmsVariableSpecfication object
MmsVariableSpecification* MmsVariableSpecification_createAlternateAccess ( char *  domainId,
char *  itemId,
int32_t  index,
char *  componentName 
)

Create a new MmsVariableSpecification that can be used to define named variable lists. The created object can be deleted with free(). If the parameter strings were dynamically allocated the deallocation is in the responsibility of the user. This function should be used for named variable list entries that are array elements or components of array elements in the case when the array element is of complex (structured) type.

Parameters
domainIdthe MMS domain name of the variable
itemIdthe name for the MMS variable
indexthe array index to describe an array element
componentNamethe name of the component of the array element. Should be set to NULL if the array element is of simple type or the whole array element is required.
Returns
reference to the new MmsVariableSpecfication object