PubSub Module

Functions and definitions for the PubSub module in the server. More...

Modules
	PubSub Configuration
	Helper function for creation of PubSub configurations (see "More" for an example and details).

Data Structures
struct	pubsub_module_callback
	Callback interface for custom PubSub message handling. More...
struct	pubsub_module_config_callback

Macros
#define	PUBSUB_DEFAULT_CONFIG_FILENAME   "pubsubconfig.uabinary"
	Default name of the PubSub configuration file, used if g_appconfig.pubsub.config_filename is not set.

Typedefs
typedef int(*	datasetreader_dispatch_cb_fn) (struct ua_decoder_context *decoder, struct pubsub_datasetmsg_ctx *context_datasetmessage, void *user_data)
	Callback which allows the application to process the DataSet message for a DataSetReader. More...
typedef int(*	pubsub_module_nstable_get_fn) (int32_t *num_namespaces, struct ua_string **namespaces, void *arg)
	Callback definition to provide a different namespace table then the default one form the server.

Enumerations
enum	PUBSUB_MODULE_CONFIG {   PUBSUB_MODULE_CONFIG_NONE = 0, PUBSUB_MODULE_CONFIG_FILE = 1, PUBSUB_MODULE_CONFIG_FILE_IGN_INVALID = 2, PUBSUB_MODULE_CONFIG_FILETYPE_CREATE = 4,   PUBSUB_MODULE_CONFIG_DISABLE_COMMUNICATION = 8 }
	Controls how the pubsub configuration is loaded. More...

Functions
SERVER_EXPORT int	pubsub_module_init (uint32_t mode)
	Initialize the PubSub module. More...
SERVER_EXPORT void	pubsub_module_cleanup (void)
	Cleanup PubSub module. More...
SERVER_EXPORT bool	pubsub_module_is_running (void)
	Returns true if the pubsub module has loaded a valid config and is actively publishing/subscribing.
SERVER_EXPORT const struct ua_uabinaryfiledatatype *	pubsub_module_get_config (void)
	Returns the configuration currently used by the pubsub module. More...
SERVER_EXPORT const struct pubsub_api *	pubsub_module_get_api (void)
SERVER_EXPORT int	pubsub_module_set_config_struct_const (const struct ua_uabinaryfiledatatype *config)
	Set a new PubSub configuration as constant structure. More...
SERVER_EXPORT int	pubsub_module_set_config_struct (struct ua_uabinaryfiledatatype *config)
	Set a new PubSub configuration as structure. More...
SERVER_EXPORT int	pubsub_module_set_config_data (const struct ua_bytestring *data)
	Set a new PubSub configuration as UA binary encoded structure. More...
SERVER_EXPORT int	pubsub_module_set_config_file (const char *filename)
	Set a new PubSub configuration from a file. More...
SERVER_EXPORT int	pubsub_module_prepare_update_configuration (struct pubsub_delta_config *delta_config, struct pubsub_delta_result *result)
SERVER_EXPORT pubsub_handle	pubsub_module_apply_update_configuration (struct pubsub_delta_result *result)
SERVER_EXPORT int	pubsub_module_abort_update_configuration (struct pubsub_delta_result *result)
SERVER_EXPORT int	pubsub_module_reserve_ids (struct ua_string transport_profile_uri, uint16_t num_req_writergroup_ids, uint16_t num_req_writer_ids, struct ua_variant *default_publisher_id, uint16_t **writergroup_ids, int32_t *num_writergroup_ids, uint16_t **writer_ids, int32_t *num_writer_ids)
SERVER_EXPORT void	pubsub_module_set_network_backend (struct pubsub_backend *pubsub_network_backend)
	Set custom PubSub network backend. More...
SERVER_EXPORT void	pubsub_module_set_callback (struct pubsub_module_callback *pubsub_module_cb)
	Set PubSub module callback. More...
SERVER_EXPORT void	pubsub_module_set_config_callback (struct pubsub_module_config_callback *pubsub_config_cb)
	Set PubSub module callback. More...
SERVER_EXPORT void	pubsub_module_set_namespacetable_callback (pubsub_module_nstable_get_fn nstable_cb, void *arg)
	Set custom callback to provide a namespace table to the pubsub stack. More...
SERVER_EXPORT int	pubsub_module_set_config_permissions (uint16_t num_permissions, const struct ua_nodepermission *permissions)
	Set PubSub configuration permissions. More...
SERVER_EXPORT int	pubsub_module_set_defaultpublisherid (uint64_t default_publisher_id)
	Set default publisher id for datagram connections. More...
SERVER_EXPORT int	pubsub_module_get_defaultpublisherid (uint64_t *default_publisher_id)
	Get default publisher id for datagram connections. More...
SERVER_EXPORT const struct ua_pubsubconnectiondatatype *	pubsub_module_get_pubsub_connection (pubsub_handle connection)
	Get PubSubConnection configuration structure. More...
SERVER_EXPORT const struct ua_writergroupdatatype *	pubsub_module_get_writer_group (pubsub_handle writer_group)
	Get WriterGroup configuration structure. More...
SERVER_EXPORT const struct ua_datasetwriterdatatype *	pubsub_module_get_dataset_writer (pubsub_handle dataset_writer)
	Get DataSetWriter configuration structure. More...
SERVER_EXPORT const struct ua_publisheddatasetdatatype *	pubsub_module_get_published_dataset (pubsub_handle dataset_writer)
	Get PublishedDataSet configuration structure for a DataSetWriter. More...
SERVER_EXPORT const struct ua_datasetreaderdatatype *	pubsub_module_get_dataset_reader (pubsub_handle dataset_reader)
	Get DataSetReader configuration structure. More...
SERVER_EXPORT void	pubsub_module_sample (pubsub_handle writer_group)
	Sample WriterGroup to create NetworkMaesage(s) for the WriterGroup. More...
SERVER_EXPORT void	pubsub_module_publish (pubsub_handle writer_group)
	Publish WriterGroup to send NetworkMaesage(s) for the WriterGroup. More...

Variables
UA_BEGIN_EXTERN_C typedef int(*	datasetwriter_sample_cb_fn )(struct ua_encoder_context *encoder, struct pubsub_datasetmsg_ctx *context_datasetmessage, void *user_data)
	Callback which allows the application to write the DataSet message payload for a DataSetWriter. More...

Detailed Description

Functions and definitions for the PubSub module in the server.

Typedef Documentation

datasetreader_dispatch_cb_fn

typedef int(* datasetreader_dispatch_cb_fn) (struct ua_decoder_context *decoder, struct pubsub_datasetmsg_ctx *context_datasetmessage, void *user_data)

Callback which allows the application to process the DataSet message for a DataSetReader.

Parameters

[in]	decoder	Decoder used to read the DataSet message payload from the network message buffer
[in,out]	context_datasetmessage	Header and status fields for the DataSet message received
[in]	user_data	User data provided for the processing of the DataSetReader in pubsub_module_callback

Returns

0 on success, -1 otherwise.

Enumeration Type Documentation

PUBSUB_MODULE_CONFIG

enum PUBSUB_MODULE_CONFIG

Controls how the pubsub configuration is loaded.

Enumerator
PUBSUB_MODULE_CONFIG_NONE	None of the other flags is set.
PUBSUB_MODULE_CONFIG_FILE	Try to load config from file.
PUBSUB_MODULE_CONFIG_FILE_IGN_INVALID	Ignore errors when loading config from file.
PUBSUB_MODULE_CONFIG_FILETYPE_CREATE	Create a filetype object to load a config.
PUBSUB_MODULE_CONFIG_DISABLE_COMMUNICATION	Manage configuration but disable communication.

Function Documentation

pubsub_module_cleanup()

SERVER_EXPORT void pubsub_module_cleanup

(

void

)

Cleanup PubSub module.

Stops publishing/subscribing and cleans up all resources like a set configuration and filetype.

pubsub_module_get_config()

SERVER_EXPORT const struct ua_uabinaryfiledatatype* pubsub_module_get_config

(

void

)

Returns the configuration currently used by the pubsub module.

This configuration is just for reading and may not be modified.

Returns

Pointer to configuration or NULL if none is set.

pubsub_module_get_dataset_reader()

SERVER_EXPORT const struct ua_datasetreaderdatatype* pubsub_module_get_dataset_reader

(

pubsub_handle

dataset_reader

)

Get DataSetReader configuration structure.

Parameters

dataset_reader

PubSub stack handle for the DataSetReader

Returns

DataSetReader configuration structure on success and NULL on failure

pubsub_module_get_dataset_writer()

SERVER_EXPORT const struct ua_datasetwriterdatatype* pubsub_module_get_dataset_writer

(

pubsub_handle

dataset_writer

)

Get DataSetWriter configuration structure.

Parameters

dataset_writer

PubSub stack handle for the DataSetWriter

Returns

DataSetWriter configuration structure on success and NULL on failure

pubsub_module_get_defaultpublisherid()

SERVER_EXPORT int pubsub_module_get_defaultpublisherid

(

uint64_t *

default_publisher_id

)

Get default publisher id for datagram connections.

Returns

0 on success or errorcode

pubsub_module_get_published_dataset()

SERVER_EXPORT const struct ua_publisheddatasetdatatype* pubsub_module_get_published_dataset

(

pubsub_handle

dataset_writer

)

Get PublishedDataSet configuration structure for a DataSetWriter.

Parameters

dataset_writer

PubSub stack handle for the DataSetWriter

Returns

PublishedDataSet configuration structure on success and NULL on failure

pubsub_module_get_pubsub_connection()

SERVER_EXPORT const struct ua_pubsubconnectiondatatype* pubsub_module_get_pubsub_connection

(

pubsub_handle

connection

)

Get PubSubConnection configuration structure.

Parameters

connection

PubSub stack handle for the PubSubConnection

Returns

PubSubConnection configuration structure on success and NULL on failure

pubsub_module_get_writer_group()

SERVER_EXPORT const struct ua_writergroupdatatype* pubsub_module_get_writer_group

(

pubsub_handle

writer_group

)

Get WriterGroup configuration structure.

Parameters

writer_group

PubSub stack handle for the WriterGroup

Returns

WriterGroup configuration structure on success and NULL on failure

pubsub_module_init()

SERVER_EXPORT int pubsub_module_init

(

uint32_t

mode

)

Initialize the PubSub module.

This function must be called before any of the other pubsub_module_set_config_* functions like pubsub_module_set_config_file. The function can be influenced by the mode, which is a bitmask of PUBSUB_MODULE_CONFIG values.

If PUBSUB_MODULE_CONFIG_FILE is set, a pubsub config is loaded from a file. The filename is taken from the appconfig, or if not set the default PUBSUB_DEFAULT_CONFIG_FILENAME is used. To suppress errors when the file does not exists or does not contain a valid config, the additional flag PUBSUB_MODULE_CONFIG_FILE_IGN_INVALID can be set. If file IO is disabled there is still an error returned.

If PUBSUB_MODULE_CONFIG_FILETYPE_CREATE is set, the PubSubConfiguration object functionality is activated to handle pubsub configuration read and update through the standard PubSubConfiguration file object. Only members of the Role ConfigureAdmin are able to read or write the PubSubConfiguration file object.

If PUBSUB_MODULE_CONFIG_DISABLE_COMMUNICATION is set, the instance of the PubSub stack does not start and PubSub communication but manages the PubSub configuration and security keys. This can be used to manage the PubSub configuration in a server process but to run the PubSub communication in another process.

After successful initialization a config can be set with any of the pubsub_module_set_config_* functions, in case the pubsub module is already running, the configuration is replaced with the new one and the module is restarted.

Returns

Zero on success or errorcode on failure.

pubsub_module_publish()

SERVER_EXPORT void pubsub_module_publish

(

pubsub_handle

writer_group

)

Publish WriterGroup to send NetworkMaesage(s) for the WriterGroup.

Parameters

writer_group

PubSub stack handle for the WriterGroup

pubsub_module_sample()

SERVER_EXPORT void pubsub_module_sample

(

pubsub_handle

writer_group

)

Sample WriterGroup to create NetworkMaesage(s) for the WriterGroup.

Parameters

writer_group

PubSub stack handle for the WriterGroup

pubsub_module_set_callback()

SERVER_EXPORT void pubsub_module_set_callback

(

struct pubsub_module_callback *

pubsub_module_cb

)

Set PubSub module callback.

Parameters

pubsub_module_cb

PubSub module callback interface

pubsub_module_set_config_callback()

SERVER_EXPORT void pubsub_module_set_config_callback

(

struct pubsub_module_config_callback *

pubsub_config_cb

)

Set PubSub module callback.

Parameters

pubsub_config_cb

Interface to overwrite default configuration persisting behaviour

pubsub_module_set_config_data()

SERVER_EXPORT int pubsub_module_set_config_data

(

const struct ua_bytestring *

data

)

Set a new PubSub configuration as UA binary encoded structure.

This setter must only be called after pubsub_module_init, it loads the config and starts the pubsub module. If the module is already running, it is stopped, the new config is loaded and the module is restarted. In case of an error the old config is restored and the module tries to restart with the old config. In this case an error is still returned.

Parameters

data	PubSub configuration data as encoded ua_uabinaryfiledatatype.

Returns

Zero on success, a negative status code if the operation fails.

pubsub_module_set_config_file()

SERVER_EXPORT int pubsub_module_set_config_file

(

const char *

filename

)

Set a new PubSub configuration from a file.

This setter must only be called after pubsub_module_init, it loads the config and starts the pubsub module. If the module is already running, it is stopped, the new config is loaded and the module is restarted. In case of an error the old config is restored and the module tries to restart with the old config. In this case an error is still returned.

The file needs to contain a ua_uabinaryfiledatatype encoded in UA binary format.

Parameters

filename

Path and name of the file containing the configuration data.

Returns

Zero on success, a negative status code if the operation fails.

pubsub_module_set_config_permissions()

SERVER_EXPORT int pubsub_module_set_config_permissions	(	uint16_t	num_permissions,
		const struct ua_nodepermission *	permissions
	)

Set PubSub configuration permissions.

Overrides the default configuration permissions. The default permissions allow read access for Anonymous and AuthenticatedUser roles and write access for the ConfigAdmin role.

Parameters

num_permissions	number of configuration permissions
permissions	configuration permissions

pubsub_module_set_config_struct()

SERVER_EXPORT int pubsub_module_set_config_struct

(

struct ua_uabinaryfiledatatype *

config

)

Set a new PubSub configuration as structure.

This setter must only be called after pubsub_module_init, it loads the config and starts the pubsub module. If the module is already running, it is stopped, the new config is loaded and the module is restarted. In case of an error the old config is restored and the module tries to restart with the old config. In this case an error is still returned.

This function always takes ownership of the given config, even in case of error. So the caller may no longer access the struct.

Parameters

config

PubSub configuration data as a ua_uabinaryfiledatatype structure.

Returns

Zero on success, a negative status code if the operation fails.

pubsub_module_set_config_struct_const()

SERVER_EXPORT int pubsub_module_set_config_struct_const

(

const struct ua_uabinaryfiledatatype *

config

)

Set a new PubSub configuration as constant structure.

This setter must only be called after pubsub_module_init, it loads the config and starts the pubsub module. If the module is already running, it is stopped, the new config is loaded and the module is restarted. In case of an error the old config is restored and the module tries to restart with the old config. In this case an error is still returned.

This function creates a copy of the given config and does not modify the original one.

Parameters

config

PubSub configuration data as a ua_uabinaryfiledatatype structure.

Returns

Zero on success, a negative status code if the operation fails.

pubsub_module_set_defaultpublisherid()

SERVER_EXPORT int pubsub_module_set_defaultpublisherid

(

uint64_t

default_publisher_id

)

Set default publisher id for datagram connections.

Returns

0 on success or errorcode

pubsub_module_set_namespacetable_callback()

SERVER_EXPORT void pubsub_module_set_namespacetable_callback	(	pubsub_module_nstable_get_fn	nstable_cb,
		void *	arg
	)

Set custom callback to provide a namespace table to the pubsub stack.

Must be called before pubsub_module_init().

Parameters

nstable_cb	callback function
arg	user data that will be provided to the callback

pubsub_module_set_network_backend()

SERVER_EXPORT void pubsub_module_set_network_backend

(

struct pubsub_backend *

pubsub_network_backend

)

Set custom PubSub network backend.

Parameters

pubsub_network_backend

Interface of the custom network backend

Variable Documentation

datasetwriter_sample_cb_fn

UA_BEGIN_EXTERN_C typedef int(* datasetwriter_sample_cb_fn) (struct ua_encoder_context *encoder, struct pubsub_datasetmsg_ctx *context_datasetmessage, void *user_data)

Callback which allows the application to write the DataSet message payload for a DataSetWriter.

Parameters

[in]	encoder	Encoder used to write the DataSet message payload into the network message buffer
[in,out]	context_datasetmessage	Header and status fields for the DataSet message. The callback may modify fields, especially the valid flag and the status
[in]	user_data	User data provided for the processing of the DataSetWriter in pubsub_module_callback

Returns

0 on success, -1 otherwise.