open62541 Client Subscriptions API

ua_client_subscriptions.h

/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#ifndef UA_CLIENT_SUBSCRIPTIONS_H_
#define UA_CLIENT_SUBSCRIPTIONS_H_

#include "ua_client.h"

#ifdef UA_ENABLE_SUBSCRIPTIONS

#ifdef __cplusplus
extern "C" {
#endif

/**
 * .. _client-subscriptions:
 *
 * Client-side Subscriptions Handling
 * ----------------------------------
 *
 * At this time, the client does not yet contain its own thread or event-driven
 * main-loop. So the client will not perform any actions automatically in the
 * background. This is especially relevant for subscriptions. The user will have
 * to periodically call `UA_Client_Subscriptions_manuallySendPublishRequest`.
 * See also :ref:`here <client-subscriptions>`. */

UA_StatusCode UA_EXPORT
UA_Client_manuallySendPublishRequests(UA_Client *client);

/**
 * Subscriptions Handling
 * ^^^^^^^^^^^^^^^^^^^^^^ */

typedef struct {
    /* Server-side parameters */
    UA_Double publishingInterval;
    UA_UInt32 lifetimeCount;
    UA_UInt32 maxKeepAliveCount;
    UA_UInt32 maxNotificationsPerPublish;
    UA_Byte priority;
} UA_SubscriptionParameters;

extern const UA_EXPORT
UA_SubscriptionParameters UA_SubscriptionParameters_default;

typedef void (*UA_Subscription_DeleteCallback)
    (UA_Client *client, UA_UInt32 subscriptionId, void *subscriptionContext);

typedef void (*UA_Subscription_StatusChangeNotificationCallback)
    (UA_UInt32 subscriptionId, void *subscriptionContext,
     UA_DateTime publishTime, const UA_StatusChangeNotification *notification);

UA_StatusCode UA_EXPORT
UA_Client_Subscription_create(UA_Client *client,
                              UA_SubscriptionParameters requestedParameters,
                              UA_Boolean publishingEnabled, void *subscriptionContext,
                              UA_StatusChangeNotificationCallback statusChangeCallback,
                              UA_DeleteSubscriptionCallback deleteCallback,
                              UA_UInt32 *newSubscriptionId);

UA_StatusCode UA_EXPORT
UA_Client_Subscription_delete(UA_Client *client, UA_UInt32 subscriptionsId);

UA_EXPORT UA_StatusCode
UA_Client_Subscription_setParameters(UA_Client *client, UA_UInt32 subscriptionId,
                                     const UA_SubscriptionParameters *parameters);

UA_EXPORT UA_StatusCode
UA_Client_Subscription_getParameters(UA_Client *client, UA_UInt32 subscriptionId,
                                     UA_SubscriptionParameters *parameters);

UA_EXPORT UA_StatusCode
UA_Client_Subscription_setPublishingMode(UA_Client *client, UA_UInt32 subscriptionId,
                                         UA_Boolean publishingEnabled);

UA_EXPORT UA_StatusCode
UA_Client_Subscription_getPublishingMode(UA_Client *client, UA_UInt32 subscriptionId,
                                         UA_Boolean *publishingEnabled);

/* Republish is called internally. */

/* TODO: TransferSubscriptions */

/**
 * MonitoredItem Handling
 * ^^^^^^^^^^^^^^^^^^^^^^
 * Every MonitoredItem is attached to a Subscription. The Subscription publishes
 * the Notifications generated by the MonitoredItem.*/

UA_EXPORT extern const UA_MonitoringParameters UA_MonitoringParameters_default;

typedef void (*UA_DeleteMonitoredItemCallback)
    (UA_Client *client, UA_UInt32 subscriptionId, void *subscriptionContext,
     UA_UInt32 monitoredItemId, void *monitoredItemContext);

/* Use the typed version of this method below. */
UA_EXPORT UA_StatusCode
__UA_Client_MonitoredItem_create(UA_Client *client, UA_UInt32 subscriptionId,
                                 const UA_NodeId *nodeId, UA_AttributeId attributeId,
                                 const UA_MonitoringParameters *parameters,
                                 UA_MonitoringMode monitoringMode,
                                 UA_Boolean expectEventCallback,
                                 void *notificationCallback,
                                 UA_DeleteMonitoredItemCallback *deleteCallback,
                                 void *context, UA_UInt32 *newMonitoredItemId);

/**
 * DataChange-MonitoredItems monitor attributes of nodes in the information
 * model. They allow two kinds of MonitoringFilter in the parameters:
 * DataChangeFilter and AggregateFilter. The DataChange notifications contain a
 * DataValue and optionally a DiagnosticInfo. */

/* DiagnosticInfo may be NULL (and usually is) */
typedef void (*UA_DataChangeNotificationCallback)
    (UA_Client *client, UA_UInt32 subscriptionId, void *subscriptionContext,
     UA_UInt32 monitoredItemId, void *monitoredItemContext, UA_DateTime publishTime,
     const UA_DataValue *value, const UA_DiagnosticInfo *diagnosticInfo);

UA_EXPORT UA_StatusCode
UA_Client_MonitoredItem_create_DataChange(UA_Client *client, UA_UInt32 subscriptionId,
                                          const UA_NodeId nodeId, UA_AttributeId attributeId,
                                          const UA_MonitoringParameters *parameters,
                                          UA_MonitoringMode monitoringMode,
                                          UA_DataChangeNotificationCallback notificationCallback,
                                          UA_DeleteMonitoredItemCallback deleteCallback,
                                          void *context, UA_UInt32 *newMonitoredItemId) {
    return __UA_Client_MonitoredItem_create(client, subscriptionId, &nodeId, attributeId,
                                            parameters, monitoringMode, false,
                                            (void*)notificationCallback, deleteCallback,
                                            context, newMonitoredItemId);
}

/**
 * Event-MonitoredItems monitor Events emitted by ObjectNodes in the information
 * model. They allow an EventFilter to be defined in the parameters. The Event
 * notifications contain a list of Variants. */

typedef void (*UA_EventNotificationCallback)
    (UA_Client *client, UA_UInt32 subscriptionId, void *subscriptionContext,
     UA_UInt32 monitoredItemId, void *monitoredItemContext, UA_DateTime publishTime,
     size_t eventFieldsSize, const UA_Variant *eventFields);

UA_EXPORT UA_StatusCode
UA_Client_MonitoredItem_create_Event(UA_Client *client, UA_UInt32 subscriptionId,
                                     const UA_NodeId nodeId,
                                     const UA_MonitoringParameters *parameters,
                                     UA_MonitoringMode monitoringMode,
                                     UA_EventNotificationCallback notificationCallback,
                                     UA_DeleteMonitoredItemCallback deleteCallback,
                                     void *context, UA_UInt32 *newMonitoredItemId) {
    return __UA_Client_MonitoredItem_create(client, subscriptionId, &nodeId,
                                            UA_ATTRIBUTEID_EVENTNOTIFIER,
                                            parameters, monitoringMode, true,
                                            (void*)notificationCallback,
                                            deleteCallback, context, newMonitoredItemId);
}

UA_EXPORT UA_StatusCode
UA_Client_MonitoredItem_delete(UA_Client *client, UA_UInt32 subscriptionId,
                               UA_UInt32 monitoredItemId);

UA_EXPORT UA_StatusCode
UA_Client_MonitoredItem_setParameters(UA_Client *client, UA_UInt32 subscriptionId,
                                      UA_UInt32 monitoredItemId,
                                      const UA_MonitoringParameters *parameters);

UA_EXPORT UA_StatusCode
UA_Client_MonitoredItem_getParameters(UA_Client *client, UA_UInt32 subscriptionId,
                                      UA_UInt32 monitoredItemId,
                                      UA_MonitoringParameters *parameters);

UA_EXPORT UA_StatusCode
UA_Client_MonitoredItem_setMonitoringMode(UA_Client *client, UA_UInt32 subscriptionId,
                                          UA_UInt32 monitoredItemId,
                                          UA_MonitoringMode monitoringMode);

UA_EXPORT UA_StatusCode
UA_Client_MonitoredItem_getMonitoringMode(UA_Client *client, UA_UInt32 subscriptionId,
                                          UA_UInt32 monitoredItemId,
                                          UA_MonitoringMode *monitoringMode);

UA_EXPORT UA_StatusCode
UA_Client_MonitoredItem_setTriggering(UA_Client *client, UA_UInt32 subscriptionId,
                                      UA_UInt32 monitoredItemId,
                                      size_t linksToAddSize,
                                      const UA_UInt32 *linksToAdd,
                                      size_t linksToRemoveSize,
                                      const UA_UInt32 *linksToRemove);

UA_EXPORT UA_StatusCode
UA_Client_MonitoredItem_getTriggering(UA_Client *client, UA_UInt32 subscriptionId,
                                      UA_UInt32 monitoredItemId,
                                      size_t *linksSize, UA_UInt32 **links);

#ifdef __cplusplus
} // extern "C"
#endif

#endif /* UA_ENABLE_SUBSCRIPTIONS */

#endif /* UA_CLIENT_SUBSCRIPTIONS_H_ */