open62541/include/ua_server_pubsub.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/.
 *
 * Copyright (c) 2017-2018 Fraunhofer IOSB (Author: Andreas Ebner)
 */

#ifndef UA_SERVER_PUBSUB_H
#define UA_SERVER_PUBSUB_H

#ifdef __cplusplus
extern "C" {
#endif

#include "ua_server.h"

/**
 * .. _pubsub:
 *
 * Publish/Subscribe
 * =================
 *
 * Work in progress!
 * This part will be a new chapter later.
 *
 * TODO: write general PubSub introduction
 *
 * The Publish/Subscribe (PubSub) extension for OPC UA enables fast and efficient
 * 1:m communication. The PubSub extension is protocol agnostic and can be used
 * with broker based protocols like MQTT and AMQP or brokerless implementations like UDP-Multicasting.
 *
 * The PubSub API uses the following scheme:
 *
 * 1. Create a configuration for the needed PubSub element.
 *
 * 2. Call the add[element] function and pass in the configuration.
 * 
 * 3. The add[element] function returns the unique nodeId of the internally created element.
 *
 * Take a look on the PubSub Tutorials for mor details about the API usage.::
 *
 *  +-----------+
 *  | UA_Server |
 *  +-----------+
 *   |    |
 *   |    |
 *   |    |
 *   |    |  +----------------------+
 *   |    +->| UA_PubSubConnections |  UA_Server_addPubSubConnection
 *   |       +----------------------+
 *   |        |    |
 *   |        |    |    +-----------------------+
 *   |        |    +--->| UA_PubSubWriterGroups |
 *   |        |         +-----------------------+
 *   |        |
 *   |        |         +-----------------------+
 *   |        +-------->| UA_PubSubReaderGroups |
 *   |                  +-----------------------+
 *   |
 *   |       +---------------------------+
 *   +------>| UA_PubSubPublishedDataSet |  UA_Server_addPublishedDataSet
 *           +---------------------------+
 *
 * Connections
 * -----------
 * The PubSub connections are the abstraction between the concrete transport protocol
 * and the PubSub functionality. It is possible to create multiple connections with
 * different transport protocols at runtime.
 *
 * Take a look on the PubSub Tutorials for mor details about the API usage.
 * Connections
 * -----------
 */

typedef struct{
    UA_String name;
    UA_Boolean enabled;
    union{ //std: valid types UInt or String
        UA_UInt32 numeric;
        UA_String string;
    }publisherId;
    UA_String transportProfileUri;
    UA_Variant address;
    size_t connectionPropertiesSize;
    UA_KeyValuePair *connectionProperties;
    UA_Variant connectionTransportSettings;
} UA_PubSubConnectionConfig;

/**
 * Connection handling
 * ^^^^^^^^^^^^^^^^^^^
 */

UA_StatusCode
UA_Server_addPubSubConnection(UA_Server *server, const UA_PubSubConnectionConfig *connectionConfig,
                              UA_NodeId *connectionIdentifier);

UA_StatusCode
UA_Server_removePubSubConnection(UA_Server *server, UA_NodeId connectionIdentifier);

UA_StatusCode
UA_PubSubConnection_getConfig(UA_Server *server, UA_NodeId connectionIdentifier,
                              UA_PubSubConnectionConfig *config);

/**
 * PublishedDataSets
 * -----------------
 * The PublishedDataSets (PDS) are containers for the published information. The PDS contain
 * the published variables and meta informations. The metainformations are commonly autogenerated
 * or given as constant argument as part of the template functions. The template functions are standard
 * defined and should only be used for configuration tools. You should normally
 * create a empty PDS and call the functions to add new fields.
 */

typedef struct {
    UA_StatusCode addResult;
    size_t fieldAddResultsSize;
    UA_StatusCode *fieldAddResults;
    UA_ConfigurationVersionDataType configurationVersion;
} UA_AddPublishedDataSetResult;

typedef enum {
    UA_PUBSUB_DATASET_PUBLISHEDITEMS,
    UA_PUBSUB_DATASET_PUBLISHEDEVENTS,
    UA_PUBSUB_DATASET_PUBLISHEDITEMS_TEMPLATE,
    UA_PUBSUB_DATASET_PUBLISHEDEVENTS_TEMPLATE,
} UA_PublishedDataSetType;

/* The UA_PUBSUB_DATASET_PUBLISHEDITEMS has currently no additional members
 * and thus no dedicated config structure.
 */

typedef struct {
    UA_DataSetMetaDataType metaData;
    size_t variablesToAddSize;
    UA_PublishedVariableDataType *variablesToAdd;
} UA_PublishedDataItemsTemplateConfig;

typedef struct {
    UA_NodeId eventNotfier;
    UA_ContentFilter filter;
} UA_PublishedEventConfig;

typedef struct {
    UA_DataSetMetaDataType metaData;
    UA_NodeId eventNotfier;
    size_t selectedFieldsSize;
    UA_SimpleAttributeOperand *selectedFields;
    UA_ContentFilter filter;
} UA_PublishedEventTemplateConfig;

/* Configuration structure for PubSubDataSet */
typedef struct {
    UA_String name;
    UA_PublishedDataSetType publishedDataSetType;
    union{
        /* The UA_PUBSUB_DATASET_PUBLISHEDITEMS has currently no additional members
         * and thus no dedicated config structure.*/
        UA_PublishedDataItemsTemplateConfig itemsTemplate;
        UA_PublishedEventConfig event;
        UA_PublishedEventTemplateConfig eventTemplate;
    } config;
} UA_PublishedDataSetConfig;

/**
 * PublishedDataSet handling
 * ^^^^^^^^^^^^^^^^^^^^^^^^^
 */

UA_AddPublishedDataSetResult
UA_Server_addPublishedDataSet(UA_Server *server, const UA_PublishedDataSetConfig *publishedDataSetConfig,
                              UA_NodeId *pdsIdentifier);

UA_StatusCode
UA_Server_removePublishedDataSet(UA_Server *server, UA_NodeId pdsIdentifier);

UA_StatusCode
UA_PublishedDataSet_getConfig(UA_Server *server, UA_NodeId publishedDataSetIdentifier,
                              UA_PublishedDataSetConfig *config);
void
UA_PublishedDataSetConfig_deleteMembers(UA_PublishedDataSetConfig *pdsConfig);


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

#endif /* UA_SERVER_PUBSUB_H */