S2OPC OPCUA Toolkit
Loading...
Searching...
No Matches
libs2opc_client.h File Reference

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

#include <stdbool.h>
#include <stdint.h>
#include "sopc_types.h"
#include "libs2opc_client_config.h"

Go to the source code of this file.

Typedefs

typedef struct SOPC_ClientConnection SOPC_ClientConnection
 Structure representing a secure connection to a server.
 
typedef void SOPC_ClientConnectionEvent_Fct(SOPC_ClientConnection *conn, SOPC_ClientConnectionEvent event, SOPC_StatusCode status)
 Type of callback called on client connection event.
 
typedef struct SOPC_ClientHelper_Subscription SOPC_ClientHelper_Subscription
 
typedef void SOPC_ClientSubscriptionNotification_Fct(const SOPC_ClientHelper_Subscription *subscription, SOPC_StatusCode status, SOPC_EncodeableType *notificationType, uint32_t nbNotifElts, const void *notification, uintptr_t *monitoredItemCtxArray)
 Type of callback called on Subscription Notification.
 

Enumerations

enum  SOPC_ClientConnectionEvent { SOPC_ClientConnectionEvent_Disconnected , SOPC_ClientConnectionEvent_Connected , SOPC_ClientConnectionEvent_Reconnecting }
 

Functions

SOPC_ReturnStatus SOPC_ClientHelper_DiscoveryServiceAsync (SOPC_SecureConnection_Config *secConnConfig, void *request, uintptr_t userContext)
 Sends a discovery request without user session creation and activation and retrieve response asynchronously. Service response callback configured through SOPC_ClientConfigHelper_SetServiceAsyncResponse will be called on service response or in case of service request sending failure.
 
SOPC_ReturnStatus SOPC_ClientHelper_DiscoveryServiceSync (SOPC_SecureConnection_Config *secConnConfig, void *request, void **response)
 Sends a discovery request without user session creation and activation and retrieve response synchronously.
 
SOPC_ReturnStatus SOPC_ClientHelper_Connect (SOPC_SecureConnection_Config *secConnConfig, SOPC_ClientConnectionEvent_Fct *connectEventCb, SOPC_ClientConnection **secureConnection)
 Establishes the connection in a blocking way (synchronously).
 
SOPC_ReturnStatus SOPC_ClientHelper_Disconnect (SOPC_ClientConnection **secureConnection)
 Disconnects the connection established with SOPC_ClientHelper_Connect in a blocking way (synchronously).
 
SOPC_ReturnStatus SOPC_ClientHelper_ServiceAsync (SOPC_ClientConnection *secureConnection, void *request, uintptr_t userContext)
 Executes an OPC UA service on server (read, write, browse, discovery service, etc.) asynchronously. Service response callback configured through SOPC_ClientConfigHelper_SetServiceAsyncResponse will be called on service response or in case of service request sending failure.
 
SOPC_ReturnStatus SOPC_ClientHelper_ServiceSync (SOPC_ClientConnection *secureConnection, void *request, void **response)
 Executes an OPC UA service on server (read, write, browse, discovery service, etc.) synchronously.
 
SOPC_ClientHelper_SubscriptionSOPC_ClientHelper_CreateSubscription (SOPC_ClientConnection *secureConnection, OpcUa_CreateSubscriptionRequest *subParams, SOPC_ClientSubscriptionNotification_Fct *subNotifCb, uintptr_t userParam)
 Creates a subscription on the server.
 
SOPC_ReturnStatus SOPC_ClientHelper_DeleteSubscription (SOPC_ClientHelper_Subscription **subscription)
 Deletes a subscription on the server.
 
SOPC_ReturnStatus SOPC_ClientHelper_Subscription_SetAvailableTokens (SOPC_ClientHelper_Subscription *subscription, uint32_t nbPublishTokens)
 Sets the number of publish tokens to be used for the subscription. This number shall be greater than 0 and indicates the number of publish request sent to the server that might be used to send back notifications.
 
SOPC_ReturnStatus SOPC_ClientHelper_Subscription_GetRevisedParameters (SOPC_ClientHelper_Subscription *subscription, double *revisedPublishingInterval, uint32_t *revisedLifetimeCount, uint32_t *revisedMaxKeepAliveCount)
 Gets the created subscription parameters values revised by the server.
 
uintptr_t SOPC_ClientHelper_Subscription_GetUserParam (const SOPC_ClientHelper_Subscription *subscription)
 Returns the user parameter defined in SOPC_ClientHelper_CreateSubscription.
 
SOPC_ClientConnectionSOPC_ClientHelper_GetSecureConnection (const SOPC_ClientHelper_Subscription *subscription)
 Gets the secure connection on which the subscription rely on.
 
SOPC_ReturnStatus SOPC_ClientHelper_GetSubscriptionId (const SOPC_ClientHelper_Subscription *subscription, uint32_t *pSubscriptionId)
 Gets the subscription Id associated to the subscription. It should only be used in the context of server method calls (ConditionRefresh, etc.) and is not referenced by the rest of this client API.
 
SOPC_ReturnStatus SOPC_ClientHelper_Subscription_CreateMonitoredItems (const SOPC_ClientHelper_Subscription *subscription, OpcUa_CreateMonitoredItemsRequest *monitoredItemsReq, const uintptr_t *monitoredItemCtxArray, OpcUa_CreateMonitoredItemsResponse *monitoredItemsResp)
 Creates new monitored items on the given subscription. A context array might be provided and context will be provided on notification for corresponding monitored item in notification callback. A pointer to empty message response might be provided to retrieve the creation result and monitored item id affected by the server (needed to modify or delete monitored items prior to subscription deletion)
 
SOPC_ReturnStatus SOPC_ClientHelper_Subscription_DeleteMonitoredItems (const SOPC_ClientHelper_Subscription *subscription, OpcUa_DeleteMonitoredItemsRequest *delMonitoredItemsReq, OpcUa_DeleteMonitoredItemsResponse *delMonitoredItemsResp)
 Deletes monitored items on the given subscription using the server monitored item ids. A pointer to empty message response might be provided to retrieve the deletion result.
 
SOPC_ReturnStatus SOPC_ClientHelper_Subscription_SyncService (const SOPC_ClientHelper_Subscription *subscription, void *subOrMIrequest, void **subOrMIresponse)
 Executes an OPC UA service on server related to the given subscription synchronously.
 
SOPC_ReturnStatus SOPC_ClientHelper_Subscription_AsyncService (const SOPC_ClientHelper_Subscription *subscription, void *subOrMIrequest, uintptr_t userContext)
 Executes an OPC UA service on server related to the given subscription asynchronously. Service response callback configured through SOPC_ClientConfigHelper_SetServiceAsyncResponse will be called on service response or in case of service request sending failure.
 

Detailed Description

High level interface to run an OPC UA client.

Once the client is configured using functions of libs2opc_client_config.h, the client should establish connection using SOPC_ClientHelper_Connect or call a discovery service using SOPC_ClientHelper_DiscoveryServiceAsync (or SOPC_ClientHelper_DiscoveryServiceSync). Until connection is stopped by a call to SOPC_ClientHelper_Disconnect or due to an error (socket closed, etc.), the client application might use the connections. This is done using OPC UA services using SOPC_ClientHelper_ServiceAsync (or SOPC_ClientHelper_ServiceSync). The request messages can be built using the helper functions of libs2opc_request_builder.h (e.g.: SOPC_ReadRequest_Create, SOPC_ReadRequest_SetReadValue, etc.).

Dedicated functions are provided to handle subscriptions: SOPC_ClientHelper_CreateSubscription (SOPC_ClientHelper_DeleteSubscription) to create (delete) a unique subscription instance for the connection. SOPC_ClientHelper_Subscription_CreateMonitoredItems (SOPC_ClientHelper_Subscription_DeleteMonitoredItems) to create (delete) monitored items in a subscription instance. SOPC_ClientHelper_Subscription_AsyncService and SOPC_ClientHelper_Subscription_SyncService to call other subscription related services on the subscription instance.

Typedef Documentation

◆ SOPC_ClientConnection

Structure representing a secure connection to a server.

◆ SOPC_ClientConnectionEvent_Fct

typedef void SOPC_ClientConnectionEvent_Fct(SOPC_ClientConnection *conn, SOPC_ClientConnectionEvent event, SOPC_StatusCode status)

Type of callback called on client connection event.

Warning
No blocking operation shall be done in callback
Parameters
connIndicates the connection concerned by the event
eventThe event that occurred on the connection
statusIndicates the return status of client connection

◆ SOPC_ClientHelper_Subscription

◆ SOPC_ClientSubscriptionNotification_Fct

typedef void SOPC_ClientSubscriptionNotification_Fct(const SOPC_ClientHelper_Subscription *subscription, SOPC_StatusCode status, SOPC_EncodeableType *notificationType, uint32_t nbNotifElts, const void *notification, uintptr_t *monitoredItemCtxArray)

Type of callback called on Subscription Notification.

Warning
No blocking operation shall be done in callback (e.g. call to SOPC_ClientHelper_Subscription_CreateMonitoredItems and SOPC_ClientHelper_Subscription_SyncService are forbidden)
Parameters
subscriptionIndicates the subscription concerned by the notification
statusOPC UA status code for the subscription, notification is only valid when SOPC_IsGoodStatus
notificationTypeType of notification received (OpcUa_DataChangeNotification_EncodeableType or OpcUa_EventNotificationList_EncodeableType) or NULL (if status is not good)
nbNotifEltsNumber of elements in notification received and in monitoredItemCtxArray
notificationNotification of the type indicated by notificationType, either pointer to a OpcUa_DataChangeNotification or OpcUa_EventNotificationList. Or NULL if status is not good. Content is freed after callback return, thus any content to record shall be copied.
monitoredItemCtxArrayArray of context for monitored items for which notification were received in notification. Notification element and monitored item context have the same index in the array.

Enumeration Type Documentation

◆ SOPC_ClientConnectionEvent

Enumerator
SOPC_ClientConnectionEvent_Disconnected 

Connection terminated unexpectedly, it will not be established again unless a new connection attempt is done. To do a new attempt the following functions shall be called:

SOPC_ClientConnectionEvent_Connected 

(NOT IMPLEMENTED YET) Connection established (SC & session), only triggered when asynchronous SOPC_ClientHelper_StartConnection is used or in case of reconnection.

SOPC_ClientConnectionEvent_Reconnecting 

(NOT IMPLEMENTED YET) Connection temporarily interrupted, attempt to re-establish connection on-going. Do not use connection until Connected event received

Function Documentation

◆ SOPC_ClientHelper_DiscoveryServiceAsync()

SOPC_ReturnStatus SOPC_ClientHelper_DiscoveryServiceAsync ( SOPC_SecureConnection_Config * secConnConfig,
void * request,
uintptr_t userContext )

Sends a discovery request without user session creation and activation and retrieve response asynchronously. Service response callback configured through SOPC_ClientConfigHelper_SetServiceAsyncResponse will be called on service response or in case of service request sending failure.

Parameters
secConnConfigThe secure connection configuration.
requestAn instance of one of the following OPC UA request:

The request messages can be built using the helper functions of libs2opc_request_builder.h (e.g.: SOPC_GetEndpointsRequest_Create, SOPC_GetEndpointsRequest_SetPreferredLocales, etc.).

Note: it shall be allocated on heap since it will be freed by S2OPC library during treatment.

Parameters
userContextUser defined context that will be provided with the corresponding response in SOPC_LocalServiceAsyncResp_Fct
Returns
SOPC_STATUS_OK in case of success, SOPC_STATUS_INVALID_PARAMETERS in case of invalid parameters, otherwise SOPC_STATUS_INVALID_STATE if the client is not running.
Note
The provided request memory is managed by the function after this call (even in case of error) and shall not be accessed nor freed after call.
Warning
If the server endpoint is not a discovery endpoint, or an activated session is expected, usual connection and generic services functions shall be used.
Caller of this API should wait at least SOPC_REQUEST_TIMEOUT_MS milliseconds after calling this function and prior to call SOPC_ClientConfigHelper_Clear. It is necessary to ensure asynchronous context is freed and no memory leak occurs.

◆ SOPC_ClientHelper_DiscoveryServiceSync()

SOPC_ReturnStatus SOPC_ClientHelper_DiscoveryServiceSync ( SOPC_SecureConnection_Config * secConnConfig,
void * request,
void ** response )

Sends a discovery request without user session creation and activation and retrieve response synchronously.

Parameters
secConnConfigThe secure connection configuration.
requestAn instance of one of the following OPC UA request:

The request messages can be built using the helper functions of libs2opc_request_builder.h (e.g.: SOPC_GetEndpointsRequest_Create, SOPC_GetEndpointsRequest_SetPreferredLocales, etc.).

Note: it shall be allocated on heap since it will be freed by S2OPC library during treatment.

Parameters
[out]responsePointer into which instance of response complying with the OPC UA request is provided: 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.
Returns
SOPC_STATUS_OK in case of success, SOPC_STATUS_TIMEOUT in case of timeout to receive response, SOPC_STATUS_INVALID_PARAMETERS in case of invalid parameters, SOPC_STATUS_INVALID_STATE if the client is not running. And dedicated status if request sending failed.
Note
The provided request memory is managed by the function after this call (even in case of error) and shall not be accessed nor freed after call.
Caller is responsible of output response memory after successful call
Warning
If the server endpoint is not a discovery endpoint, or an activated session is expected, usual connection and generic services functions shall be used.
Service synchronous call shall only be called from the application thread and shall not be called from client callbacks used for notification, asynchronous response, client event, etc. (SOPC_ServiceAsyncResp_Fct, SOPC_ClientConnectionEvent_Fct, etc.). Otherwise this will lead to a deadlock situation.

◆ SOPC_ClientHelper_Connect()

SOPC_ReturnStatus SOPC_ClientHelper_Connect ( SOPC_SecureConnection_Config * secConnConfig,
SOPC_ClientConnectionEvent_Fct * connectEventCb,
SOPC_ClientConnection ** secureConnection )

Establishes the connection in a blocking way (synchronously).

Warning
A single connection can be established for a given secure connection secConnConfig .
Parameters
secConnConfigThe secure connection configuration to establish
connectEventCbCallback called on connection event, it is only used in case of further unexpected disconnection
[out]secureConnectionPointer to the secure connection established when returned value is SOPC_STATUS_OK
Returns
SOPC_STATUS_OK in case of success, SOPC_STATUS_CLOSED in case of failure, SOPC_STATUS_INVALID_PARAMETERS in case of invalid parameters, otherwise SOPC_STATUS_INVALID_STATE if the configuration is not possible (toolkit not initialized, connection state unexpected, connection already established).

◆ SOPC_ClientHelper_Disconnect()

SOPC_ReturnStatus SOPC_ClientHelper_Disconnect ( SOPC_ClientConnection ** secureConnection)

Disconnects the connection established with SOPC_ClientHelper_Connect in a blocking way (synchronously).

Warning
This function shall not be called if pointed secureConnection is currently in use for any other operation and shall be prevented to be used for other operation. Internal references to secureConnection should have been cleared prior to this call.
If a subscription was created on this connection using SOPC_ClientHelper_CreateSubscription and was not deleted since then, it will be automatically deleted and the subscription pointer shall not be used anymore after this call.
Parameters
secureConnectionPointer to the secure connection reference to stop, set to NULL during successful call.
Returns
SOPC_STATUS_OK in case of success, SOPC_STATUS_INVALID_PARAMETERS in case of invalid parameters, otherwise SOPC_STATUS_INVALID_STATE if the connection is already disconnected

◆ SOPC_ClientHelper_ServiceAsync()

SOPC_ReturnStatus SOPC_ClientHelper_ServiceAsync ( SOPC_ClientConnection * secureConnection,
void * request,
uintptr_t userContext )

Executes an OPC UA service on server (read, write, browse, discovery service, etc.) asynchronously. Service response callback configured through SOPC_ClientConfigHelper_SetServiceAsyncResponse will be called on service response or in case of service request sending failure.

Note
SOPC_ClientHelper_Connect shall have been called and the connection shall be still active
Parameters
secureConnectionThe client connection instance to use to execute the service
requestAn instance of one of the following OPC UA request:

The request messages can be built using the helper functions of libs2opc_request_builder.h (e.g.: SOPC_ReadRequest_Create, SOPC_ReadRequest_SetReadValue, etc.).

Note: it shall be allocated on heap since it will be freed by S2OPC library during treatment.

Parameters
userContextUser defined context that will be provided with the corresponding response in SOPC_LocalServiceAsyncResp_Fct
Returns
SOPC_STATUS_OK in case of success, SOPC_STATUS_INVALID_PARAMETERS in case of invalid parameters, otherwise SOPC_STATUS_INVALID_STATE if the client is not running.
Note
The provided request memory is managed by the function after this call (even in case of error) and shall not be accessed nor freed after call.
Warning
Caller of this API should wait at least SOPC_REQUEST_TIMEOUT_MS milliseconds after calling this function and prior to call SOPC_ClientConfigHelper_Clear. It is necessary to ensure asynchronous context is freed and no memory leak occurs.

◆ SOPC_ClientHelper_ServiceSync()

SOPC_ReturnStatus SOPC_ClientHelper_ServiceSync ( SOPC_ClientConnection * secureConnection,
void * request,
void ** response )

Executes an OPC UA service on server (read, write, browse, discovery service, etc.) synchronously.

Note
SOPC_ClientHelper_Connect shall have been called and the connection shall be still active
Parameters
secureConnectionThe client connection instance to use to execute the service
requestAn instance of OPC UA request:

The request messages can be built using the helper functions of libs2opc_request_builder.h (e.g.: SOPC_ReadRequest_Create, SOPC_ReadRequest_SetReadValue, etc.).

Note: it shall be allocated on heap since it will be freed by S2OPC library during treatment.

Parameters
[out]responsePointer into which instance of response complying with the OPC UA request is provided: 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.
Returns
SOPC_STATUS_OK in case of success, SOPC_STATUS_TIMEOUT in case of timeout to receive response, SOPC_STATUS_INVALID_PARAMETERS in case of invalid parameters, SOPC_STATUS_INVALID_STATE if the client is not running. And dedicated status if request sending failed.
Note
The provided request memory is managed by the function after this call (even in case of error) and shall not be accessed nor freed after call.
Caller is responsible of output response memory after successful call. E.g. use SOPC_EncodeableObject_Delete.
Warning
service synchronous call shall only be called from the application thread and shall not be called from client callbacks used for asynchronous response, connections event, etc. (SOPC_ServiceAsyncResp_Fct, SOPC_ClientConnectionEvent_Fct, etc.). Otherwise this will lead to a deadlock situation.

◆ SOPC_ClientHelper_CreateSubscription()

SOPC_ClientHelper_Subscription * SOPC_ClientHelper_CreateSubscription ( SOPC_ClientConnection * secureConnection,
OpcUa_CreateSubscriptionRequest * subParams,
SOPC_ClientSubscriptionNotification_Fct * subNotifCb,
uintptr_t userParam )

Creates a subscription on the server.

Warning
The current implementation is limited to 1 subscription per connection
Parameters
secureConnectionThe client connection instance to use to execute the service
subParamsThe subscription creation request containing subscription parameters (created using SOPC_CreateSubscriptionRequest_CreateDefault or :: SOPC_CreateSubscriptionRequest_Create) Note: it shall be allocated on heap since it will be freed by S2OPC library during treatment.
subNotifCbThe callback to be called on subscription notification
userParamThe user parameter associated to the subscription that can be accessed using SOPC_ClientHelper_Subscription_GetUserParam
Returns
The subscription instance or NULL in case of error (invalid parameters, subscription already created, etc.)
Note
The provided subParams memory is managed by the function after this call (even in case of error) and shall not be accessed nor freed after call.

◆ SOPC_ClientHelper_DeleteSubscription()

SOPC_ReturnStatus SOPC_ClientHelper_DeleteSubscription ( SOPC_ClientHelper_Subscription ** subscription)

Deletes a subscription on the server.

Parameters
subscriptionPointer to the subscription pointer returned by SOPC_ClientHelper_CreateSubscription and to be deleted.
Returns
SOPC_STATUS_OK in case of success, SOPC_STATUS_INVALID_PARAMETERS in case of invalid parameters, SOPC_STATUS_INVALID_STATE if the client or subscription is not running.

◆ SOPC_ClientHelper_Subscription_SetAvailableTokens()

SOPC_ReturnStatus SOPC_ClientHelper_Subscription_SetAvailableTokens ( SOPC_ClientHelper_Subscription * subscription,
uint32_t nbPublishTokens )

Sets the number of publish tokens to be used for the subscription. This number shall be greater than 0 and indicates the number of publish request sent to the server that might be used to send back notifications.

Note
By default 3 publish tokens are configured.
A new publish request token is sent back to the server each time a publish response is received (i.e. token consumed)
Parameters
subscriptionThe subscription instance
nbPublishTokensThe number of publish tokens to be used by the client
Returns
SOPC_STATUS_OK in case of success, SOPC_STATUS_INVALID_PARAMETERS in case of invalid parameters, SOPC_STATUS_INVALID_STATE if the client or subscription is not running.

◆ SOPC_ClientHelper_Subscription_GetRevisedParameters()

SOPC_ReturnStatus SOPC_ClientHelper_Subscription_GetRevisedParameters ( SOPC_ClientHelper_Subscription * subscription,
double * revisedPublishingInterval,
uint32_t * revisedLifetimeCount,
uint32_t * revisedMaxKeepAliveCount )

Gets the created subscription parameters values revised by the server.

Parameters
subscriptionThe subscription instance
[out]revisedPublishingIntervalPointer for the revised publishing interval output value (optional)
[out]revisedLifetimeCountPointer for the revised lifetime count output value (optional)
[out]revisedMaxKeepAliveCountPointer for the revised max keep alive count output value (optional)
Returns
SOPC_STATUS_OK in case of success, SOPC_STATUS_INVALID_PARAMETERS in case of invalid subscription pointer, SOPC_STATUS_INVALID_STATE if the client or connection is not running.

◆ SOPC_ClientHelper_Subscription_GetUserParam()

uintptr_t SOPC_ClientHelper_Subscription_GetUserParam ( const SOPC_ClientHelper_Subscription * subscription)

Returns the user parameter defined in SOPC_ClientHelper_CreateSubscription.

Parameters
subscriptionThe subscription instance
Returns
User defined parameter provided in SOPC_ClientHelper_CreateSubscription for creation of subscription

◆ SOPC_ClientHelper_GetSecureConnection()

SOPC_ClientConnection * SOPC_ClientHelper_GetSecureConnection ( const SOPC_ClientHelper_Subscription * subscription)

Gets the secure connection on which the subscription rely on.

Parameters
subscriptionThe subscription instance
Returns
The secure connection instance

◆ SOPC_ClientHelper_GetSubscriptionId()

SOPC_ReturnStatus SOPC_ClientHelper_GetSubscriptionId ( const SOPC_ClientHelper_Subscription * subscription,
uint32_t * pSubscriptionId )

Gets the subscription Id associated to the subscription. It should only be used in the context of server method calls (ConditionRefresh, etc.) and is not referenced by the rest of this client API.

Parameters
subscriptionThe subscription instance
[out]pSubscriptionIdThe subscription Id associated to the subscription by server
Returns
SOPC_STATUS_OK in case of success, SOPC_STATUS_INVALID_PARAMETERS in case of invalid subscription pointer, SOPC_STATUS_INVALID_STATE if the client or connection is not running.

◆ SOPC_ClientHelper_Subscription_CreateMonitoredItems()

SOPC_ReturnStatus SOPC_ClientHelper_Subscription_CreateMonitoredItems ( const SOPC_ClientHelper_Subscription * subscription,
OpcUa_CreateMonitoredItemsRequest * monitoredItemsReq,
const uintptr_t * monitoredItemCtxArray,
OpcUa_CreateMonitoredItemsResponse * monitoredItemsResp )

Creates new monitored items on the given subscription. A context array might be provided and context will be provided on notification for corresponding monitored item in notification callback. A pointer to empty message response might be provided to retrieve the creation result and monitored item id affected by the server (needed to modify or delete monitored items prior to subscription deletion)

Parameters
subscriptionThe subscription instance on which monitored items shall be created
monitoredItemsReqThe create monitored items requests to use for creation parameters. SubscriptionId and ClientHandle parameters are ignored and set automatically. Simplified way to create it is to use SOPC_CreateMonitoredItemsRequest_CreateDefault or SOPC_CreateMonitoredItemsRequest_CreateDefaultFromStrings. Note: it shall be allocated on heap since it will be freed by S2OPC library during treatment.
monitoredItemCtxArray(optional) The array of context for monitored items to be created (might be freed by caller after call only content is recorded in subscription)
[out]monitoredItemsResp(optional) Pointer to the empty response that will be filled with the response received from the server and containing the status result and server monitored items ids.
Returns
SOPC_STATUS_OK in case of success, SOPC_STATUS_INVALID_PARAMETERS in case of invalid parameters, SOPC_STATUS_INVALID_STATE if the client is not running. And dedicated status if creation failed.
Note
The provided monitoredItemsReq memory is managed by the function after this call (even in case of error) and shall not be accessed nor freed after call.

◆ SOPC_ClientHelper_Subscription_DeleteMonitoredItems()

SOPC_ReturnStatus SOPC_ClientHelper_Subscription_DeleteMonitoredItems ( const SOPC_ClientHelper_Subscription * subscription,
OpcUa_DeleteMonitoredItemsRequest * delMonitoredItemsReq,
OpcUa_DeleteMonitoredItemsResponse * delMonitoredItemsResp )

Deletes monitored items on the given subscription using the server monitored item ids. A pointer to empty message response might be provided to retrieve the deletion result.

Parameters
subscriptionThe subscription instance on which monitored items shall be created
delMonitoredItemsReqThe delete monitored items requests to use for creation parameters. SubscriptionId parameter is ignored and set automatically. Note: it shall be allocated on heap since it will be freed by S2OPC library during treatment.
[out]delMonitoredItemsResp(optional) Pointer to the empty response that will be filled with the response received from the server and containing the status result.
Returns
SOPC_STATUS_OK in case of success, SOPC_STATUS_INVALID_PARAMETERS in case of invalid parameters, SOPC_STATUS_INVALID_STATE if the client is not running. And dedicated status if deletion failed.
Note
The provided delMonitoredItemsReq memory is managed by the function after this call (even in case of error) and shall not be accessed nor freed after call.

◆ SOPC_ClientHelper_Subscription_SyncService()

SOPC_ReturnStatus SOPC_ClientHelper_Subscription_SyncService ( const SOPC_ClientHelper_Subscription * subscription,
void * subOrMIrequest,
void ** subOrMIresponse )

Executes an OPC UA service on server related to the given subscription synchronously.

Note
The subscription identifier part in the request provided is automatically set by this function.
The requests to create / delete subscription or monitored items are not supported since dedicated API function shall be used.
The transfer subscription service is not supported by client.
Parameters
subscriptionThe subscription instance for which the service shall be executed
subOrMIrequestAn instance of one of the following OPC UA request:
[out]subOrMIresponsePointer into which instance of response complying with the OPC UA request is provided: 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.
Returns
SOPC_STATUS_OK in case of success, SOPC_STATUS_INVALID_PARAMETERS in case of invalid parameters, SOPC_STATUS_INVALID_STATE if the client is not running. And dedicated status if request sending failed.
Note
The provided subOrMIrequest memory is managed by the function after this call (even in case of error) and shall not be accessed nor freed after call.
caller is responsible of output response memory after successful call. E.g. use SOPC_EncodeableObject_Delete.
Warning
service synchronous call shall only be called from the application thread and shall not be called from client callbacks used for asynchronous response, connections event, etc. (SOPC_ServiceAsyncResp_Fct, SOPC_ClientConnectionEvent_Fct, etc.). Otherwise this will lead to a deadlock situation.

◆ SOPC_ClientHelper_Subscription_AsyncService()

SOPC_ReturnStatus SOPC_ClientHelper_Subscription_AsyncService ( const SOPC_ClientHelper_Subscription * subscription,
void * subOrMIrequest,
uintptr_t userContext )

Executes an OPC UA service on server related to the given subscription asynchronously. Service response callback configured through SOPC_ClientConfigHelper_SetServiceAsyncResponse will be called on service response or in case of service request sending failure.

Note
The subscription identifier part in the request provided is automatically set by this function.
The requests to create / delete subscription or monitored items are not supported since dedicated API function shall be used.
The transfer subscription service is not supported by client.
Parameters
subscriptionThe subscription instance for which the service shall be executed
subOrMIrequestAn instance of one of the following OPC UA request:
userContextUser defined context that will be provided with the corresponding response in SOPC_LocalServiceAsyncResp_Fct
Returns
SOPC_STATUS_OK in case of success, SOPC_STATUS_INVALID_PARAMETERS in case of invalid parameters, otherwise SOPC_STATUS_INVALID_STATE if the client is not running.
Note
The provided subOrMIrequest memory is managed by the function after this call (even in case of error) and shall not be accessed nor freed after call.
Warning
Caller of this API should wait at least SOPC_REQUEST_TIMEOUT_MS milliseconds after calling this function and prior to call SOPC_ClientConfigHelper_Clear. It is necessary to ensure asynchronous context is freed and no memory leak occurs.