libs2opc_client_common.h File Reference

Common internal interface for different client libraries. More...

#include <stdint.h>
#include "libs2opc_client.h"
#include "libs2opc_client_cmds.h"

Go to the source code of this file.

Typedefs
typedef void	SOPC_ClientCommon_DiscoveryCbk(const SOPC_StatusCode requestStatus, const void *response, const uintptr_t responseContext)
	Callback type for discovery events. More...

Functions
SOPC_ReturnStatus	SOPC_ClientCommon_Initialize (const SOPC_LibSub_StaticCfg *pCfg, SOPC_ClientCommon_DiscoveryCbk *const cbkGetEndpoints)
	Configure the library. This function shall be called once by the host application before any other service can be used. It shall be done after a call to SOPC_CommonHelper_Initialize. More...
void	SOPC_ClientCommon_Clear (void)
	Clears the connections and configurations. It shall be done before a call to SOPC_CommonHelper_Clear. More...
uint32_t	SOPC_ClientCommon_CreateReverseEndpoint (const char *reverseEndpointURL)
	Creates a new reverse endpoint to be used for reverse connection mechanism Return a reverse endpoint id or error code. All parameters are copied and can be freed by the caller. More...
SOPC_ReturnStatus	SOPC_ClientCommon_ConfigureConnection (const SOPC_LibSub_ConnectionCfg *pCfg, SOPC_LibSub_ConfigurationId *pCfgId)
	Configure a future connection. The given /p pCfgId is later used to create connections. More...
SOPC_ReturnStatus	SOPC_ClientCommon_Connect (const SOPC_LibSub_ConfigurationId cfgId, SOPC_LibSub_ConnectionId *pCliId)
	Creates a new connection to a remote OPC server from configuration id cfg_id. The connection represent the whole client and is later identified by the returned cli_id. The function waits until the client is effectively connected, or the Toolkit times out. More...
SOPC_ReturnStatus	SOPC_ClientCommon_CreateSubscription (const SOPC_LibSub_ConnectionId cliId, SOPC_ClientHelper_DataChangeCbk cbkWrapper)
	Create a subscription. More...
SOPC_ReturnStatus	SOPC_ClientCommon_DeleteSubscription (const SOPC_LibSub_ConnectionId cliId)
	deletes a subscription More...
SOPC_ReturnStatus	SOPC_ClientCommon_AddToSubscription (const SOPC_LibSub_ConnectionId cliId, const SOPC_LibSub_CstString *lszNodeId, const SOPC_LibSub_AttributeId *lattrId, int32_t nElements, SOPC_LibSub_DataId *lDataId, OpcUa_CreateMonitoredItemsResponse *results)
	Add variables to the subscription of the connection. This call is synchroneous: it waits for the server response, or the Toolkit times out. The connection timeout is also used for this function. More...
SOPC_ReturnStatus	SOPC_ClientCommon_AsyncSendRequestOnSession (SOPC_LibSub_ConnectionId cliId, void *requestStruct, uintptr_t requestContext)
	Sends a generic request on the connection. The request must be accepted by the SOPC encoders (OpcUa_<MessageStruct>*) which are defined in "sopc_types.h". Upon response, the SOPC_ClientCommon_EventCbk callback configured with this connection is called with the OpcUa response. More...
SOPC_ReturnStatus	SOPC_ClientCommon_AsyncSendGetEndpointsRequest (SOPC_ClientHelper_EndpointConnection *connection, uintptr_t requestContext)
	sends a GetEndpoints request More...
SOPC_ReturnStatus	SOPC_ClientCommon_Disconnect (const SOPC_LibSub_ConnectionId cliId)
	Disconnect from a remote OPC server. The function waits until the client is effectively disconnected, or the Toolkit times out. More...
SOPC_ReturnStatus	SOPC_ClientCommon_SetLocaleIds (size_t nbLocales, const char **localeIds)
	Define client preferred locales ids from an array of locale strings. More...
SOPC_ReturnStatus	SOPC_ClientCommon_SetApplicationDescription (const char *applicationUri, const char *productUri, const char *defaultAppName, const char *defaultAppNameLocale, OpcUa_ApplicationType applicationType)
	Define client application description. More...

Detailed Description

Common internal interface for different client libraries.

Deprecated:

This file is deprecated since version 1.5.0 and will be removed in version 1.6.0. Please use libs2opc_client_new.h instead.

The functions of this interface are threadsafe, except stated otherwise.

Typedef Documentation

SOPC_ClientCommon_DiscoveryCbk

typedef void SOPC_ClientCommon_DiscoveryCbk(const SOPC_StatusCode requestStatus, const void *response, const uintptr_t responseContext)

Callback type for discovery events.

Parameters

requestStatus	status code of the request
response	discovery request response
responseContext	context of the response

Warning

ServiceFault can be retrieve instead of the expected response

Function Documentation

SOPC_ClientCommon_Initialize()

SOPC_ReturnStatus SOPC_ClientCommon_Initialize	(	const SOPC_LibSub_StaticCfg *	pCfg,
		SOPC_ClientCommon_DiscoveryCbk *const	cbkGetEndpoints
	)

Configure the library. This function shall be called once by the host application before any other service can be used. It shall be done after a call to SOPC_CommonHelper_Initialize.

Warning

This function is not threadsafe.

Parameters

pCfg	Non null pointer to the static configuration. The content of the configuration is copied and the object pointed by /p pCfg can be freed by the caller.
cbkGetEndpoints	GetEndpoints request callback, NULL if not used

Returns

The operation status

SOPC_ClientCommon_Clear()

void SOPC_ClientCommon_Clear

(

void

)

Clears the connections and configurations. It shall be done before a call to SOPC_CommonHelper_Clear.

Warning

As this function should be called only once, it is not threadsafe.

SOPC_ClientCommon_CreateReverseEndpoint()

uint32_t SOPC_ClientCommon_CreateReverseEndpoint

(

const char *

reverseEndpointURL

)

Creates a new reverse endpoint to be used for reverse connection mechanism Return a reverse endpoint id or error code. All parameters are copied and can be freed by the caller.

Parameters

reverseEndpointURL

reverse endpoint URL created by client for reverse connections

Returns

If this operation succeeded, returns a reverse endpoint configuration index

>

0. Otherwise returns 0.

SOPC_ClientCommon_ConfigureConnection()

SOPC_ReturnStatus SOPC_ClientCommon_ConfigureConnection	(	const SOPC_LibSub_ConnectionCfg *	pCfg,
		SOPC_LibSub_ConfigurationId *	pCfgId
	)

Configure a future connection. The given /p pCfgId is later used to create connections.

Parameters

	pCfg	Non null pointer to the connection configuration. The content of the configuration is copied and the object pointed by /p pCfg can be freed by the caller.
[out]	pCfgId	The configuration connection id. Set when the value returned is "SOPC_STATUS_OK".

Returns

The operation status

SOPC_ClientCommon_Connect()

SOPC_ReturnStatus SOPC_ClientCommon_Connect	(	const SOPC_LibSub_ConfigurationId	cfgId,
		SOPC_LibSub_ConnectionId *	pCliId
	)

Creates a new connection to a remote OPC server from configuration id cfg_id. The connection represent the whole client and is later identified by the returned cli_id. The function waits until the client is effectively connected, or the Toolkit times out.

Parameters

	cfgId	The parameters of the connection to create, return by SOPC_ClientCommon_ConfigureConnection().
[out]	pCliId	The connection id of the newly created client, set when returned status is SOPC_STATUS_OK

Returns

The operation status and SOPC_STATUS_TIMEOUT when connection hanged for more than connection_cfg->timeout_ms milliseconds

Warning

The disconnect callback might be called before the function returns if connection succeeds and then fails immediately (in this case *pCliId is already set)

SOPC_ClientCommon_CreateSubscription()

SOPC_ReturnStatus SOPC_ClientCommon_CreateSubscription	(	const SOPC_LibSub_ConnectionId	cliId,
		SOPC_ClientHelper_DataChangeCbk	cbkWrapper
	)

Create a subscription.

Parameters

cliId	The connection id.
cbkWrapper	The data change callback with wrapper style

Returns

The operation status.

SOPC_ClientCommon_DeleteSubscription()

SOPC_ReturnStatus SOPC_ClientCommon_DeleteSubscription

(

const SOPC_LibSub_ConnectionId

cliId

)

deletes a subscription

Delete subscription.

Parameters

cliId

The connection id.

Returns

The operation status.

SOPC_ClientCommon_AddToSubscription()

SOPC_ReturnStatus SOPC_ClientCommon_AddToSubscription	(	const SOPC_LibSub_ConnectionId	cliId,
		const SOPC_LibSub_CstString *	lszNodeId,
		const SOPC_LibSub_AttributeId *	lattrId,
		int32_t	nElements,
		SOPC_LibSub_DataId *	lDataId,
		OpcUa_CreateMonitoredItemsResponse *	results
	)

Add variables to the subscription of the connection. This call is synchroneous: it waits for the server response, or the Toolkit times out. The connection timeout is also used for this function.

Parameters

	cliId	The connection id.
	lszNodeId	An array of zero-terminated strings describing the NodeIds to add. It should be at least nElements long.
	lattrId	An array of attributes id. The subscription is created for the attribute lAttrId[i] for the node id lszNodeId[i]. It should be at least nElements long.
	nElements	The number of elements in previous arrays.
[out]	lDataId	A pre-allocated array to the output unique variable data identifiers. It should be at least nElements long. The values will be used in call to SOPC_LibSub_DataChangeCbk data_change_callback.
[out]	results	A pre-allocated response structure that contains the detailed result for each element added. It should be used to check if some elements failed to be added to the subscription in the server or to be aware of revised values provided by the server. It might be NULL if the caller does not need this information

Returns

The operation status. lDataId is only valid when the return status is SOPC_STATUS_OK. SOPC_STATUS_TIMEOUT is returned when the timeout expires before receiving a response.

SOPC_ClientCommon_AsyncSendRequestOnSession()

SOPC_ReturnStatus SOPC_ClientCommon_AsyncSendRequestOnSession	(	SOPC_LibSub_ConnectionId	cliId,
		void *	requestStruct,
		uintptr_t	requestContext
	)

Sends a generic request on the connection. The request must be accepted by the SOPC encoders (OpcUa_<MessageStruct>*) which are defined in "sopc_types.h". Upon response, the SOPC_ClientCommon_EventCbk callback configured with this connection is called with the OpcUa response.

Parameters

cliId	The connection id.
requestStruct	OPC UA message payload structure pointer (OpcUa_<MessageStruct>*). Deallocated by toolkit.
requestContext	A context value, it will be provided in the callback alongside the corresponding response.

SOPC_ClientCommon_AsyncSendGetEndpointsRequest()

SOPC_ReturnStatus SOPC_ClientCommon_AsyncSendGetEndpointsRequest	(	SOPC_ClientHelper_EndpointConnection *	connection,
		uintptr_t	requestContext
	)

sends a GetEndpoints request

Parameters

connection	endpoint connection configuration (Server URL and URI, activation of reverse connection, ...) Content is copied and can be cleared after call
requestContext	context of the request. It will be passed alongside the response.

Returns

the operation status

SOPC_ClientCommon_Disconnect()

SOPC_ReturnStatus SOPC_ClientCommon_Disconnect

(

const SOPC_LibSub_ConnectionId

cliId

)

Disconnect from a remote OPC server. The function waits until the client is effectively disconnected, or the Toolkit times out.

Parameters

cliId

The connection id to disconnect

Returns

The operation status. Erroneous case are:

• unitialized or unconfigured toolkit (SOPC_STATUS_INVALID_STATE),
• inexisting connection (SOPC_STATUS_INVALID_PARAMETERS),
• already closed connection (SOPC_STATUS_NOK).

SOPC_ClientCommon_SetLocaleIds()

SOPC_ReturnStatus SOPC_ClientCommon_SetLocaleIds	(	size_t	nbLocales,
		const char **	localeIds
	)

Define client preferred locales ids from an array of locale strings.

Parameters

nbLocales	The number of locales defined in the array. It might be 0 if no locale defined (only default exist)
localeIds	The array of locales in priority order for localized strings to be returned by server. Array and its content is copied by function.

Returns

SOPC_STATUS_OK in case of success, otherwise SOPC_STATUS_INVALID_PARAMETERS if localeIds is invalid when nbLocales > 0 or SOPC_STATUS_INVALID_STATE if the configuration is not possible.

Warning

It shall not be called once a connection is established

SOPC_ClientCommon_SetApplicationDescription()

SOPC_ReturnStatus SOPC_ClientCommon_SetApplicationDescription	(	const char *	applicationUri,
		const char *	productUri,
		const char *	defaultAppName,
		const char *	defaultAppNameLocale,
		OpcUa_ApplicationType	applicationType
	)

Define client application description.

Parameters

applicationUri	The globally unique identifier for the application instance.
productUri	The globally unique identifier for the product.
defaultAppName	The name of the application using the default locale language.
defaultAppNameLocale	The default locale if any. If defined it shall exists in preferred locales.
applicationType	The type of application, it shall be one of the OpcUa_ApplicationType_Client* types

Returns

SOPC_STATUS_OK in case of success, otherwise SOPC_STATUS_INVALID_PARAMETERS if applicationUri, productUri or defaultAppName are invalid or SOPC_STATUS_INVALID_STATE if the configuration is not possible.

Warning

It shall not be called once a connection is established