S2OPC OPCUA Toolkit
Data Structures | Macros | Typedefs | Enumerations | Functions
libs2opc_client.h File Reference

Interface of an example client library supporting the subscription management. More...

#include <stdint.h>

Go to the source code of this file.

Data Structures

struct  SOPC_LibSub_Value
 Structure defining the value of a node. More...
 
struct  SOPC_LibSub_StaticCfg
 Static configuration of OPC client library. More...
 
struct  SOPC_LibSub_ConnectionCfg
 Connection configuration to a remote OPC server. More...
 

Macros

#define SOPC_SecurityPolicy_None_URI   "http://opcfoundation.org/UA/SecurityPolicy#None"
 
#define SOPC_SecurityPolicy_Basic256_URI   "http://opcfoundation.org/UA/SecurityPolicy#Basic256"
 
#define SOPC_SecurityPolicy_Basic256Sha256_URI   "http://opcfoundation.org/UA/SecurityPolicy#Basic256Sha256"
 
#define SOPC_LibSub_AttributeId_NodeId   1
 
#define SOPC_LibSub_AttributeId_NodeClass   2
 
#define SOPC_LibSub_AttributeId_BrowseName   3
 
#define SOPC_LibSub_AttributeId_DisplayName   4
 
#define SOPC_LibSub_AttributeId_Description   5
 
#define SOPC_LibSub_AttributeId_WriteMask   6
 
#define SOPC_LibSub_AttributeId_UserWriteMask   7
 
#define SOPC_LibSub_AttributeId_IsAbstract   8
 
#define SOPC_LibSub_AttributeId_Symmetric   9
 
#define SOPC_LibSub_AttributeId_InverseName   10
 
#define SOPC_LibSub_AttributeId_ContainsNoLoops   11
 
#define SOPC_LibSub_AttributeId_EventNotifier   12
 
#define SOPC_LibSub_AttributeId_Value   13
 
#define SOPC_LibSub_AttributeId_DataType   14
 
#define SOPC_LibSub_AttributeId_ValueRank   15
 
#define SOPC_LibSub_AttributeId_ArrayDimensions   16
 
#define SOPC_LibSub_AttributeId_AccessLevel   17
 
#define SOPC_LibSub_AttributeId_UserAccessLevel   18
 
#define SOPC_LibSub_AttributeId_MinimumSamplingInterval   19
 
#define SOPC_LibSub_AttributeId_Historizing   20
 
#define SOPC_LibSub_AttributeId_Executable   21
 
#define SOPC_LibSub_AttributeId_UserExecutable   22
 

Typedefs

typedef uint32_t SOPC_StatusCode
 
typedef enum SOPC_ReturnStatus SOPC_ReturnStatus
 
typedef char * SOPC_LibSub_String
 
typedef const char * SOPC_LibSub_CstString
 
typedef uint32_t SOPC_LibSub_ConfigurationId
 
typedef uint32_t SOPC_LibSub_ConnectionId
 
typedef uint32_t SOPC_LibSub_DataId
 
typedef uint64_t SOPC_LibSub_Timestamp
 
typedef uint32_t SOPC_LibSub_AttributeId
 AttributeIds, as defined in the OPC UA Reference, Part 6 Annex A. More...
 
typedef enum SOPC_LibSub_ApplicativeEvent SOPC_LibSub_ApplicativeEvent
 The event passed to the connection SOPC_LibSub_EventCbk. Either an error or a valid response notification. More...
 
typedef void(* SOPC_LibSub_LogCbk) (const SOPC_Log_Level log_level, SOPC_LibSub_CstString text)
 Log callback type. More...
 
typedef void(* SOPC_LibSub_DisconnectCbk) (const SOPC_LibSub_ConnectionId c_id)
 Callback type for disconnect event. More...
 
typedef void(* SOPC_LibSub_DataChangeCbk) (const SOPC_LibSub_ConnectionId c_id, const SOPC_LibSub_DataId d_id, const SOPC_LibSub_Value *value)
 Callback type for data change event (related to a subscription) More...
 
typedef void(* SOPC_LibSub_EventCbk) (SOPC_LibSub_ConnectionId c_id, SOPC_LibSub_ApplicativeEvent event, SOPC_StatusCode status, const void *response, uintptr_t responseContext)
 Callback for generic responses to a call to SOPC_LibSub_AsyncSendRequestOnSession(). More...
 

Enumerations

enum  SOPC_ReturnStatus {
  SOPC_STATUS_OK = 0, SOPC_STATUS_NOK = 1, SOPC_STATUS_INVALID_PARAMETERS = 2, SOPC_STATUS_INVALID_STATE = 3,
  SOPC_STATUS_ENCODING_ERROR = 4, SOPC_STATUS_WOULD_BLOCK = 5, SOPC_STATUS_TIMEOUT = 6, SOPC_STATUS_OUT_OF_MEMORY = 7,
  SOPC_STATUS_CLOSED = 8, SOPC_STATUS_NOT_SUPPORTED = 9, SOPC_STATUS_OK = 0, SOPC_STATUS_NOK,
  SOPC_STATUS_INVALID_PARAMETERS, SOPC_STATUS_INVALID_STATE, SOPC_STATUS_ENCODING_ERROR, SOPC_STATUS_WOULD_BLOCK,
  SOPC_STATUS_TIMEOUT, SOPC_STATUS_OUT_OF_MEMORY, SOPC_STATUS_CLOSED, SOPC_STATUS_NOT_SUPPORTED
}
 
enum  SOPC_Log_Level {
  SOPC_LOG_LEVEL_ERROR = 0, SOPC_LOG_LEVEL_WARNING = 1, SOPC_LOG_LEVEL_INFO = 2, SOPC_LOG_LEVEL_DEBUG = 3,
  SOPC_LOG_LEVEL_ERROR = 0, SOPC_LOG_LEVEL_WARNING = 1, SOPC_LOG_LEVEL_INFO = 2, SOPC_LOG_LEVEL_DEBUG = 3
}
 
enum  OpcUa_MessageSecurityMode { OpcUa_MessageSecurityMode_Invalid = 0, OpcUa_MessageSecurityMode_None = 1, OpcUa_MessageSecurityMode_Sign = 2, OpcUa_MessageSecurityMode_SignAndEncrypt = 3 }
 
enum  SOPC_UserPolicyId { SOPC_USER_POLICY_ID_ANONYMOUS = 0, SOPC_USER_POLICY_ID_USERNAME = 1 }
 
enum  SOPC_LibSub_DataType {
  SOPC_LibSub_DataType_bool = 1, SOPC_LibSub_DataType_integer = 2, SOPC_LibSub_DataType_string = 3, SOPC_LibSub_DataType_bytestring = 4,
  SOPC_LibSub_DataType_other = 5
}
 
enum  SOPC_LibSub_ApplicativeEvent { SOPC_LibSub_ApplicativeEvent_SendFailed, SOPC_LibSub_ApplicativeEvent_Response }
 The event passed to the connection SOPC_LibSub_EventCbk. Either an error or a valid response notification. More...
 

Functions

void SOPC_Sleep (unsigned int milliseconds)
 
SOPC_LibSub_CstString SOPC_LibSub_GetVersion (void)
 Return the current version of the library. More...
 
SOPC_ReturnStatus SOPC_LibSub_Initialize (const SOPC_LibSub_StaticCfg *pCfg)
 Configure the library. This function shall be called once by the host application before any other service can be used. More...
 
void SOPC_LibSub_Clear (void)
 Clears the connections, configurations, and clears the Toolkit. More...
 
SOPC_ReturnStatus SOPC_LibSub_ConfigureConnection (const SOPC_LibSub_ConnectionCfg *pCfg, SOPC_LibSub_ConfigurationId *pCfgId)
 Configure a future connection. This function shall be called once per connection before a call to SOPC_LibSub_Configured(). The given /p pCfgId is later used to create connections. More...
 
SOPC_ReturnStatus SOPC_LibSub_Configured (void)
 Mark the library as configured. All calls to SOPC_LibSub_ConfigureConnection() shall be done prior to calling this function. All calls to SOPC_LibSub_Connect() shall be done after calling this function. More...
 
SOPC_ReturnStatus SOPC_LibSub_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. A subscription is created and associated with this client. The function waits until the client is effectively connected and the subscription created, or the Toolkit times out. More...
 
SOPC_ReturnStatus SOPC_LibSub_AddToSubscription (const SOPC_LibSub_ConnectionId cliId, const SOPC_LibSub_CstString *lszNodeId, const SOPC_LibSub_AttributeId *lattrId, int32_t nElements, SOPC_LibSub_DataId *lDataId)
 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_LibSub_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_LibSub_EventCbk callback configured with this connection is called with the OpcUa response. More...
 
SOPC_ReturnStatus SOPC_LibSub_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...
 
void Helpers_Log (const SOPC_Log_Level log_level, const char *format,...)
 Buffers a log message, then calls the callback configured with the LibSub. More...
 
void Helpers_LoggerStdout (const SOPC_Log_Level log_level, const SOPC_LibSub_CstString text)
 Helper logger, prints a log message to stdout, with the following format "# log_level: text\n". More...
 

Detailed Description

Interface of an example client library supporting the subscription management.

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

Macro Definition Documentation

◆ SOPC_SecurityPolicy_None_URI

#define SOPC_SecurityPolicy_None_URI   "http://opcfoundation.org/UA/SecurityPolicy#None"

◆ SOPC_SecurityPolicy_Basic256_URI

#define SOPC_SecurityPolicy_Basic256_URI   "http://opcfoundation.org/UA/SecurityPolicy#Basic256"

◆ SOPC_SecurityPolicy_Basic256Sha256_URI

#define SOPC_SecurityPolicy_Basic256Sha256_URI   "http://opcfoundation.org/UA/SecurityPolicy#Basic256Sha256"

◆ SOPC_LibSub_AttributeId_NodeId

#define SOPC_LibSub_AttributeId_NodeId   1

◆ SOPC_LibSub_AttributeId_NodeClass

#define SOPC_LibSub_AttributeId_NodeClass   2

◆ SOPC_LibSub_AttributeId_BrowseName

#define SOPC_LibSub_AttributeId_BrowseName   3

◆ SOPC_LibSub_AttributeId_DisplayName

#define SOPC_LibSub_AttributeId_DisplayName   4

◆ SOPC_LibSub_AttributeId_Description

#define SOPC_LibSub_AttributeId_Description   5

◆ SOPC_LibSub_AttributeId_WriteMask

#define SOPC_LibSub_AttributeId_WriteMask   6

◆ SOPC_LibSub_AttributeId_UserWriteMask

#define SOPC_LibSub_AttributeId_UserWriteMask   7

◆ SOPC_LibSub_AttributeId_IsAbstract

#define SOPC_LibSub_AttributeId_IsAbstract   8

◆ SOPC_LibSub_AttributeId_Symmetric

#define SOPC_LibSub_AttributeId_Symmetric   9

◆ SOPC_LibSub_AttributeId_InverseName

#define SOPC_LibSub_AttributeId_InverseName   10

◆ SOPC_LibSub_AttributeId_ContainsNoLoops

#define SOPC_LibSub_AttributeId_ContainsNoLoops   11

◆ SOPC_LibSub_AttributeId_EventNotifier

#define SOPC_LibSub_AttributeId_EventNotifier   12

◆ SOPC_LibSub_AttributeId_Value

#define SOPC_LibSub_AttributeId_Value   13

◆ SOPC_LibSub_AttributeId_DataType

#define SOPC_LibSub_AttributeId_DataType   14

◆ SOPC_LibSub_AttributeId_ValueRank

#define SOPC_LibSub_AttributeId_ValueRank   15

◆ SOPC_LibSub_AttributeId_ArrayDimensions

#define SOPC_LibSub_AttributeId_ArrayDimensions   16

◆ SOPC_LibSub_AttributeId_AccessLevel

#define SOPC_LibSub_AttributeId_AccessLevel   17

◆ SOPC_LibSub_AttributeId_UserAccessLevel

#define SOPC_LibSub_AttributeId_UserAccessLevel   18

◆ SOPC_LibSub_AttributeId_MinimumSamplingInterval

#define SOPC_LibSub_AttributeId_MinimumSamplingInterval   19

◆ SOPC_LibSub_AttributeId_Historizing

#define SOPC_LibSub_AttributeId_Historizing   20

◆ SOPC_LibSub_AttributeId_Executable

#define SOPC_LibSub_AttributeId_Executable   21

◆ SOPC_LibSub_AttributeId_UserExecutable

#define SOPC_LibSub_AttributeId_UserExecutable   22

Typedef Documentation

◆ SOPC_StatusCode

typedef uint32_t SOPC_StatusCode

◆ SOPC_ReturnStatus

◆ SOPC_LibSub_String

typedef char* SOPC_LibSub_String

◆ SOPC_LibSub_CstString

typedef const char* SOPC_LibSub_CstString

◆ SOPC_LibSub_ConfigurationId

typedef uint32_t SOPC_LibSub_ConfigurationId

◆ SOPC_LibSub_ConnectionId

typedef uint32_t SOPC_LibSub_ConnectionId

◆ SOPC_LibSub_DataId

typedef uint32_t SOPC_LibSub_DataId

◆ SOPC_LibSub_Timestamp

typedef uint64_t SOPC_LibSub_Timestamp

◆ SOPC_LibSub_AttributeId

typedef uint32_t SOPC_LibSub_AttributeId

AttributeIds, as defined in the OPC UA Reference, Part 6 Annex A.

◆ SOPC_LibSub_ApplicativeEvent

The event passed to the connection SOPC_LibSub_EventCbk. Either an error or a valid response notification.

◆ SOPC_LibSub_LogCbk

typedef void(* SOPC_LibSub_LogCbk) (const SOPC_Log_Level log_level, SOPC_LibSub_CstString text)

Log callback type.

Parameters
log_levelThe Log level (SOPC_Log_Level). Note: SOPC_log_error shall be non-returning.
textThe text string to log (shall not be null)

◆ SOPC_LibSub_DisconnectCbk

typedef void(* SOPC_LibSub_DisconnectCbk) (const SOPC_LibSub_ConnectionId c_id)

Callback type for disconnect event.

Parameters
c_idThe connection id that has been disconnected

◆ SOPC_LibSub_DataChangeCbk

typedef void(* SOPC_LibSub_DataChangeCbk) (const SOPC_LibSub_ConnectionId c_id, const SOPC_LibSub_DataId d_id, const SOPC_LibSub_Value *value)

Callback type for data change event (related to a subscription)

Parameters
c_idThe connection id on which the datachange happened
d_idThe data id of the monitored item (see SOPC_LibSub_AddToSubscription())
valueThe new 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. The NULL pointer is given to the callback when the SOPC_DataValue could not be converted to a SOPC_LibSub_Value, or the malloc failed.

◆ SOPC_LibSub_EventCbk

typedef void(* SOPC_LibSub_EventCbk) (SOPC_LibSub_ConnectionId c_id, SOPC_LibSub_ApplicativeEvent event, SOPC_StatusCode status, const void *response, uintptr_t responseContext)

Callback for generic responses to a call to SOPC_LibSub_AsyncSendRequestOnSession().

Parameters
c_idThe connection id on which the event happened
eventThe type of the event:
  • SOPC_LibSub_ApplicativeEvent_SendFailed: the request was not sent and status holds the reason. In this case, response shall be NULL but the responseContext is valid. The underlying connection is about to be closed.
  • SOPC_LibSub_ApplicativeEvent_Response: the response pointer and the response context are valid and the status is Good.
statusThe status code for the event
responseAn (OpcUa_<MessageStruct>*) pointing to the OPC-UA response structure. This message is freed by the caller and should not be modified by the callback function.
responseContextThe requestContext given in SOPC_LibSub_AsyncSendRequestOnSession().

Enumeration Type Documentation

◆ SOPC_ReturnStatus

Enumerator
SOPC_STATUS_OK 
SOPC_STATUS_NOK 
SOPC_STATUS_INVALID_PARAMETERS 
SOPC_STATUS_INVALID_STATE 
SOPC_STATUS_ENCODING_ERROR 
SOPC_STATUS_WOULD_BLOCK 
SOPC_STATUS_TIMEOUT 
SOPC_STATUS_OUT_OF_MEMORY 
SOPC_STATUS_CLOSED 
SOPC_STATUS_NOT_SUPPORTED 
SOPC_STATUS_OK 
SOPC_STATUS_NOK 
SOPC_STATUS_INVALID_PARAMETERS 
SOPC_STATUS_INVALID_STATE 
SOPC_STATUS_ENCODING_ERROR 
SOPC_STATUS_WOULD_BLOCK 
SOPC_STATUS_TIMEOUT 
SOPC_STATUS_OUT_OF_MEMORY 
SOPC_STATUS_CLOSED 
SOPC_STATUS_NOT_SUPPORTED 

◆ SOPC_Log_Level

Enumerator
SOPC_LOG_LEVEL_ERROR 
SOPC_LOG_LEVEL_WARNING 
SOPC_LOG_LEVEL_INFO 
SOPC_LOG_LEVEL_DEBUG 
SOPC_LOG_LEVEL_ERROR 
SOPC_LOG_LEVEL_WARNING 
SOPC_LOG_LEVEL_INFO 
SOPC_LOG_LEVEL_DEBUG 

◆ OpcUa_MessageSecurityMode

Enumerator
OpcUa_MessageSecurityMode_Invalid 
OpcUa_MessageSecurityMode_None 
OpcUa_MessageSecurityMode_Sign 
OpcUa_MessageSecurityMode_SignAndEncrypt 

◆ SOPC_UserPolicyId

Enumerator
SOPC_USER_POLICY_ID_ANONYMOUS 
SOPC_USER_POLICY_ID_USERNAME 

◆ SOPC_LibSub_DataType

Enumerator
SOPC_LibSub_DataType_bool 
SOPC_LibSub_DataType_integer 
SOPC_LibSub_DataType_string 
SOPC_LibSub_DataType_bytestring 
SOPC_LibSub_DataType_other 

◆ SOPC_LibSub_ApplicativeEvent

The event passed to the connection SOPC_LibSub_EventCbk. Either an error or a valid response notification.

Enumerator
SOPC_LibSub_ApplicativeEvent_SendFailed 
SOPC_LibSub_ApplicativeEvent_Response 

Function Documentation

◆ SOPC_Sleep()

void SOPC_Sleep ( unsigned int  milliseconds)

◆ SOPC_LibSub_GetVersion()

SOPC_LibSub_CstString SOPC_LibSub_GetVersion ( void  )

Return the current version of the library.

◆ SOPC_LibSub_Initialize()

SOPC_ReturnStatus SOPC_LibSub_Initialize ( const SOPC_LibSub_StaticCfg pCfg)

Configure the library. This function shall be called once by the host application before any other service can be used.

Warning
This function is not threadsafe.
Parameters
pCfgNon 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.
Returns
The operation status

◆ SOPC_LibSub_Clear()

void SOPC_LibSub_Clear ( void  )

Clears the connections, configurations, and clears the Toolkit.

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

◆ SOPC_LibSub_ConfigureConnection()

SOPC_ReturnStatus SOPC_LibSub_ConfigureConnection ( const SOPC_LibSub_ConnectionCfg pCfg,
SOPC_LibSub_ConfigurationId pCfgId 
)

Configure a future connection. This function shall be called once per connection before a call to SOPC_LibSub_Configured(). The given /p pCfgId is later used to create connections.

Parameters
pCfgNon 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]pCfgIdThe configuration connection id. Set when the value returned is "SOPC_STATUS_OK".
Returns
The operation status

◆ SOPC_LibSub_Configured()

SOPC_ReturnStatus SOPC_LibSub_Configured ( void  )

Mark the library as configured. All calls to SOPC_LibSub_ConfigureConnection() shall be done prior to calling this function. All calls to SOPC_LibSub_Connect() shall be done after calling this function.

Warning
As this function should be called only once, it is not threadsafe.
Returns
The operation status

◆ SOPC_LibSub_Connect()

SOPC_ReturnStatus SOPC_LibSub_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. A subscription is created and associated with this client. The function waits until the client is effectively connected and the subscription created, or the Toolkit times out.

Parameters
cfgIdThe parameters of the connection to create, return by SOPC_LibSub_ConfigureConnection().
[out]pCliIdThe connection id of the newly created client, set when return 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 end of the function

◆ SOPC_LibSub_AddToSubscription()

SOPC_ReturnStatus SOPC_LibSub_AddToSubscription ( const SOPC_LibSub_ConnectionId  cliId,
const SOPC_LibSub_CstString lszNodeId,
const SOPC_LibSub_AttributeId lattrId,
int32_t  nElements,
SOPC_LibSub_DataId lDataId 
)

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
cliIdThe connection id.
lszNodeIdAn array of zero-terminated strings describing the NodeIds to add. It should be at least nElements long.
lattrIdAn 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.
nElementsThe number of elements in previous arrays.
[out]lDataIdA 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 data_change_callback.
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_LibSub_AsyncSendRequestOnSession()

SOPC_ReturnStatus SOPC_LibSub_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_LibSub_EventCbk callback configured with this connection is called with the OpcUa response.

Parameters
cliIdThe connection id.
requestStructOPC UA message payload structure pointer (OpcUa_<MessageStruct>*). Deallocated by toolkit.
requestContextA context value, it will be provided in the callback alongside the corresponding response.

◆ SOPC_LibSub_Disconnect()

SOPC_ReturnStatus SOPC_LibSub_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
cliIdThe 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).

◆ Helpers_Log()

void Helpers_Log ( const SOPC_Log_Level  log_level,
const char *  format,
  ... 
)

Buffers a log message, then calls the callback configured with the LibSub.

◆ Helpers_LoggerStdout()

void Helpers_LoggerStdout ( const SOPC_Log_Level  log_level,
const SOPC_LibSub_CstString  text 
)

Helper logger, prints a log message to stdout, with the following format "# log_level: text\n".