Source Code API Reference

This section provides the internal API reference for the EPICS OPC UA Device Support, generated from the source code Doxygen comments.

class Session

The Session interface to the client side OPC UA session.

Main interface for connecting with any OPC UA Server. The implementation manages the connection to an OPC Unified Architecture server and the application session established with it.

The connect call establishes and maintains a Session with a Server.

The disconnect call disconnects the Session, deleting all Subscriptions and freeing all related resources on both server and client.

Subclassed by DevOpcua::SessionOpen62541, DevOpcua::SessionUaSdk

Public Functions

virtual long connect(bool manual = true) = 0

Connect the underlying OPC UA Session.

Try connecting the session to the OPC UA server.

Non-blocking. Connection status changes shall be reported through a callback interface.

If the connection attempt fails and the autoConnect flag is true, the reconnect timer shall be restarted.

The manual parameter does not affect the OPC UA functional part, but enables printing the result of the connect service. (Logging failures because of autoconnect attempts is suppressed.)

Parameters:: manual – set if called as a result of a manual action
Returns:: long status (0 = OK)

virtual long disconnect() = 0

Disconnect the underlying OPC UA Session.

Disconnect the session from the OPC UA server.

This shall delete all subscriptions related to the session on both client and server side, and free all connected resources. The disconnect shall complete and the status change to disconnected even if the underlying service fails and a bad status is returned.

The call shall block until all outstanding service calls and active client-side callbacks have been completed. Those are not allowed to block, else client deadlocks will appear.

Connection status changes shall be reported through a callback interface.

Returns:: long status (0 = OK)

virtual bool isConnected() const = 0

Return connection status of the underlying OPC UA Session.

Returns:: bool connection status

virtual const std::string &getName() const = 0

Get session name.

Returns:: const std::string & name

virtual void show(const int level) const = 0

Print configuration and status on stdout.

The verbosity level controls the amount of information: 0 = one line 1 = session line, then one line per subscription

Parameters:: level – verbosity level

virtual void showSecurity() = 0: Do a discovery and show the available endpoints.

virtual void setOption(const std::string &name, const std::string &value) = 0

Set an option for the session.

Parameters:

name – option name
value – value

virtual void addNamespaceMapping(const unsigned short nsIndex, const std::string &uri) = 0

Add namespace index mapping (local index -> URI).

Parameters:

nsIndex – local namespace index
uri – namespace URI

Public Members

int debug: debug verbosity level

Public Static Functions

static void showAll(const int level)

Print configuration and status of all sessions on stdout.

The verbosity level controls the amount of information: 0 = one summary 1 = one line per session 2 = one session line, then one line per subscription

Parameters:: level – verbosity level

static void showClientSecurity(): Show client security setup and certificate info.

static Session *createSession(const std::string &name, const std::string &url)

Factory method to create a session (implementation specific).

Parameters:

name – name of the new session
url – url of the server to connect
debuglevel – initial debug level
autoconnect – connect automatically at IOC init

Returns:

pointer to the new session, nullptr if not created

static Session *find(const std::string &name)

Find a session by name (implementation specific).

Parameters:: name – session name to search for
Returns:: pointer to session, nullptr if not found

static std::set<Session*> glob(const std::string &pattern)

Find sessions with names matching a glob pattern.

Parameters:: pattern – session name pattern to match
Returns:: set of pointers to matching sessions

static inline void setClientCertificate(const std::string &&pubKey, const std::string &&prvKey)

Set client certificate (public key, private key) file paths.

Parameters:

pubPath – full path to certificate (public key)
prvPath – full path to private key file

static void setupPKI(const std::string &&certTrustList, const std::string &&certRevocationList, const std::string &&issuersTrustList, const std::string &&issuersRevocationList)

Setup client PKI (cert store locations).

Parameters:

certTrustList – server certificate location
certRevocationList – server revocation list location
issuersTrustList – issuers certificate location
issuersRevocationList – issuers revocation list location

static void saveRejected(const std::string &location = "")

Enable saving of rejected (untrusted) server certificates.

Parameters:: location – location for saving rejected certs (empty = use default)

static void initOnce(void *junk): epicsThreadOnce runner

Public Static Attributes

static const char optionUsage [] = "Sets options for existing OPC UA sessions orsubscriptions.\n\n""patternpattern for session or subscription names (* and ? supported)\n" "[options] list of options in 'key=value' format\n\n""Valid sessionoptionsare:\n""debugdebug level [default 0 = no debug]\n" "autoconnect automatically connect sessions [default y]\n" "nodes-max max. nodes per service call [0 = no limit]\n" "read-nodes-max max. nodes per read service call [0 = no limit]\n" "read-timeout-min min. timeout (holdoff) after read service call [ms]\n" "read-timeout-maxtimeout (holdoff) after read service call w/ max elements [ms]\n" "write-nodes-max max. nodes per write service call [0 = no limit]\n" "write-timeout-min min. timeout (holdoff) after write service call [ms]\n" "write-timeout-maxtimeout (holdoff) after write service call w/ max elements [ms]\n" "sec-moderequested securitymode\n""sec-policyrequested securitypolicy\n""ident-filefile to read identity credentialsfrom\n\n""": option info for the specific implementation

static epicsThreadOnceId onceId = EPICS_THREAD_ONCE_INIT: epicsThreadOnce id

class Subscription

The Subscription interface for a UA client created subscription.

The interface provides all subscription related UA services.

Subclassed by DevOpcua::SubscriptionOpen62541, DevOpcua::SubscriptionUaSdk

Public Functions

virtual void show(int level) const = 0

Print configuration and status on stdout.

The verbosity level controls the amount of information: 0 = one line

Parameters:: level – verbosity level

virtual void setOption(const std::string &name, const std::string &value) = 0

Set an option for the subscription.

Parameters:

name – option name
value – value

virtual Session &getSession() const = 0

Get the session that this subscription is running on.

Returns:: Session

Public Members

const std::string name: subscription name

int debug: debug verbosity level

Public Static Functions

static Subscription *createSubscription(const std::string &name, const std::string &session, const double publishingInterval)

Factory method to create a subscription (implementation specific).

Parameters:

name – subscription name
session – session that the subscription should be linked to
publishingInterval – initial publishing interval

Returns:

pointer to the new subscription, nullptr if not created

static void showAll(int level)

Print configuration and status of all subscriptions on stdout.

The verbosity level controls the amount of information: 0 = one summary line 1 = one line per subscription 2 = one subscription line, then one line per monitored item

Parameters:: level – verbosity level

static Subscription *find(const std::string &name)

Find a subscription by name (implementation specific).

Parameters:: name – subscription name
Returns:: pointer to subscription, nullptr if not found

static std::set<Subscription*> glob(const std::string &pattern)

Find subscriptions with names matching a glob pattern.

Parameters:: pattern – subscription name pattern to match
Returns:: set of pointers to matching subscriptions

Public Static Attributes

static const char optionUsage [] = "Valid subscription optionsare:\n""debugdebug level [default 0 = no debug]\n" "priority priority level [default 0(lowest) .. 255]\n" "": option info for the specific implementation

class Item

The Item interface for an OPC UA item.

The interface provides all item related configuration and functionality.

Subclassed by DevOpcua::ItemOpen62541, DevOpcua::ItemUaSdk

Public Functions

virtual void requestRead() = 0: Schedule a read request (using beginRead service).

virtual void requestWrite() = 0: Schedule a write request (using beginWrite service).

virtual void requestWriteIfDirty() = 0: Schedule a write request if item data is “dirty”.

virtual void getStatus(epicsUInt32 *code, char *text = nullptr, const epicsUInt32 len = 0, epicsTimeStamp *ts = nullptr) = 0

Get the cached status of the last item operation.

Parameters:

code – [out] OPC UA status code
text – [out] OPC UA status text (will be null terminated)
len – [in] Length of text buffer
ts – [out] EPICS timestamp

virtual void setState(const ConnectionStatus state) = 0

Set the EPICS-related state of the item.

Parameters:: newState – state to be set

virtual void show(int level) const = 0

Print configuration and status on stdout.

The verbosity level controls the amount of information: 0 = one line 1 = item line, then one line per data element

Parameters:: level – verbosity level

virtual bool isMonitored() const = 0

Return the monitored status of the item.

Returns:: true if item is monitored

Public Members

const linkInfo &linkinfo: configuration of the item as parsed from the EPICS record

RecordConnector *recConnector: pointer to the relevant recordConnector

Public Static Functions

static Item *newItem(const linkInfo &info)

Factory method to dynamically create an Item of the specific implementation.

Parameters:: info – linkinfo data of the parsed record link
Returns:: pointer to the Item base class of the created object

class DataElement

The DataElement interface for a single piece of data.

A data element can either be the top level data of an item (in that case its name is an empty string) or be an element of a structured data type (in that case name is the data element name).

Inside a structure, a data element can either be a leaf, i.e. be of one of the builtin types and connected to a record (through the pconnector member) or be a node of a structured data type and contain a list of its child elements.

As resource conflicts can only occur in nodes that are accessed by records (database side) and items (OPC UA side), the RecordConnector lock must be held when operating on a data element.

Subclassed by DevOpcua::DataElementOpen62541Leaf, DevOpcua::DataElementUaSdkLeaf

Public Functions

void setRecordConnector(RecordConnector *connector)

Setter to create a (bidirectional) link to a RecordConnector.

Sets the internal pointer to the record connector as well as the inverse link in the record connector that points back.

An existing link is cleanly removed before the new link is set up.

Parameters:: connector – pointer to the RecordConnector to link to

virtual void show(const int level, const unsigned int indent) const = 0

Print configuration and status on stdout.

The verbosity level controls the amount of information: 0 = one line

Parameters:

level – verbosity level
indent – indentation level

virtual long readScalar(epicsInt32 *value, dbCommon *prec, ProcessReason *nextReason = nullptr, epicsUInt32 *statusCode = nullptr, char *statusText = nullptr, const epicsUInt32 statusTextLen = MAX_STRING_SIZE + 1) = 0

Read incoming data as a scalar epicsInt32.

Takes the next element off the queue of incoming data, converts it to the target EPICS type, sets the record’s STAT/SEVR according to the ProcessReason, status code and success of the conversion, and returns the value, the ProcessReason of the next queue element, the time stamp, the status code and text of the OPC UA status of the item related to this DataElement.

Parameters:

value – [out] set to value
prec – [in] pointer to EPICS record
nextReason – [out] set to ProcessReason for the next update, none if last element
statusCode – [out] set to the OPC UA status code of the update
statusText – [out] set to the OPC UA status text of the update (will be null terminated)
statusTextLen – [in] length of the statusText buffer

Returns:

status 0 = ok, 1 = error

virtual long readScalar(epicsInt64 *value, dbCommon *prec, ProcessReason *nextReason = nullptr, epicsUInt32 *statusCode = nullptr, char *statusText = nullptr, const epicsUInt32 statusTextLen = MAX_STRING_SIZE + 1) = 0

Read incoming data as a scalar epicsInt64.

Takes the next element off the queue of incoming data, converts it to the target EPICS type, sets the record’s STAT/SEVR according to the ProcessReason, status code and success of the conversion, and returns the value, the ProcessReason of the next queue element, the time stamp, the status code and text of the OPC UA status of the item related to this DataElement.

Parameters:

value – [out] set to value
prec – [in] pointer to EPICS record
nextReason – [out] set to ProcessReason for the next update, none if last element
statusCode – [out] set to the OPC UA status code of the update
statusText – [out] set to the OPC UA status text of the update (will be null terminated)
statusTextLen – [in] length of the statusText buffer

Returns:

status 0 = ok, 1 = error

virtual long readScalar(epicsUInt32 *value, dbCommon *prec, ProcessReason *nextReason = nullptr, epicsUInt32 *statusCode = nullptr, char *statusText = nullptr, const epicsUInt32 statusTextLen = MAX_STRING_SIZE + 1) = 0

Read incoming data as a scalar epicsUInt32.

Takes the next element off the queue of incoming data, converts it to the target EPICS type, sets the record’s STAT/SEVR according to the ProcessReason, status code and success of the conversion, and returns the value, the ProcessReason of the next queue element, the time stamp, the status code and text of the OPC UA status of the item related to this DataElement.

Parameters:

value – [out] set to value
prec – [in] pointer to EPICS record
nextReason – [out] set to ProcessReason for the next update, none if last element
statusCode – [out] set to the OPC UA status code of the update
statusText – [out] set to the OPC UA status text of the update (will be null terminated)
statusTextLen – [in] length of the statusText buffer

Returns:

status 0 = ok, 1 = error

virtual long readScalar(epicsFloat64 *value, dbCommon *prec, ProcessReason *nextReason = nullptr, epicsUInt32 *statusCode = nullptr, char *statusText = nullptr, const epicsUInt32 statusTextLen = MAX_STRING_SIZE + 1) = 0

Read incoming data as a scalar epicsFloat64.

Takes the next element off the queue of incoming data, converts it to the target EPICS type, sets the record’s STAT/SEVR according to the ProcessReason, status code and success of the conversion, and returns the value, the ProcessReason of the next queue element, the time stamp, the status code and text of the OPC UA status of the item related to this DataElement.

Parameters:

value – [out] set to value
prec – [in] pointer to EPICS record
nextReason – [out] set to ProcessReason for the next update, none if last element
statusCode – [out] set to the OPC UA status code of the update
statusText – [out] set to the OPC UA status text of the update (will be null terminated)
statusTextLen – [in] length of the statusText buffer

Returns:

status 0 = ok, 1 = error

virtual long readScalar(char *value, const epicsUInt32 len, dbCommon *prec, ProcessReason *nextReason = nullptr, epicsUInt32 *lenRead = nullptr, epicsUInt32 *statusCode = nullptr, char *statusText = nullptr, const epicsUInt32 statusTextLen = MAX_STRING_SIZE + 1) = 0

Read incoming data as a classic C string (null terminated array of char).

Takes the next element off the queue of incoming data, converts it to the target type, sets the record’s STAT/SEVR according to the ProcessReason, status code and success of the conversion, and returns the value, the ProcessReason of the next queue element, the time stamp, the status code and text of the OPC UA status of the item related to this DataElement.

Parameters:

value – [out] target string buffer
len – [in] length of target string buffer (including null byte)
prec – [in] pointer to EPICS record
nextReason – [out] set to ProcessReason for the next update, none if last element
lenRead – [out] actual number of chars read (may be NULL)
statusCode – [out] set to the OPC UA status code of the update
statusText – [out] set to the OPC UA status text of the update (will be null terminated)
statusTextLen – [in] length of the statusText buffer

Returns:

status 0 = ok, 1 = error

virtual long readArray(epicsInt8 *value, const epicsUInt32 num, epicsUInt32 *numRead, dbCommon *prec, ProcessReason *nextReason = nullptr, epicsUInt32 *statusCode = nullptr, char *statusText = nullptr, const epicsUInt32 statusTextLen = MAX_STRING_SIZE + 1) = 0

Read incoming data as array of epicsInt8.

Takes the next element off the queue of incoming data, converts it to the target type, sets the record’s STAT/SEVR according to the ProcessReason, status code and success of the conversion, and writes the value, the ProcessReason of the next queue element, the time stamp, the status code and text of the OPC UA status of the item related to this DataElement.

Parameters:

value – [out] pointer to target array
num – [in] target array size
numRead – [out] number of elements written
prec – [in] pointer to EPICS record
nextReason – [out] set to ProcessReason for the next update, none if last element
statusCode – [out] set to the OPC UA status code of the update
statusText – [out] set to the OPC UA status text of the update (will be null terminated)
statusTextLen – [in] length of the statusText buffer

Returns:

status 0 = ok, 1 = error

virtual long readArray(epicsUInt8 *value, const epicsUInt32 num, epicsUInt32 *numRead, dbCommon *prec, ProcessReason *nextReason = nullptr, epicsUInt32 *statusCode = nullptr, char *statusText = nullptr, const epicsUInt32 statusTextLen = MAX_STRING_SIZE + 1) = 0

Read incoming data as array of epicsUInt8.

Takes the next element off the queue of incoming data, converts it to the target type, sets the record’s STAT/SEVR according to the ProcessReason, status code and success of the conversion, and writes the value, the ProcessReason of the next queue element, the time stamp, the status code and text of the OPC UA status of the item related to this DataElement.

Parameters:

value – [out] pointer to target array
num – [in] target array size
numRead – [out] number of elements written
prec – [in] pointer to EPICS record
nextReason – [out] set to ProcessReason for the next update, none if last element
statusCode – [out] set to the OPC UA status code of the update
statusText – [out] set to the OPC UA status text of the update (will be null terminated)
statusTextLen – [in] length of the statusText buffer

Returns:

status 0 = ok, 1 = error

virtual long readArray(epicsInt16 *value, const epicsUInt32 num, epicsUInt32 *numRead, dbCommon *prec, ProcessReason *nextReason = nullptr, epicsUInt32 *statusCode = nullptr, char *statusText = nullptr, const epicsUInt32 statusTextLen = MAX_STRING_SIZE + 1) = 0

Read incoming data as array of epicsInt16.

Takes the next element off the queue of incoming data, converts it to the target type, sets the record’s STAT/SEVR according to the ProcessReason, status code and success of the conversion, and writes the value, the ProcessReason of the next queue element, the time stamp, the status code and text of the OPC UA status of the item related to this DataElement.

Parameters:

value – [out] pointer to target array
num – [in] target array size
numRead – [out] number of elements written
prec – [in] pointer to EPICS record
nextReason – [out] set to ProcessReason for the next update, none if last element
statusCode – [out] set to the OPC UA status code of the update
statusText – [out] set to the OPC UA status text of the update (will be null terminated)
statusTextLen – [in] length of the statusText buffer

Returns:

status 0 = ok, 1 = error

virtual long readArray(epicsUInt16 *value, const epicsUInt32 num, epicsUInt32 *numRead, dbCommon *prec, ProcessReason *nextReason = nullptr, epicsUInt32 *statusCode = nullptr, char *statusText = nullptr, const epicsUInt32 statusTextLen = MAX_STRING_SIZE + 1) = 0

Read incoming data as array of epicsUInt16.

Takes the next element off the queue of incoming data, converts it to the target type, sets the record’s STAT/SEVR according to the ProcessReason, status code and success of the conversion, and writes the value, the ProcessReason of the next queue element, the time stamp, the status code and text of the OPC UA status of the item related to this DataElement.

Parameters:

value – [out] pointer to target array
num – [in] target array size
numRead – [out] number of elements written
prec – [in] pointer to EPICS record
nextReason – [out] set to ProcessReason for the next update, none if last element
statusCode – [out] set to the OPC UA status code of the update
statusText – [out] set to the OPC UA status text of the update (will be null terminated)
statusTextLen – [in] length of the statusText buffer

Returns:

status 0 = ok, 1 = error

virtual long readArray(epicsInt32 *value, const epicsUInt32 num, epicsUInt32 *numRead, dbCommon *prec, ProcessReason *nextReason = nullptr, epicsUInt32 *statusCode = nullptr, char *statusText = nullptr, const epicsUInt32 statusTextLen = MAX_STRING_SIZE + 1) = 0

Read incoming data as array of epicsInt32.

Takes the next element off the queue of incoming data, converts it to the target type, sets the record’s STAT/SEVR according to the ProcessReason, status code and success of the conversion, and writes the value, the ProcessReason of the next queue element, the time stamp, the status code and text of the OPC UA status of the item related to this DataElement.

Parameters:

value – [out] pointer to target array
num – [in] target array size
numRead – [out] number of elements written
prec – [in] pointer to EPICS record
nextReason – [out] set to ProcessReason for the next update, none if last element
statusCode – [out] set to the OPC UA status code of the update
statusText – [out] set to the OPC UA status text of the update (will be null terminated)
statusTextLen – [in] length of the statusText buffer

Returns:

status 0 = ok, 1 = error

virtual long readArray(epicsUInt32 *value, const epicsUInt32 num, epicsUInt32 *numRead, dbCommon *prec, ProcessReason *nextReason = nullptr, epicsUInt32 *statusCode = nullptr, char *statusText = nullptr, const epicsUInt32 statusTextLen = MAX_STRING_SIZE + 1) = 0

Read incoming data as array of epicsUInt32.

Takes the next element off the queue of incoming data, converts it to the target type, sets the record’s STAT/SEVR according to the ProcessReason, status code and success of the conversion, and writes the value, the ProcessReason of the next queue element, the time stamp, the status code and text of the OPC UA status of the item related to this DataElement.

Parameters:

value – [out] pointer to target array
num – [in] target array size
numRead – [out] number of elements written
prec – [in] pointer to EPICS record
nextReason – [out] set to ProcessReason for the next update, none if last element
statusCode – [out] set to the OPC UA status code of the update
statusText – [out] set to the OPC UA status text of the update (will be null terminated)
statusTextLen – [in] length of the statusText buffer

Returns:

status 0 = ok, 1 = error

virtual long readArray(epicsInt64 *value, const epicsUInt32 num, epicsUInt32 *numRead, dbCommon *prec, ProcessReason *nextReason = nullptr, epicsUInt32 *statusCode = nullptr, char *statusText = nullptr, const epicsUInt32 statusTextLen = MAX_STRING_SIZE + 1) = 0

Read incoming data as array of epicsInt64.

Takes the next element off the queue of incoming data, converts it to the target type, sets the record’s STAT/SEVR according to the ProcessReason, status code and success of the conversion, and writes the value, the ProcessReason of the next queue element, the time stamp, the status code and text of the OPC UA status of the item related to this DataElement.

Parameters:

value – [out] pointer to target array
num – [in] target array size
numRead – [out] number of elements written
prec – [in] pointer to EPICS record
nextReason – [out] set to ProcessReason for the next update, none if last element
statusCode – [out] set to the OPC UA status code of the update
statusText – [out] set to the OPC UA status text of the update (will be null terminated)
statusTextLen – [in] length of the statusText buffer

Returns:

status 0 = ok, 1 = error

virtual long readArray(epicsUInt64 *value, const epicsUInt32 num, epicsUInt32 *numRead, dbCommon *prec, ProcessReason *nextReason = nullptr, epicsUInt32 *statusCode = nullptr, char *statusText = nullptr, const epicsUInt32 statusTextLen = MAX_STRING_SIZE + 1) = 0

Read incoming data as array of epicsUInt64.

Takes the next element off the queue of incoming data, converts it to the target type, sets the record’s STAT/SEVR according to the ProcessReason, status code and success of the conversion, and writes the value, the ProcessReason of the next queue element, the time stamp, the status code and text of the OPC UA status of the item related to this DataElement.

Parameters:

value – [out] pointer to target array
num – [in] target array size
numRead – [out] number of elements written
prec – [in] pointer to EPICS record
nextReason – [out] set to ProcessReason for the next update, none if last element
statusCode – [out] set to the OPC UA status code of the update
statusText – [out] set to the OPC UA status text of the update (will be null terminated)
statusTextLen – [in] length of the statusText buffer

Returns:

status 0 = ok, 1 = error

virtual long readArray(epicsFloat32 *value, const epicsUInt32 num, epicsUInt32 *numRead, dbCommon *prec, ProcessReason *nextReason = nullptr, epicsUInt32 *statusCode = nullptr, char *statusText = nullptr, const epicsUInt32 statusTextLen = MAX_STRING_SIZE + 1) = 0

Read incoming data as array of epicsFloat32.

Takes the next element off the queue of incoming data, converts it to the target type, sets the record’s STAT/SEVR according to the ProcessReason, status code and success of the conversion, and writes the value, the ProcessReason of the next queue element, the time stamp, the status code and text of the OPC UA status of the item related to this DataElement.

Parameters:

value – [out] pointer to target array
num – [in] target array size
numRead – [out] number of elements written
prec – [in] pointer to EPICS record
nextReason – [out] set to ProcessReason for the next update, none if last element
statusCode – [out] set to the OPC UA status code of the update
statusText – [out] set to the OPC UA status text of the update (will be null terminated)
statusTextLen – [in] length of the statusText buffer

Returns:

status 0 = ok, 1 = error

virtual long readArray(epicsFloat64 *value, const epicsUInt32 num, epicsUInt32 *numRead, dbCommon *prec, ProcessReason *nextReason = nullptr, epicsUInt32 *statusCode = nullptr, char *statusText = nullptr, const epicsUInt32 statusTextLen = MAX_STRING_SIZE + 1) = 0

Read incoming data as array of epicsFloat64.

Takes the next element off the queue of incoming data, converts it to the target type, sets the record’s STAT/SEVR according to the ProcessReason, status code and success of the conversion, and writes the value, the ProcessReason of the next queue element, the time stamp, the status code and text of the OPC UA status of the item related to this DataElement.

Parameters:

value – [out] pointer to target array
num – [in] target array size
numRead – [out] number of elements written
prec – [in] pointer to EPICS record
nextReason – [out] set to ProcessReason for the next update, none if last element
statusCode – [out] set to the OPC UA status code of the update
statusText – [out] set to the OPC UA status text of the update (will be null terminated)
statusTextLen – [in] length of the statusText buffer

Returns:

status 0 = ok, 1 = error

virtual long readArray(char *value, const epicsUInt32 len, const epicsUInt32 num, epicsUInt32 *numRead, dbCommon *prec, ProcessReason *nextReason = nullptr, epicsUInt32 *statusCode = nullptr, char *statusText = nullptr, const epicsUInt32 statusTextLen = MAX_STRING_SIZE + 1) = 0

Read incoming data as array of EPICS String type (char[MAX_STRING_SIZE]).

Takes the next element off the queue of incoming data, converts it to the target type, sets the record’s STAT/SEVR according to the ProcessReason, status code and success of the conversion, and writes the value, the ProcessReason of the next queue element, the time stamp, the status code and text of the OPC UA status of the item related to this DataElement.

Parameters:

value – [out] pointer to target array
len – [in] length of an EPICS String element
num – [in] target array size
numRead – [out] number of elements written
prec – [in] pointer to EPICS record
nextReason – [out] set to ProcessReason for the next update, none if last element
statusCode – [out] set to the OPC UA status code of the update
statusText – [out] set to the OPC UA status text of the update (will be null terminated)
statusTextLen – [in] length of the statusText buffer

Returns:

status 0 = ok, 1 = error

virtual long writeScalar(const epicsInt32 &value, dbCommon *prec) = 0

Write outgoing scalar epicsInt32 data.

Takes the provided data value, converts it to the target OPC UA type, sets the record’s STAT/SEVR according to the success of the conversion, and triggers an OPC UA write operation.

Parameters:

value – set to value
prec – pointer to EPICS record

Returns:

status 0 = ok, 1 = error

virtual long writeScalar(const epicsInt64 &value, dbCommon *prec) = 0

Write outgoing scalar epicsInt64 data.

Takes the provided data value, converts it to the target OPC UA type, sets the record’s STAT/SEVR according to the success of the conversion, and triggers an OPC UA write operation.

Parameters:

value – set to value
prec – pointer to EPICS record

Returns:

status 0 = ok, 1 = error

virtual long writeScalar(const epicsUInt32 &value, dbCommon *prec) = 0

Write outgoing scalar epicsUInt32 data.

Takes the provided data value, converts it to the target OPC UA type, sets the record’s STAT/SEVR according to the success of the conversion, and triggers an OPC UA write operation.

Parameters:

value – set to value
prec – pointer to EPICS record

Returns:

status 0 = ok, 1 = error

virtual long writeScalar(const epicsFloat64 &value, dbCommon *prec) = 0

Write outgoing scalar epicsFloat64 data.

Takes the provided data value, converts it to the target OPC UA type, sets the record’s STAT/SEVR according to the success of the conversion, and triggers an OPC UA write operation.

Parameters:

value – set to value
prec – pointer to EPICS record

Returns:

status 0 = ok, 1 = error

virtual long writeScalar(const char *value, const epicsUInt32 len, dbCommon *prec) = 0

Write outgoing classic C string (char[]) data.

Parameters:

value – pointer to null terminated source string
len – source string length
prec – pointer to EPICS record

Returns:

status 0 = ok, 1 = error

virtual long writeArray(const epicsInt8 *value, const epicsUInt32 num, dbCommon *prec) = 0

Write outgoing array of epicsInt8 data.

Takes the provided data value, converts it to the target OPC UA type, sets the record’s STAT/SEVR according to the success of the conversion, and triggers an OPC UA write operation.

Parameters:

value – pointer to source array
num – source array size
prec – pointer to EPICS record

Returns:

status 0 = ok, 1 = error

virtual long writeArray(const epicsUInt8 *value, const epicsUInt32 num, dbCommon *prec) = 0

Write outgoing array of epicsUInt8 data.

Takes the provided data value, converts it to the target OPC UA type, sets the record’s STAT/SEVR according to the success of the conversion, and triggers an OPC UA write operation.

Parameters:

value – pointer to source array
num – source array size
prec – pointer to EPICS record

Returns:

status 0 = ok, 1 = error

virtual long writeArray(const epicsInt16 *value, const epicsUInt32 num, dbCommon *prec) = 0

Write outgoing array of epicsInt16 data.

Takes the provided data value, converts it to the target OPC UA type, sets the record’s STAT/SEVR according to the success of the conversion, and triggers an OPC UA write operation.

Parameters:

value – pointer to source array
num – source array size
prec – pointer to EPICS record

Returns:

status 0 = ok, 1 = error

virtual long writeArray(const epicsUInt16 *value, const epicsUInt32 num, dbCommon *prec) = 0

Write outgoing array of epicsUInt16 data.

Takes the provided data value, converts it to the target OPC UA type, sets the record’s STAT/SEVR according to the success of the conversion, and triggers an OPC UA write operation.

Parameters:

value – pointer to source array
num – source array size
prec – pointer to EPICS record

Returns:

status 0 = ok, 1 = error

virtual long writeArray(const epicsInt32 *value, const epicsUInt32 num, dbCommon *prec) = 0

Write outgoing array of epicsInt32 data.

Takes the provided data value, converts it to the target OPC UA type, sets the record’s STAT/SEVR according to the success of the conversion, and triggers an OPC UA write operation.

Parameters:

value – pointer to source array
num – source array size
prec – pointer to EPICS record

Returns:

status 0 = ok, 1 = error

virtual long writeArray(const epicsUInt32 *value, const epicsUInt32 num, dbCommon *prec) = 0

Write outgoing array of epicsUInt32 data.

Takes the provided data value, converts it to the target OPC UA type, sets the record’s STAT/SEVR according to the success of the conversion, and triggers an OPC UA write operation.

Parameters:

value – pointer to source array
num – source array size
prec – pointer to EPICS record

Returns:

status 0 = ok, 1 = error

virtual long writeArray(const epicsInt64 *value, const epicsUInt32 num, dbCommon *prec) = 0

Write outgoing array of epicsInt64 data.

Takes the provided data value, converts it to the target OPC UA type, sets the record’s STAT/SEVR according to the success of the conversion, and triggers an OPC UA write operation.

Parameters:

value – pointer to source array
num – source array size
prec – pointer to EPICS record

Returns:

status 0 = ok, 1 = error

virtual long writeArray(const epicsUInt64 *value, const epicsUInt32 num, dbCommon *prec) = 0

Write outgoing array of epicsUInt64 data.

Takes the provided data value, converts it to the target OPC UA type, sets the record’s STAT/SEVR according to the success of the conversion, and triggers an OPC UA write operation.

Parameters:

value – pointer to source array
num – source array size
prec – pointer to EPICS record

Returns:

status 0 = ok, 1 = error

virtual long writeArray(const epicsFloat32 *value, const epicsUInt32 num, dbCommon *prec) = 0

Write outgoing array of epicsFloat32 data.

Takes the provided data value, converts it to the target OPC UA type, sets the record’s STAT/SEVR according to the success of the conversion, and triggers an OPC UA write operation.

Parameters:

value – pointer to source array
num – source array size
prec – pointer to EPICS record

Returns:

status 0 = ok, 1 = error

virtual long writeArray(const epicsFloat64 *value, const epicsUInt32 num, dbCommon *prec) = 0

Write outgoing array of epicsFloat64 data.

Takes the provided data value, converts it to the target OPC UA type, sets the record’s STAT/SEVR according to the success of the conversion, and triggers an OPC UA write operation.

Parameters:

value – pointer to source array
num – source array size
prec – pointer to EPICS record

Returns:

status 0 = ok, 1 = error

virtual long writeArray(const char *value, const epicsUInt32 len, const epicsUInt32 num, dbCommon *prec) = 0

Write outgoing array of EPICS String (char[MAX_STRING_SIZE]) data.

Takes the provided data value, converts it to the target OPC UA type, sets the record’s STAT/SEVR according to the success of the conversion, and triggers an OPC UA write operation.

Parameters:

value – pointer to source array
len – length of an EPICS String element
num – source array size
prec – pointer to EPICS record

Returns:

status 0 = ok, 1 = error

virtual void requestRecordProcessing(const ProcessReason reason) const = 0: Create processing requests for record(s) attached to this element.

Public Members

const EnumChoices *enumChoices = nullptr: enum definition if this element is an enum

Public Static Functions

static void addElementToTree(Item *item, RecordConnector *pconnector, const std::list<std::string> &elementPath)

“Factory” method to construct a linked list of data elements between a record connector and an item.

Creates the leaf element first, then identifies the part of the path that already exists on the item and creates the missing list of linked nodes.

Parameters:

pitem – pointer to corresponding Item
pconnector – pointer to record connector to link to
elementPath – path of leaf element inside the structure

class RecordConnector

Public Static Functions

static RecordConnector *findRecordConnector(const std::string &name)

Find record connector by record name.

Parameters:: name – record name
Returns:: pointer to record connector (nullptr if record not found)

static std::set<RecordConnector*> glob(const std::string &pattern)

Find record connector with record names matching a glob pattern.

Parameters:: pattern – record name pattern to match
Returns:: set of record connector pointers

class DBEntry

template<typename NE, typename E, typename I> class ElementTree

Tree of DataElements representing structured OPC UA data.

Principle of operation for the DataElement tree

An Element can be a structural Node, having children elements, or a Leaf, pointing to a RecordConnector. Each Element has a single parent Node. (The root Element has no parent.)

In the simple case (scalar data), the root element is the unnamed leaf. In the structure case, there is always a root node named [ROOT], so that e.g. all leafs with simple names are children of that root node.

The tree implementation makes heavy use of C++ smart pointers: Each Element has a shared_ptr to its parent. Each Node has a std::vector of weak_ptr to its children. That way any Leaf can freely be added or removed and all intermediate Nodes are properly added, ref-counted and deleted.

The template types used (all specific to the implementation) and their constraints:

NE is the Node Element class with a constructor NE::NE(const std::string &name, I *item) and methods void NE::setParent(std::shared_ptr<NE> parent); void NE::addChild(std::weak_ptr<NE> child); std::shared_ptr<NE> findChild(const std::string &name)

E is the common base class of Node Element (NE) and Leaf Element with the method void E::setParent(std::shared_ptr<E> parent);

I is the Item class

Public Functions

inline std::weak_ptr<E> root() const

Return root element.

Returns:: weak_ptr to root element

inline std::shared_ptr<E> nearestNode(std::list<std::string> &path)

Find the existing part of an element path and return pointer to nearest node.

Parameters:

root – [in] weak_ptr to the root of the element structure
path – [inout] element path; existing leading nodes will be removed

Returns:

shared_ptr to the nearest existing node in the tree, shared_ptr<>() if no overlap

inline void addLeaf(std::shared_ptr<E> leaf, const std::list<std::string> &fullpath, I *item)

Add a new leaf element to the element tree.

Parameters:

leaf – shared_ptr to the leaf to insert
path – full path of the leaf

Throws:

runtime_error – when trying to add elements to a leaf node when adding with empty path but [ROOT] exists

template<typename T> class Registry

A registry for managing named sessions and subscriptions.

Names will be kept unique across the whole namespace (session and subscription names).

The template parameter T is the implementation specific object class (i.e., the class of the things to be managed). Objects are added by calling insert() with a pair of name (key) and a pointer to the object.

Public Functions

inline long insert(std::pair<const std::string, T*> object)

Insert an object into the registry.

Parameters:: object – pair of { name, object* } to insert
Returns:: 0 if successful, -1 on error

inline T *find(const std::string &name)

Find an object by name.

Parameters:: name – object name to search for
Returns:: pointer to object, nullptr if not found

inline bool contains(const std::string &name)

Check for the presence of a name in the registry.

Parameters:: name – object name to check
Returns:: true if exists

template<class B> inline std::set<B*> glob(const std::string &pattern)

Return objects with names matching a glob pattern.

Template parameter B is the base class of T that will be used in the returned set.

Parameters:: pattern – name pattern to match
Returns:: vector of pointers to matching objects

template<typename T> class RequestQueueBatcher : public epicsThreadRunable

A queue + batcher for handling outgoing service requests.

Items put requests (reads or writes) on the queue, specifying the EPICS priority. (Internally a set of 3 queues is used to implement priority queueing.)

A worker thread pops requests from the queue and collects them into a batch (std::vector<>), honoring the configured limit of items per service request. The batch is delivered to the consumer (lower level library) followed by waiting the configured hold-off time (linear interpolation between a minimal time (after a batch of size 1) and a maximum (after a full batch).

The template parameter T is the implementation specific request cargo class (i.e., the class of the things to be queued).

Public Functions

inline RequestQueueBatcher(const std::string &name, RequestConsumer<T> &consumer, const unsigned int maxRequestsPerBatch = 0, const unsigned int minHoldOff = 0, const unsigned int maxHoldOff = 0, const bool startWorkerNow = true, void (*sleep)(double) = epicsThread::sleep)

Construct (and possibly start) a RequestQueueBatcher.

The sleep parameter can be used for intercepting the sleep in tests.

Parameters:

name – name for the batcher thread
consumer – callback interface of the request consumer
maxRequestsPerBatch – limit of items per service call
minHoldOff – minimal holdoff time (after a batch of 1) [msec]
maxHoldOff – maximal holdoff time (after a full batch) [msec]
startWorkerNow – true = start now; false = use start() method
sleep – function to use for sleep [epicsThread::sleep]

inline void startWorker(): Starts the worker thread.

inline void pushRequest(std::shared_ptr<T> cargo, const menuPriority priority)

Pushes a request to the appropriate queue.

Pushes the cargo to the appropriate queue and signals the worker thread.

Parameters:

cargo – shared_ptr to the request
priority – EPICS priority (0=low, 1=mid, 2=high)

inline void pushRequest(std::vector<std::shared_ptr<T>> &cargo, const menuPriority priority)

Pushes a vector of requests to the appropriate queue.

Pushes the cargo to the appropriate queue and signals the worker thread. Keeps the queue locked during the push operation (so that all requests may be handed to the worker at one time).

Parameters:

cargo – vector of shared_ptr to the request
priority – EPICS priority (0=low, 1=mid, 2=high)

inline bool empty(const menuPriority priority) const

Checks whether a queue is empty.

Checks if the queue has no elements for the specified priority.

Parameters:: priority – EPICS priority (0=low, 1=mid, 2=high)
Returns:: true if the queue is empty, false otherwise

inline size_t size(const menuPriority priority) const

Returns the number of elements in a queue.

Returns the number of elements for the specified priority.

Parameters:: priority – EPICS priority (0=low, 1=mid, 2=high)
Returns:: number of elements in the queue

inline void clear(): Clears all queues (removing all unprocessed requests).

inline void setParams(const unsigned int maxRequestsPerBatch, const unsigned int minHoldOff = 0, const unsigned int maxHoldOff = 0)

Sets batcher parameters.

Parameters:

maxRequestsPerBatch – limit of items per service call
minHoldOff – minimal holdoff time (after a batch of 1) [msec]
maxHoldOff – maximal holdoff time (after a full batch) [msec]

inline unsigned int maxRequests() const

Get maxRequestsPerBatch parameter.

Returns:: current limit for requests per batch

inline unsigned int minHoldOff() const

Get minimal holdoff time parameter.

Returns:: current minimal holdoff time [msec]

inline unsigned int maxHoldOff() const

Get maximal holdoff time parameter.

Returns:: current maximal holdoff time [msec]

template<typename T, typename S> class Update

An update for an OPC UA Data Element.

An update is created for every Data Element after results of an OPC UA service call have been received, or as a result of a special situation (e.g. connection loss).

It consists of the mandatory parts

(EPICS) time stamp
update type (ProcessReason for the update)

and the optional (implementation dependent type) parts

data object (using a std::unique_ptr)
status code

Update uses C++11 std::unique_ptr to manage the data object, i.e. the data is owned by the Update until it goes out of scope. The status code is assumed to be small, i.e. the minimal raw type that holds an OPC UA status.

Public Functions

inline Update(const epicsTime &time, ProcessReason reason, const T &newdata, S status)

Constructor with const reference for data.

This constructor creates a new unique_ptr managed data object, creating a copy of the data.

Parameters:

time – EPICS time stamp of this update
type – type of the update (process reason)
data – const reference to the data to put in the update
status – status code related to the update

inline Update(const epicsTime &time, const ProcessReason reason, std::unique_ptr<T> newdata, S status)

Constructor with unique_ptr for data.

This constructor moves a unique_ptr managed data rvalue into the Update.

Parameters:

ts – EPICS time stamp of this update
type – type of the update (process reason)
newdata – data to put in the update
status – status code related to the update

inline Update(const epicsTime &time, const ProcessReason reason)

Constructor with no data, for service results without data.

Parameters:

ts – EPICS time stamp of this update
type – type of the update (process reason)
status – status code related to the update

inline void override(Update<T, S> &other)

Override an update with data.

Overrides the update object, increasing the overrides counter, replacing its data and time stamp with a copy of the specified other update and moving the other update’s data into this

This is used to drop this update, replacing it with the (newer) update behind it.

Parameters:: other – update whose data is used to replace this

inline void override(unsigned long count)

Override an update without data.

Adds the argument to its overrides counter.

This is used to carry over the overrides counter if the (older) update in front of this one was dropped.

Parameters:: count – number to step up the overrides counter

inline epicsTime getTimeStamp() const

Getter for the update’s EPICS time stamp.

Returns:: EPICS time stamp of the update

inline ProcessReason getType() const

Getter for the update’s type.

Returns:: type of the update

inline std::unique_ptr<T> releaseData()

Mover for the update’s data.

Ownership is moved from update to the caller.

Returns:: unique_ptr to the update data

inline T &getData() const

Getter for the update’s data.

Ownership is retained by the update. Undefined if the Update has no data.

Returns:: reference to the update’s data

inline S getStatus() const

Getter for the update’s status.

Undefined if the Update has no data.

Returns:: update’s status

inline unsigned long getOverrides() const

Getter for the update’s overrides counter.

Returns:: overrides counter

inline explicit operator bool() const noexcept

Checks if the update contains data.

Checks if this->data stores a pointer, i.e. whether getData() is defined.

template<typename T> class UpdateQueue

A fixed size queue for handling incoming updates (data and events).

When updates are pushed to a full queue, either the front or the back update on the queue (depending on the queue’s discard policy) are dropped and the overrides counter of the following update is stepped up.

C++11 shared_ptr is used for managing the updates on the queue. This allows to e.g. always cache a pointer to the latest update while all updates go through the queue and are consumed at the other end.

The template parameter T is expected to be an instance of the Update class, i.e. it must provide the override(), getOverrides() and getType() methods.

Public Functions

inline void pushUpdate(std::shared_ptr<T> update, bool *wasFirst = nullptr)

Inserts an update at the end.

Pushes the given update to the end of the queue.

Parameters:

update – the update to push
wasFirst – [out] true if pushed element was the first one, false otherwise

inline std::shared_ptr<T> popUpdate(ProcessReason *nextReason = nullptr)

Removes an update from the front.

Removes an update from the front of the underlying queue and returns it.

Calling popUpdate on an empty queue is undefined.

Parameters:: nextReason – [out] ProcessReason of the next element, none if last element
Returns:: reference to the removed update

inline bool empty() const

Checks whether the queue is empty.

Checks if the underlying queue has no elements, i.e. whether updq.empty().

Returns:: true if the queue is empty, false otherwise

inline size_t size() const

Returns the number of elements.

Returns the number of elements in the underlying queue, i.e., updq.size().

Returns:: number of elements in the queue

inline size_t capacity() const

Returns the maximum number of elements.

Returns the maximum allowed number of elements.

Returns:: queue capacity (max. number of elements)

struct linkInfo

Configuration data for a single record instance.

This structure holds all configuration data for a single instance of a supported standard record type, i.e. the result of INP/OUT link parsing.

It is kept around, as in the case of a server disconnect/reconnect, the sequence of creating the lower level interface will have to be partially repeated.

Public Members

Item *item: pointer to root item (if structure element)