S2OPC OPCUA Toolkit
|
Interface of a library supporting the subscription management, read/write operation and browse. More...
#include <stdbool.h>
#include <stdint.h>
#include <stdlib.h>
#include "sopc_builtintypes.h"
#include "sopc_crypto_profiles.h"
#include "sopc_enum_types.h"
#include "sopc_log_manager.h"
#include "sopc_user_app_itf.h"
Go to the source code of this file.
Data Structures | |
struct | SOPC_ClientHelper_Security |
Connection configuration to a remote OPC server. More... | |
struct | SOPC_ClientHelper_EndpointConnection |
Connection configuration to a remote OPC server. More... | |
struct | SOPC_ClientHelper_WriteValue |
Structure defining a node and value to write. Value should be single value or one-dimensional array: value.value.ArrayType should be SingleValue or Array. More... | |
struct | SOPC_ClientHelper_ReadValue |
Structure defining a node, an attribute. More... | |
struct | SOPC_ClientHelper_BrowseRequest |
Structure defining a node, an attribute and a value. More... | |
struct | SOPC_ClientHelper_BrowseResultReference |
Structure defining a node, an attribute and a value. More... | |
struct | SOPC_ClientHelper_BrowseResult |
structure containing the result of a browse request More... | |
struct | SOPC_ClientHelper_CallMethodRequest |
structure containing the requested method to call and input parameters More... | |
struct | SOPC_ClientHelper_CallMethodResult |
structure containing the result of a method call More... | |
struct | SOPC_ClientHelper_UserIdentityToken |
structure containing a user identity token More... | |
struct | SOPC_ClientHelper_EndpointDescription |
structure containing an endpoint description More... | |
struct | SOPC_ClientHelper_GetEndpointsResult |
structure containing the result of a GetEndpoints request More... | |
Typedefs | |
typedef void | SOPC_ClientHelper_DataChangeCbk(const int32_t connectionId, const char *nodeId, const SOPC_DataValue *value) |
Callback type for data change event (related to a subscription) More... | |
typedef void | SOPC_ClientHelper_DisconnectCbk(const uint32_t connectionId) |
Callback type for disconnection. More... | |
Functions | |
void | SOPC_ClientHelper_BrowseResultReference_Move (SOPC_ClientHelper_BrowseResultReference *dest, SOPC_ClientHelper_BrowseResultReference *src) |
Move the content of the SOPC_ClientHelper_BrowseResultReference from source to destination. Note: after use of move function, clearing source has no effect on destination structure content since source does not point to allocated data anymore. More... | |
void | SOPC_ClientHelper_BrowseResultReference_Clear (SOPC_ClientHelper_BrowseResultReference *brr) |
Clears the content of the SOPC_ClientHelper_BrowseResultReference structure pointed by brr . More... | |
void | SOPC_ClientHelper_BrowseResults_Clear (size_t nbElements, SOPC_ClientHelper_BrowseResult *results) |
Clears the content of the SOPC_ClientHelper_BrowseResult[] results . The array is not deallocated since it is managed by the caller of SOPC_ClientHelper_Browse. More... | |
int32_t | SOPC_ClientHelper_Initialize (SOPC_ClientHelper_DisconnectCbk *const disconnect_callback) |
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_ClientHelper_Finalize (void) |
Clears the connections and configurations. It shall be done before a call to SOPC_CommonHelper_Clear. More... | |
int32_t | SOPC_ClientHelper_GetEndpoints (SOPC_ClientHelper_EndpointConnection *connection, SOPC_ClientHelper_GetEndpointsResult **result) |
Sends a GetEndpoints request to the endpointUrl and provide the results. More... | |
void | SOPC_ClientHelper_GetEndpointsResult_Free (SOPC_ClientHelper_GetEndpointsResult **getEpResult) |
Free the get endpoints result and its content. Make copy or move data to be kept prior to call this function. More... | |
int32_t | SOPC_ClientHelper_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... | |
int32_t | SOPC_ClientHelper_CreateConfiguration (SOPC_ClientHelper_EndpointConnection *connection, SOPC_ClientHelper_Security *security, OpcUa_GetEndpointsResponse *expectedEndpoints) |
Creates a new configuration to connect to a remote OPC server. Return a configuration id or error code. All parameters are copied and can be freed by the caller. More... | |
int32_t | SOPC_ClientHelper_CreateConnection (int32_t cfg_id) |
Creates a new connection to a remote OPC server. The connection represent the whole client and is later identified by the returned connectionId. The function waits until the client is effectively connected or the Toolkit times out. Return a connection id or error code. More... | |
int32_t | SOPC_ClientHelper_CreateSubscription (int32_t connectionId, SOPC_ClientHelper_DataChangeCbk *callback) |
Create a subscription associated to the given connection The given callback will be called on data changes. More... | |
int32_t | SOPC_ClientHelper_AddMonitoredItems (int32_t connectionId, char **nodeIds, size_t nbNodeIds, SOPC_StatusCode *results) |
Adds monitored items to the subscription associated to the given connection. SOPC_ClientHelper_CreateSubscription() should have been called previously. More... | |
int32_t | SOPC_ClientHelper_Unsubscribe (int32_t connectionId) |
Delete subscription associated to the given connection. If this function succeed, no more data changes notification is received about this connection until SOPC_ClientHelper_CreateSubscription() and SOPC_ClientHelper_AddMonitorItems() are called. More... | |
int32_t | SOPC_ClientHelper_Disconnect (int32_t connectionId) |
Disconnect from a remote OPC server. The function waits until the client is effectively disconnected, or the Toolkit times out. More... | |
int32_t | SOPC_ClientHelper_Write (int32_t connectionId, SOPC_ClientHelper_WriteValue *writeValues, size_t nbElements, SOPC_StatusCode *writeResults) |
Write values to attributes "Value" of one or more Nodes. This function waits for the server response, or the Toolkit times out. More... | |
int32_t | SOPC_ClientHelper_Read (int32_t connectionId, SOPC_ClientHelper_ReadValue *readValues, size_t nbElements, SOPC_DataValue *values) |
Read one or more attributes of one or more Nodes. Return both the source and Server timestamps for each requested Variable Value Attribute. More... | |
void | SOPC_ClientHelper_ReadResults_Free (size_t nbElements, SOPC_DataValue *values) |
Free the result provided by SOPC_ClientHelper_Read. More... | |
int32_t | SOPC_ClientHelper_Browse (int32_t connectionId, SOPC_ClientHelper_BrowseRequest *browseRequests, size_t nbElements, SOPC_ClientHelper_BrowseResult *browseResults) |
Discover the references of a Node using Browse and browseNext services. If Browse Response returns ContinuationPoint, a BrowseNext Request is sent until no ContinuationPoint is returned. More... | |
int32_t | SOPC_ClientHelper_CallMethod (int32_t connectionId, SOPC_ClientHelper_CallMethodRequest *callRequests, size_t nbOfElements, SOPC_ClientHelper_CallMethodResult *callResults) |
Call a method. More... | |
SOPC_ReturnStatus | SOPC_ClientHelper_GenericService (int32_t connectionId, void *requestMsg, void **responseMsg) |
Call a generic OPC UA service using OPC UA request/response types. Note: request builder module functions might be used (see example below in requestMsg documentation). More... | |
void | SOPC_ClientHelper_CallMethodResults_Clear (size_t nbElements, SOPC_ClientHelper_CallMethodResult *results) |
Clears the content of the SOPC_ClientHelper_CallMethodResult[] results . The array is not deallocated since it is managed by the caller of SOPC_ClientHelper_CallMethod. More... | |
SOPC_ReturnStatus | SOPC_ClientHelper_SetLocaleIds (size_t nbLocales, const char **localeIds) |
Define client preferred locales ids from an array of locale strings. More... | |
SOPC_ReturnStatus | SOPC_ClientHelper_SetApplicationDescription (const char *applicationUri, const char *productUri, const char *defaultAppName, const char *defaultAppNameLocale, OpcUa_ApplicationType applicationType) |
Define client application description. More... | |
Interface of a library supporting the subscription management, read/write operation and browse.
The functions of this interface are synchronous and mutually excluded: functions wait for server's response and 2 functions cannot be called simultaneously.
typedef void SOPC_ClientHelper_DataChangeCbk(const int32_t connectionId, const char *nodeId, const SOPC_DataValue *value) |
Callback type for data change event (related to a subscription)
connectionId | The connection id on which the datachange happened |
nodeId | The node id of changed node |
value | The new value of the Attribute 'Value'. Its content is freed by the LibSub after this function has been called, hence the callback must copy it if it should be used outside the callback. |
typedef void SOPC_ClientHelper_DisconnectCbk(const uint32_t connectionId) |
Callback type for disconnection.
connectionId | The disconnected connection id |
void SOPC_ClientHelper_BrowseResultReference_Move | ( | SOPC_ClientHelper_BrowseResultReference * | dest, |
SOPC_ClientHelper_BrowseResultReference * | src | ||
) |
Move the content of the SOPC_ClientHelper_BrowseResultReference from source to destination. Note: after use of move function, clearing source has no effect on destination structure content since source does not point to allocated data anymore.
dest | A pointer to the SOPC_ClientHelper_BrowseResultReference structure to use as destination |
src | A pointer to the SOPC_ClientHelper_BrowseResultReference structure to use as source |
void SOPC_ClientHelper_BrowseResultReference_Clear | ( | SOPC_ClientHelper_BrowseResultReference * | brr | ) |
Clears the content of the SOPC_ClientHelper_BrowseResultReference structure pointed by brr
.
brr | A pointer to the SOPC_ClientHelper_BrowseResultReference structure to clear. |
void SOPC_ClientHelper_BrowseResults_Clear | ( | size_t | nbElements, |
SOPC_ClientHelper_BrowseResult * | results | ||
) |
Clears the content of the SOPC_ClientHelper_BrowseResult[] results
. The array is not deallocated since it is managed by the caller of SOPC_ClientHelper_Browse.
SOPC_ClientHelper_BrowseResultReference_Move might be use to keep partial result before calling this function.
nbElements | The number of elements in the browse result array |
results | The SOPC_ClientHelper_BrowseResult array to clear. |
int32_t SOPC_ClientHelper_Initialize | ( | SOPC_ClientHelper_DisconnectCbk *const | disconnect_callback | ) |
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.
disconnect_callback | Optional, can be NULL. Callback called when a connection is disconnected. |
void SOPC_ClientHelper_Finalize | ( | void | ) |
Clears the connections and configurations. It shall be done before a call to SOPC_CommonHelper_Clear.
int32_t SOPC_ClientHelper_GetEndpoints | ( | SOPC_ClientHelper_EndpointConnection * | connection, |
SOPC_ClientHelper_GetEndpointsResult ** | result | ||
) |
Sends a GetEndpoints request to the endpointUrl and provide the results.
connection | endpoint connection configuration (Server URL and URI, activation of reverse connection, ...) Content is copied and can be cleared after call |
result | result of the request, shall not be used if function result is not 0. |
void SOPC_ClientHelper_GetEndpointsResult_Free | ( | SOPC_ClientHelper_GetEndpointsResult ** | getEpResult | ) |
Free the get endpoints result and its content. Make copy or move data to be kept prior to call this function.
getEpResult | The SOPC_ClientHelper_GetEndpointsResult structure to clear |
int32_t SOPC_ClientHelper_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.
reverseEndpointURL | reverse endpoint URL created by client for reverse connections |
>0. If invalid reverseEndpointURL detected, return -1. If configuration failed, return '-100'.
int32_t SOPC_ClientHelper_CreateConfiguration | ( | SOPC_ClientHelper_EndpointConnection * | connection, |
SOPC_ClientHelper_Security * | security, | ||
OpcUa_GetEndpointsResponse * | expectedEndpoints | ||
) |
Creates a new configuration to connect to a remote OPC server. Return a configuration id or error code. All parameters are copied and can be freed by the caller.
connection | endpoint connection configuration (Server URL and URI, activation of reverse connection, ...) Content is deeply copied and can be cleared after call |
security | security configuration to use (policy, mode, certificates, ...). Content is deeply copied and can be cleared after call |
expectedEndpoints | Response returned by prior call to GetEndpoints service and checked to be the same during session establishment, NULL otherwise (no verification will be done) |
>0. If NULL connection detected, return -1. If invalid endpointUrl detected, return -2. If invalid security detected, return
-<10+n>with
<n>field number (starting from 1). If configuration failed, return '-100'.
int32_t SOPC_ClientHelper_CreateConnection | ( | int32_t | cfg_id | ) |
Creates a new connection to a remote OPC server. The connection represent the whole client and is later identified by the returned connectionId. The function waits until the client is effectively connected or the Toolkit times out. Return a connection id or error code.
cfg_id | Configuration Id created by SOPC_ClientHelper_CreateConfiguration() |
int32_t SOPC_ClientHelper_CreateSubscription | ( | int32_t | connectionId, |
SOPC_ClientHelper_DataChangeCbk * | callback | ||
) |
Create a subscription associated to the given connection The given callback will be called on data changes.
Only attributes "Value" are monitored. The function waits until the subscription is effectively created or the Toolkit times out. Returns 0 if succeeded, otherwise an error code < 0. This function can be called only once time for a valid connection id or user should call SOPC_ClientHelper_unsubscribe() before.
connectionId | The connection id. It should be > 0 |
callback | The callback for data change notification. Should not be null. |
int32_t SOPC_ClientHelper_AddMonitoredItems | ( | int32_t | connectionId, |
char ** | nodeIds, | ||
size_t | nbNodeIds, | ||
SOPC_StatusCode * | results | ||
) |
Adds monitored items to the subscription associated to the given connection. SOPC_ClientHelper_CreateSubscription() should have been called previously.
Only attributes "Value" are monitored. The function waits until the monitored items are effectively created or the Toolkit times out. Returns 0 if succeeded, otherwise an error code < 0.
connectionId | The connection id. It should be > 0 | |
nodeIds | An array of zero-terminated strings describing the NodeIds to add. It should be not NULL and be at least nbNodeIds long. See OPC Unified Architecture, Part 3 for NodeId description. | |
nbNodeIds | Number of elements to subscribes. It should be between 1 and INT32_MAX | |
[out] | results | Pre-allocated array of status codes indicating the add MonitoredItem operation result. It shall have the same size and order than in nodeIds array. It might be NULL if the caller does not need this information. Otherwise it is relevant only if return value is >= 0. |
int32_t SOPC_ClientHelper_Unsubscribe | ( | int32_t | connectionId | ) |
Delete subscription associated to the given connection. If this function succeed, no more data changes notification is received about this connection until SOPC_ClientHelper_CreateSubscription() and SOPC_ClientHelper_AddMonitorItems() are called.
connectionId | The connection id. It should be > 0 |
int32_t SOPC_ClientHelper_Disconnect | ( | int32_t | connectionId | ) |
Disconnect from a remote OPC server. The function waits until the client is effectively disconnected, or the Toolkit times out.
connectionId | The connection id to disconnect |
int32_t SOPC_ClientHelper_Write | ( | int32_t | connectionId, |
SOPC_ClientHelper_WriteValue * | writeValues, | ||
size_t | nbElements, | ||
SOPC_StatusCode * | writeResults | ||
) |
Write values to attributes "Value" of one or more Nodes. This function waits for the server response, or the Toolkit times out.
Restrictions:
connectionId | The connection id. It should be > 0 |
writeValues | An array of Writevalue describing the NodeIds and the Values to write. Its content can be freed after the function returned. It should be not NULL and be at least nbElements long. |
nbElements | Number of elements to write. It should be between 1 and INT32_MAX |
writeResults | A pre-allocated array of StatusCode, filled with result for each write value It should not be NULL and be at least nbElements long. |
int32_t SOPC_ClientHelper_Read | ( | int32_t | connectionId, |
SOPC_ClientHelper_ReadValue * | readValues, | ||
size_t | nbElements, | ||
SOPC_DataValue * | values | ||
) |
Read one or more attributes of one or more Nodes. Return both the source and Server timestamps for each requested Variable Value Attribute.
Restrictions:
connectionId | The connection id. It should be > 0 | |
readValues | An array of ReadValue describing the NodeIds and AttributesId to read. Its content can be freed after the function returned. It should be not NULL and be at least nbElements long. | |
nbElements | Number of elements to read. It should be between 1 and INT32_MAX | |
[out] | values | A pre-allocated array of SOPC_DataValue, filled with the result of each read value. It should not be NULL and be at least nbElements long. When return, the order of this list matches the order of readValues . After using this function, the user must invoke SOPC_ClientHelper_ReadResults_Free() function in order to free the returned SOPC_DataValues. |
void SOPC_ClientHelper_ReadResults_Free | ( | size_t | nbElements, |
SOPC_DataValue * | values | ||
) |
Free the result provided by SOPC_ClientHelper_Read.
If some data of the result shall be kept, either:
nbElements | Number of elements in result. It should be between 1 and INT32_MAX | |
[out] | values | Clear content of the SOPC_DataValue[] array. The array is not freed. It shall be nElements long. |
int32_t SOPC_ClientHelper_Browse | ( | int32_t | connectionId, |
SOPC_ClientHelper_BrowseRequest * | browseRequests, | ||
size_t | nbElements, | ||
SOPC_ClientHelper_BrowseResult * | browseResults | ||
) |
Discover the references of a Node using Browse and browseNext services. If Browse Response returns ContinuationPoint, a BrowseNext Request is sent until no ContinuationPoint is returned.
Restrictions:
connectionId | The connection id. It should be > 0 | |
browseRequests | An array of BrowseRequest describing the NodeIds to browse and ReferenceType to follow. Its content can be freed after the function returned. It should be not NULL and be at least nbElements long. | |
nbElements | Number of elements to browse. It should be between 1 and INT32_MAX | |
[out] | browseResults | A pre-allocated array to the output list of BrowseResult. It should be at least nElements long. When return, the order of this list matches the order of browseRequests . The ownership of the data moved to caller which should free the content of this array. |
int32_t SOPC_ClientHelper_CallMethod | ( | int32_t | connectionId, |
SOPC_ClientHelper_CallMethodRequest * | callRequests, | ||
size_t | nbOfElements, | ||
SOPC_ClientHelper_CallMethodResult * | callResults | ||
) |
Call a method.
connectionId | The connection id. It shall be > 0 | |
callRequests | An array of SOPC_ClientHelper_CallMethodRequest describing the method called with input parameters Note: inputParams are moved using SOPC_Variant_Move and should not be used after this function call | |
nbOfElements | number of elements in the callRequests and callResults arrays. It should be between 1 and INT32_MAX. | |
[out] | callResults | A pre-allocated array of SOPC_ClientHelper_CallMethodeResult structures |
SOPC_ReturnStatus SOPC_ClientHelper_GenericService | ( | int32_t | connectionId, |
void * | requestMsg, | ||
void ** | responseMsg | ||
) |
Call a generic OPC UA service using OPC UA request/response types. Note: request builder module functions might be used (see example below in requestMsg
documentation).
connectionId | The connection id. It shall be > 0 | |
requestMsg | A pointer to a request message of type OpcUa_*_Request (e.g.: OpcUa_AddNodesRequest), it might be built using request builder module functions (e.g. SOPC_AddNodesRequest_Create). The requestMsg is deallocated by toolkit when returned status is not invalid state or parameters. | |
[out] | responseMsg | Address of a pointer that will be used to store the response message in case of success. |
responseMsg
is valid, otherwise SOPC_STATUS_INVALID_STATE in case incorrect initialized state, SOPC_STATUS_INVALID_PARAMETERS in case of invalid parameter. void SOPC_ClientHelper_CallMethodResults_Clear | ( | size_t | nbElements, |
SOPC_ClientHelper_CallMethodResult * | results | ||
) |
Clears the content of the SOPC_ClientHelper_CallMethodResult[] results
. The array is not deallocated since it is managed by the caller of SOPC_ClientHelper_CallMethod.
Note: the variant values to keep after this call shall have been copied or moved using corresponding SOPC_Variant_* function.
nbElements | The number of elements in the call method result array |
results | The SOPC_ClientHelper_CallMethodResult array to clear. |
SOPC_ReturnStatus SOPC_ClientHelper_SetLocaleIds | ( | size_t | nbLocales, |
const char ** | localeIds | ||
) |
Define client preferred locales ids from an array of locale strings.
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. |
localeIds
is invalid when nbLocales
> 0 or SOPC_STATUS_INVALID_STATE if the configuration is not possible.SOPC_ReturnStatus SOPC_ClientHelper_SetApplicationDescription | ( | const char * | applicationUri, |
const char * | productUri, | ||
const char * | defaultAppName, | ||
const char * | defaultAppNameLocale, | ||
OpcUa_ApplicationType | applicationType | ||
) |
Define client application description.
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 |
applicationUri
, productUri
or defaultAppName
are invalid or SOPC_STATUS_INVALID_STATE if the configuration is not possible.