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.
typedef void	SOPC_ServiceAsyncResp_Fct(SOPC_EncodeableType *type, const void *response, uintptr_t userContext)
	Type of callback to provide asynchronous service response.
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.
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.
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.

Functions
SOPC_ReturnStatus	SOPC_ClientConfigHelper_Initialize (void)
	Initializes 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.
void	SOPC_ClientConfigHelper_Clear (void)
	Clears the S2OPC client frontend configuration It shall be done before a call to SOPC_CommonHelper_Clear.
SOPC_ReturnStatus	SOPC_ClientConfigHelper_ConfigureFromXML (const char *clientConfigPath, SOPC_ConfigClientXML_Custom *customConfig, size_t *nbScConfigs, SOPC_SecureConnection_Config ***scConfigArray)
	Configures client from XML configuration files for: client connections.
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.
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.
SOPC_ReturnStatus	SOPC_ClientConfigHelper_SetServiceAsyncResponse (SOPC_ServiceAsyncResp_Fct *asyncRespCb)
	Defines the service response callback to be used.
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.
SOPC_ReturnStatus	SOPC_ClientConfigHelper_SetUserKeyPasswordCallback (SOPC_GetClientUserKeyPassword_Fct *getClientX509userKeyPassword)
	Defines the callback to retrieve password for decryption of the user X509 token private key.
SOPC_ReturnStatus	SOPC_ClientConfigHelper_SetClientKeyPasswordCallback (SOPC_GetPassword_Fct *getClientKeyPassword)
	Defines the callback to retrieve password for decryption of the client private key.

Detailed Description

High level interface to configure an OPC UA client.

Typedef Documentation

SOPC_ConfigClientXML_Custom

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.

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

type	The SOPC_EncodeableType of the provided response response
response	An asynchronous response to a service request sent using SOPC_ClientHelper_ServiceAsync Response will be a pointer to the service response corresponding to sent request: OpcUa_ReadResponse OpcUa_WriteResponse OpcUa_BrowseResponse OpcUa_GetEndpointsResponse OpcUa_FindServersResponse OpcUa_FindServersOnNetworkResponse OpcUa_RegisterServer2Response 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.
userContext	The context that was provided with the corresponding request provided on SOPC_ClientHelper_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

	secConnConfig	the secure connection configuration for the session to activate
[out]	outUserName	the newly allocated username which shall be used for session activation, it shall be a zero-terminated string in case of success.
[out]	outPassword	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 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

	secConnConfig	the secure connection configuration for the session to activate
	userCertThumb	user certificate thumbprint containing the public key paired with the private key to decrypt
[out]	outPassword	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 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]

outPassword

out 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

)

Initializes 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

)

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

Note

The remaining client connection are disconnected, subscriptions deleted and reverse endpoint are closed

Warning

The caller must ensure that no further call to access the existing configuration, connections and subscriptions after this call.

SOPC_ClientConfigHelper_ConfigureFromXML()

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

Configures 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

	clientConfigPath	Path to client configuration XML file (s2opc_clientserver_config.xsd schema)
	customConfig	Shall be NULL. Reserved for future customization of configuration from XML (PKI provider, etc.).
[out]	nbScConfigs	Number of secure connection configurations parsed in the XML configuration
[out]	scConfigArray	Pointer 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

userDefinedId

The 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

secConnConfig

The 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

)

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

Parameters

asyncRespCb

The 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

getClientUsernamePassword

The 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

getClientX509userKeyPassword

The 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

getClientKeyPassword

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