Data Structures
struct	LastApplError

Typedefs
typedef struct sIedConnection *	IedConnection

typedef void(*	IedConnection_GenericServiceHandler) (uint32_t invokeId, void *parameter, IedClientError err)
	Generic serivce callback handler. More...

typedef void(*	IedConnectionClosedHandler) (void *parameter, IedConnection connection)
	Callback handler that is invoked when the connection is closed. More...

typedef void(*	IedConnection_StateChangedHandler) (void *parameter, IedConnection connection, IedConnectionState newState)
	Callback handler that is invoked whenever the connection state (IedConnectionState) changes. More...

Enumerations
enum	IedConnectionState { IED_STATE_CLOSED = 0 , IED_STATE_CONNECTING , IED_STATE_CONNECTED , IED_STATE_CLOSING }

enum	IedClientError { IED_ERROR_OK = 0 , IED_ERROR_NOT_CONNECTED = 1 , IED_ERROR_ALREADY_CONNECTED = 2 , IED_ERROR_CONNECTION_LOST = 3 , IED_ERROR_SERVICE_NOT_SUPPORTED = 4 , IED_ERROR_CONNECTION_REJECTED = 5 , IED_ERROR_OUTSTANDING_CALL_LIMIT_REACHED = 6 , IED_ERROR_USER_PROVIDED_INVALID_ARGUMENT = 10 , IED_ERROR_ENABLE_REPORT_FAILED_DATASET_MISMATCH = 11 , IED_ERROR_OBJECT_REFERENCE_INVALID = 12 , IED_ERROR_UNEXPECTED_VALUE_RECEIVED = 13 , IED_ERROR_TIMEOUT = 20 , IED_ERROR_ACCESS_DENIED = 21 , IED_ERROR_OBJECT_DOES_NOT_EXIST = 22 , IED_ERROR_OBJECT_EXISTS = 23 , IED_ERROR_OBJECT_ACCESS_UNSUPPORTED = 24 , IED_ERROR_TYPE_INCONSISTENT = 25 , IED_ERROR_TEMPORARILY_UNAVAILABLE = 26 , IED_ERROR_OBJECT_UNDEFINED = 27 , IED_ERROR_INVALID_ADDRESS = 28 , IED_ERROR_HARDWARE_FAULT = 29 , IED_ERROR_TYPE_UNSUPPORTED = 30 , IED_ERROR_OBJECT_ATTRIBUTE_INCONSISTENT = 31 , IED_ERROR_OBJECT_VALUE_INVALID = 32 , IED_ERROR_OBJECT_INVALIDATED = 33 , IED_ERROR_MALFORMED_MESSAGE = 34 , IED_ERROR_OBJECT_CONSTRAINT_CONFLICT = 35 , IED_ERROR_SERVICE_NOT_IMPLEMENTED = 98 , IED_ERROR_UNKNOWN = 99 }

Functions
LIB61850_API const char *	IedClientError_toString (IedClientError err)
	Convert error value to string. More...

LIB61850_API IedConnection	IedConnection_create (void)
	create a new IedConnection instance More...

LIB61850_API IedConnection	IedConnection_createEx (TLSConfiguration tlsConfig, bool useThreads)
	create a new IedConnection instance (extended version) More...

LIB61850_API IedConnection	IedConnection_createWithTlsSupport (TLSConfiguration tlsConfig)
	create a new IedConnection instance that has support for TLS More...

LIB61850_API void	IedConnection_destroy (IedConnection self)
	destroy an IedConnection instance. More...

LIB61850_API void	IedConnection_setLocalAddress (IedConnection self, const char *localIpAddress, int localPort)
	Set the local IP address and port to be used by the client. More...

LIB61850_API void	IedConnection_setConnectTimeout (IedConnection self, uint32_t timeoutInMs)
	set the connect timeout in ms More...

LIB61850_API void	IedConnection_setMaxOutstandingCalls (IedConnection self, int calling, int called)
	Set the maximum number outstanding calls allowed for this connection. More...

LIB61850_API void	IedConnection_setRequestTimeout (IedConnection self, uint32_t timeoutInMs)
	set the request timeout in ms More...

LIB61850_API uint32_t	IedConnection_getRequestTimeout (IedConnection self)
	get the request timeout in ms for this connection More...

LIB61850_API void	IedConnection_setTimeQuality (IedConnection self, bool leapSecondKnown, bool clockFailure, bool clockNotSynchronized, int subsecondPrecision)
	Set the time quality for all timestamps generated by this IedConnection instance. More...

LIB61850_API bool	IedConnection_tick (IedConnection self)
	Perform MMS message handling and house-keeping tasks (for non-thread mode only) More...

LIB61850_API void	IedConnection_connect (IedConnection self, IedClientError error, const char hostname, int tcpPort)
	Connect to a server. More...

LIB61850_API void	IedConnection_connectAsync (IedConnection self, IedClientError error, const char hostname, int tcpPort)
	Asynchronously connect to a server. More...

LIB61850_API void	IedConnection_abort (IedConnection self, IedClientError *error)
	Abort the connection. More...

LIB61850_API void	IedConnection_abortAsync (IedConnection self, IedClientError *error)
	Asynchronously abort the connection. More...

LIB61850_API void	IedConnection_release (IedConnection self, IedClientError *error)
	Release the connection. More...

LIB61850_API void	IedConnection_releaseAsync (IedConnection self, IedClientError *error)
	Asynchronously release the connection. More...

LIB61850_API void	IedConnection_close (IedConnection self)
	Close the connection. More...

LIB61850_API IedConnectionState	IedConnection_getState (IedConnection self)
	return the state of the connection. More...

LIB61850_API LastApplError	IedConnection_getLastApplError (IedConnection self)
	Access to last application error received by the client connection. More...

LIB61850_API void	IedConnection_installConnectionClosedHandler (IedConnection self, IedConnectionClosedHandler handler, void *parameter)
	Install a handler function that is called when the connection is lost/closed. More...

LIB61850_API void	IedConnection_installStateChangedHandler (IedConnection self, IedConnection_StateChangedHandler handler, void *parameter)
	Install a handler function that is called when the connection state changes. More...

LIB61850_API MmsConnection	IedConnection_getMmsConnection (IedConnection self)
	get a handle to the underlying MmsConnection More...

Detailed Description

Typedef Documentation

◆ IedConnection

typedef struct sIedConnection* IedConnection

An opaque handle to the instance data of the IedConnection object

◆ IedConnection_GenericServiceHandler

typedef void(* IedConnection_GenericServiceHandler) (uint32_t invokeId, void *parameter, IedClientError err)

Generic serivce callback handler.

NOTE: This callback handler is used by several asynchronous service functions that require only a simple feedback in form of a success (IED_ERROR_OK) or failure (other err value).

Parameters

invokeId	the invoke ID used by the related service request
parameter	user provided parameter
err	the result code. IED_ERROR_OK indicates success.

◆ IedConnection_StateChangedHandler

typedef void(* IedConnection_StateChangedHandler) (void *parameter, IedConnection connection, IedConnectionState newState)

Callback handler that is invoked whenever the connection state (IedConnectionState) changes.

Parameters

user	provided parameter
connection	the related connection
newState	the new state of the connection

◆ IedConnectionClosedHandler

typedef void(* IedConnectionClosedHandler) (void *parameter, IedConnection connection)

Callback handler that is invoked when the connection is closed.

Deprecated:: Use IedConnection_StateChangedHandler instead

Parameters

user	provided parameter
connection	the connection object of the closed connection

Enumeration Type Documentation

◆ IedClientError

enum IedClientError

used to describe the error reason for most client side service functions

Enumerator
IED_ERROR_OK	No error occurred - service request has been successful
IED_ERROR_NOT_CONNECTED	The service request can not be executed because the client is not yet connected
IED_ERROR_ALREADY_CONNECTED	Connect service not execute because the client is already connected
IED_ERROR_CONNECTION_LOST	The service request can not be executed caused by a loss of connection
IED_ERROR_SERVICE_NOT_SUPPORTED	The service or some given parameters are not supported by the client stack or by the server
IED_ERROR_CONNECTION_REJECTED	Connection rejected by server
IED_ERROR_OUTSTANDING_CALL_LIMIT_REACHED	Cannot send request because outstanding call limit is reached
IED_ERROR_USER_PROVIDED_INVALID_ARGUMENT	API function has been called with an invalid argument
IED_ERROR_ENABLE_REPORT_FAILED_DATASET_MISMATCH
IED_ERROR_OBJECT_REFERENCE_INVALID	The object provided object reference is invalid (there is a syntactical error).
IED_ERROR_UNEXPECTED_VALUE_RECEIVED	Received object is of unexpected type
IED_ERROR_TIMEOUT	The communication to the server failed with a timeout
IED_ERROR_ACCESS_DENIED	The server rejected the access to the requested object/service due to access control
IED_ERROR_OBJECT_DOES_NOT_EXIST	The server reported that the requested object does not exist (returned by server)
IED_ERROR_OBJECT_EXISTS	The server reported that the requested object already exists
IED_ERROR_OBJECT_ACCESS_UNSUPPORTED	The server does not support the requested access method (returned by server)
IED_ERROR_TYPE_INCONSISTENT	The server expected an object of another type (returned by server)
IED_ERROR_TEMPORARILY_UNAVAILABLE	The object or service is temporarily unavailable (returned by server)
IED_ERROR_OBJECT_UNDEFINED	The specified object is not defined in the server (returned by server)
IED_ERROR_INVALID_ADDRESS	The specified address is invalid (returned by server)
IED_ERROR_HARDWARE_FAULT	Service failed due to a hardware fault (returned by server)
IED_ERROR_TYPE_UNSUPPORTED	The requested data type is not supported by the server (returned by server)
IED_ERROR_OBJECT_ATTRIBUTE_INCONSISTENT	The provided attributes are inconsistent (returned by server)
IED_ERROR_OBJECT_VALUE_INVALID	The provided object value is invalid (returned by server)
IED_ERROR_OBJECT_INVALIDATED	The object is invalidated (returned by server)
IED_ERROR_MALFORMED_MESSAGE	Received an invalid response message from the server
IED_ERROR_OBJECT_CONSTRAINT_CONFLICT	Service was not executed because required resource is still in use
IED_ERROR_SERVICE_NOT_IMPLEMENTED	Service not implemented
IED_ERROR_UNKNOWN	unknown error

◆ IedConnectionState

enum IedConnectionState

Connection state of the IedConnection instance - either closed(idle), connecting, connected, or closing)

Enumerator
IED_STATE_CLOSED
IED_STATE_CONNECTING
IED_STATE_CONNECTED
IED_STATE_CLOSING

Function Documentation

◆ IedClientError_toString()

LIB61850_API const char* IedClientError_toString ( IedClientError err )

Convert error value to string.

Returns: string constant representing the error

◆ IedConnection_abort()

LIB61850_API void IedConnection_abort	(	IedConnection	self,
		IedClientError *	error
	)

Abort the connection.

This will close the MMS association by sending an ACSE abort message to the server. After sending the abort message the connection is closed immediately. The client can assume the connection to be closed when the function returns and the destroy method can be called. If the connection is not in "connected" state an IED_ERROR_NOT_CONNECTED error will be reported.

Parameters

self	the connection object
error	the error code if an error occurs

◆ IedConnection_abortAsync()

LIB61850_API void IedConnection_abortAsync	(	IedConnection	self,
		IedClientError *	error
	)

Asynchronously abort the connection.

This will close the MMS association by sending an ACSE abort message to the server. After sending the abort message the connection is closed immediately. If the connection is not in "connected" state an IED_ERROR_NOT_CONNECTED error will be reported.

NOTE: This function works asynchronously. The IedConnection object should not be destroyed before the connection state changes to IED_STATE_CLOSED.

Parameters

self	the connection object
error	the error code if an error occurs

◆ IedConnection_close()

LIB61850_API void IedConnection_close ( IedConnection self )

Close the connection.

This will close the MMS association and the underlying TCP connection.

Parameters

self	the connection object

◆ IedConnection_connect()

LIB61850_API void IedConnection_connect	(	IedConnection	self,
		IedClientError *	error,
		const char *	hostname,
		int	tcpPort
	)

Connect to a server.

NOTE: Function will block until connection is up or timeout happened.

Parameters

self	the connection object
error	the error code if an error occurs
hostname	the host name or IP address of the server to connect to
tcpPort	the TCP port number of the server to connect to

◆ IedConnection_connectAsync()

LIB61850_API void IedConnection_connectAsync	(	IedConnection	self,
		IedClientError *	error,
		const char *	hostname,
		int	tcpPort
	)

Asynchronously connect to a server.

The function will return immediately. No error doesn't indicate that the connection is established. The current connection state has to be tracked by polling the IedConnection_getState function or by using IedConnection_StateChangedHandler

Parameters

self	the connection object
error	the error code if an error occurs
hostname	the host name or IP address of the server to connect to
tcpPort	the TCP port number of the server to connect to

◆ IedConnection_create()

LIB61850_API IedConnection IedConnection_create ( void )

create a new IedConnection instance

This function creates a new IedConnection instance that is used to handle a connection to an IED. It allocated all required resources. The new connection is in the "CLOSED" state. Before it can be used the connect method has to be called. The connection will be in non-TLS and thread mode.

Returns: the new IedConnection instance

◆ IedConnection_createEx()

LIB61850_API IedConnection IedConnection_createEx	(	TLSConfiguration	tlsConfig,
		bool	useThreads
	)

create a new IedConnection instance (extended version)

This function creates a new IedConnection instance that is used to handle a connection to an IED. It allocated all required resources. The new connection is in the "CLOSED" state. Before it can be used the IedConnection_connect or IedConnection_connectAsync method has to be called. The connection will use TLS when a TLSConfiguration object is provided. The useThread is false the IedConnection is in non-thread mode and the IedConnection_tick function has to be called periodically to receive messages and perform the house-keeping tasks.

Parameters

tlsConfig	the TLS configuration to be used, or NULL for non-TLS connection
useThreads	when true, the IedConnection is in thread mode

Returns: the new IedConnection instance

◆ IedConnection_createWithTlsSupport()

LIB61850_API IedConnection IedConnection_createWithTlsSupport ( TLSConfiguration tlsConfig )

create a new IedConnection instance that has support for TLS

This function creates a new IedConnection instance that is used to handle a connection to an IED. It allocated all required resources. The new connection is in the "CLOSED" state. Before it can be used the IedConnection_connect or IedConnection_connectAsync method has to be called. The connection will use TLS when a TLSConfiguration object is provided. The connection will be in thread mode.

Deprecated:: Use IedConnection_createEx instead

Parameters

tlsConfig the TLS configuration to be used

Returns: the new IedConnection instance

◆ IedConnection_destroy()

LIB61850_API void IedConnection_destroy ( IedConnection self )

destroy an IedConnection instance.

The connection will be closed if it is in "connected" state. All allocated resources of the connection will be freed.

Parameters

self	the connection object

◆ IedConnection_getLastApplError()

LIB61850_API LastApplError IedConnection_getLastApplError ( IedConnection self )

Access to last application error received by the client connection.

Parameters

self	the connection object

Returns: the LastApplError value

◆ IedConnection_getMmsConnection()

LIB61850_API MmsConnection IedConnection_getMmsConnection ( IedConnection self )

get a handle to the underlying MmsConnection

Get access to the underlying MmsConnection instance used by this IedConnection. This can be used to set/change specific MmsConnection parameters or to call low-level MMS services/functions.

Parameters

self	the connection object

Returns: the MmsConnection instance used by this IedConnection.

◆ IedConnection_getRequestTimeout()

LIB61850_API uint32_t IedConnection_getRequestTimeout ( IedConnection self )

get the request timeout in ms for this connection

Parameters

self	the connection object

Returns: request timeout in milliseconds

◆ IedConnection_getState()

LIB61850_API IedConnectionState IedConnection_getState ( IedConnection self )

return the state of the connection.

This function can be used to determine if the connection is established or closed.

Parameters

self	the connection object

Returns: the connection state

◆ IedConnection_installConnectionClosedHandler()

LIB61850_API void IedConnection_installConnectionClosedHandler	(	IedConnection	self,
		IedConnectionClosedHandler	handler,
		void *	parameter
	)

Install a handler function that is called when the connection is lost/closed.

Deprecated:: Use IedConnection_StateChangedHandler instead

Parameters

self	the connection object
handler	that callback function
parameter	the user provided parameter that is handed over to the callback function

◆ IedConnection_installStateChangedHandler()

LIB61850_API void IedConnection_installStateChangedHandler	(	IedConnection	self,
		IedConnection_StateChangedHandler	handler,
		void *	parameter
	)

Install a handler function that is called when the connection state changes.

Parameters

self	the connection object
handler	that callback function
parameter	the user provided parameter that is handed over to the callback function

◆ IedConnection_release()

LIB61850_API void IedConnection_release	(	IedConnection	self,
		IedClientError *	error
	)

Release the connection.

This will release the MMS association by sending an MMS conclude message to the server. The client can NOT assume the connection to be closed when the function returns, It can also fail if the server returns with a negative response. To be sure that the connection will be close the close or abort methods should be used. If the connection is not in "connected" state an IED_ERROR_NOT_CONNECTED error will be reported.

Parameters

self	the connection object
error	the error code if an error occurs

◆ IedConnection_releaseAsync()

LIB61850_API void IedConnection_releaseAsync	(	IedConnection	self,
		IedClientError *	error
	)

Asynchronously release the connection.

This will release the MMS association by sending an MMS conclude message to the server. The client can NOT assume the connection to be closed when the function returns, It can also fail if the server returns with a negative response. To be sure that the connection will be close the close or abort methods should be used. If the connection is not in "connected" state an IED_ERROR_NOT_CONNECTED error will be reported.

Parameters

self	the connection object
error	the error code if an error occurs

◆ IedConnection_setConnectTimeout()

LIB61850_API void IedConnection_setConnectTimeout	(	IedConnection	self,
		uint32_t	timeoutInMs
	)

set the connect timeout in ms

Set the connect timeout for this connection. This function has to be called before IedConnection_connect is called.

Parameters

self	the connection object
timoutInMs	the connection timeout in ms

◆ IedConnection_setLocalAddress()

LIB61850_API void IedConnection_setLocalAddress	(	IedConnection	self,
		const char *	localIpAddress,
		int	localPort
	)

Set the local IP address and port to be used by the client.

NOTE: This function is optional. When not used the OS decides what IP address and TCP port to use.

Parameters

self	IedConnection instance
localIpAddress	the local IP address or hostname as C string
localPort	the local TCP port to use. When < 1 the OS will chose the TCP port to use.

◆ IedConnection_setMaxOutstandingCalls()

LIB61850_API void IedConnection_setMaxOutstandingCalls	(	IedConnection	self,
		int	calling,
		int	called
	)

Set the maximum number outstanding calls allowed for this connection.

Parameters

self	the connection object
calling	the maximum outstanding calls allowed by the caller (client)
called	the maximum outstanding calls allowed by the called endpoint (server)

◆ IedConnection_setRequestTimeout()

LIB61850_API void IedConnection_setRequestTimeout	(	IedConnection	self,
		uint32_t	timeoutInMs
	)

set the request timeout in ms

Set the request timeout for this connection. You can call this function any time to adjust timeout behavior.

Parameters

self	the connection object
timoutInMs	the connection timeout in ms

◆ IedConnection_setTimeQuality()

LIB61850_API void IedConnection_setTimeQuality	(	IedConnection	self,
		bool	leapSecondKnown,
		bool	clockFailure,
		bool	clockNotSynchronized,
		int	subsecondPrecision
	)

Set the time quality for all timestamps generated by this IedConnection instance.

Parameters

self	the connection object
leapSecondKnown	set/unset leap seconds known flag
clockFailure	set/unset clock failure flag
clockNotSynchronized	set/unset clock not synchronized flag
subsecondPrecision	set the subsecond precision (number of significant bits of the fractionOfSecond part of the time stamp)

◆ IedConnection_tick()

LIB61850_API bool IedConnection_tick ( IedConnection self )

Perform MMS message handling and house-keeping tasks (for non-thread mode only)

This function has to be called periodically by the user application in non-thread mode. The return value helps to decide when the stack has nothing to do and other tasks can be executed.

NOTE: When using non-thread mode you should NOT use the synchronous (blocking) API functions. The synchronous functions will block forever when IedConnection_tick is not called in a separate thread.

Returns: true when connection is currently waiting and calling thread can be suspended, false means connection is busy and the tick function should be called again as soon as possible.

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ IedConnection

◆ IedConnection_GenericServiceHandler

◆ IedConnection_StateChangedHandler

◆ IedConnectionClosedHandler

Enumeration Type Documentation

◆ IedClientError

◆ IedConnectionState

Function Documentation

◆ IedClientError_toString()

◆ IedConnection_abort()

◆ IedConnection_abortAsync()

◆ IedConnection_close()

◆ IedConnection_connect()

◆ IedConnection_connectAsync()

◆ IedConnection_create()

◆ IedConnection_createEx()

◆ IedConnection_createWithTlsSupport()

◆ IedConnection_destroy()

◆ IedConnection_getLastApplError()

◆ IedConnection_getMmsConnection()

◆ IedConnection_getRequestTimeout()

◆ IedConnection_getState()

◆ IedConnection_installConnectionClosedHandler()

◆ IedConnection_installStateChangedHandler()

◆ IedConnection_release()

◆ IedConnection_releaseAsync()

◆ IedConnection_setConnectTimeout()

◆ IedConnection_setLocalAddress()

◆ IedConnection_setMaxOutstandingCalls()

◆ IedConnection_setRequestTimeout()

◆ IedConnection_setTimeQuality()

◆ IedConnection_tick()