S2OPC OPCUA Toolkit: /builds/systerel/S2OPC/src/ClientServer/frontend/client_wrapper/state

The state machine of the subscribing client. More...

#include <stdbool.h>
#include "sopc_builtintypes.h"
#include "sopc_crypto_profiles.h"
#include "sopc_log_manager.h"
#include "sopc_types.h"
#include "sopc_user_app_itf.h"
#include "libs2opc_client.h"
#include "libs2opc_client_cmds.h"

Go to the source code of this file.

Data Structures
struct	SOPC_StaMac_ReqCtx

struct	SOPC_CreateMonitoredItem_Ctx
	Context structure to be provided when using SOPC_StaMac_CreateMonitoredItem. More...

Macros
#define	MONIT_TIMESTAMPS_TO_RETURN OpcUa_TimestampsToReturn_Both

#define	MONIT_QSIZE 10

#define	SKIP_S2OPC_DEFINITIONS

Typedefs
typedef struct SOPC_StaMac_Machine	SOPC_StaMac_Machine

typedef struct SOPC_CreateMonitoredItem_Ctx	SOPC_CreateMonitoredItem_Ctx
	Context structure to be provided when using SOPC_StaMac_CreateMonitoredItem. More...

Functions
SOPC_ReturnStatus	SOPC_StaMac_Create (uint32_t iscConfig, SOPC_ReverseEndpointConfigIdx reverseConfigIdx, uint32_t iCliId, const char szPolicyId, const char szUsername, const char szPassword, const char szPath_cert_x509_token, const char szPath_key_x509_token, SOPC_LibSub_DataChangeCbk cbkLibSubDataChanged, double fPublishInterval, uint32_t iCntMaxKeepAlive, uint32_t iCntLifetime, uint32_t iTokenTarget, int64_t iTimeoutMs, SOPC_LibSub_EventCbk cbkGenericEvent, uintptr_t userContext, SOPC_StaMac_Machine *ppSM)
	Creates a new state machine, initialized in state stInit. More...

SOPC_ReturnStatus	SOPC_StaMac_ConfigureDataChangeCallback (SOPC_StaMac_Machine pSM, SOPC_ClientHelper_DataChangeCbk pCbkClientHelper)

void	SOPC_StaMac_Delete (SOPC_StaMac_Machine **ppSM)
	Deletes and deallocate the machine. More...

SOPC_ReturnStatus	SOPC_StaMac_StartSession (SOPC_StaMac_Machine *pSM)
	Creates a session asynchronously. More...

SOPC_ReturnStatus	SOPC_StaMac_StopSession (SOPC_StaMac_Machine *pSM)
	Closes the session. More...

SOPC_ReturnStatus	SOPC_StaMac_SendRequest (SOPC_StaMac_Machine pSM, void requestStruct, uintptr_t appCtx, SOPC_StaMac_RequestScope requestScope, SOPC_StaMac_RequestType requestType)
	Sends a request, wraps SOPC_ToolkitClient_AsyncSendRequestOnSession(). More...

SOPC_ReturnStatus	SOPC_StaMac_CreateSubscription (SOPC_StaMac_Machine *pSM)

SOPC_ReturnStatus	SOPC_StaMac_DeleteSubscription (SOPC_StaMac_Machine *pSM)
	Delete subscription associated to the given state machine. More...

SOPC_ReturnStatus	SOPC_StaMac_CreateMonitoredItem (SOPC_StaMac_Machine pSM, char const const lszNodeId, const uint32_t liAttrId, int32_t nElems, SOPC_CreateMonitoredItem_Ctx pAppCtx, uint32_t lCliHndl)
	Creates a MonitoredItem asynchronously. More...

bool	SOPC_StaMac_IsConnectable (SOPC_StaMac_Machine *pSM)
	Returns a bool whether the machine is configured and ready for a new SecureChannel. More...

bool	SOPC_StaMac_IsConnected (SOPC_StaMac_Machine *pSM)
	Returns a bool whether the machine is in a connected state or not. More...

bool	SOPC_StaMac_IsError (SOPC_StaMac_Machine *pSM)
	Returns a bool whether the machine is in stError or not. More...

void	SOPC_StaMac_SetError (SOPC_StaMac_Machine *pSM)
	Put the state machine in error state (without closing). This avoids additional notifications. More...

bool	SOPC_StaMac_HasSubscription (SOPC_StaMac_Machine *pSM)
	Returns a bool whether the machine has an active subscription or not. More...

bool	SOPC_StaMac_HasMonItByAppCtx (SOPC_StaMac_Machine pSM, SOPC_CreateMonitoredItem_Ctx pAppCtx)
	Returns whether the machine has created the MonitoredItem with the given `appCtx` or not. More...

int64_t	SOPC_StaMac_GetTimeout (SOPC_StaMac_Machine *pSM)
	Returns the timeout of the machine, used for the synchroneous calls. More...

uintptr_t	SOPC_StaMac_GetUserContext (SOPC_StaMac_Machine *pSM)
	Returns the user context provided to SOPC_StaMac_Create or modified through SOPC_StaMac_SetUserContext. More...

void	SOPC_StaMac_SetUserContext (SOPC_StaMac_Machine *pSM, uintptr_t userContext)
	Overwrite the user content in the given state machine. More...

bool	SOPC_StaMac_EventDispatcher (SOPC_StaMac_Machine pSM, uintptr_t pAppCtx, SOPC_App_Com_Event event, uint32_t arg, void *pParam, uintptr_t appCtx)
	Handles the events from the Toolkit and changes the state machine state. More...

Detailed Description

The state machine of the subscribing client.

The machine handles:

Toolkit configuration,
SecureChannel and Session creation,
Creation of the Subscription,
Creation of the MonitoredItems,
A number of PublishRequest.

The machine starts in the init state. It shall be configured with a call to SOPC_StaMac_ConfigureMachine(), which configures the Toolkit. TheSOPC_StaMac_EventDispatcher() shall be called on the state machine from the callback given to SOPC_Toolkit_Initialize.

The machine API is thread safe.

Macro Definition Documentation

◆ MONIT_TIMESTAMPS_TO_RETURN

#define MONIT_TIMESTAMPS_TO_RETURN OpcUa_TimestampsToReturn_Both

◆ MONIT_QSIZE

#define MONIT_QSIZE 10

◆ SKIP_S2OPC_DEFINITIONS

#define SKIP_S2OPC_DEFINITIONS

Typedef Documentation

◆ SOPC_StaMac_Machine

typedef struct SOPC_StaMac_Machine SOPC_StaMac_Machine

◆ SOPC_CreateMonitoredItem_Ctx

typedef struct SOPC_CreateMonitoredItem_Ctx SOPC_CreateMonitoredItem_Ctx

Context structure to be provided when using SOPC_StaMac_CreateMonitoredItem.

Enumeration Type Documentation

◆ SOPC_StaMac_State

enum SOPC_StaMac_State

Enumerator
stError
stInit
stActivating
stActivated
stCreatingSubscr
stCreatingMonIt
stDeletingSubscr
stClosing

◆ SOPC_StaMac_RequestType

enum SOPC_StaMac_RequestType

Enumerator
SOPC_REQUEST_TYPE_UNKNOWN
SOPC_REQUEST_TYPE_USER
SOPC_REQUEST_TYPE_PUBLISH
SOPC_REQUEST_TYPE_CREATE_SUBSCRIPTION
SOPC_REQUEST_TYPE_CREATE_MONITORED_ITEMS
SOPC_REQUEST_TYPE_DELETE_SUBSCRIPTION
SOPC_REQUEST_TYPE_GET_ENDPOINTS

◆ SOPC_StaMac_RequestScope

enum SOPC_StaMac_RequestScope

Enumerator
SOPC_REQUEST_SCOPE_STATE_MACHINE
SOPC_REQUEST_SCOPE_APPLICATION	The request is part of the inner working of the state machine
SOPC_REQUEST_SCOPE_DISCOVERY	The request is issued by the applicative layer and the response will be forwarded to the generic event callback The request is a discovery request and shall not be processed by a StaMac

Function Documentation

◆ SOPC_StaMac_Create()

SOPC_ReturnStatus SOPC_StaMac_Create	(	uint32_t	iscConfig,
		SOPC_ReverseEndpointConfigIdx	reverseConfigIdx,
		uint32_t	iCliId,
		const char *	szPolicyId,
		const char *	szUsername,
		const char *	szPassword,
		const char *	szPath_cert_x509_token,
		const char *	szPath_key_x509_token,
		SOPC_LibSub_DataChangeCbk *	cbkLibSubDataChanged,
		double	fPublishInterval,
		uint32_t	iCntMaxKeepAlive,
		uint32_t	iCntLifetime,
		uint32_t	iTokenTarget,
		int64_t	iTimeoutMs,
		SOPC_LibSub_EventCbk *	cbkGenericEvent,
		uintptr_t	userContext,
		SOPC_StaMac_Machine **	ppSM
	)

Creates a new state machine, initialized in state stInit.

Parameters

iscConfig	The configuration identifier to use with this machine
reverseConfigIdx	If the reverse connection mechanism shall be used, it shall be set with index of the reverse endpoint configuration returned by SOPC_ClientCommon_CreateReverseEndpoint. Otherwise it shall be set to 0.
iCliId	The client id of the machine, it shall be unique.
szPolicyId	Zero-terminated user identity policy id, see SOPC_LibSub_ConnectionCfg
szUsername	Zero-terminated username, see SOPC_LibSub_ConnectionCfg
szPassword	Zero-terminated password, see SOPC_LibSub_ConnectionCfg
szPath_cert_x509_token	Zero-terminated path of the x509 certificate for X509IdentiyToken (DER format)
szPath_key_x509_token	Zero-terminated path of the private key for X509IdentiyToken (PEM format)
cbkLibSubDataChanged	The callback to trigger when a PublishResponse is received
fPublishInterval	Subscription publish interval, in milliseconds
iCntMaxKeepAlive	The number of times an empty PublishResponse is not sent
iCntLifetime	The number of times a PublishResponse cannot be sent before killing the subscription
iTokenTarget	Number of subscription tokens the server should always have
iTimeoutMs	Timeout for the synchroneous calls
cbkGenericEvent	Callback for generic responses to a call to SOPC_LibSub_AsyncSendRequestOnSession()
userContext	Caller defined user context that could be retrieved or set using accessors
ppSM	The returned machine, when successful

Returns: SOPC_STATUS_OK when ppSM points to a pointer to a valid machine. In other cases, (*ppSM) is not modified.

◆ SOPC_StaMac_ConfigureDataChangeCallback()

SOPC_ReturnStatus SOPC_StaMac_ConfigureDataChangeCallback	(	SOPC_StaMac_Machine *	pSM,
		SOPC_ClientHelper_DataChangeCbk *	pCbkClientHelper
	)

◆ SOPC_StaMac_Delete()

void SOPC_StaMac_Delete ( SOPC_StaMac_Machine ** ppSM )

Deletes and deallocate the machine.

◆ SOPC_StaMac_StartSession()

SOPC_ReturnStatus SOPC_StaMac_StartSession ( SOPC_StaMac_Machine * pSM )

Creates a session asynchronously.

The state machine will also create a subscription. See SOPC_StaMac_HasSubscription().

See SOPC_ToolkitClient_AsyncActivateSession(). You shall call SOPC_StaMac_StopSession() to close the connection gracefully.

◆ SOPC_StaMac_StopSession()

SOPC_ReturnStatus SOPC_StaMac_StopSession ( SOPC_StaMac_Machine * pSM )

Closes the session.

If not SOPC_StaMac_IsConnected(), the machine is put in state stError.

◆ SOPC_StaMac_SendRequest()

SOPC_ReturnStatus SOPC_StaMac_SendRequest	(	SOPC_StaMac_Machine *	pSM,
		void *	requestStruct,
		uintptr_t	appCtx,
		SOPC_StaMac_RequestScope	requestScope,
		SOPC_StaMac_RequestType	requestType
	)

Sends a request, wraps SOPC_ToolkitClient_AsyncSendRequestOnSession().

The machine must be activated.

Warning: Every client request should be sent with this wrapper, so that the machine can recognize the response from the server.

Parameters

pSM	The state machine used to send request
requestStruct	The structure of the request, see SOPC_ToolkitClient_AsyncSendRequestOnSession()
appCtx	An ID that will be given back through the call to the event handler. The value 0 indicates "no ID".
requestScope	scope of the request (state machine or application)
requestType	type of the request

◆ SOPC_StaMac_CreateSubscription()

SOPC_ReturnStatus SOPC_StaMac_CreateSubscription ( SOPC_StaMac_Machine * pSM )

◆ SOPC_StaMac_DeleteSubscription()

SOPC_ReturnStatus SOPC_StaMac_DeleteSubscription ( SOPC_StaMac_Machine * pSM )

Delete subscription associated to the given state machine.

◆ SOPC_StaMac_CreateMonitoredItem()

SOPC_ReturnStatus SOPC_StaMac_CreateMonitoredItem	(	SOPC_StaMac_Machine *	pSM,
		char const const	lszNodeId,
		const uint32_t *	liAttrId,
		int32_t	nElems,
		SOPC_CreateMonitoredItem_Ctx *	pAppCtx,
		uint32_t *	lCliHndl
	)

Creates a MonitoredItem asynchronously.

The optional pAppCtx may be used to test the effective creation of the MonitoredItem with SOPC_StaMac_HasMonitoredItem().

Parameters

pSM	The state machine with a subscription used to create monitored items
lszNodeId	An array of describing the NodeIds to add. It should be at least `nElems` long.
liAttrId	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 `nElems` long.
nElems	The number of elements in previous arrays.
pAppCtx	The create monitored item application context is stored in this pointer and could be used to call SOPC_StaMac_HasMonItByAppCtx
lCliHndl	An array of client handles to be filled.

Warning: The szNodeId must be \0-terminated.

◆ SOPC_StaMac_IsConnectable()

bool SOPC_StaMac_IsConnectable ( SOPC_StaMac_Machine * pSM )

Returns a bool whether the machine is configured and ready for a new SecureChannel.

Note: for now, it is the stInit state.

◆ SOPC_StaMac_IsConnected()

bool SOPC_StaMac_IsConnected ( SOPC_StaMac_Machine * pSM )

Returns a bool whether the machine is in a connected state or not.

Connected states are: stActivating, stActivated, stCreating*, stClosing.

◆ SOPC_StaMac_IsError()

bool SOPC_StaMac_IsError ( SOPC_StaMac_Machine * pSM )

Returns a bool whether the machine is in stError or not.

◆ SOPC_StaMac_SetError()

void SOPC_StaMac_SetError ( SOPC_StaMac_Machine * pSM )

Put the state machine in error state (without closing). This avoids additional notifications.

◆ SOPC_StaMac_HasSubscription()

bool SOPC_StaMac_HasSubscription ( SOPC_StaMac_Machine * pSM )

Returns a bool whether the machine has an active subscription or not.

◆ SOPC_StaMac_HasMonItByAppCtx()

bool SOPC_StaMac_HasMonItByAppCtx	(	SOPC_StaMac_Machine *	pSM,
		SOPC_CreateMonitoredItem_Ctx *	pAppCtx
	)

Returns whether the machine has created the MonitoredItem with the given appCtx or not.

◆ SOPC_StaMac_GetTimeout()

int64_t SOPC_StaMac_GetTimeout ( SOPC_StaMac_Machine * pSM )

Returns the timeout of the machine, used for the synchroneous calls.

◆ SOPC_StaMac_GetUserContext()

uintptr_t SOPC_StaMac_GetUserContext ( SOPC_StaMac_Machine * pSM )

Returns the user context provided to SOPC_StaMac_Create or modified through SOPC_StaMac_SetUserContext.

◆ SOPC_StaMac_SetUserContext()

void SOPC_StaMac_SetUserContext	(	SOPC_StaMac_Machine *	pSM,
		uintptr_t	userContext
	)

Overwrite the user content in the given state machine.

◆ SOPC_StaMac_EventDispatcher()

bool SOPC_StaMac_EventDispatcher	(	SOPC_StaMac_Machine *	pSM,
		uintptr_t *	pAppCtx,
		SOPC_App_Com_Event	event,
		uint32_t	arg,
		void *	pParam,
		uintptr_t	appCtx
	)

Handles the events from the Toolkit and changes the state machine state.

This function can be called even if the message is not destined to this particular machine. If the event is a response from a request issued with the SOPC_REQUEST_SCOPE_APPLICATION, the generic event callback of the machine is called.

Parameters

pSM	The state machine for which event should be handled
pAppCtx	A pointer to an uintptr_t which will contain the appCtx given to SOPC_StaMac_SendRequest(). NULL is valid. 0 indicates "appID unavailable".
event	The event to be handled in the state machine
arg	The first parameter (id or status) associated with the event
pParam	The second parameter associated with the event
appCtx	The appCtx given by the Toolkit.

Warning: This function shall be called upon each event raised by the Toolkit.

Returns: True if the event is targeted to the machine (including all request scopes). False otherwise, or when pSM is NULL.

Enumerations
enum	SOPC_StaMac_State { stError, stInit, stActivating, stActivated, stCreatingSubscr, stCreatingMonIt, stDeletingSubscr, stClosing }

enum	SOPC_StaMac_RequestType { SOPC_REQUEST_TYPE_UNKNOWN = 0, SOPC_REQUEST_TYPE_USER, SOPC_REQUEST_TYPE_PUBLISH, SOPC_REQUEST_TYPE_CREATE_SUBSCRIPTION, SOPC_REQUEST_TYPE_CREATE_MONITORED_ITEMS, SOPC_REQUEST_TYPE_DELETE_SUBSCRIPTION, SOPC_REQUEST_TYPE_GET_ENDPOINTS }

enum	SOPC_StaMac_RequestScope { SOPC_REQUEST_SCOPE_STATE_MACHINE, SOPC_REQUEST_SCOPE_APPLICATION, SOPC_REQUEST_SCOPE_DISCOVERY }

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ MONIT_TIMESTAMPS_TO_RETURN

◆ MONIT_QSIZE

◆ SKIP_S2OPC_DEFINITIONS

Typedef Documentation

◆ SOPC_StaMac_Machine

◆ SOPC_CreateMonitoredItem_Ctx

Enumeration Type Documentation

◆ SOPC_StaMac_State

◆ SOPC_StaMac_RequestType

◆ SOPC_StaMac_RequestScope

Function Documentation

◆ SOPC_StaMac_Create()

◆ SOPC_StaMac_ConfigureDataChangeCallback()

◆ SOPC_StaMac_Delete()

◆ SOPC_StaMac_StartSession()

◆ SOPC_StaMac_StopSession()

◆ SOPC_StaMac_SendRequest()

◆ SOPC_StaMac_CreateSubscription()

◆ SOPC_StaMac_DeleteSubscription()

◆ SOPC_StaMac_CreateMonitoredItem()

◆ SOPC_StaMac_IsConnectable()

◆ SOPC_StaMac_IsConnected()

◆ SOPC_StaMac_IsError()

◆ SOPC_StaMac_SetError()

◆ SOPC_StaMac_HasSubscription()

◆ SOPC_StaMac_HasMonItByAppCtx()

◆ SOPC_StaMac_GetTimeout()

◆ SOPC_StaMac_GetUserContext()

◆ SOPC_StaMac_SetUserContext()

◆ SOPC_StaMac_EventDispatcher()