S2OPC OPCUA Toolkit
Data Structures | Typedefs | Functions
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)
 Request to open a connection listener for the given endpoint description configuration as a server. More...
 
void SOPC_ToolkitServer_AsyncCloseEndpoint (SOPC_EndpointConfigIdx endpointConfigIdx)
 Request to close a connection listener for the given endpoint description configuration. More...
 
void SOPC_ToolkitServer_AsyncLocalServiceRequest (SOPC_EndpointConfigIdx endpointConfigIdx, void *requestStruct, uintptr_t requestContext)
 Request to execute locally the given service request on server and receive response. More...
 
void SOPC_ToolkitServer_AsyncReEvalSecureChannels (bool ownCert)
 Configuration parameters for a connection to a server endpoint. The connection is either initiated by the client (classic) or by the server (reverse). More...
 
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. More...
 
SOPC_EndpointConnectionCfg SOPC_EndpointConnectionCfg_CreateClassic (SOPC_SecureChannelConfigIdx secureChannelConfigIdx)
 Create an endpoint connection configuration for a classic connection (initiated by client) More...
 
SOPC_EndpointConnectionCfg SOPC_EndpointConnectionCfg_CreateReverse (SOPC_ReverseEndpointConfigIdx reverseEndpointConfigIdx, SOPC_SecureChannelConfigIdx secureChannelConfigIdx)
 Create an endpoint connection configuration for a reverse connection (initiated by server) More...
 
SOPC_ReturnStatus SOPC_ToolkitClient_AsyncActivateSession (SOPC_EndpointConnectionCfg endpointConnectionCfg, const char *sessionName, uintptr_t sessionContext, SOPC_ExtensionObject *userToken, void *userTokenCtx)
 Request to activate a new session for the given endpoint connection configuration as client. More...
 
SOPC_ReturnStatus SOPC_ToolkitClient_AsyncActivateSession_Anonymous (SOPC_EndpointConnectionCfg endpointConnectionCfg, const char *sessionName, uintptr_t sessionContext, const char *policyId)
 Request to activate an anonymous session. See SOPC_ToolkitClient_AsyncActivateSession() More...
 
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)
 Request to activate a session with a UserNameIdentityToken. See SOPC_ToolkitClient_AsyncActivateSession(). More...
 
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)
 Request to activate a session with a x509IdentityToken. See SOPC_ToolkitClient_AsyncActivateSession(). More...
 
void SOPC_ToolkitClient_AsyncSendRequestOnSession (SOPC_SessionId sessionId, void *requestStruct, uintptr_t requestContext)
 Request to send a service request on given active session. More...
 
void SOPC_ToolkitClient_AsyncCloseSession (SOPC_SessionId sessionId)
 Request to close the given session. More...
 
SOPC_ReturnStatus SOPC_ToolkitClient_AsyncSendDiscoveryRequest (SOPC_EndpointConnectionCfg endpointConnectionCfg, void *discoveryReqStruct, uintptr_t requestContext)
 Request to send a discovery service request without using session. More...
 
void SOPC_ToolkitClient_AsyncOpenReverseEndpoint (SOPC_ReverseEndpointConfigIdx reverseEndpointConfigIdx)
 Request to open a connection listener for the given reverse endpoint description configuration as a client. More...
 
void SOPC_ToolkitClient_AsyncCloseReverseEndpoint (SOPC_ReverseEndpointConfigIdx reverseEndpointConfigIdx)
 Request to close a connection listener for the given endpoint description configuration. More...
 
void SOPC_ToolkitClient_AsyncReEvalSecureChannels (bool ownCert)
 Request 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. More...
 

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

Function Documentation

◆ SOPC_ToolkitServer_AsyncOpenEndpoint()

void SOPC_ToolkitServer_AsyncOpenEndpoint ( SOPC_EndpointConfigIdx  endpointConfigIdx)

Request 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
endpointConfigIdxEndpoint description configuration index provided by SOPC_ToolkitServer_AddEndpointConfig()

◆ SOPC_ToolkitServer_AsyncCloseEndpoint()

void SOPC_ToolkitServer_AsyncCloseEndpoint ( SOPC_EndpointConfigIdx  endpointConfigIdx)

Request 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
endpointConfigIdxEndpoint description configuration index provided to SOPC_ToolkitServer_AsyncOpenEndpoint()

◆ SOPC_ToolkitServer_AsyncLocalServiceRequest()

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

Request 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
endpointConfigIdxEndpoint description configuration index provided to
requestStructOPC UA message payload structure pointer (OpcUa_<MessageStruct>*). Deallocated by the toolkit.
requestContextA 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_AsyncReEvalSecureChannels()

void SOPC_ToolkitServer_AsyncReEvalSecureChannels ( bool  ownCert)

Configuration parameters for a connection to a server endpoint. The connection is either initiated by the client (classic) or by the server (reverse).

Note
reverseEndpointConfigIdx != 0 => reverse connection reverseEndpointConfigIdx == 0 => classic connection

Request 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
ownCertIt 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)

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

Parameters
secureChannelConfigIdxIndex 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 
)

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

Parameters
reverseEndpointConfigIdxIndex of the Reverse Endpoint configuration to listen for server connection returned by SOPC_ToolkitClient_AddReverseEndpointConfig()
secureChannelConfigIdxIndex 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 
)

Request 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
endpointConnectionCfgEndpoint connection configuration.
sessionName(Optional) Human readable string that identifies the session (NULL terminated C string) If defined it should be unique for the client.
sessionContextA context value, it will be provided in case of session activation or failure notification
userTokenAn 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.
userTokenCtxContext 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 
)

Request to activate an anonymous session. See SOPC_ToolkitClient_AsyncActivateSession()

Parameters
endpointConnectionCfgEndpoint connection configuration.
sessionName(Optional) Human readable string that identifies the session (NULL terminated C string) If defined it should be unique for the client.
sessionContextA context value, it will be provided in case of session activation or failure notification
policyIdThe 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 
)

Request 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
endpointConnectionCfgEndpoint connection configuration.
sessionName(Optional) Human readable string that identifies the session (NULL terminated C string) If defined it should be unique for the client.
sessionContextA context value, it will be provided in case of session activation or failure notification
policyIdThe policy id to use for the identity token, must not be NULL
usernameThe zero-terminated string username, may be NULL
passwordThe bytestring containing the password, may be NULL
length_passwordThe 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 
)

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

Parameters
endpointConnectionCfgEndpoint connection configuration.
sessionName(Optional) Human readable string that identifies the session (NULL terminated C string) If defined it should be unique for the client.
sessionContextA context value, it will be provided in case of session activation or failure notification
policyIdThe policy id to use for the identity token, must not be NULL
pCertX509Certificate of the X509IdentityToken.
pKeyA 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
sessionIdSession Id (provided by event SE_ACTIVATED_SESSION) on which the service request shall be sent
requestStructOPC UA message payload structure pointer (OpcUa_<MessageStruct>*). Deallocated by toolkit.
requestContextA 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)

Request to close the given session.

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

Parameters
sessionIdSession 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 
)

Request 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
endpointConnectionCfgEndpoint connection configuration.
discoveryReqStructOPC UA Discovery message request payload structure pointer (OpcUa_<MessageStruct>*). Deallocated by toolkit.
requestContextA 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)

Request 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
reverseEndpointConfigIdxEndpoint description configuration index provided by SOPC_ToolkitClient_AddReverseEndpointConfig()

◆ SOPC_ToolkitClient_AsyncCloseReverseEndpoint()

void SOPC_ToolkitClient_AsyncCloseReverseEndpoint ( SOPC_ReverseEndpointConfigIdx  reverseEndpointConfigIdx)

Request 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
reverseEndpointConfigIdxEndpoint description configuration index provided to SOPC_ToolkitClient_AsyncOpenReverseEndpoint()

◆ SOPC_ToolkitClient_AsyncReEvalSecureChannels()

void SOPC_ToolkitClient_AsyncReEvalSecureChannels ( bool  ownCert)

Request 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
ownCertIt shall be true when client certificate / key update occurred and false when client PKI trust list occurred