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

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

#include <stdbool.h>
#include "sopc_builtintypes.h"
#include "sopc_types.h"

Go to the source code of this file.

Data Structures

struct  SOPC_StaMac_ReqCtx
 
struct  SOPC_CreateMonitoredItems_Ctx
 Context structure to be provided when using SOPC_StaMac_NewCreateMonitoredItems. More...
 
struct  SOPC_DeleteMonitoredItems_Ctx
 Context structure to be provided when using SOPC_StaMac_NewDeleteMonitoredItems. More...
 

Macros

#define MONIT_TIMESTAMPS_TO_RETURN   OpcUa_TimestampsToReturn_Both
 
#define MONIT_QSIZE   10
 

Typedefs

typedef enum _SOPC_StaMac_ApplicativeEvent SOPC_StaMac_ApplicativeEvent
 The event passed to the connection SOPC_LibSub_EventCbk. Either an error or a valid response notification.
 
typedef void SOPC_StaMac_EventCbk(uint32_t c_id, SOPC_StaMac_ApplicativeEvent event, SOPC_StatusCode status, const void *response, uintptr_t responseContext)
 Callback for generic responses to a call to SOPC_StaMac_SendRequest().
 
typedef struct SOPC_StaMac_Machine SOPC_StaMac_Machine
 
typedef struct SOPC_CreateMonitoredItems_Ctx SOPC_CreateMonitoredItems_Ctx
 Context structure to be provided when using SOPC_StaMac_NewCreateMonitoredItems.
 
typedef void SOPC_StaMacNotification_Fct(uintptr_t subscriptionAppCtx, SOPC_StatusCode status, SOPC_EncodeableType *notificationType, uint32_t nbNotifElts, const void *notification, uintptr_t *monitoredItemCtxArray)
 Type of callback called on Subscription Notification.
 
typedef struct SOPC_DeleteMonitoredItems_Ctx SOPC_DeleteMonitoredItems_Ctx
 Context structure to be provided when using SOPC_StaMac_NewDeleteMonitoredItems.
 

Enumerations

enum  _SOPC_StaMac_ApplicativeEvent { SOPC_StaMac_ApplicativeEvent_SendFailed , SOPC_StaMac_ApplicativeEvent_Response }
 The event passed to the connection SOPC_LibSub_EventCbk. Either an error or a valid response notification. More...
 
enum  SOPC_StaMac_State {
  stError , stInit , stActivating , stActivated ,
  stCreatingSubscr , stCreatingMonIt , stDeletingMonIt , stDeletingSubscr ,
  stClosing
}
 
enum  SOPC_StaMac_RequestType {
  SOPC_REQUEST_TYPE_UNKNOWN = 0 , SOPC_REQUEST_TYPE_USER , SOPC_REQUEST_TYPE_PUBLISH , SOPC_REQUEST_TYPE_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 SOPC_SerializedCertificate *pUserCertX509, const SOPC_SerializedAsymmetricKey *pUserKey, uint32_t iTokenTarget, SOPC_StaMac_EventCbk *cbkGenericEvent, uintptr_t userContext, SOPC_StaMac_Machine **ppSM)
 Creates a new state machine, initialized in state stInit.
 
void SOPC_StaMac_Delete (SOPC_StaMac_Machine **ppSM)
 Deletes and deallocate the machine.
 
SOPC_ReturnStatus SOPC_StaMac_StartSession (SOPC_StaMac_Machine *pSM)
 Creates a session asynchronously.
 
SOPC_ReturnStatus SOPC_StaMac_StopSession (SOPC_StaMac_Machine *pSM)
 Closes the session.
 
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().
 
SOPC_ReturnStatus SOPC_StaMac_NewCreateSubscription (SOPC_StaMac_Machine *pSM, OpcUa_CreateSubscriptionRequest *req, uintptr_t userAppContext)
 
uintptr_t SOPC_StaMac_GetSubscriptionCtx (SOPC_StaMac_Machine *pSM)
 return the context provided in SOPC_StaMac_NewCreateSubscription
 
SOPC_ReturnStatus SOPC_StaMac_GetSubscriptionRevisedParams (SOPC_StaMac_Machine *pSM, double *revisedPublishingInterval, uint32_t *revisedLifetimeCount, uint32_t *revisedMaxKeepAliveCount)
 
SOPC_ReturnStatus SOPC_StaMac_SetSubscriptionNbTokens (SOPC_StaMac_Machine *pSM, uint32_t nbTokens)
 
SOPC_ReturnStatus SOPC_StaMac_DeleteSubscription (SOPC_StaMac_Machine *pSM)
 Delete subscription associated to the given state machine.
 
SOPC_ReturnStatus SOPC_StaMac_NewConfigureNotificationCallback (SOPC_StaMac_Machine *pSM, SOPC_StaMacNotification_Fct *pNotificationCb)
 
SOPC_ReturnStatus SOPC_StaMac_NewCreateMonitoredItems (SOPC_StaMac_Machine *pSM, OpcUa_CreateMonitoredItemsRequest *req, const uintptr_t *userAppCtxArray, SOPC_CreateMonitoredItems_Ctx *pAppCtx)
 Creates new monitored items for the state machine subscription using the request (new API)
 
SOPC_ReturnStatus SOPC_StaMac_NewDeleteMonitoredItems (SOPC_StaMac_Machine *pSM, OpcUa_DeleteMonitoredItemsRequest *req, SOPC_DeleteMonitoredItems_Ctx *outAppCtx)
 Deletes created monitored items for the state machine subscription using the request (new API)
 
bool SOPC_StaMac_IsConnectable (SOPC_StaMac_Machine *pSM)
 Returns a bool whether the machine is configured and ready for a new SecureChannel.
 
bool SOPC_StaMac_IsConnected (SOPC_StaMac_Machine *pSM)
 Returns a bool whether the machine is in a connected state or not.
 
bool SOPC_StaMac_IsError (SOPC_StaMac_Machine *pSM)
 Returns a bool whether the machine is in stError or not.
 
void SOPC_StaMac_SetError (SOPC_StaMac_Machine *pSM)
 Put the state machine in error state (without closing). This avoids additional notifications.
 
bool SOPC_StaMac_HasSubscription (SOPC_StaMac_Machine *pSM)
 Returns a bool whether the machine has an active subscription or not.
 
uint32_t SOPC_StaMac_HasSubscriptionId (SOPC_StaMac_Machine *pSM)
 Returns subscription Id whether the machine has an active subscription or not (id = 0).
 
bool SOPC_StaMac_PopMonItByAppCtx (SOPC_StaMac_Machine *pSM, SOPC_CreateMonitoredItems_Ctx *pAppCtx)
 Returns whether the machine has created the MonitoredItems with the given appCtx or not. When it returns true, it is considered acknowledged and the application context is removed from state machine.
 
bool SOPC_StaMac_PopDeleteMonItByAppCtx (SOPC_StaMac_Machine *pSM, SOPC_DeleteMonitoredItems_Ctx *pAppCtx)
 Returns whether the machine has deleted the MonitoredItems with the given appCtx or not. When it returns true, it is considered acknowledged and the application context is removed from state machine.
 
uintptr_t SOPC_StaMac_GetUserContext (SOPC_StaMac_Machine *pSM)
 Returns the user context provided to SOPC_StaMac_Create or modified through SOPC_StaMac_SetUserContext.
 
void SOPC_StaMac_SetUserContext (SOPC_StaMac_Machine *pSM, uintptr_t userContext)
 Overwrite the user content in the given state machine.
 
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.
 

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

Typedef Documentation

◆ SOPC_StaMac_ApplicativeEvent

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

◆ SOPC_StaMac_EventCbk

typedef void SOPC_StaMac_EventCbk(uint32_t c_id, SOPC_StaMac_ApplicativeEvent event, SOPC_StatusCode status, const void *response, uintptr_t responseContext)

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

Parameters
c_idThe connection id on which the event happened
eventThe type of the event:
  • SOPC_StaMac_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_StaMac_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().

◆ SOPC_StaMac_Machine

◆ SOPC_CreateMonitoredItems_Ctx

typedef struct SOPC_CreateMonitoredItems_Ctx SOPC_CreateMonitoredItems_Ctx

Context structure to be provided when using SOPC_StaMac_NewCreateMonitoredItems.

◆ SOPC_StaMacNotification_Fct

typedef void SOPC_StaMacNotification_Fct(uintptr_t subscriptionAppCtx, SOPC_StatusCode status, SOPC_EncodeableType *notificationType, uint32_t nbNotifElts, const void *notification, uintptr_t *monitoredItemCtxArray)

Type of callback called on Subscription Notification.

Parameters
subscriptionAppCtxThe user application context provided in SOPC_StaMac_NewCreateSubscription call
statusOPC UA status code, notification is only valid when SOPC_IsGoodStatus
notificationTypeType of notification received (OpcUa_DataChangeNotification_EncodeableType or OpcUa_EventNotificationList_EncodeableType)
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. 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.

◆ SOPC_DeleteMonitoredItems_Ctx

typedef struct SOPC_DeleteMonitoredItems_Ctx SOPC_DeleteMonitoredItems_Ctx

Context structure to be provided when using SOPC_StaMac_NewDeleteMonitoredItems.

Enumeration Type Documentation

◆ _SOPC_StaMac_ApplicativeEvent

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

Enumerator
SOPC_StaMac_ApplicativeEvent_SendFailed 
SOPC_StaMac_ApplicativeEvent_Response 

◆ SOPC_StaMac_State

Enumerator
stError 
stInit 
stActivating 
stActivated 
stCreatingSubscr 
stCreatingMonIt 
stDeletingMonIt 
stDeletingSubscr 
stClosing 

◆ SOPC_StaMac_RequestType

Enumerator
SOPC_REQUEST_TYPE_UNKNOWN 
SOPC_REQUEST_TYPE_USER 
SOPC_REQUEST_TYPE_PUBLISH 
SOPC_REQUEST_TYPE_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 SOPC_SerializedCertificate * pUserCertX509,
const SOPC_SerializedAsymmetricKey * pUserKey,
uint32_t iTokenTarget,
SOPC_StaMac_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. Otherwise it shall be set to 0.
iCliIdThe client id of the machine, it shall be unique.
szPolicyIdZero-terminated user identity policy id
szUsernameZero-terminated username
szPasswordZero-terminated password
pUserCertX509X509 serialized certificate for X509IdentiyToken (DER format)
pUserKeySerialized private key for X509IdentiyToken (PEM format)
iTokenTargetNumber of subscription tokens the server should always have
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_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_NewCreateSubscription()

SOPC_ReturnStatus SOPC_StaMac_NewCreateSubscription ( SOPC_StaMac_Machine * pSM,
OpcUa_CreateSubscriptionRequest * req,
uintptr_t userAppContext )

◆ SOPC_StaMac_GetSubscriptionCtx()

uintptr_t SOPC_StaMac_GetSubscriptionCtx ( SOPC_StaMac_Machine * pSM)

return the context provided in SOPC_StaMac_NewCreateSubscription

◆ SOPC_StaMac_GetSubscriptionRevisedParams()

SOPC_ReturnStatus SOPC_StaMac_GetSubscriptionRevisedParams ( SOPC_StaMac_Machine * pSM,
double * revisedPublishingInterval,
uint32_t * revisedLifetimeCount,
uint32_t * revisedMaxKeepAliveCount )

◆ SOPC_StaMac_SetSubscriptionNbTokens()

SOPC_ReturnStatus SOPC_StaMac_SetSubscriptionNbTokens ( SOPC_StaMac_Machine * pSM,
uint32_t nbTokens )

◆ SOPC_StaMac_DeleteSubscription()

SOPC_ReturnStatus SOPC_StaMac_DeleteSubscription ( SOPC_StaMac_Machine * pSM)

Delete subscription associated to the given state machine.

◆ SOPC_StaMac_NewConfigureNotificationCallback()

SOPC_ReturnStatus SOPC_StaMac_NewConfigureNotificationCallback ( SOPC_StaMac_Machine * pSM,
SOPC_StaMacNotification_Fct * pNotificationCb )

◆ SOPC_StaMac_NewCreateMonitoredItems()

SOPC_ReturnStatus SOPC_StaMac_NewCreateMonitoredItems ( SOPC_StaMac_Machine * pSM,
OpcUa_CreateMonitoredItemsRequest * req,
const uintptr_t * userAppCtxArray,
SOPC_CreateMonitoredItems_Ctx * pAppCtx )

Creates new monitored items for the state machine subscription using the request (new API)

The pAppCtx shall be used to test the effective creation of the MonitoredItem with SOPC_StaMac_PopMonItByAppCtx.

Parameters
pSMThe state machine with a subscription used to create monitored items
reqThe create monitored items request
userAppCtxArrayAn array of user context defined with the same indexes as the monitored items in req. The context will be provided in the callback defined by when a notification occurs on a monitored item.
[out]pAppCtxThe create monitored item application context is stored in the pointed structure and could be used to call SOPC_StaMac_PopMonItByAppCtx

◆ SOPC_StaMac_NewDeleteMonitoredItems()

SOPC_ReturnStatus SOPC_StaMac_NewDeleteMonitoredItems ( SOPC_StaMac_Machine * pSM,
OpcUa_DeleteMonitoredItemsRequest * req,
SOPC_DeleteMonitoredItems_Ctx * outAppCtx )

Deletes created monitored items for the state machine subscription using the request (new API)

The outAppCtx shall be used to test the effective deletion of the MonitoredItem with SOPC_StaMac_PopDeleteMonItByAppCtx.

Parameters
pSMThe state machine with a subscription for which monitored items shall be deleted
reqThe delete monitored items request
[out]outAppCtxThe delete monitored item application context is stored in the pointed structure and could be used to call SOPC_StaMac_PopDeleteMonItByAppCtx

◆ 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_HasSubscriptionId()

uint32_t SOPC_StaMac_HasSubscriptionId ( SOPC_StaMac_Machine * pSM)

Returns subscription Id whether the machine has an active subscription or not (id = 0).

◆ SOPC_StaMac_PopMonItByAppCtx()

bool SOPC_StaMac_PopMonItByAppCtx ( SOPC_StaMac_Machine * pSM,
SOPC_CreateMonitoredItems_Ctx * pAppCtx )

Returns whether the machine has created the MonitoredItems with the given appCtx or not. When it returns true, it is considered acknowledged and the application context is removed from state machine.

◆ SOPC_StaMac_PopDeleteMonItByAppCtx()

bool SOPC_StaMac_PopDeleteMonItByAppCtx ( SOPC_StaMac_Machine * pSM,
SOPC_DeleteMonitoredItems_Ctx * pAppCtx )

Returns whether the machine has deleted the MonitoredItems with the given appCtx or not. When it returns true, it is considered acknowledged and the application context is removed from state machine.

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