S2OPC OPCUA Toolkit
Typedefs | Functions
libs2opc_client_config.h File Reference

High level interface to configure an OPC UA client. More...

#include <stdbool.h>
#include "sopc_enums.h"
#include "sopc_user_app_itf.h"

Go to the source code of this file.

Typedefs

typedef struct SOPC_ConfigClientXML_Custom SOPC_ConfigClientXML_Custom
 Structure reserved for future use in order to customize the configuration through XML. e.g.: PKI provider alternative, etc. More...
 
typedef void SOPC_ServiceAsyncResp_Fct(SOPC_EncodeableType *type, const void *response, uintptr_t userContext)
 Type of callback to provide asynchronous service response. More...
 
typedef bool SOPC_GetClientUserNamePassword_Fct(const SOPC_SecureConnection_Config *secConnConfig, char **outUserName, char **outPassword)
 Type of callback to retrieve username and password for session activation. More...
 
typedef bool SOPC_GetClientUserKeyPassword_Fct(const SOPC_SecureConnection_Config *secConnConfig, const char *userCertThumb, char **outPassword)
 Type of callback to retrieve password for decryption of the user private key. More...
 
typedef bool SOPC_GetPassword_Fct(char **outPassword)
 Type of callback to retrieve password for decryption of the client application private key or the user x509 token private key. More...
 

Functions

SOPC_ReturnStatus SOPC_ClientConfigHelper_Initialize (void)
 Initialize the S2OPC client frontend configuration Call to SOPC_ClientConfigHelper_Initialize is required before any other operation and shall be done after a call to SOPC_CommonHelper_Initialize. More...
 
void SOPC_ClientConfigHelper_Clear (void)
 Clear the S2OPC client frontend configuration It shall be done before a call to SOPC_CommonHelper_Clear. More...
 
SOPC_ReturnStatus SOPC_ClientConfigHelper_ConfigureFromXML (const char *clientConfigPath, SOPC_ConfigClientXML_Custom *customConfig, size_t *nbScConfigs, SOPC_SecureConnection_Config ***scConfigArray)
 Configure client from XML configuration files for: client connections. More...
 
SOPC_SecureConnection_ConfigSOPC_ClientConfigHelper_GetConfigFromId (const char *userDefinedId)
 Returns the secure connection configuration which has the given user defined identifier. The user defined identifier is the id attribute of the connection in XML configuration. More...
 
const char * SOPC_ClientConfigHelper_GetUserIdFromConfig (const SOPC_SecureConnection_Config *secConnConfig)
 Returns the user defined identifier attached to a secure connection configuration. The user defined identifier is the id attribute of the connection in XML configuration. More...
 
SOPC_ReturnStatus SOPC_ClientConfigHelper_SetServiceAsyncResponse (SOPC_ServiceAsyncResp_Fct *asyncRespCb)
 Define the service response callback to be used. More...
 
SOPC_ReturnStatus SOPC_ClientConfigHelper_SetUserNamePasswordCallback (SOPC_GetClientUserNamePassword_Fct *getClientUsernamePassword)
 Defines the callback to retrieve the username and password to activate the client session. This is necessary if a username token type is used and shall be defined before starting client and loading its configuration. More...
 
SOPC_ReturnStatus SOPC_ClientConfigHelper_SetUserKeyPasswordCallback (SOPC_GetClientUserKeyPassword_Fct *getClientX509userKeyPassword)
 Defines the callback to retrieve password for decryption of the user X509 token private key. More...
 
SOPC_ReturnStatus SOPC_ClientConfigHelper_SetClientKeyPasswordCallback (SOPC_GetPassword_Fct *getClientKeyPassword)
 Defines the callback to retrieve password for decryption of the client private key. More...
 

Detailed Description

High level interface to configure an OPC UA client.

Typedef Documentation

◆ SOPC_ConfigClientXML_Custom

Structure reserved for future use in order to customize the configuration through XML. e.g.: PKI provider alternative, etc.

◆ SOPC_ServiceAsyncResp_Fct

typedef void SOPC_ServiceAsyncResp_Fct(SOPC_EncodeableType *type, const void *response, uintptr_t userContext)

Type of callback to provide asynchronous service response.

Parameters
responseAn asynchronous response to a local service request sent using SOPC_ClientHelperNew_ServiceAsync Response will be a pointer to the service response corresponding to sent request: In case of service failure the response type is always OpcUa_ServiceFault, in this case the response.encodeableType points to OpcUa_ServiceFault_EncodeableType and SOPC_IsGoodStatus(response.ResponseHeader.ServiceResult) is false. In case of sending failure the response is NULL and only the userContext is provided.
userContextThe context that was provided with the corresponding request provided on SOPC_ClientHelperNew_ServiceAsync call
Warning
The callback function shall not do anything blocking or long treatment since it will block any other callback call (other instance of response, data change notification, etc.).

◆ SOPC_GetClientUserNamePassword_Fct

typedef bool SOPC_GetClientUserNamePassword_Fct(const SOPC_SecureConnection_Config *secConnConfig, char **outUserName, char **outPassword)

Type of callback to retrieve username and password for session activation.

Parameters
secConnConfigthe secure connection configuration for the session to activate
[out]outUserNamethe newly allocated username which shall be used for session activation, it shall be a zero-terminated string in case of success.
[out]outPasswordthe newly allocated password which shall be a zero-terminated string in case of success.
Returns
true in case of success, otherwise false.
Warning
The implementation of the user callback must free the outUserName and outPassword and set them it back to NULL in case of failure.

◆ SOPC_GetClientUserKeyPassword_Fct

typedef bool SOPC_GetClientUserKeyPassword_Fct(const SOPC_SecureConnection_Config *secConnConfig, const char *userCertThumb, char **outPassword)

Type of callback to retrieve password for decryption of the user private key.

Parameters
secConnConfigthe secure connection configuration for the session to activate (NULL if the old client API is used, old API will be removed in version 1.6.0)
userCertThumbuser certificate thumbprint containing the public key paired with the private key to decrypt
[out]outPasswordthe newly allocated password which shall be a zero-terminated string in case of success
Returns
true in case of success, otherwise false.
Warning
The implementation of the callback must free the outPassword and set it back to NULL in case of failure.

◆ SOPC_GetPassword_Fct

typedef bool SOPC_GetPassword_Fct(char **outPassword)

Type of callback to retrieve password for decryption of the client application private key or the user x509 token private key.

Parameters
[out]outPasswordout parameter, the newly allocated password which shall be a zero-terminated string in case of success.
Returns
true in case of success, otherwise false.
Warning
The implementation of the user callback must free the outPassword and set it back to NULL in case of failure.

Function Documentation

◆ SOPC_ClientConfigHelper_Initialize()

SOPC_ReturnStatus SOPC_ClientConfigHelper_Initialize ( void  )

Initialize the S2OPC client frontend configuration Call to SOPC_ClientConfigHelper_Initialize is required before any other operation and shall be done after a call to SOPC_CommonHelper_Initialize.

The default log configuration is provided by the SOPC_Common_GetDefaultLogConfiguration function.
By default, the log configuration is :
.logLevel = SOPC_LOG_LEVEL_INFO
.logSystem = SOPC_LOG_SYSTEM_FILE
.logSysConfig = {.fileSystemLogConfig = {.logDirPath = "", .logMaxBytes = 1048576, .logMaxFiles = 50}}

Returns
SOPC_STATUS_OK in case of success, otherwise SOPC_STATUS_INVALID_STATE in case of double initialization.

◆ SOPC_ClientConfigHelper_Clear()

void SOPC_ClientConfigHelper_Clear ( void  )

Clear the S2OPC client frontend configuration It shall be done before a call to SOPC_CommonHelper_Clear.

◆ SOPC_ClientConfigHelper_ConfigureFromXML()

SOPC_ReturnStatus SOPC_ClientConfigHelper_ConfigureFromXML ( const char *  clientConfigPath,
SOPC_ConfigClientXML_Custom customConfig,
size_t *  nbScConfigs,
SOPC_SecureConnection_Config ***  scConfigArray 
)

Configure client from XML configuration files for: client connections.

If not used or used partially, see libs2opc_client_config_custom.h to manually configure through API.

Parameters
clientConfigPathPath to client configuration XML file (s2opc_clientserver_config.xsd schema)
customConfigShall be NULL. Reserved for future customization of configuration from XML (PKI provider, etc.).
[out]nbScConfigsNumber of secure connection configurations parsed in the XML configuration
[out]scConfigArrayPointer to the array of secure connection configurations of length nbScConfigs.
Returns
SOPC_STATUS_OK in case of success, SOPC_STATUS_NOK in case of parsing error, otherwise SOPC_STATUS_INVALID_PARAMETERS if a path is invalid or all paths are NULL or SOPC_STATUS_INVALID_STATE if the configuration is not possible (toolkit not initialized, server already started).

◆ SOPC_ClientConfigHelper_GetConfigFromId()

SOPC_SecureConnection_Config* SOPC_ClientConfigHelper_GetConfigFromId ( const char *  userDefinedId)

Returns the secure connection configuration which has the given user defined identifier. The user defined identifier is the id attribute of the connection in XML configuration.

Note
If several connections have the same identifier, the first match will be returned.
Parameters
userDefinedIdThe identifier searched for in secure connections configured
Returns
The (first) secure connection configuration for which configured id match userDefinedId or NULL if none is found.

◆ SOPC_ClientConfigHelper_GetUserIdFromConfig()

const char* SOPC_ClientConfigHelper_GetUserIdFromConfig ( const SOPC_SecureConnection_Config secConnConfig)

Returns the user defined identifier attached to a secure connection configuration. The user defined identifier is the id attribute of the connection in XML configuration.

Parameters
secConnConfigThe secure connection configuration
Returns
The user defined identifier of secConnConfig or NULL if it is not defined for this secure connection configuration.

◆ SOPC_ClientConfigHelper_SetServiceAsyncResponse()

SOPC_ReturnStatus SOPC_ClientConfigHelper_SetServiceAsyncResponse ( SOPC_ServiceAsyncResp_Fct asyncRespCb)

Define the service response callback to be used.

This is optional if not used or only synchronous version used. This shall be defined before starting the server and using SOPC_ClientHelperNew_ServiceAsync.

Parameters
asyncRespCbThe service asynchronous response callback to be used
Returns
SOPC_STATUS_OK in case of success, otherwise SOPC_STATUS_INVALID_PARAMETERS if asyncRespCb is invalid or SOPC_STATUS_INVALID_STATE if the configuration is not possible (toolkit not initialized, client connection initiated).
Warning
The callback function shall not do anything blocking or long treatment since it will block any other callback call (other instance of data change notification, service sync/async response, etc.).

◆ SOPC_ClientConfigHelper_SetUserNamePasswordCallback()

SOPC_ReturnStatus SOPC_ClientConfigHelper_SetUserNamePasswordCallback ( SOPC_GetClientUserNamePassword_Fct getClientUsernamePassword)

Defines the callback to retrieve the username and password to activate the client session. This is necessary if a username token type is used and shall be defined before starting client and loading its configuration.

Parameters
getClientUsernamePasswordThe callback to retrieve the password associated to the given username
Returns
SOPC_STATUS_OK in case of success, SOPC_STATUS_INVALID_STATE or SOPC_STATUS_INVALID_PARAMETERS otherwise.
Note
This function must be called before the configuration of the secure channel.

◆ SOPC_ClientConfigHelper_SetUserKeyPasswordCallback()

SOPC_ReturnStatus SOPC_ClientConfigHelper_SetUserKeyPasswordCallback ( SOPC_GetClientUserKeyPassword_Fct getClientX509userKeyPassword)

Defines the callback to retrieve password for decryption of the user X509 token private key.

This is optional but if used it shall be defined before starting client and loading its configuration.

Parameters
getClientX509userKeyPasswordThe callback to retrieve the user X509 token private key password
Returns
SOPC_STATUS_OK in case of success, SOPC_STATUS_INVALID_STATE or SOPC_STATUS_INVALID_PARAMETERS otherwise.
Note
This function must be called before the configuration of the secure channel.

◆ SOPC_ClientConfigHelper_SetClientKeyPasswordCallback()

SOPC_ReturnStatus SOPC_ClientConfigHelper_SetClientKeyPasswordCallback ( SOPC_GetPassword_Fct getClientKeyPassword)

Defines the callback to retrieve password for decryption of the client private key.

This is optional but if used it shall be defined before starting client and loading its configuration.

Parameters
getClientKeyPasswordThe callback to retrieve the password
Returns
SOPC_STATUS_OK in case of success, otherwise SOPC_STATUS_INVALID_PARAMETERS if getClientKeyPassword is invalid.
Note
This function must be called before the configuration of the secure channel.