Data Structures
struct	MmsConnectionParameters

struct	MmsServerIdentity

struct	MmsJournalEntry

struct	MmsJournalVariable

struct	AcseAuthenticationParameter

struct	TSelector
	COTP T selector. More...

struct	SSelector

struct	IsoConnectionParameters

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

typedef struct sMmsConnection *	MmsConnection

typedef void(*	MmsRawMessageHandler) (void parameter, uint8_t message, int messageLength, bool received)
	Callback function to intercept raw MMS messages. More...

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, IsoApplicationReference appReference)
	Callback function to authenticate a client. More...

Enumerations
enum	AcseAuthenticationMechanism { ACSE_AUTH_NONE = 0, ACSE_AUTH_PASSWORD = 1, ACSE_AUTH_CERTIFICATE = 2, ACSE_AUTH_TLS = 3 }
	authentication mechanism úsed by AcseAuthenticator More...

Functions
MmsConnection	MmsConnection_create (void)
	Create a new MmsConnection instance. More...

MmsConnection	MmsConnection_createSecure (TLSConfiguration tlsConfig)
	Create a new secure (TLS enabled) MmsConnection instance. More...

void	MmsConnection_setRawMessageHandler (MmsConnection self, MmsRawMessageHandler handler, void *parameter)
	Set the callback handler to intercept the raw MMS messages of the connection. More...

void	MmsConnection_setFilestoreBasepath (MmsConnection self, const char *basepath)
	Set the virtual filestore basepath for the MMS obtain file services. 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 ISO connection parameters for an MmsConnection instance. More...

MmsConnectionParameters	MmsConnection_getMmsConnectionParameters (MmsConnection self)
	Get the MMS specific 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 or VMD scope of the server. More...

LinkedList	MmsConnection_getDomainJournals (MmsConnection self, MmsError mmsError, const char domainId)
	Get the names of all journals 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...

MmsValue *	MmsConnection_readVariable (MmsConnection self, MmsError mmsError, const char domainId, const char *itemId)
	Read a single variable from the server. More...

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. More...

MmsValue *	MmsConnection_readMultipleVariables (MmsConnection self, MmsError mmsError, const char domainId, LinkedListitems)
	Read multiple variables of a domain from the server with one request message. More...

MmsDataAccessError	MmsConnection_writeVariable (MmsConnection self, MmsError mmsError, const char domainId, const char itemId, MmsValue value)
	Write a single variable to the server. More...

MmsDataAccessError	MmsConnection_writeArrayElements (MmsConnection self, MmsError mmsError, const char domainId, const char itemId, int index, int numberOfElements, MmsValue value)
	Write a single array element or a sub array to an array type variable. More...

void	MmsConnection_writeMultipleVariables (MmsConnection self, MmsError mmsError, const char domainId, LinkedListitems, LinkedListvalues, LinkedList *accessResults)
	Write multiple variables to the server. More...

void	MmsConnection_writeNamedVariableList (MmsConnection self, MmsError mmsError, bool isAssociationSpecific, const char domainId, const char itemId, LinkedList values, LinkedList accessResults)
	Write named variable list values 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...

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. More...

MmsValue *	MmsConnection_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 VMD or domain scoped 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...

bool	MmsConnection_deleteNamedVariableList (MmsConnection self, MmsError mmsError, const char domainId, const char *listName)
	Delete a named variable list at the server. More...

bool	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)

MmsServerIdentity *	MmsConnection_identify (MmsConnection self, MmsError *mmsError)
	get the identity of the connected server More...

void	MmsServerIdentity_destroy (MmsServerIdentity *self)
	Destroy (free) an MmsServerIdentity object. More...

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...

void	MmsConnection_obtainFile (MmsConnection self, MmsError mmsError, const char sourceFile, const char *destinationFile)
	Send an obtainFile request to the server (used to initiate file download to server) 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...

void	MmsJournalEntry_destroy (MmsJournalEntry self)
	Destroy a single MmsJournalEntry instance. More...

const MmsValue *	MmsJournalEntry_getEntryID (MmsJournalEntry self)

const MmsValue *	MmsJournalEntry_getOccurenceTime (MmsJournalEntry self)

const LinkedList	MmsJournalEntry_getJournalVariables (MmsJournalEntry self)

const char *	MmsJournalVariable_getTag (MmsJournalVariable self)

const MmsValue *	MmsJournalVariable_getValue (MmsJournalVariable self)

LinkedList	MmsConnection_readJournalTimeRange (MmsConnection self, MmsError mmsError, const char domainId, const char itemId, MmsValue startingTime, MmsValue endingTime, bool moreFollows)

LinkedList	MmsConnection_readJournalStartAfter (MmsConnection self, MmsError mmsError, const char domainId, const char itemId, MmsValue timeSpecification, MmsValue entrySpecification, bool moreFollows)

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_setTlsConfiguration (IsoConnectionParameters self, TLSConfiguration tlsConfig)

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, SSelector sSelector, TSelector tSelector)
	set remote addresses for the lower layers More...

void	IsoConnectionParameters_setLocalApTitle (IsoConnectionParameters self, const char *apTitle, int aeQualifier)
	set the local AP-Title and AE-Qualifier More...

void	IsoConnectionParameters_setLocalAddresses (IsoConnectionParameters self, uint32_t pSelector, SSelector sSelector, TSelector tSelector)
	set local addresses for the lower layers More...

Detailed Description

Typedef Documentation

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

Callback function to authenticate a client.

Parameters

parameter	user provided parameter - set when user registers the authenticator
authParameter	the authentication parameters provided by the client
securityToken	pointer where to store an application specific security token - can be ignored if not used.
appReference	ISO application reference (ap-title + ae-qualifier)

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

connection	MmsConnection object of the lost connection
parameter	user 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)

typedef void(* MmsRawMessageHandler) (void *parameter, uint8_t *message, int messageLength, bool received)

Callback function to intercept raw MMS messages.

IMPORTANT: the message buffer is only valid in the context of the the callback function. If the message data is required elsewhere it has to be copied here!

Parameters

parameter	user provided parameter that is passed to the callback function
message	buffer of the message.
messageLength	length of the message in bytes
received	if true message has been received, false when message has been sent.

Enumeration Type Documentation

enum AcseAuthenticationMechanism

authentication mechanism úsed by AcseAuthenticator

Enumerator
ACSE_AUTH_NONE	Neither ACSE nor TLS authentication used
ACSE_AUTH_PASSWORD	Use ACSE password for client authentication
ACSE_AUTH_CERTIFICATE	Use ACSE certificate for client authentication
ACSE_AUTH_TLS	Use TLS certificate for client authentication

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

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

self	the IsoConnectionParameters instance

void IsoConnectionParameters_setAcseAuthenticationParameter	(	IsoConnectionParameters	self,
		AcseAuthenticationParameter	acseAuthParameter
	)

set the authentication parameter

This will set the authentication parameter and activates authentication.

Parameters

self	the IsoConnectionParameters instance
acseAuthParameter

void IsoConnectionParameters_setLocalAddresses	(	IsoConnectionParameters	self,
		uint32_t	pSelector,
		SSelector	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

self	the IsoConnectionParameters instance
pSelector	the P-Selector (presentation layer address)
sSelector	the S-Selector (session layer address)
tSelector	the T-Selector (ISO transport layer address)

void IsoConnectionParameters_setLocalApTitle	(	IsoConnectionParameters	self,
		const 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

self	the IsoConnectionParameters instance
apTitle	the AP-Title OID as string.
aeQualifier	the AP-qualifier

void IsoConnectionParameters_setRemoteAddresses	(	IsoConnectionParameters	self,
		uint32_t	pSelector,
		SSelector	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

self	the IsoConnectionParameters instance
pSelector	the P-Selector (presentation layer address)
sSelector	the S-Selector (session layer address)
tSelector	the 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

self	the IsoConnectionParameters instance
apTitle	the AP-Title OID as string.
aeQualifier	the 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

self	the IsoConnectionParameters instance
hostname	the hostname of IP address if the server
tcpPort	the TCP port number of the server

void IsoConnectionParameters_setTlsConfiguration	(	IsoConnectionParameters	self,
		TLSConfiguration	tlsConfig
	)

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. 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. In case the server doesn't close the connection after the internal timeout interval the client will close the TCP connection and set mmsError to MMS_ERROR_SERVICE_TIMEOUT.

Parameters

self	MmsConnection instance to operate on
mmsError	user 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

self	MmsConnection 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

self	MmsConnection instance to operate on
mmsError	user 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

self	MmsConnection instance to operate on
mmsError	user provided variable to store error code
serverName	hostname or IP address of the server to connect
serverPort	TCP port number of the server to connect or -1 to use default port (102 for MMS or 3872 for MMS over TLS)

Returns: true on success. false if the connection attempt failed.

MmsConnection MmsConnection_create ( void )

Create a new MmsConnection instance.

Returns: the newly created instance.

MmsConnection MmsConnection_createSecure ( TLSConfiguration tlsConfig )

Create a new secure (TLS enabled) MmsConnection instance.

Parameters

tlsConfig TLS configuration parameters and certificates

Returns: the newly created instance.

void MmsConnection_defineNamedVariableList	(	MmsConnection	self,
		MmsError *	mmsError,
		const char *	domainId,
		const char *	listName,
		LinkedList	variableSpecs
	)

Define a new VMD or domain scoped named variable list at the server.

The resulting named variable list will either be of domain scope (when the domainId argument is present) or VMD scope when the domainId argument is NULL.

Parameters

self	MmsConnection instance to operate on
mmsError	user provided variable to store error code
domainId	the domain name of the domain for the new variable list
listName	the name of the named variable list
variableSpecs	a 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

self	MmsConnection instance to operate on
mmsError	user provided variable to store error code
listName	the name of the named variable list
variableSpecs	list of variable specifications for the new variable list.The list elements have to be of type MmsVariableAccessSpecification*.

bool MmsConnection_deleteAssociationSpecificNamedVariableList	(	MmsConnection	self,
		MmsError *	mmsError,
		const char *	listName
	)

Delete an association specific named variable list at the server.

Parameters

self	MmsConnection instance to operate on
mmsError	user provided variable to store error code
listName	the name of the named variable list

Returns: true if named variable list has been deleted, false otherwise

bool MmsConnection_deleteNamedVariableList	(	MmsConnection	self,
		MmsError *	mmsError,
		const char *	domainId,
		const char *	listName
	)

Delete a named variable list at the server.

The resulting named variable list will either be of domain scope (when the domainId argument is present) or VMD scope when the domainId argument is NULL.

Parameters

self	MmsConnection instance to operate on
mmsError	user provided variable to store error code
domainId	the domain name of the domain of the variable list
listName	the name of the named variable list

Returns: true if named variable list has been deleted, false otherwise

void MmsConnection_destroy ( MmsConnection self )

Destroy an MmsConnection instance and release all resources.

Parameters

self	MmsConnection instance to operate on

void MmsConnection_fileClose	(	MmsConnection	self,
		MmsError *	mmsError,
		int32_t	frsmId
	)

close the file with the specified frsmID

Parameters

self	MmsConnection instance to operate on
mmsError	user provided variable to store error code
frsmId	id of the file to close

void MmsConnection_fileDelete	(	MmsConnection	self,
		MmsError *	mmsError,
		const char *	fileName
	)

delete the file with the specified name

Parameters

self	MmsConnection instance to operate on
mmsError	user provided variable to store error code
fileName	name 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

Parameters

self	MmsConnection instance to operate on
mmsError	user provided variable to store error code

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

self	MmsConnection instance to operate on
mmsError	user provided variable to store error code
frsmId	the FRSM ID (file read state machine) handle of the file
handler	callback that is invoked to deliver the received data
handlerParameter	user 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

self	MmsConnection instance to operate on
mmsError	user provided variable to store error code
currentFileName	name of the file to rename
newFileName	new name of the file

LinkedList MmsConnection_getDomainJournals	(	MmsConnection	self,
		MmsError *	mmsError,
		const char *	domainId
	)

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

This will result in a domain specific GetNameList request.

Parameters

self	MmsConnection instance to operate on
mmsError	user provided variable to store error code
domainId	the domain name for the domain specific request

Returns: the domain specific journal names or NULL if the request failed.

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

self	MmsConnection instance to operate on
mmsError	user 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 or VMD scope of the server.

This will result in a domain specific GetNameList request.

Parameters

self	MmsConnection instance to operate on
mmsError	user provided variable to store error code
domainId	the domain name for the domain specific request or NULL for a VMD scope 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

self	MmsConnection instance to operate on
mmsError	user provided variable to store error code
domainId	the 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

self	MmsConnection instance to operate on
mmsError	user provided variable to store error code
fileSpecification	the file specification of the directory to browse or NULL to browse the root directory
continueAfter	continuation point or NULL for the first request. The continuation point is the first entry after the provided continuation file name.
handler	user provided callback handler
handlerParameter	user provided parameter that is passed to the handler

Returns: (more follows) true if more data is available

IsoConnectionParameters MmsConnection_getIsoConnectionParameters ( MmsConnection self )

Get the ISO connection parameters for an MmsConnection instance.

Parameters

self	MmsConnection instance to operate on

Returns: params the to be used by this connection

int32_t MmsConnection_getLocalDetail ( MmsConnection self )

MmsConnectionParameters MmsConnection_getMmsConnectionParameters ( MmsConnection self )

Get the MMS specific connection parameters for an MmsConnection instance.

Parameters

self	MmsConnection instance to operate on

Returns: params the to be used by this connection

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

self	MmsConnection instance to operate on
mmsError	user provided variable to store error code
vmdLogicalStatus	user provided variable to store the logical state of the VMD
vmdPhysicalStatus	user provided variable to store the physical state of the VMD
extendedDerivation	instructs 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

self	MmsConnection instance to operate on
mmsError	user provided variable to store error code
domainId	the domain name of the variable or NULL for a VMD specific request
itemId	name 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

self	MmsConnection instance to operate on
mmsError	user 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

self	MmsConnection instance to operate on
mmsError	user 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

self	MmsConnection instance to operate on
mmsError	user provided variable to store error code

void MmsConnection_obtainFile	(	MmsConnection	self,
		MmsError *	mmsError,
		const char *	sourceFile,
		const char *	destinationFile
	)

Send an obtainFile request to the server (used to initiate file download to server)

Parameters

self	MmsConnection instance to operate on
mmsError	user provided variable to store error code
sourceFile	the name of the source file (client side name)
destinationFile	the name of the destination file (server side name)

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

self	MmsConnection instance to operate on
mmsError	user provided variable to store error code
domainId	the domain name of the variable to be read
itemId	name of the variable to be read
startIndex	index of element to read or start index if a element range is to be read
numberOfElements	Number 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_readJournalStartAfter	(	MmsConnection	self,
		MmsError *	mmsError,
		const char *	domainId,
		const char *	itemId,
		MmsValue *	timeSpecification,
		MmsValue *	entrySpecification,
		bool *	moreFollows
	)

LinkedList MmsConnection_readJournalTimeRange	(	MmsConnection	self,
		MmsError *	mmsError,
		const char *	domainId,
		const char *	itemId,
		MmsValue *	startingTime,
		MmsValue *	endingTime,
		bool *	moreFollows
	)

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

self	MmsConnection instance to operate on
mmsError	user provided variable to store error code
domainId	the 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.

The resulting named variable list will either be of domain scope (when the domainId argument is present) or VMD scope when the domainId argument is NULL.

Parameters

self	MmsConnection instance to operate on
mmsError	user provided variable to store error code
domainId	the domain name of the domain of the variable list
listName	the name of the named variable list
deletable	THIS 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

self	MmsConnection instance to operate on
mmsError	user provided variable to store error code
listName	the 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.

The resulting named variable list will either be of domain scope (when the domainId argument is present) or VMD scope when the domainId argument is NULL.

Parameters

self	MmsConnection instance to operate on
mmsError	user provided variable to store error code
domainId	the domain name of the requested variables.
listName	the name of the named variable list
specWithResult	if 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

self	MmsConnection instance to operate on
mmsError	user provided variable to store error code
listName	the name of the named variable list
specWithResult	if 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

self	MmsConnection instance to operate on
mmsError	user provided variable to store error code
domainId	the domain name of the variable to be read or NULL to read a VMD specific named variable
itemId	name 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. It is also possible that the return value is NULL even if mmsError = MMS_ERROR_NON. This is the case when the servers returns an empty result list.

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

handler	the user provided callback function
handlerParameter	a 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

self	MmsConnection instance to operate on
timeoutInMs	connect timeout in milliseconds

void MmsConnection_setFilestoreBasepath	(	MmsConnection	self,
		const char *	basepath
	)

Set the virtual filestore basepath for the MMS obtain 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.

Parameters

self	the MmsServer instance
basepath	the new virtual filestore basepath

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

self	MmsConnection instance to operate on
handler	the handler function to install for this client connection
parameter	a 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

self	MmsConnection instance to operate on
params	the 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

self	MmsConnection instance to operate on
localDetail	the maximum size of the MMS PDU that will be accepted.

void MmsConnection_setRawMessageHandler	(	MmsConnection	self,
		MmsRawMessageHandler	handler,
		void *	parameter
	)

Set the callback handler to intercept the raw MMS messages of the connection.

This function can be used to log raw MMS messages. It may be useful for debugging purposes or advanced test tools. This function will only work when the flag CONFIG_MMS_RAW_MESSAGE_LOGGING it set in stack_config.h

Parameters

self	MmsConnection instance to operate on
handler	the connection specific callback function
a	user provided parameter passed to the callback function (use NULL if not required).

void MmsConnection_setRequestTimeout	(	MmsConnection	self,
		uint32_t	timeoutInMs
	)

Set the request timeout in ms for this connection.

Parameters

self	MmsConnection instance to operate on
timeoutInMs	request timeout in milliseconds

MmsDataAccessError MmsConnection_writeArrayElements	(	MmsConnection	self,
		MmsError *	mmsError,
		const char *	domainId,
		const char *	itemId,
		int	index,
		int	numberOfElements,
		MmsValue *	value
	)

Write a single array element or a sub array to an array type variable.

When a single array element is address the MmsValue object value has to be of the type of the array elements. When multiple array elements have to be written (index range) the MmsValue object value has to be of type MMS_ARRAY containing "numberOfElements" elements.

Parameters

self	MmsConnection instance to operate on
mmsError	user provided variable to store error code
domainId	the domain name of the variable to be written
index	the index of the array element or the start index of a index range
numberOfElements	the number of array elements to write starting with index. If 0 only one array element is written.
itemId	name of the variable to be written
value	value of the array element(s) to be written. Has to be of the type of the array elements or of type MMS_ARRAY when it is a sub array (index range)

Returns: when successful, the data access error value returned by the server

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 to 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

self	MmsConnection instance to operate on
mmsError	user provided variable to store error code
domainId	the common domain name of all variables to be written
items	a linked list containing the names of the variables to be written. The names are C strings.
values	values 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_writeNamedVariableList	(	MmsConnection	self,
		MmsError *	mmsError,
		bool	isAssociationSpecific,
		const char *	domainId,
		const char *	itemId,
		LinkedList	values,
		LinkedList *	accessResults
	)

Write named variable list values to 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 in the responsibility of the user to free this objects properly (e.g. with LinkedList_destroyDeep(accessResults, MmsValue_delete)). If accessResult is the to NULL the result will not be stored.

Parameters

self	MmsConnection instance to operate on
mmsError	user provided variable to store error code
isAssociationSpecifc	true if the named variable list is an association specific named variable list
domainId	the common domain name of all variables to be written
values	values 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.

MmsDataAccessError MmsConnection_writeVariable	(	MmsConnection	self,
		MmsError *	mmsError,
		const char *	domainId,
		const char *	itemId,
		MmsValue *	value
	)

Write a single variable to the server.

NOTE: added return value in version 1.1

Parameters

self	MmsConnection instance to operate on
mmsError	user provided variable to store error code
domainId	the domain name of the variable to be written
itemId	name of the variable to be written
value	value of the variable to be written

Returns: when successful, the data access error value returned by the server

void MmsJournalEntry_destroy ( MmsJournalEntry self )

Destroy a single MmsJournalEntry instance.

This function will destroy the whole MmsJournalEntry object including the attached list of MmsJournalVariable objects. It is intended to be used in conjunction with the LinkedList_destroyDeep function in order to free the result of MmsConnection_readJournalTimeRange or MmsConnection_readJournalStartAfter

LinkedList_destroyDeep(journalEntries, (LinkedListValueDeleteFunction) MmsJournalEntry_destroy);

Parameters

self	the MmsJournalEntry instance to destroy

const MmsValue* MmsJournalEntry_getEntryID ( MmsJournalEntry self )

const LinkedList MmsJournalEntry_getJournalVariables ( MmsJournalEntry self )

const MmsValue* MmsJournalEntry_getOccurenceTime ( MmsJournalEntry self )

const char* MmsJournalVariable_getTag ( MmsJournalVariable self )

const MmsValue* MmsJournalVariable_getValue ( MmsJournalVariable self )

void MmsServerIdentity_destroy ( MmsServerIdentity * self )

Destroy (free) an MmsServerIdentity object.

Parameters

self	the object to destroy

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

domainId	the MMS domain name of the variable
itemId	the 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

domainId	the MMS domain name of the variable
itemId	the name for the MMS variable
index	the array index to describe an array element
componentName	the 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

self	the instance to delete

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation