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

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...
 

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 }
 

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:

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

◆ SOPC_CreateMonitoredItem_Ctx

Context structure to be provided when using SOPC_StaMac_CreateMonitoredItem.

Enumeration Type Documentation

◆ SOPC_StaMac_State

Enumerator
stError 
stInit 
stActivating 
stActivated 
stCreatingSubscr 
stCreatingMonIt 
stDeletingSubscr 
stClosing 

◆ 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

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
iscConfigThe configuration identifier to use with this machine
reverseConfigIdxIf 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.
iCliIdThe client id of the machine, it shall be unique.
szPolicyIdZero-terminated user identity policy id, see SOPC_LibSub_ConnectionCfg
szUsernameZero-terminated username, see SOPC_LibSub_ConnectionCfg
szPasswordZero-terminated password, see SOPC_LibSub_ConnectionCfg
szPath_cert_x509_tokenZero-terminated path of the x509 certificate for X509IdentiyToken (DER format)
szPath_key_x509_tokenZero-terminated path of the private key for X509IdentiyToken (PEM format)
cbkLibSubDataChangedThe callback to trigger when a PublishResponse is received
fPublishIntervalSubscription publish interval, in milliseconds
iCntMaxKeepAliveThe number of times an empty PublishResponse is not sent
iCntLifetimeThe number of times a PublishResponse cannot be sent before killing the subscription
iTokenTargetNumber of subscription tokens the server should always have
iTimeoutMsTimeout for the synchroneous calls
cbkGenericEventCallback for generic responses to a call to SOPC_LibSub_AsyncSendRequestOnSession()
userContextCaller defined user context that could be retrieved or set using accessors
ppSMThe 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
pSMThe state machine used to send request
requestStructThe structure of the request, see SOPC_ToolkitClient_AsyncSendRequestOnSession()
appCtxAn ID that will be given back through the call to the event handler. The value 0 indicates "no ID".
requestScopescope of the request (state machine or application)
requestTypetype 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
pSMThe state machine with a subscription used to create monitored items
lszNodeIdAn array of describing the NodeIds to add. It should be at least nElems long.
liAttrIdAn 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.
nElemsThe number of elements in previous arrays.
pAppCtxThe create monitored item application context is stored in this pointer and could be used to call SOPC_StaMac_HasMonItByAppCtx
lCliHndlAn 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
pSMThe state machine for which event should be handled
pAppCtxA pointer to an uintptr_t which will contain the appCtx given to SOPC_StaMac_SendRequest(). NULL is valid. 0 indicates "appID unavailable".
eventThe event to be handled in the state machine
argThe first parameter (id or status) associated with the event
pParamThe second parameter associated with the event
appCtxThe 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.