sopc_toolkit_async_api.h File Reference

This module provides an asynchronous API to request toolkit services It is required to configure the toolkit before calling any service. More...

#include <stdbool.h>
#include <stdint.h>
#include "sopc_builtintypes.h"
#include "sopc_enums.h"
#include "sopc_toolkit_config.h"
#include "sopc_user_app_itf.h"

Go to the source code of this file.

Data Structures
struct	SOPC_EndpointConnectionCfg

Typedefs
typedef struct SOPC_EndpointConnectionCfg	SOPC_EndpointConnectionCfg

Functions
void	SOPC_ToolkitServer_AsyncOpenEndpoint (SOPC_EndpointConfigIdx endpointConfigIdx)
	Requests to open a connection listener for the given endpoint description configuration as a server.
void	SOPC_ToolkitServer_AsyncCloseEndpoint (SOPC_EndpointConfigIdx endpointConfigIdx)
	Requests to close a connection listener for the given endpoint description configuration.
void	SOPC_ToolkitServer_AsyncLocalServiceRequest (SOPC_EndpointConfigIdx endpointConfigIdx, void *requestStruct, uintptr_t requestContext)
	Requests to execute locally the given service request on server and receive response.
void	SOPC_ToolkitServer_TriggerEvent (const SOPC_NodeId *notifierNodeId, SOPC_Event *event, uint32_t optSubscriptionId, uint32_t optMonitoredItemId)
	Triggers the given event from the given node as notifier.
void	SOPC_ToolkitServer_AsyncReEvalSecureChannels (bool ownCert)
	Requests to re-evaluate the current server secure channels due to server certificate / key update (force SC re-establishment) or server PKI trust list update (client certificate re-validation necessary) When ownCert is set it concerns a certificate / key application update, otherwise it concerns a PKI trust list update.
void	SOPC_ToolkitServer_AsyncReEvalUserCertSessions (void)
	Request to re-evaluate X509IdentityToken certificates for all active sessions due to user PKI trustlist update. If user PKI trustlist changed and user certificate is not valid or trusted anymore, the associated session is closed.
SOPC_EndpointConnectionCfg	SOPC_EndpointConnectionCfg_CreateClassic (SOPC_SecureChannelConfigIdx secureChannelConfigIdx)
	Creates an endpoint connection configuration for a classic connection (initiated by client)
SOPC_EndpointConnectionCfg	SOPC_EndpointConnectionCfg_CreateReverse (SOPC_ReverseEndpointConfigIdx reverseEndpointConfigIdx, SOPC_SecureChannelConfigIdx secureChannelConfigIdx)
	Creates an endpoint connection configuration for a reverse connection (initiated by server)
SOPC_ReturnStatus	SOPC_ToolkitClient_AsyncActivateSession (SOPC_EndpointConnectionCfg endpointConnectionCfg, const char *sessionName, uintptr_t sessionContext, SOPC_ExtensionObject *userToken, void *userTokenCtx)
	Requests to activate a new session for the given endpoint connection configuration as client.
SOPC_ReturnStatus	SOPC_ToolkitClient_AsyncActivateSession_Anonymous (SOPC_EndpointConnectionCfg endpointConnectionCfg, const char *sessionName, uintptr_t sessionContext, const char *policyId)
	Requests to activate an anonymous session. See SOPC_ToolkitClient_AsyncActivateSession()
SOPC_ReturnStatus	SOPC_ToolkitClient_AsyncActivateSession_UsernamePassword (SOPC_EndpointConnectionCfg endpointConnectionCfg, const char *sessionName, uintptr_t sessionContext, const char *policyId, const char *username, const uint8_t *password, int32_t length_password)
	Requests to activate a session with a UserNameIdentityToken. See SOPC_ToolkitClient_AsyncActivateSession().
SOPC_ReturnStatus	SOPC_ToolkitClient_AsyncActivateSession_Certificate (SOPC_EndpointConnectionCfg endpointConnectionCfg, const char *sessionName, uintptr_t sessionContext, const char *policyId, const SOPC_SerializedCertificate *pCertX509, SOPC_SerializedAsymmetricKey *pKey)
	Requests to activate a session with a x509IdentityToken. See SOPC_ToolkitClient_AsyncActivateSession().
void	SOPC_ToolkitClient_AsyncSendRequestOnSession (SOPC_SessionId sessionId, void *requestStruct, uintptr_t requestContext)
	Request to send a service request on given active session.
void	SOPC_ToolkitClient_AsyncCloseSession (SOPC_SessionId sessionId)
	Requests to close the given session.
SOPC_ReturnStatus	SOPC_ToolkitClient_AsyncSendDiscoveryRequest (SOPC_EndpointConnectionCfg endpointConnectionCfg, void *discoveryReqStruct, uintptr_t requestContext)
	Requests to send a discovery service request without using session.
void	SOPC_ToolkitClient_AsyncOpenReverseEndpoint (SOPC_ReverseEndpointConfigIdx reverseEndpointConfigIdx)
	Requests to open a connection listener for the given reverse endpoint description configuration as a client.
void	SOPC_ToolkitClient_AsyncCloseReverseEndpoint (SOPC_ReverseEndpointConfigIdx reverseEndpointConfigIdx)
	Requests to close a connection listener for the given endpoint description configuration.
void	SOPC_ToolkitClient_AsyncReEvalSecureChannels (bool ownCert)
	Requests to re-evaluate the client secure channels due to client certificate / key update (force SC re-establishment) or client PKI trust list update (server certificate re-validation necessary) When ownCert is set it concerns a certificate / key application update, otherwise it concerns a PKI trust list update.

Detailed Description

This module provides an asynchronous API to request toolkit services It is required to configure the toolkit before calling any service.

Service responses are always provided asynchronously through the callback defined during toolkit configuration.

Typedef Documentation

SOPC_EndpointConnectionCfg

typedef struct SOPC_EndpointConnectionCfg SOPC_EndpointConnectionCfg

Function Documentation

SOPC_ToolkitServer_AsyncOpenEndpoint()

void SOPC_ToolkitServer_AsyncOpenEndpoint

(

SOPC_EndpointConfigIdx

endpointConfigIdx

)

Requests to open a connection listener for the given endpoint description configuration as a server.

In case of failure the SE_CLOSED_ENDPOINT event will be triggered to SOPC_ComEvent_Fct(), otherwise the listener could be considered as opened.

Parameters

endpointConfigIdx

Endpoint description configuration index provided by SOPC_ToolkitServer_AddEndpointConfig()

SOPC_ToolkitServer_AsyncCloseEndpoint()

void SOPC_ToolkitServer_AsyncCloseEndpoint

(

SOPC_EndpointConfigIdx

endpointConfigIdx

)

Requests to close a connection listener for the given endpoint description configuration.

In any case the SE_CLOSED_ENDPOINT event will be triggered to SOPC_ComEvent_Fct(), once triggered if the listener was opened it could be now considered closed.

Parameters

endpointConfigIdx

Endpoint description configuration index provided to SOPC_ToolkitServer_AsyncOpenEndpoint()

SOPC_ToolkitServer_AsyncLocalServiceRequest()

void SOPC_ToolkitServer_AsyncLocalServiceRequest	(	SOPC_EndpointConfigIdx	endpointConfigIdx,
		void *	requestStruct,
		uintptr_t	requestContext )

Requests to execute locally the given service request on server and receive response.

The SE_LOCAL_SERVICE_RESPONSE event will be triggered to SOPC_ComEvent_Fct(), once service request evaluated.

Parameters

endpointConfigIdx	Endpoint description configuration index provided to
requestStruct	OPC UA message payload structure pointer (OpcUa_<MessageStruct>*). Deallocated by the toolkit.
requestContext	A context value, it will be provided with corresponding response

Note: the provided request message structure and its content is automatically deallocated by the toolkit

SOPC_ToolkitServer_TriggerEvent()

void SOPC_ToolkitServer_TriggerEvent	(	const SOPC_NodeId *	notifierNodeId,
		SOPC_Event *	event,
		uint32_t	optSubscriptionId,
		uint32_t	optMonitoredItemId )

Triggers the given event from the given node as notifier.

Parameters

notifierNodeId	NodeId of the node notifier for the triggered event
event	The event to be triggered
optSubscriptionId	(optional) The subscriptionId for which the event is triggered or 0.
optMonitoredItemId	(optional) The monitored item Id for which the event is triggered or 0.

Note: the provided event and its content is automatically deallocated by the toolkit

SOPC_ToolkitServer_AsyncReEvalSecureChannels()

void SOPC_ToolkitServer_AsyncReEvalSecureChannels

(

bool

ownCert

)

Requests to re-evaluate the current server secure channels due to server certificate / key update (force SC re-establishment) or server PKI trust list update (client certificate re-validation necessary) When ownCert is set it concerns a certificate / key application update, otherwise it concerns a PKI trust list update.

   This shall be triggered in case of server certificate / key update ( \p ownCert = true)
   or when an server PKI trust list update occurred ( \p ownCert = false).

   If server certificate changed, the secure channels using it are closed.
   If server PKI trustlist changed and client certificate is not valid or trusted anymore, the secure channel is

closed.

Parameters

ownCert

It shall be true when server certificate / key update occurred and false when server PKI trust list occurred

SOPC_ToolkitServer_AsyncReEvalUserCertSessions()

void SOPC_ToolkitServer_AsyncReEvalUserCertSessions

(

void

)

Request to re-evaluate X509IdentityToken certificates for all active sessions due to user PKI trustlist update. If user PKI trustlist changed and user certificate is not valid or trusted anymore, the associated session is closed.

SOPC_EndpointConnectionCfg_CreateClassic()

SOPC_EndpointConnectionCfg SOPC_EndpointConnectionCfg_CreateClassic

(

SOPC_SecureChannelConfigIdx

secureChannelConfigIdx

)

Creates an endpoint connection configuration for a classic connection (initiated by client)

Parameters

secureChannelConfigIdx

Index of the Secure Channel configuration for endpoint connection returned by SOPC_ToolkitClient_AddSecureChannelConfig()

SOPC_EndpointConnectionCfg_CreateReverse()

SOPC_EndpointConnectionCfg SOPC_EndpointConnectionCfg_CreateReverse	(	SOPC_ReverseEndpointConfigIdx	reverseEndpointConfigIdx,
		SOPC_SecureChannelConfigIdx	secureChannelConfigIdx )

Creates an endpoint connection configuration for a reverse connection (initiated by server)

Parameters

reverseEndpointConfigIdx	Index of the Reverse Endpoint configuration to listen for server connection returned by SOPC_ToolkitClient_AddReverseEndpointConfig()
secureChannelConfigIdx	Index of the Secure Channel configuration for endpoint connection returned by SOPC_ToolkitClient_AddSecureChannelConfig()

SOPC_ToolkitClient_AsyncActivateSession()

SOPC_ReturnStatus SOPC_ToolkitClient_AsyncActivateSession	(	SOPC_EndpointConnectionCfg	endpointConnectionCfg,
		const char *	sessionName,
		uintptr_t	sessionContext,
		SOPC_ExtensionObject *	userToken,
		void *	userTokenCtx )

Requests to activate a new session for the given endpoint connection configuration as client.

When requesting activation of a session the following steps are automatically done:

• Establish a new secure channel for the endpoint connection configuration provided if not existing
• When secure channel established, request creation of a session
• When session is created, request activation of the session
• When session is activated, notify session is active

In case of failure SE_SESSION_ACTIVATION_FAILURE event will be triggered to SOPC_ComEvent_Fct(), otherwise SE_ACTIVATED_SESSION event will be triggered when session is activated provided the session Id for other operations on session.

See helper functions SOPC_ToolkitClient_AsyncActivateSession_Anonymous(), SOPC_ToolkitClient_AsyncActivateSession_UsernamePassword().

Parameters

endpointConnectionCfg	Endpoint connection configuration.
sessionName	(Optional) Human readable string that identifies the session (NULL terminated C string) If defined it should be unique for the client.
sessionContext	A context value, it will be provided in case of session activation or failure notification
userToken	An extension object, containing either an OpcUa_AnonymousIdentityToken, a OpcUa_UserNameIdentityToken, or a OpcUa_X509IdentityToken. This object is borrowed by the Toolkit and shall not be freed or modified by the caller.
userTokenCtx	Context for X509IdentityToken, an allocated SOPC_SerializedAsymmetricKey* is expected which will be deallocated by toolkit. NULL if userToken is not a OpcUa_X509IdentityToken extension object.

Returns

SOPC_STATUS_OK in case of success, SOPC_STATUS_INVALID_PARAMETERS or SOPC_STATUS_OUT_OF_MEMORY otherwise

SOPC_ToolkitClient_AsyncActivateSession_Anonymous()

SOPC_ReturnStatus SOPC_ToolkitClient_AsyncActivateSession_Anonymous	(	SOPC_EndpointConnectionCfg	endpointConnectionCfg,
		const char *	sessionName,
		uintptr_t	sessionContext,
		const char *	policyId )

Requests to activate an anonymous session. See SOPC_ToolkitClient_AsyncActivateSession()

Parameters

endpointConnectionCfg	Endpoint connection configuration.
sessionName	(Optional) Human readable string that identifies the session (NULL terminated C string) If defined it should be unique for the client.
sessionContext	A context value, it will be provided in case of session activation or failure notification
policyId	The policy id to use for the identity token.

Returns

SOPC_STATUS_OK when SOPC_ToolkitClient_AsyncActivateSession() is called successfully.

SOPC_ToolkitClient_AsyncActivateSession_UsernamePassword()

SOPC_ReturnStatus SOPC_ToolkitClient_AsyncActivateSession_UsernamePassword	(	SOPC_EndpointConnectionCfg	endpointConnectionCfg,
		const char *	sessionName,
		uintptr_t	sessionContext,
		const char *	policyId,
		const char *	username,
		const uint8_t *	password,
		int32_t	length_password )

Requests to activate a session with a UserNameIdentityToken. See SOPC_ToolkitClient_AsyncActivateSession().

Note

The password will be encrypted, or not, depending on the user token security policy associated to the policyId or if it is empty depending on the SecureChannel security policy.

Warning

The UserNamePassword mode should never be used in the following cases since the password will be sent as plain text to the server:

• SecureChannel security policy is None and user token security policy is None or empty
• SecureChannel security mode is Sign only and user token security policy is None

Parameters

endpointConnectionCfg	Endpoint connection configuration.
sessionName	(Optional) Human readable string that identifies the session (NULL terminated C string) If defined it should be unique for the client.
sessionContext	A context value, it will be provided in case of session activation or failure notification
policyId	The policy id to use for the identity token, must not be NULL
username	The zero-terminated string username, may be NULL
password	The bytestring containing the password, may be NULL
length_password	The password length, ignored when password is NULL

Returns

SOPC_STATUS_OK when SOPC_ToolkitClient_AsyncActivateSession() is called successfully.

SOPC_ToolkitClient_AsyncActivateSession_Certificate()

SOPC_ReturnStatus SOPC_ToolkitClient_AsyncActivateSession_Certificate	(	SOPC_EndpointConnectionCfg	endpointConnectionCfg,
		const char *	sessionName,
		uintptr_t	sessionContext,
		const char *	policyId,
		const SOPC_SerializedCertificate *	pCertX509,
		SOPC_SerializedAsymmetricKey *	pKey )

Requests to activate a session with a x509IdentityToken. See SOPC_ToolkitClient_AsyncActivateSession().

Parameters

endpointConnectionCfg	Endpoint connection configuration.
sessionName	(Optional) Human readable string that identifies the session (NULL terminated C string) If defined it should be unique for the client.
sessionContext	A context value, it will be provided in case of session activation or failure notification
policyId	The policy id to use for the identity token, must not be NULL
pCertX509	Certificate of the X509IdentityToken.
pKey	A valid pointer to the private key of the X509IdentityToken. This object should never be freed by the caller of this function, let the toolkit do it.

Returns

SOPC_STATUS_OK when SOPC_ToolkitClient_AsyncActivateSession() is called successfully.

SOPC_ToolkitClient_AsyncSendRequestOnSession()

void SOPC_ToolkitClient_AsyncSendRequestOnSession	(	SOPC_SessionId	sessionId,
		void *	requestStruct,
		uintptr_t	requestContext )

Request to send a service request on given active session.

In case of service response received, the SE_RCV_SESSION_RESPONSE event will be triggered to SOPC_ComEvent_Fct().

Parameters

sessionId	Session Id (provided by event SE_ACTIVATED_SESSION) on which the service request shall be sent
requestStruct	OPC UA message payload structure pointer (OpcUa_<MessageStruct>*). Deallocated by toolkit.
requestContext	A context value, it will be provided with corresponding response or in case of sending error notification

Note: the provided request message structure and its content is automatically deallocated by the toolkit

SOPC_ToolkitClient_AsyncCloseSession()

void SOPC_ToolkitClient_AsyncCloseSession

(

SOPC_SessionId

sessionId

)

Requests to close the given session.

When the session is closed, the SE_CLOSED_SESSION event will be triggered to SOPC_ComEvent_Fct().

Parameters

sessionId

Session Id (provided by event SE_ACTIVATED_SESSION) on which the service request shall be sent

SOPC_ToolkitClient_AsyncSendDiscoveryRequest()

SOPC_ReturnStatus SOPC_ToolkitClient_AsyncSendDiscoveryRequest	(	SOPC_EndpointConnectionCfg	endpointConnectionCfg,
		void *	discoveryReqStruct,
		uintptr_t	requestContext )

Requests to send a discovery service request without using session.

In case of service response received, the SE_RCV_DISCOVERY_RESPONSE event will be triggered to SOPC_ComEvent_Fct().

Parameters

endpointConnectionCfg	Endpoint connection configuration.
discoveryReqStruct	OPC UA Discovery message request payload structure pointer (OpcUa_<MessageStruct>*). Deallocated by toolkit.
requestContext	A context value, it will be provided with corresponding response or in case of sending error notification

Returns

SOPC_STATUS_OK in case of success, SOPC_STATUS_INVALID_PARAMETERS or SOPC_STATUS_OUT_OF_MEMORY otherwise

Note: the provided request message structure and its content is automatically deallocated by the toolkit

SOPC_ToolkitClient_AsyncOpenReverseEndpoint()

void SOPC_ToolkitClient_AsyncOpenReverseEndpoint

(

SOPC_ReverseEndpointConfigIdx

reverseEndpointConfigIdx

)

Requests to open a connection listener for the given reverse endpoint description configuration as a client.

In case of failure the SE_CLOSED_ENDPOINT event will be triggered to SOPC_ComEvent_Fct, otherwise the listener must be considered as opened.

Parameters

reverseEndpointConfigIdx

Endpoint description configuration index provided by SOPC_ToolkitClient_AddReverseEndpointConfig()

SOPC_ToolkitClient_AsyncCloseReverseEndpoint()

void SOPC_ToolkitClient_AsyncCloseReverseEndpoint

(

SOPC_ReverseEndpointConfigIdx

reverseEndpointConfigIdx

)

Requests to close a connection listener for the given endpoint description configuration.

In any case the SE_CLOSED_ENDPOINT event will be triggered to SOPC_ComEvent_Fct, once triggered if the listener was opened it must be considered closed.

Parameters

reverseEndpointConfigIdx

Endpoint description configuration index provided to SOPC_ToolkitClient_AsyncOpenReverseEndpoint()

SOPC_ToolkitClient_AsyncReEvalSecureChannels()

void SOPC_ToolkitClient_AsyncReEvalSecureChannels

(

bool

ownCert

)

Requests to re-evaluate the client secure channels due to client certificate / key update (force SC re-establishment) or client PKI trust list update (server certificate re-validation necessary) When ownCert is set it concerns a certificate / key application update, otherwise it concerns a PKI trust list update.

   This shall be triggered in case of client certificate / key update ( \p ownCert = true)
   or when an client PKI trust list update occurred ( \p ownCert = false).

   If client certificate changed, the secure channels using it are closed.
   If client PKI trustlist changed and server certificate is not valid or trusted anymore, the secure channel is

closed.

Parameters

ownCert

It shall be true when client certificate / key update occurred and false when client PKI trust list occurred