libIEC61850  0.8.2
Open-source IEC 61850 MMS/GOOSE server and client library
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Groups Pages
Classes | Macros | Typedefs | Enumerations | Functions
MMS client API (for IEC 61850 use IEC 61850 client API instead!)

Classes

struct  MmsConnectionParameters
 
struct  MmsServerIdentity
 
struct  AcseAuthenticationParameter
 
struct  TSelector
 COTP T selector. More...
 
struct  IsoConnectionParameters
 

Macros

#define AUTH_NONE   ACSE_AUTH_NONE
 
#define AUTH_PASSWORD   ACSE_AUTH_PASSWORD
 

Typedefs

typedef void(* MmsInformationReportHandler )(void *parameter, char *domainName, char *variableListName, MmsValue *value, bool isVariableListName)
 
typedef struct sMmsConnection * MmsConnection
 
typedef void(* MmsConnectionLostHandler )(MmsConnection connection, void *parameter)
 User provided handler function that will be called if the connection to the server is lost. More...
 
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)
 
typedef bool(* AcseAuthenticator )(void *parameter, AcseAuthenticationParameter authParameter, void **securityToken)
 Callback function to authenticate a client. More...
 

Enumerations

enum  AcseAuthenticationMechanism { ACSE_AUTH_NONE = 0, ACSE_AUTH_PASSWORD = 1 }
 

Functions

MmsConnection MmsConnection_create (void)
 Create a new MmsConnection instance. More...
 
void MmsConnection_setRequestTimeout (MmsConnection self, uint32_t timeoutInMs)
 Set the request timeout in ms for this connection. More...
 
void MmsConnection_setConnectTimeout (MmsConnection self, uint32_t timeoutInMs)
 Set the connect timeout in ms for this connection instance. More...
 
void MmsConnection_setInformationReportHandler (MmsConnection self, MmsInformationReportHandler handler, void *parameter)
 Install a handler function for MMS information reports (unsolicited messages from the server). More...
 
IsoConnectionParameters MmsConnection_getIsoConnectionParameters (MmsConnection self)
 Get the connection parameters for an MmsConnection instance. More...
 
void MmsConnection_setConnectionLostHandler (MmsConnection self, MmsConnectionLostHandler handler, void *handlerParameter)
 Install a callback function that will be called by the client stack if the MMS connection to the server is lost. More...
 
void MmsConnection_setIsoConnectionParameters (MmsConnection self, IsoConnectionParameters *params)
 Set the ISO connection parameters for a MmsConnection instance. More...
 
void MmsConnection_destroy (MmsConnection self)
 Destroy an MmsConnection instance and release all resources. More...
 
bool MmsConnection_connect (MmsConnection self, MmsError *mmsError, const char *serverName, int serverPort)
 Connect to an MMS server. More...
 
void MmsConnection_close (MmsConnection self)
 Close the connection - not recommended. More...
 
void MmsConnection_abort (MmsConnection self, MmsError *mmsError)
 Uses the MMS/ACSE abort service to close the connection to the server. More...
 
void MmsConnection_conclude (MmsConnection self, MmsError *mmsError)
 Uses the MMS conclude service to close the connection to the server. More...
 
LinkedList MmsConnection_getVMDVariableNames (MmsConnection self, MmsError *mmsError)
 Get the names of all VMD scope variables of the server. More...
 
LinkedList MmsConnection_getDomainNames (MmsConnection self, MmsError *mmsError)
 Get the domains names for all domains of the server. More...
 
LinkedList MmsConnection_getDomainVariableNames (MmsConnection self, MmsError *mmsError, const char *domainId)
 Get the names of all variables present in a MMS domain of the server. More...
 
LinkedList MmsConnection_getDomainVariableListNames (MmsConnection self, MmsError *mmsError, const char *domainId)
 Get the names of all named variable lists present in a MMS domain of the server. More...
 
LinkedList MmsConnection_getVariableListNamesAssociationSpecific (MmsConnection self, MmsError *mmsError)
 Get the names of all named variable lists associated with this client connection. More...
 
MmsValueMmsConnection_readVariable (MmsConnection self, MmsError *mmsError, const char *domainId, const char *itemId)
 Read a single variable from the server. More...
 
MmsValueMmsConnection_readArrayElements (MmsConnection self, MmsError *mmsError, const char *domainId, const char *itemId, uint32_t startIndex, uint32_t numberOfElements)
 Read an element of a single array variable from the server. More...
 
MmsValueMmsConnection_readMultipleVariables (MmsConnection self, MmsError *mmsError, const char *domainId, LinkedListitems)
 Read multiple variables of a domain from the server with one request message. More...
 
void MmsConnection_writeVariable (MmsConnection self, MmsError *mmsError, const char *domainId, const char *itemId, MmsValue *value)
 Write a single variable to the server. More...
 
void MmsConnection_writeMultipleVariables (MmsConnection self, MmsError *mmsError, const char *domainId, LinkedListitems, LinkedListvalues, LinkedList *accessResults)
 Write multiple variables to the server. More...
 
MmsVariableSpecification * MmsConnection_getVariableAccessAttributes (MmsConnection self, MmsError *mmsError, const char *domainId, const char *itemId)
 Get the variable access attributes of a MMS named variable of the server. More...
 
MmsValueMmsConnection_readNamedVariableListValues (MmsConnection self, MmsError *mmsError, const char *domainId, const char *listName, bool specWithResult)
 Read the values of a domain specific named variable list. More...
 
MmsValueMmsConnection_readNamedVariableListValuesAssociationSpecific (MmsConnection self, MmsError *mmsError, const char *listName, bool specWithResult)
 Read the values of a association specific named variable list. More...
 
void MmsConnection_defineNamedVariableList (MmsConnection self, MmsError *mmsError, const char *domainId, const char *listName, LinkedList variableSpecs)
 Define a new named variable list at the server. More...
 
void MmsConnection_defineNamedVariableListAssociationSpecific (MmsConnection self, MmsError *mmsError, const char *listName, LinkedList variableSpecs)
 Define a new association specific named variable list at the server. More...
 
LinkedList MmsConnection_readNamedVariableListDirectory (MmsConnection self, MmsError *mmsError, const char *domainId, const char *listName, bool *deletable)
 Read the entry list of a named variable list at the server. More...
 
LinkedList MmsConnection_readNamedVariableListDirectoryAssociationSpecific (MmsConnection self, MmsError *mmsError, const char *listName, bool *deletable)
 Read the entry list of an association specific named variable list at the server. More...
 
void MmsConnection_deleteNamedVariableList (MmsConnection self, MmsError *mmsError, const char *domainId, const char *listName)
 Delete a named variable list at the server. More...
 
void MmsConnection_deleteAssociationSpecificNamedVariableList (MmsConnection self, MmsError *mmsError, const char *listName)
 Delete an association specific named variable list at the server. More...
 
MmsVariableAccessSpecification * MmsVariableAccessSpecification_create (char *domainId, char *itemId)
 Create a new MmsVariableSpecification that can be used to define named variable lists. More...
 
MmsVariableAccessSpecification * MmsVariableAccessSpecification_createAlternateAccess (char *domainId, char *itemId, int32_t index, char *componentName)
 Create a new MmsVariableSpecification that can be used to define named variable lists. More...
 
void MmsVariableAccessSpecification_destroy (MmsVariableAccessSpecification *self)
 Delete the MmsVariableAccessSpecification data structure. More...
 
void MmsConnection_setLocalDetail (MmsConnection self, int32_t localDetail)
 Get the MMS local detail parameter (local detail means maximum MMS PDU size). More...
 
int32_t MmsConnection_getLocalDetail (MmsConnection self)
 
MmsServerIdentityMmsConnection_identify (MmsConnection self, MmsError *mmsError)
 get the identity of the connected server More...
 
void MmsServerIdentity_destroy (MmsServerIdentity *self)
 
void MmsConnection_getServerStatus (MmsConnection self, MmsError *mmsError, int *vmdLogicalStatus, int *vmdPhysicalStatus, bool extendedDerivation)
 get the VMD status of the connected server (is MMS status service) More...
 
int32_t MmsConnection_fileOpen (MmsConnection self, MmsError *mmsError, const char *filename, uint32_t initialPosition, uint32_t *fileSize, uint64_t *lastModified)
 open a file for read More...
 
bool MmsConnection_fileRead (MmsConnection self, MmsError *mmsError, int32_t frsmId, MmsFileReadHandler handler, void *handlerParameter)
 read the next data block from the file More...
 
void MmsConnection_fileClose (MmsConnection self, MmsError *mmsError, int32_t frsmId)
 close the file with the specified frsmID More...
 
void MmsConnection_fileDelete (MmsConnection self, MmsError *mmsError, const char *fileName)
 delete the file with the specified name More...
 
void MmsConnection_fileRename (MmsConnection self, MmsError *mmsError, const char *currentFileName, const char *newFileName)
 rename the file with the specified name More...
 
bool MmsConnection_getFileDirectory (MmsConnection self, MmsError *mmsError, const char *fileSpecification, const char *continueAfter, MmsFileDirectoryHandler handler, void *handlerParameter)
 get the file directory of the server. More...
 
AcseAuthenticationParameter AcseAuthenticationParameter_create (void)
 
void AcseAuthenticationParameter_destroy (AcseAuthenticationParameter self)
 
void AcseAuthenticationParameter_setAuthMechanism (AcseAuthenticationParameter self, AcseAuthenticationMechanism mechanism)
 
void AcseAuthenticationParameter_setPassword (AcseAuthenticationParameter self, char *password)
 
IsoConnectionParameters IsoConnectionParameters_create (void)
 create a new IsoConnectionParameters instance (FOR LIBRARY INTERNAL USE) More...
 
void IsoConnectionParameters_destroy (IsoConnectionParameters self)
 Destroy an IsoConnectionParameters instance (FOR LIBRARY INTERNAL USE) More...
 
void IsoConnectionParameters_setAcseAuthenticationParameter (IsoConnectionParameters self, AcseAuthenticationParameter acseAuthParameter)
 set the authentication parameter More...
 
void IsoConnectionParameters_setTcpParameters (IsoConnectionParameters self, const char *hostname, int tcpPort)
 Set TCP parameters (FOR LIBRARY INTERNAL USE) More...
 
void IsoConnectionParameters_setRemoteApTitle (IsoConnectionParameters self, const char *apTitle, int aeQualifier)
 set the remote AP-Title and AE-Qualifier More...
 
void IsoConnectionParameters_setRemoteAddresses (IsoConnectionParameters self, uint32_t pSelector, uint16_t sSelector, TSelector tSelector)
 set remote addresses for the lower layers More...
 
void IsoConnectionParameters_setLocalApTitle (IsoConnectionParameters self, char *apTitle, int aeQualifier)
 set the local AP-Title and AE-Qualifier More...
 
void IsoConnectionParameters_setLocalAddresses (IsoConnectionParameters self, uint32_t pSelector, uint16_t sSelector, TSelector tSelector)
 set local addresses for the lower layers More...
 

Detailed Description

Macro Definition Documentation

#define AUTH_NONE   ACSE_AUTH_NONE
#define AUTH_PASSWORD   ACSE_AUTH_PASSWORD

Typedef Documentation

typedef bool(* AcseAuthenticator)(void *parameter, AcseAuthenticationParameter authParameter, void **securityToken)

Callback function to authenticate a client.

Parameters
parameteruser provided parameter - set when user registers the authenticator
authParameterthe authentication parameters provided by the client
securityTokenpointer where to store an application specific security token - can be ignored if not used.
Returns
true if client connection is accepted, false otherwise
typedef struct sMmsConnection* MmsConnection

Opaque handle for MMS client connection instance.

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

User provided handler function that will be called if the connection to the server is lost.

Parameters
connectionMmsConnection object of the lost connection
parameteruser provided parameter.
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)
typedef void(* MmsInformationReportHandler)(void *parameter, char *domainName, char *variableListName, MmsValue *value, bool isVariableListName)

Enumeration Type Documentation

Enumerator
ACSE_AUTH_NONE 
ACSE_AUTH_PASSWORD 

Function Documentation

AcseAuthenticationParameter AcseAuthenticationParameter_create ( void  )
void AcseAuthenticationParameter_destroy ( AcseAuthenticationParameter  self)
void AcseAuthenticationParameter_setAuthMechanism ( AcseAuthenticationParameter  self,
AcseAuthenticationMechanism  mechanism 
)
void AcseAuthenticationParameter_setPassword ( AcseAuthenticationParameter  self,
char *  password 
)
IsoConnectionParameters IsoConnectionParameters_create ( void  )

create a new IsoConnectionParameters instance (FOR LIBRARY INTERNAL USE)

NOTE: This function used internally by the MMS client library. When using the MMS or IEC 61850 API there should be no reason for the user to call this function.

Returns
new IsoConnectionParameters instanceextern "C" {
void IsoConnectionParameters_destroy ( IsoConnectionParameters  self)

Destroy an IsoConnectionParameters instance (FOR LIBRARY INTERNAL USE)

NOTE: This function used internally by the MMS client library. When using the MMS or IEC 61850 API there should be no reason for the user to call this function.

Parameters
selfthe IsoConnectionParameters instance
void IsoConnectionParameters_setAcseAuthenticationParameter ( IsoConnectionParameters  self,
AcseAuthenticationParameter  acseAuthParameter 
)

set the authentication parameter

This will set the authentication parameter and activates authentication.

Parameters
selfthe IsoConnectionParameters instance
acseAuthParameter
void IsoConnectionParameters_setLocalAddresses ( IsoConnectionParameters  self,
uint32_t  pSelector,
uint16_t  sSelector,
TSelector  tSelector 
)

set local addresses for the lower layers

This function can be used to set the addresses for the lower layer protocols (presentation, session, and transport layer). Calling this function is optional and not recommended. If not called the default parameters are used.

Parameters
selfthe IsoConnectionParameters instance
pSelectorthe P-Selector (presentation layer address)
sSelectorthe S-Selector (session layer address)
tSelectorthe T-Selector (ISO transport layer address)
void IsoConnectionParameters_setLocalApTitle ( IsoConnectionParameters  self,
char *  apTitle,
int  aeQualifier 
)

set the local AP-Title and AE-Qualifier

Calling this function is optional and not recommended. If not called the default parameters are used. If apTitle is NULL the parameter the AP-Title and AE-Qualifier will not be transmitted. This seems to be required by some server devices.

Parameters
selfthe IsoConnectionParameters instance
apTitlethe AP-Title OID as string.
aeQualifierthe AP-qualifier
void IsoConnectionParameters_setRemoteAddresses ( IsoConnectionParameters  self,
uint32_t  pSelector,
uint16_t  sSelector,
TSelector  tSelector 
)

set remote addresses for the lower layers

This function can be used to set the addresses for the lower layer protocols (presentation, session, and transport layer). Calling this function is optional and not recommended. If not called the default parameters are used.

Parameters
selfthe IsoConnectionParameters instance
pSelectorthe P-Selector (presentation layer address)
sSelectorthe S-Selector (session layer address)
tSelectorthe T-Selector (ISO transport layer address)
void IsoConnectionParameters_setRemoteApTitle ( IsoConnectionParameters  self,
const char *  apTitle,
int  aeQualifier 
)

set the remote AP-Title and AE-Qualifier

Calling this function is optional and not recommended. If not called the default parameters are used. If apTitle is NULL the parameter the AP-Title and AE-Qualifier will not be transmitted. This seems to be required by some server devices.

Parameters
selfthe IsoConnectionParameters instance
apTitlethe AP-Title OID as string.
aeQualifierthe AP-qualifier
void IsoConnectionParameters_setTcpParameters ( IsoConnectionParameters  self,
const char *  hostname,
int  tcpPort 
)

Set TCP parameters (FOR LIBRARY INTERNAL USE)

NOTE: This function used internally by the MMS client library. When using the MMS or IEC 61850 API there should be no reason for the user to call this function

Parameters
selfthe IsoConnectionParameters instance
hostnamethe hostname of IP address if the server
tcpPortthe TCP port number of the server
void MmsConnection_abort ( MmsConnection  self,
MmsError *  mmsError 
)

Uses the MMS/ACSE abort service to close the connection to the server.

This service should be used to abruptly interrupt the connection to the server. The TCP connection will be closed immediately after sending the ACSE abort message to the server. It is not quite clear what the benefit of this service is (simply closing the TCP connection should do the same). Though it is required by conformance tests.

Parameters
selfMmsConnection instance to operate on
mmsErroruser provided variable to store error code
void MmsConnection_close ( MmsConnection  self)

Close the connection - not recommended.

This service simply closes the TCP socket without any hand-shaking with the server. This behavior is not specified. Use with care!

Parameters
selfMmsConnection instance to operate on
void MmsConnection_conclude ( MmsConnection  self,
MmsError *  mmsError 
)

Uses the MMS conclude service to close the connection to the server.

This should be used to orderly release the connection to the server. If the server denies the conclude request (by sending a concludeError PDU) this service fails with an error (mmsError set accordingly) and the connection remains open. In this case the close or abort methods have to be used to close the connection. It is not quite clear if this service is really useful but it is required by conformance tests.

Parameters
selfMmsConnection instance to operate on
mmsErroruser provided variable to store error code
bool MmsConnection_connect ( MmsConnection  self,
MmsError *  mmsError,
const char *  serverName,
int  serverPort 
)

Connect to an MMS server.

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

Parameters
selfMmsConnection instance to operate on
mmsErroruser provided variable to store error code
serverNamehostname or IP address of the server to connect
serverPortTCP port number of the server to connect (usually 102)
Returns
true on success. false if the connection attempt failed.
MmsConnection MmsConnection_create ( void  )

Create a new MmsConnection instance.

Returns
the newly created instance.
void MmsConnection_defineNamedVariableList ( MmsConnection  self,
MmsError *  mmsError,
const char *  domainId,
const char *  listName,
LinkedList  variableSpecs 
)

Define a new named variable list at the server.

Parameters
selfMmsConnection instance to operate on
mmsErroruser provided variable to store error code
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 list. The list elements have to be of type MmsVariableAccessSpecification*.
void MmsConnection_defineNamedVariableListAssociationSpecific ( MmsConnection  self,
MmsError *  mmsError,
const char *  listName,
LinkedList  variableSpecs 
)

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

Parameters
selfMmsConnection instance to operate on
mmsErroruser provided variable to store error code
listNamethe name of the named variable list
variableSpecslist of variable specifications for the new variable list.The list elements have to be of type MmsVariableAccessSpecification*.
void MmsConnection_deleteAssociationSpecificNamedVariableList ( MmsConnection  self,
MmsError *  mmsError,
const char *  listName 
)

Delete an association specific named variable list at the server.

Parameters
selfMmsConnection instance to operate on
mmsErroruser provided variable to store error code
listNamethe name of the named variable list
void MmsConnection_deleteNamedVariableList ( MmsConnection  self,
MmsError *  mmsError,
const char *  domainId,
const char *  listName 
)

Delete a named variable list at the server.

Parameters
selfMmsConnection instance to operate on
mmsErroruser provided variable to store error code
domainIdthe domain name of the domain of the variable list
listNamethe name of the named variable list
void MmsConnection_destroy ( MmsConnection  self)

Destroy an MmsConnection instance and release all resources.

Parameters
selfMmsConnection instance to operate on
void MmsConnection_fileClose ( MmsConnection  self,
MmsError *  mmsError,
int32_t  frsmId 
)

close the file with the specified frsmID

Parameters
selfMmsConnection instance to operate on
mmsErroruser provided variable to store error code
frsmIdid of the file to close
void MmsConnection_fileDelete ( MmsConnection  self,
MmsError *  mmsError,
const char *  fileName 
)

delete the file with the specified name

Parameters
selfMmsConnection instance to operate on
mmsErroruser provided variable to store error code
fileNamename of the file to delete
int32_t MmsConnection_fileOpen ( MmsConnection  self,
MmsError *  mmsError,
const char *  filename,
uint32_t  initialPosition,
uint32_t *  fileSize,
uint64_t *  lastModified 
)

open a file for read

Returns
the FRSM ID (file read state machine) handle of the opened file
bool MmsConnection_fileRead ( MmsConnection  self,
MmsError *  mmsError,
int32_t  frsmId,
MmsFileReadHandler  handler,
void *  handlerParameter 
)

read the next data block from the file

Parameters
selfMmsConnection instance to operate on
mmsErroruser provided variable to store error code
frsmIdthe FRSM ID (file read state machine) handle of the file
handlercallback that is invoked to deliver the received data
handlerParameteruser provided paramter that is passed to the callback function
Returns
true if more data follows, false if last data has been received.
void MmsConnection_fileRename ( MmsConnection  self,
MmsError *  mmsError,
const char *  currentFileName,
const char *  newFileName 
)

rename the file with the specified name

Parameters
selfMmsConnection instance to operate on
mmsErroruser provided variable to store error code
currentFileNamename of the file to rename
newFileNamenew name of the file
LinkedList MmsConnection_getDomainNames ( MmsConnection  self,
MmsError *  mmsError 
)

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
mmsErroruser provided variaextern "C" {ble to store error code
Returns
the list of domain names or NULL if the request failed.
LinkedList MmsConnection_getDomainVariableListNames ( MmsConnection  self,
MmsError *  mmsError,
const 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
mmsErroruser provided variable to store error code
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,
MmsError *  mmsError,
const 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
mmsErroruser provided variable to store error code
domainIdthe domain name for the domain specific request
Returns
the of domain specific variable names or NULL if the request failed.
bool MmsConnection_getFileDirectory ( MmsConnection  self,
MmsError *  mmsError,
const char *  fileSpecification,
const char *  continueAfter,
MmsFileDirectoryHandler  handler,
void *  handlerParameter 
)

get the file directory of the server.

This function will return the directory entries of the given server directory. For each directory entry the provided callback handler is called. If the

Parameters
selfMmsConnection instance to operate on
mmsErroruser provided variable to store error code
fileSpecificationthe file specification of the directory to browse or NULL to browse the root directory
continueAftercontinuation point or NULL for the first request. The continuation point is the first entry after the provided continuation file name.
handleruser provided callback handler
handlerParameteruser provided parameter that is passed to the handler
Returns
(more follows) true if more data is available
IsoConnectionParameters MmsConnection_getIsoConnectionParameters ( MmsConnection  self)

Get the connection parameters for an MmsConnection instance.

Parameters
selfMmsConnection instance to operate on
Returns
params the to be used by this connection
int32_t MmsConnection_getLocalDetail ( MmsConnection  self)
void MmsConnection_getServerStatus ( MmsConnection  self,
MmsError *  mmsError,
int *  vmdLogicalStatus,
int *  vmdPhysicalStatus,
bool  extendedDerivation 
)

get the VMD status of the connected server (is MMS status service)

This function will return the status of the connected server by invoking the MMS status service. The services returns the logical and physical states of the server.

Parameters
selfMmsConnection instance to operate on
mmsErroruser provided variable to store error code
vmdLogicalStatususer provided variable to store the logical state of the VMD
vmdPhysicalStatususer provided variable to store the physical state of the VMD
extendedDerivationinstructs the server to invoke self-diagnosis routines to determine server status
MmsVariableSpecification* MmsConnection_getVariableAccessAttributes ( MmsConnection  self,
MmsError *  mmsError,
const char *  domainId,
const char *  itemId 
)

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

Parameters
selfMmsConnection instance to operate on
mmsErroruser provided variable to store error code
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,
MmsError *  mmsError 
)

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
mmsErroruser provided variable to store error code
Returns
the association specific named variable list names or NULL if the request failed.
LinkedList MmsConnection_getVMDVariableNames ( MmsConnection  self,
MmsError *  mmsError 
)

Get the names of all VMD scope variables of the server.

This will result in a VMD specific GetNameList request.

Parameters
selfMmsConnection instance to operate on
mmsErroruser provided variable to store error code
Returns
the of VMD specific variable names or NULL if the request failed.
MmsServerIdentity* MmsConnection_identify ( MmsConnection  self,
MmsError *  mmsError 
)

get the identity of the connected server

This function will return the identity of the server if the server supports the MMS identify service. The server identity consists of a vendor name, model name, and a revision.

Parameters
selfMmsConnection instance to operate on
mmsErroruser provided variable to store error code
MmsValue* MmsConnection_readArrayElements ( MmsConnection  self,
MmsError *  mmsError,
const char *  domainId,
const 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
mmsErroruser provided variable to store error code
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.
MmsValue* MmsConnection_readMultipleVariables ( MmsConnection  self,
MmsError *  mmsError,
const char *  domainId,
LinkedListitems   
)

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

Parameters
selfMmsConnection instance to operate on
mmsErroruser provided variable to store error code
domainIdthe domain name of the requested variables.
items,: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,
MmsError *  mmsError,
const char *  domainId,
const char *  listName,
bool *  deletable 
)

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

Parameters
selfMmsConnection instance to operate on
mmsErroruser provided variable to store error code
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
LinkedList MmsConnection_readNamedVariableListDirectoryAssociationSpecific ( MmsConnection  self,
MmsError *  mmsError,
const char *  listName,
bool *  deletable 
)

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

Parameters
selfMmsConnection instance to operate on
mmsErroruser provided variable to store error code
listNamethe name of the named variable list
Returns
List of names of the variable list entries or NULL if the request failed
MmsValue* MmsConnection_readNamedVariableListValues ( MmsConnection  self,
MmsError *  mmsError,
const char *  domainId,
const char *  listName,
bool  specWithResult 
)

Read the values of a domain specific named variable list.

Parameters
selfMmsConnection instance to operate on
mmsErroruser provided variable to store error code
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,
MmsError *  mmsError,
const char *  listName,
bool  specWithResult 
)

Read the values of a association specific named variable list.

Parameters
selfMmsConnection instance to operate on
mmsErroruser provided variable to store error code
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,
MmsError *  mmsError,
const char *  domainId,
const char *  itemId 
)

Read a single variable from the server.

Parameters
selfMmsConnection instance to operate on
mmsErroruser provided variable to store error code
domainIdthe domain name of the variable to be read or NULL to read a VMD specific named variable
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_setConnectionLostHandler ( MmsConnection  self,
MmsConnectionLostHandler  handler,
void *  handlerParameter 
)

Install a callback function that will be called by the client stack if the MMS connection to the server is lost.

Parameters
handlerthe user provided callback function
handlerParametera parameter that will be passed to the callback function. Can be set to NULL if not required.
void MmsConnection_setConnectTimeout ( MmsConnection  self,
uint32_t  timeoutInMs 
)

Set the connect timeout in ms for this connection instance.

Parameters
selfMmsConnection instance to operate on
timeoutInMsconnect timeout in milliseconds
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 65000 (or the value specified in the stack_config.h file. This function should not be called after a successful connection attempt.

Parameters
selfMmsConnection instance to operate on
localDetailthe maximum size of the MMS PDU that will be accepted.
void MmsConnection_setRequestTimeout ( MmsConnection  self,
uint32_t  timeoutInMs 
)

Set the request timeout in ms for this connection.

Parameters
selfMmsConnection instance to operate on
timeoutInMsrequest timeout in milliseconds
void MmsConnection_writeMultipleVariables ( MmsConnection  self,
MmsError *  mmsError,
const char *  domainId,
LinkedListitems  ,
LinkedListvalues  ,
LinkedList *  accessResults 
)

Write multiple variables to the server.

This function will write multiple variables at the server.

The parameter accessResults is a pointer to a LinkedList reference. The methods will create a new LinkedList object that contains the AccessResults of the single variable write attempts. It is up to the user to free this objects properly (e.g. with LinkedList_destroyDeep(accessResults, MmsValue_delete)).

Parameters
selfMmsConnection instance to operate on
mmsErroruser provided variable to store error code
domainIdthe common domain name of all variables to be written
itemsa linked list containing the names of the variables to be written. The names are C strings.
valuesvalues of the variables to be written
(OUTPUT)the MmsValue objects of type MMS_DATA_ACCESS_ERROR representing the write success of a single variable write.
void MmsConnection_writeVariable ( MmsConnection  self,
MmsError *  mmsError,
const char *  domainId,
const char *  itemId,
MmsValue value 
)

Write a single variable to the server.

Parameters
selfMmsConnection instance to operate on
mmsErroruser provided variable to store error code
domainIdthe domain name of the variable to be written
itemIdname of the variable to be written
valuevalue of the variable to be written
void MmsServerIdentity_destroy ( MmsServerIdentity self)
MmsVariableAccessSpecification* MmsVariableAccessSpecification_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
MmsVariableAccessSpecification* MmsVariableAccessSpecification_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
void MmsVariableAccessSpecification_destroy ( MmsVariableAccessSpecification *  self)

Delete the MmsVariableAccessSpecification data structure.

Parameters
selfthe instance to delete