pyuaf.client

SUMMARY of submodules:

connectionsteps
monitoreditemstates
requests
results
sessionstates
settings
subscriptionstates

SUMMARY of classes:

See sidebar.

class Client

SUMMARY:

Constructor:
Client([settings, loggingCallback]) Construct a UAF client.
Client settings:
Client.clientSettings() Get a copy of the current client settings.
Client.setClientSettings(settings) Change the client settings.
Synchronous service calls:
Client.browse(addresses[, maxAutoBrowseNext]) Browse a number of nodes synchronously.
Client.browseNext(addresses, ...) Continue a previous synchronous Browse request, in case you didn’t use the automatic BrowseNext feature of the UAF.
Client.call(objectAddress, methodAddress[, ...]) Invoke a remote method call.
Client.createMonitoredData(addresses[, ...]) Create one or more monitored data items.
Client.createMonitoredEvents(addresses[, ...]) Create one or more monitored event items.
Client.historyReadModified(addresses, ...[, ...]) Read the modification information of the historical data from one or more nodes synchronously.
Client.historyReadRaw(addresses, startTime, ...) Read the raw historical data from one or more nodes synchronously.
Client.read(addresses[, attributeId]) Read a number of node attributes synchronously.
Client.setMonitoringMode(clientHandles, ...) Set the monitoring mode for the specified monitored items.
Client.setPublishingMode(...[, serviceSettings]) Set the publishing mode, by specifying a subscription handle.
Client.write(addresses, data[, attributeId]) Write a number of node attributes synchronously.
Asynchronous service calls:
Client.beginCall(objectAddress, methodAddress) Invoke a remote method call asynchronously.
Client.beginRead(addresses[, attributeId, ...]) Read a number of node attributes asynchronously.
Client.beginWrite(addresses, data[, ...]) Write a number of node attributes asynchronously.
Callback functions for asynchronous service calls:
Client.callComplete(result) Override this method to catch the result of asynchronous method call requests.
Client.readComplete(result) Override this method to catch the result of asynchronous read requests.
Client.writeComplete(result) Override this method to catch the result of asynchronous write requests.
Callback functions for sessions, subscriptions and monitored items:
Client.dataChangesReceived(dataNotifications) Override this method to catch the “data change” notifications of MonitoredItems.
Client.eventsReceived(eventNotifications) Override this method to catch the “event” notifications of MonitoredItems.
Client.connectionStatusChanged(info) Override this method to receive connection status changes.
Client.subscriptionStatusChanged(info) Override this method to receive subscription status changes.
Client.keepAliveReceived(notification) You should override this method if you want to process keep alive messages from the UAF.
Client.notificationsMissing(info, ...) Override this method to handle missing notifications.
Register your own callback functions for sessions, subscriptions and monitored items:
Client.registerConnectionStatusCallback(callback) Register a callback to receive connection status changes.
Client.registerSubscriptionStatusCallback(...) Register a callback to receive connection status changes.
Client.registerKeepAliveCallback(callback[, ...]) Register a callback to handle KeepAlive notifications.
Client.registerNotificationsMissingCallback(...) Register a callback to handle missing notifications.
Information about the current sessions, subscriptions and monitored items:
Client.allSessionInformations() Get information about all sessions.
Client.allSubscriptionInformations() Get information about all subscriptions.
Client.monitoredItemInformation(clientHandle) Get information about the specified monitored item.
Client.sessionInformation(clientConnectionId) Get information about the specified session.
Client.subscriptionInformation(...) Get information about the specified subscription.
Fully configurable generic service calls:
Client.processRequest(request[, ...]) Process a generic request (as found in pyuaf.client.requests).
Manually created sessions and subscriptions:
Client.manuallyConnect(serverUri[, ...]) Create a session manually (instead of having the UAF do it behind the scenes).
Client.manuallyConnectToEndpoint(endpointUrl) Manually connect to a specific endpoint, without using the discovery services.
Client.manuallyDisconnect(clientConnectionId) Disconnect the session manually.
Client.manuallySubscribe(clientConnectionId) Create a subscription manually.
Client.manuallyUnsubscribe(...) Delete the subscription manually.
Handle untrusted server certificates:
Client.untrustedServerCertificateReceived(...) Override this method if you want to handle an untrusted certificate.
Client.registerUntrustedServerCertificateCallback(...) Register a callback function to handle untrusted certificates during the connection process.
Client.unregisterUntrustedServerCertificateCallback() Unregister a callback function to stop handling untrusted certificates.
Catch the logging of the UAF:
Client.logMessageReceived(message) Override this method if you want to process logging output from the UAF.
Client.registerLoggingCallback(callback) Register a callback function to receive all log messages.
Client.unregisterLoggingCallback() Unregister a callback function to stop receiving all log messages.
Discovery:
Client.serversFound() Get a list of the application descriptions of the servers found in the discovery process.
Client.findServersNow() Discover the servers immediately (instead of waiting for the background thread) by using the OPC UA FindServers service.
Client.serversOnNetworkFound() Get a list of the server descriptions of the servers found by querying the LDS.
Client.findServersOnNetworkNow() Discover the servers on the network immediately (instead of waiting for the background thread) by using the OPC UA FindServersOnNetwork service.
Override connect errors:
Client.connectErrorReceived(...) Override this method to handle connect errors by the SDK.
Client.registerConnectErrorCallback(callback) Register a callback function to handle connect errors.
Client.unregisterConnectErrorCallback() Unregister a callback function to stop handling connect errors.

DETAILED DESCRIPTION::

class pyuaf.client.Client(settings=None, loggingCallback=None)

Construct a UAF client.

Usage example:

# examples/pyuaf/client/how_to_create_a_client.py
"""
EXAMPLE: how to create a client
====================================================================================================

The Client constructor signature looks like this: 

  pyuaf.client.Client.__init__(settings=None, loggingCallback=None)

with:
  - 'settings': optional: could be 
      - a pyuaf.client.settings.ClientSettings instance
      - or simply a string (the name of the client)
      - or None (so default pyuaf.client.settings.ClientSettings() are used).
  - 'loggingCallback': optional: a callback function to catch log messages of type pyuaf.util.LogMessage.

See the PyUAF HTML documentation for more info.
"""

import time, os

import pyuaf
from pyuaf.client          import Client
from pyuaf.client.settings import ClientSettings
from pyuaf.util            import loglevels, Address, NodeId

# we can create some ClientSettings:
settings = ClientSettings()
settings.applicationName = "MyClient"
settings.discoveryUrls.append("opc.tcp://localhost:4841")
settings.logToStdOutLevel   = loglevels.Info   # print Info, Warning and Error logging to the console 
settings.logToCallbackLevel = loglevels.Debug  # send Debug, Info, Warning and Error logging to the callback

# And if you want to catch the logging output, you may also define a callback.
# In this case we define a callback to write the logging output to a file in the user's home directory.
# (but this callback is optional of course, only define one if you want to do something more with the
#  logging output than simply printing it to the console (i.e. sending it to the stdout))
f = open(os.path.expanduser("~/my_logging_output.txt"), "w")
def callback(msg):
    logDetailsString = ""
    logDetailsString += time.strftime("%a, %d %b %Y %H:%M:%S", time.localtime(msg.ctime))
    logDetailsString += ".%.3d " %msg.msec
    logDetailsString += "%-10s " %msg.applicationName
    logDetailsString += "%-20s " %msg.loggerName
    logDetailsString += "%-8s "  %loglevels.toString(msg.level)
    # msg.message may contain multiple lines, so we prepend the other logging details in
    # front of each line:
    for line in msg.message.splitlines():
        f.write("%s: %s\n" %(logDetailsString, line))


# Example 0: create a client with the default settings and no logging callback
# --------------------------------------------------------------------------------------------------
client0 = Client()

# Example 1: create a client by specifying the settings
# --------------------------------------------------------------------------------------------------
client1 = Client(settings)

# Example 2: create a client by specifying the settings
# --------------------------------------------------------------------------------------------------
client2 = Client(settings, callback)

# Example 3: create a client by specifying only the logging callback
# --------------------------------------------------------------------------------------------------
client3 = Client(loggingCallback=callback)

# you can still provide settings and register a logging callback afterwards, but you'll need to use:
#  client0.setClientSettings(settings)
#  client0.registerLoggingCallback(callback)


# read the Value attribute of some non-existing node in order to have some Error output sent to the callback:
client2.read([Address(NodeId("InvalidIdentifier","InvalidNamespace"),"InvalidServerURI")])

f.close()
Parameters:
allSessionInformations()

Get information about all sessions.

Returns:A list of information objects about all sessions.
Return type:list of SessionInformation
allSubscriptionInformations()

Get information about all subscriptions.

Returns:A list of information objects about all subscriptions.
Return type:list of SubscriptionInformation
beginCall(objectAddress, methodAddress, inputArgs=[], callback=None, **kwargs)

Invoke a remote method call asynchronously.

Unlike “strict object-oriented” method calling, a method is called by specifying both
  • the method itself (parameter methodAddress)
  • the object in which context the method should be invoked (parameter objectAddress).

In other words, in OPC UA you can call a method on different objects. In contrast to strict object-oriented languages, where a method can only be called on the object that “owns” the method.

This is a convenience function for calling processRequest with a MethodCallRequest as its first argument. For full flexibility, use that function. For instance, if you want to call multiple methods at once, you can do so by creating a MethodCallRequest and adding multiple targets.

Warning

The callbacks will run in a separate thread, and therefore any exception they raise will not be handled or propagated. So your callbacks should have a try-except clause if you want to be able to properly handle the exceptions that they may raise.

Parameters:
Returns:

The result of the asynchronous method call request.
Return type:

AsyncMethodCallResult
Raises:

pyuaf.util.errors.UafError – Base exception, catch this to handle any UAF errors.
beginRead(addresses, attributeId=13, callback=None, **kwargs)

Read a number of node attributes asynchronously.

This is a convenience function for calling processRequest with a ReadRequest as its first argument. For full flexibility, use that function.

Asynchronous communication can be handled in two ways:
  • you specify a callback function (a function with one argument). This function will be called by the UAF when the asynchronous result is received. The argument of this function call will be of type ReadResult.
  • you leave the ‘callback’ argument None. In this case, your client application need to inherit from the Client class, so it can override the readComplete() method.

Warning

Asynchronous requests MUST be invoked on a single session. Meaning: the targets of asynchronous requests MUST belong to the same server (as the UAF can currently not reconstruct an asynchronous request that must be “split up” to be called on multiple servers). If they don’t belong to the same server, an error will be raised.

Warning

The callbacks will run in a separate thread, and therefore any exception they raise will not be handled or propagated. So your callbacks should have a try-except clause if you want to be able to properly handle the exceptions that they may raise.

Parameters:
Returns:

The “immediate” result of the asynchronous read request.
Return type:

AsyncReadResult
Raises:

pyuaf.util.errors.UafError – Base exception, catch this to handle any UAF errors.
beginWrite(addresses, data, attributeId=13, callback=None, **kwargs)

Write a number of node attributes asynchronously.

This is a convenience function for calling processRequest with a AsyncWriteRequest as its first argument. For full flexibility, use that function.

Asynchronous communication can be handled in two ways:
  • you specify a callback function (a function with one argument). This function will be called by the UAF when the asynchronous result is received. The argument of this function call will be of type WriteResult.
  • you leave the ‘callback’ argument None. In this case, your client application need to inherit from the Client class, so it can override the writeComplete() method.

Warning

Asynchronous requests MUST be invoked on a single session. Meaning: the targets of asynchronous requests MUST belong to the same server (as the UAF can currently not reconstruct an asynchronous request that must be “split up” to be called on multiple servers). If they don’t belong to the same server, an error will be raised.

Warning

The callbacks will run in a separate thread, and therefore any exception they raise will not be handled or propagated. So your callbacks should have a try-except clause if you want to be able to properly handle the exceptions that they may raise.

Parameters:
Returns:

The “immediate” result of the asynchronous write request.
Return type:

AsyncWriteResult
Raises:

pyuaf.util.errors.UafError – Base exception, catch this to handle any UAF errors.
browse(addresses, maxAutoBrowseNext=100, **kwargs)

Browse a number of nodes synchronously.

This is a convenience method for calling processRequest with a BrowseRequest as its first argument. A BrowseRequest has many parameters (only few of them can be configured by this convenience method), so for full flexibility use the other method.

The second parameter (maxAutoBrowseNext) allows you to use some handy extra functionality of the UAF: the UAF can automatically invoke the BrowseNext service for you, if all browse results couldn’t be fetched by the initial Browse service. This parameter specifies how many times the UAF may silently invoke the BrowseNext service for you. Put it to 0 if you want the “normal SDK behavior”, i.e. if you want to invoke the BrowseNext service manually.

Parameters:
  • addresses (Address or a list of Address) – A single address or a list of addresses of nodes that serve as the starting point to browse.
  • maxAutoBrowseNext (int) – How many times do you allow the UAF to automatically invoke a BrowseNext for you (if that’s needed to fetch all results)? This parameter will always be used instead of the maxAutoBrowseNext attribute of the serviceSettings!
  • kwargs –

    The following **kwargs are available (see A note on **kwargs for Client services):
Returns:

The result of the browse request.
Return type:

BrowseResult
Raises:

pyuaf.util.errors.UafError – Base exception, catch this to handle any UAF errors.
browseNext(addresses, continuationPoints, **kwargs)

Continue a previous synchronous Browse request, in case you didn’t use the automatic BrowseNext feature of the UAF.

You only need to use this function if you have put maxAutoBrowseNext to 0 in the previous Browse request (or if the automatic BrowseNext calls still resulted in continuationPoints). For your convenience, it’s much easier to simple use the browse() method, and let the UAF do the BrowseNext calls for you!

This is a convenience method for calling processRequest with a BrowseNextRequest as its first argument. A BrowseNextRequest has many parameters (only few of them can be configured by this convenience method), so for full flexibility use the other method.

Parameters:
  • addresses (Address or a list of Address) – A single address or a list of addresses of nodes that serve as the starting point to browse. You need to copy the addresses here from the original Browse request, so that the UAF can use these addresses to find out to which server the BrowseNext call should be sent.
  • continuationPoints (ByteStringVector or a list of Python bytearray objects.) – A list of continuation points (represented by the built-in Python bytearray objects).
  • kwargs –

    The following **kwargs are available (see A note on **kwargs for Client services):
Returns:

The result of the BrowseNext request.
Return type:

BrowseNextResult
Raises:

pyuaf.util.errors.UafError – Base exception, catch this to handle any UAF errors.
call(objectAddress, methodAddress, inputArgs=[], **kwargs)

Invoke a remote method call.

Unlike “strict object-oriented” method calling, a method is called by specifying both
  • the method itself (parameter methodAddress)
  • the object in which context the method should be invoked (parameter objectAddress).

In other words, in OPC UA you can call a method on different objects. In contrast to strict object-oriented languages, where a method can only be called on the object that “owns” the method.

This is a convenience function for calling processRequest with a MethodCallRequest as its first argument. For full flexibility, use that function. For instance, if you want to call multiple methods at once, you can do so by creating a MethodCallRequest and adding multiple targets.

Parameters:
Returns:

The result of the method call request.
Return type:

MethodCallResult
Raises:

pyuaf.util.errors.UafError – Base exception, catch this to handle any UAF errors.
callComplete(result)

Override this method to catch the result of asynchronous method call requests.

This method will only be called by the UAF if you didn’t provide an “external” callback function already when you began the asynchronous method call request.

In other words, there are two ways how you can catch the result of asynchronous method calls:

  • either by calling processRequest() without providing an external callback function via the ‘resultCallback’ argument –> then you need to override callComplete()
  • or by calling processRequest() with providing an external callback function via the ‘resultCallback’ argument –> then only the external callback function will be called.
Parameters:result (MethodCallResult) – The asynchronously received method call result.
clientSettings()

Get a copy of the current client settings.

Returns:The currently active settings.
Return type:pyuaf.client.settings.ClientSettings
connectErrorReceived(clientConnectionId, connectionStep, sdkStatus, clientSideError)

Override this method to handle connect errors by the SDK.

By default, this method returns False, which means that client errors by the SDK will cause a failure of the connection. Return True if the client SDK error should be ignored. If the error was not a client-side SDK error (meaning: if clientSideError is False) then the return value will be ignored.

Parameters:
  • clientConnectionId (int) – The ID of the session that raised the connectError.
  • connectionStep (int) – The failing connection step, as an int defined by pyuaf.client.connectionsteps
  • sdkStatus (pyuaf.util.SdkStatus) – The error by the SDK.
  • clientSideError (bool) – True if the error was created inside the SDK.
Returns:

True to override the error a client SDK error, False by default.
Return type:

bool
connectionStatusChanged(info)

Override this method to receive connection status changes.

Alternatively, you can also register callback functions which you defined yourself, by registering them using pyuaf.client.Client.registerConnectionStatusCallback().

Parameters:info (SessionInformation) – Updated session information.
createMonitoredData(addresses, notificationCallbacks=[], **kwargs)

Create one or more monitored data items.

This is a convenience function for calling processRequest with a CreateMonitoredDataRequest as its first argument. For full flexibility, use that function.

Note

Both CreateMonitoredDataRequest and CreateMonitoredEventsRequest are “persistent” requests. It means that even when communication fails (e.g. because the server was not online), a handle is already assigned to each monitored item as soon as you call createMonitoredEvents(). In the background, the UAF will try to (re)establish the connection, and as soon as this is successful, it will create the monitored items for you on the server. From that point on, you may start to receive notifications (that can be identified by the handles that were already assigned and returned to you now). So when createMonitoredData() fails, you need to be aware that in the background the UAF will retry to create them on the server. You can access the handles that will identify their notifications

Warning

The callbacks will run in a separate thread, and therefore any exception they raise will not be handled or propagated. So your callbacks should have a try-except clause if you want to be able to properly handle the exceptions that they may raise.

Parameters:
Returns:

The result of the CreateMonitoredData request.
Return type:

CreateMonitoredDataResult
Raises:

pyuaf.util.errors.UafError – Base exception, catch this to handle any UAF errors.
createMonitoredEvents(addresses, eventFilter=None, notificationCallbacks=[], **kwargs)

Create one or more monitored event items.

This is a convenience function for calling processRequest with a CreateMonitoredEventsRequest as its first argument. For full flexibility, use that function.

Note

Both CreateMonitoredDataRequest and CreateMonitoredEventsRequest are “persistent” requests. It means that even when communication fails (e.g. because the server was not online), a handle is already assigned to each monitored item as soon as you call createMonitoredEvents(). In the background, the UAF will try to (re)establish the connection, and as soon as this is successful, it will create the monitored items for you on the server. From that point on, you may start to receive notifications (that can be identified by the handles that were already assigned and returned to you now). So when createMonitoredEvents() fails, you need to be aware that in the background the UAF will retry to create them on the server. You can access the handles that will identify their notifications

Warning

The callbacks will run in a separate thread, and therefore any exception they raise will not be handled or propagated. So your callbacks should have a try-except clause if you want to be able to properly handle the exceptions that they may raise.

Parameters:
Returns:

The result of the CreateMonitoredEvents request.
Return type:

CreateMonitoredEventsResult
Raises:

pyuaf.util.errors.UafError – Base exception, catch this to handle any UAF errors.
dataChangesReceived(dataNotifications)

Override this method to catch the “data change” notifications of MonitoredItems.

This method will only be called by the UAF if you didn’t provide “external” callback functions already when you created the monitored items.

In other words, there are two ways how you can catch the data change notifications of monitored data items:

Parameters:dataNotifications (list of DataChangeNotification) – The asynchronously received notifications.
eventsReceived(eventNotifications)

Override this method to catch the “event” notifications of MonitoredItems.

This method will only be called by the UAF if you didn’t provide “external” callback functions already when you created the monitored items.

In other words, there are two ways how you can catch the event notifications of monitored event items:

Parameters:eventNotifications (list of EventNotification) – The asynchronously received notifications.
findServersNow()

Discover the servers immediately (instead of waiting for the background thread) by using the OPC UA FindServers service.

The URLs to use for discovery are specified by the discoveryUrls attribute of the ClientSettings. Since discovery is also handled silently (and periodically) in the background, you normally don’t have to call findServersNow() manually.

Raises:
  • pyuaf.util.errors.DiscoveryError – Raised in case the FindServers service failed for one or more URLs.
  • pyuaf.util.errors.InvalidRequestError – Raised in case the FindServers service is already being invoked by the client (because no parallel FindServers invocations are allowed!). This can happen for instance when multiple threads (created by the user, or running in the background of the Client instance) try to use the FindServers service at the same time.
  • pyuaf.util.errors.UafError – Base exception, catch this to handle any other errors.
findServersOnNetworkNow()

Discover the servers on the network immediately (instead of waiting for the background thread) by using the OPC UA FindServersOnNetwork service.

The URL of the discovery server is specified by the discoveryOnNetworkDiscoveryServer attribute of the ClientSettings. Since discovery is also handled silently (and periodically) in the background if discoveryOnNetworkEnable is True, you normally don’t have to call findServersOnNetworkNow() manually.

Raises:
  • pyuaf.util.errors.DiscoveryError – Raised in case the FindServers service failed for one or more URLs.
  • pyuaf.util.errors.InvalidRequestError – Raised in case the FindServers service is already being invoked by the client (because no parallel FindServers invocations are allowed!). This can happen for instance when multiple threads (created by the user, or running in the background of the Client instance) try to use the FindServers service at the same time.
  • pyuaf.util.errors.UafError – Base exception, catch this to handle any other errors.
getEndpoints(discoveryUrl)

Get a list of endpoint descriptions supported by the server.

Parameters:

discoveryUrl (str) – The URL of a Discovery Server (e.g. opc.tcp://mymachine:4840).
Returns:

A list of the endpoint descriptions that were found.
Return type:

list of pyuaf.util.EndpointDescription
Raises:
historyReadModified(addresses, startTime, endTime, numValuesPerNode=0, maxAutoReadMore=0, continuationPoints=[], **kwargs)

Read the modification information of the historical data from one or more nodes synchronously.

This is a convenience function for calling processRequest with a HistoryReadRawModifiedRequest as its first argument. For full flexibility, use that function.

Since this convenience method is meant to fetch the modification info of historical data, the isReadModified flag of the serviceSettings will be forced to True!

Parameters:
  • addresses (Address or a list of Address) – A single address or a list of addresses of nodes of which the historical data should be retrieved.
  • startTime (DateTime) – The start time of the interval from which you would like to see the historical data. This parameter will always be used instead of the startTime attribute of the serviceSettings .
  • endTime (DateTime) – The end time of the interval from which you would like to see the historical data. This parameter will always be used instead of the startTime attribute of the serviceSettings .
  • numValuesPerNode (int) – The maximum number of values that may be returned for each node. 0 means no limit, but you may want to put it to a “safe” value (e.g. 100 if you expect to receive at most 50 historical values or so) to make sure that you’re not flooded by a huge stream of data values, e.g. in case you’ve made some mistake in the time interval! Default = 0.
  • maxAutoReadMore (int) – How many times do you allow the UAF to automatically invoke a “continuation request” for you (if that’s needed to fetch all results)? E.g. if you specify maxAutoReadMore = 10, then the UAF will automatically perform subsequent history requests, until either all results are fetched, or until 10 additional requests have been invoked automatically. This parameter will always be used instead of the maxAutoReadMore attribute of the serviceSettings. Default = 0, which means that no “automatic” continuation requests will be invoked by the UAF (so if you leave this parameter as 0 and you see that the len(result.targets[x].continuationPoint) > 0, then you must call the historyReadRaw method again with this continuationPoint to receive more historical data).
  • continuationPoints (ByteStringVector or a list of Python bytearray objects.) – Continuation points, in case you’re continuing to read the istorical data of a previous request manually. By specifying a sufficiently large number for maxAutoReadMore, you can actually let the UAF handle the “continuation requests”, if you want. If you’re not using continuationPoints manually, you can simply provide an empty list or vector. Default = empty list.
  • kwargs –

    The following **kwargs are available (see A note on **kwargs for Client services):
Returns:

The result of the history read request.
Return type:

HistoryReadRawModifiedResult
Raises:

pyuaf.util.errors.UafError – Base exception, catch this to handle any UAF errors.
historyReadRaw(addresses, startTime, endTime, numValuesPerNode=0, maxAutoReadMore=0, continuationPoints=[], **kwargs)

Read the raw historical data from one or more nodes synchronously.

This is a convenience function for calling processRequest with a HistoryReadRawModifiedRequest as its first argument. For full flexibility, use that function.

Since this convenience method is meant to fetch raw historical data, the isReadModified flag of the serviceSettings will be forced to False!

Parameters:
  • addresses (Address or a list of Address) – A single address or a list of addresses of nodes of which the historical data should be retrieved.
  • startTime (DateTime) – The start time of the interval from which you would like to see the historical data. This parameter will always be used instead of the startTime attribute of the serviceSettings.
  • endTime (DateTime) – The end time of the interval from which you would like to see the historical data. This parameter will always be used instead of the startTime attribute of the serviceSettings.
  • numValuesPerNode (int) – The maximum number of values that may be returned for each node. 0 means no limit, but you may want to put it to a “safe” value (e.g. 100 if you expect to receive at most 50 historical values or so) to make sure that you’re not flooded by a huge stream of data values, e.g. in case you’ve made some mistake in the time interval! Default = 0.
  • maxAutoReadMore (int) – How many times do you allow the UAF to automatically invoke a “continuation request” for you (if that’s needed to fetch all results)? E.g. if you specify maxAutoReadMore = 10, then the UAF will automatically perform subsequent history requests, until either all results are fetched, or until 10 additional requests have been invoked automatically. This parameter will always be used instead of the maxAutoReadMore attribute of the serviceSettings. Default = 0, which means that no “automatic” continuation requests will be invoked by the UAF (so if you leave this parameter as 0 and you see that the len(result.targets[x].continuationPoint) > 0, then you must call the historyReadRaw method again with this continuationPoint to receive more historical data).
  • continuationPoints (ByteStringVector or a list of Python bytearray objects.) – Continuation points, in case you’re continuing to read the istorical data of a previous request manually. By specifying a sufficiently large number for maxAutoReadMore, you can actually let the UAF handle the “continuation requests”, if you want. If you’re not using continuationPoints manually, you can simply provide an empty list or vector. Default = empty list.
  • kwargs –

    The following **kwargs are available (see A note on **kwargs for Client services):
Returns:

The result of the history read request.
Return type:

HistoryReadRawModifiedResult
Raises:

pyuaf.util.errors.UafError – Base exception, catch this to handle any UAF errors.
keepAliveReceived(notification)

You should override this method if you want to process keep alive messages from the UAF.

Parameters:notification (pyuaf.client.KeepAliveNotification) – The received KeepAliveNotification.
logMessageReceived(message)

Override this method if you want to process logging output from the UAF.

This method is called by the UAF if:
Parameters:message (pyuaf.util.LogMessage) – The received LogMessage.
manuallyConnect(serverUri, sessionSettings=None)

Create a session manually (instead of having the UAF do it behind the scenes).

One of the advantages of the UAF is that you can just define the addresses of some nodes, and then read/write/monitor/... them without worrying about the technical concerns such as session creation, subscription creation etc. So you don’t have to create sessions yourself, because the UAF will do it for you. However, if you want to “keep control” over the session/subscription/... management yourself, you can use methods like manuallyConnect(), manuallyDisconnect(), manuallySubscribe(), etc. In this case, you can create the sessions/subscriptions/... in advance, and then afterwards read/write/... variables by using the same sessions and subscriptions. So these “manual” methods allow you to use OPC UA in the “traditional way”, however it’s much easier to do it the “UAF way” and simply forget about the creation and deletion of sessions, subscriptions, and monitored items.

The URL(s) needed to discover the server with the given server URI, can be specified via the ClientSettings (which you can set via Client() and via setClientSettings()).

Warning

If the connection fails (e.g. because you specified a wrong server URI, or because the security settings were incorrect), this methd will not raise an Exception! It will simply return the ClientConnectionId assigned to the internal Session object, which the UAF will try to reconnect in the background! So if you want to make sure this method call resulted in a connected session, you should do something like this:

clientConnectionId = myClient.manuallyConnect(SERVER_URI)
sessionInformation = myClient.sessionInformation(clientConnectionId)
if sessionInformation.sessionState == pyuaf.client.sessionstates.Disconnected:
    pass # OK, we can proceed
else:
    print("Oops, something went wrong:")
    print(sessionInformation.lastConnectionAttemptStatus)
Parameters:
  • serverUri (str) – The server URI to manually connect to.
  • sessionSettings (SessionSettings) – The settings for the session (leave None for a default instance).
Returns:

The client connection id: a number identifying the session.
Return type:

int
Raises:
manuallyConnectToEndpoint(endpointUrl, sessionSettings=None, serverCertificate=None)

Manually connect to a specific endpoint, without using the discovery services.

A UAF client normally uses the discovery process to identify a server and connect to it. The user therefore doesn’t have to worry about connecting, disconnecting, session management, etc.

However, in certain cases you may want to connect manually to a specific endpoint, without using the discovery process (i.e. without relying on the discovery endpoint of the server). In these cases you can use this method.

You should probably only use this method if you have a good reason not to rely on the discovery services provided by the server. A server should be identified by a serverURI, not by an endpointURL!

The securitySettings attribute of the sessionSettings argument (in other words: sessionSettings.securitySettings) defines how you want to connect to the server.

This default instance has

Compliant to OPC UA specs, the serverCertificate will:

  • first be checked at the application level. If it’s not valid or not found in the trust list, then the untrustedServerCertificateReceived() callback function will be called. Override this method if you want to handle those cases.
  • then it may be used for encryption and/or signing (if a secure connection is needed, of course).

You can leave serverCertificate None (or provide a default, invalid, null PkiCertificate instance) if you trust the server (i.e. if you make sure untrustedServerCertificateReceived() returns Action_AcceptTemporarily), and if you don’t need signing or encryption.

Warning

If this method fails (in other words, when an Error is raised), then no Session has been created! This is different behavior from manuallyConnect(), which will have created a Session that automatically retries to connect.

See also

Check out example How to manually connect to an endpoint without discovery? for more information.

Parameters:
  • endpointUrl – The endpoint URL to manually connect to.
  • sessionSettings (SessionSettings) – The settings for the session (leave None for a default instance).
  • serverCertificate (PkiCertificate) – The server certificate (will be checked!)
Returns:

The client connection id: a number identifying the session.
Return type:

int
Raises:
manuallyDisconnect(clientConnectionId)

Disconnect the session manually.

A session which has been disconnected manually is “garbage collected” on the client side. When a session is created afterwards, a new ClientConnectionId will be assigned to this session (even if the properties of the new session are exactly the same as the old one).

Only use this for sessions that were created via the manuallyConnect method!

Parameters:

clientConnectionId (int) – The id of the session (that was returned by the manuallyConnect() method).
Raises:
manuallyDisconnectAllSessions()

Disconnect all sessions.

To stress that normally the UAF takes care of session connection and disconnection, this method has a “manually” prefix. Normally it should not be used explicitely, as all sessions will be disconnected automatically when the client is deleted.

manuallySubscribe(clientConnectionId, subscriptionSettings=None)

Create a subscription manually.

For more info about “manual” methods, see the documentation on the manuallyConnect() method.

Parameters:
  • clientConnectionId (int) – The id of the session which should host the subscription.
  • settings (SubscriptionSettings) – The settings of the subscription you’d like to create.
Returns:

The clientSubscriptionHandle: the handle identifying the newly created subscription.
Return type:

int
Raises:

pyuaf.util.errors.UafError – Base exception, catch this to handle any other errors.
manuallyUnsubscribe(clientConnectionId, clientSubscriptionHandle)

Delete the subscription manually.

A subscription which has been deleted manually is “garbage collected” on the client side. When a subscription is created afterwards, a new clientSubscriptionHandle will be assigned to this session (even if the properties of the new subscription are exactly the same as the old one).

Parameters:
  • clientConnectionId (int) – The id of the session that hosts the subscription.
  • clientSubscriptionHandle (int) – The id of the subscription.
Raises:
monitoredItemInformation(clientHandle)

Get information about the specified monitored item.

Check the monitoredItemState before interpreting the results of the MonitoredItemInformation! Because if the monitoredItemState is NotCreated, then the monitored item not created on the server, but instead it’s cached by the client (which tries to re-create the monitored item periodically -as configurable by the ClientSettings-).

Parameters:

clientHandle (int) – The handle of the monitored item (always assigned by the UAF, not by the user!). This clientHandle is assigned when the monitored item is requested (e.g. by calling createMonitoredData()), regardless of whether the monitored items were indeed created on the server, or not (e.g. in case of failures, or in case the server is not on-line yet).
Returns:

Information about the specified monitored item.
Return type:

MonitoredItemInformation
Raises:
notificationsMissing(info, previousSequenceNumber, newSequenceNumber)

Override this method to handle missing notifications.

Alternatively, you can also register callback functions which you defined yourself, by registering them using pyuaf.client.Client.registerNotificationsMissingCallback().

Parameters:
  • info (SubscriptionInformation) – Subscription information about the subscription which has missing notifications.
  • previousSequenceNumber (int) – Sequence number of the last notification just before notifications went missing.
  • newSequenceNumber (int) – Sequence number of the first notification just after notifications went missing.
processRequest(request, resultCallback=None, notificationCallbacks=[])

Process a generic request (as found in pyuaf.client.requests).

As for callbacks, you may:
  • specify no callbacks at all. In this case, you need to override (“virtually inherit”) the readComplete()/writeComplete()/dataChangesReceived()/... functions
  • specify a resultCallback function (only for AsyncXXXXX functions!). In this case, the ReadResult/WriteResult/MethodCallResult/... of the corresponding asynchronous requests will be forwarded to the resultCallback function.
  • specify a list of notificationCallback functions (only for CreateMonitoredDataRequests, CreateMonitoredEventsRequests, AsyncCreateMonitoredDataRequests and AsyncCreateMonitoredEventsRequests!). The number of callbacks must correspond exactly to the number of targets of the request.

Note

Both CreateMonitoredDataRequest and CreateMonitoredEventsRequest are “persistent” requests. It means that even when communication fails (e.g. because the server was not online), a handle is already assigned to each monitored item as soon as you call processRequest(). In the background, the UAF will try to (re)establish the connection, and as soon as this is successful, it will create the monitored items for you on the server. From that point on, you may start to receive notifications (that can be identified by the handles that were already assigned and returned to you now). So when processRequest() fails, you need to be aware that in the background the UAF will retry to create them on the server. You can access the handles that will identify their notifications:

Warning

Asynchronous requests MUST be invoked on a single session. Meaning: the targets of asynchronous requests MUST belong to the same server (as the UAF can currently not reconstruct an asynchronous request that must be “split up” to be called on multiple servers). If they don’t belong to the same server, an error will be raised.

Warning

The callbacks will run in a separate thread, and therefore any exception they raise will not be handled or propagated. So your callbacks should have a try-except clause if you want to be able to properly handle the exceptions that they may raise.

Parameters:request – The request (e.g. a ReadRequest or class:~pyuaf.client.requests.WriteRequest or ...
Returns:The result of the request (e.g. a ReadResult or WriteResult or ...
Raises:pyuaf.util.errors.UafError – Base exception, catch this to handle any UAF errors.
read(addresses, attributeId=13, **kwargs)

Read a number of node attributes synchronously.

This is a convenience function for calling processRequest with a ReadRequest as its first argument. For full flexibility, use that function.

Parameters:
Returns:

The result of the read request.
Return type:

ReadResult
Raises:

pyuaf.util.errors.UafError – Base exception, catch this to handle any UAF errors.
readComplete(result)

Override this method to catch the result of asynchronous read requests.

This method will only be called by the UAF if you didn’t provide an “external” callback function already when you began the asynchronous read request.

In other words, there are two ways how you can catch the result of asynchronous read requests:

  • either by calling processRequest() or :meth:~pyuaf.client.Client.beginRead without providing an external callback function –> then you need to override readComplete()
  • or by calling processRequest() with providing an external callback function –> then only the external callback function will be called.
Parameters:result (ReadResult) – The asynchronously received read result.
registerConnectErrorCallback(callback)

Register a callback function to handle connect errors.

If you register a callback function, this callback function will be called instead of the connectErrorReceived() function (so the latter function will NOT be called anymore!).

The callback function should have:

  • 4 input arguments: clientConnectionId, connectionStep, sdkStatus, clientSideError
  • 1 returned value: a bool

The signature of this method (and the meaning of these input arguments and returned value) is exactly the same as connectErrorReceived().

Parameters:callback – A callback function for handling connectErrors.
registerConnectionStatusCallback(callback, onlyServerUri=None, onlyClientConnectionId=None)

Register a callback to receive connection status changes.

You can register multiple callbacks: all of them will be called. The pyuaf.client.Client.connectionStatusChanged() method (which you may override) will also always be called, regardless of the callbacks you register.

There’s no need to provide more than one optional argument (it doesn’t make much sense in fact, since onlyClientConnectionId is more restrictive than onlyServerUri), but it’s not forbidden either. In case you provide multiple optional arguments, all of the conditions need to be satisfied for the callback function to be called.

Parameters:
  • callback – A callback function. This function should have one input argument, to which the changed SessionInformation instance will be passed.
  • onlyServerUri (str) – Optional argument: provide this argument if you don’t want to listen to the status changes of all sessions to any server, but only listen to the connection changes for all sessions to the server identified by the given serverUri.
  • onlyClientConnectionId (int) – Optional argument: provide this argument if you don’t want to listen to the status changes of all sessions to any server, but only listen to the connection changes for the single session identified by the given unique clientConnectionId.
registerKeepAliveCallback(callback, onlyClientSubscriptionHandle=None)

Register a callback to handle KeepAlive notifications.

You can register multiple callbacks: all of them will be called. The pyuaf.client.Client.keepAliveReceived() method (which you may override) will also always be called, regardless of the callbacks you register.

Parameters:
  • callback – A callback function. This function should have one input argument of type pyuaf.client.KeepAliveNotification.
  • onlyClientSubscriptionHandle (int) – Optional argument: provide this argument if you don’t want to listen to the KeepAlive notifications of all subscriptions, but only listen to the KeepAlive notifications for the single subscription identified by the given unique clientSubscriptionHandle.
registerLoggingCallback(callback)

Register a callback function to receive all log messages.

If you register a callback function, this callback function will be called instead of the logMessageReceived() function (so the latter function will NOT be called anymore!).

Parameters:callback – A callback function for the logging. This function should have one input argument, which you should call “msg” or so, because this argument is of type pyuaf.util.LogMessage.
registerNotificationsMissingCallback(callback, onlyClientSubscriptionHandle=None)

Register a callback to handle missing notifications.

You can register multiple callbacks: all of them will be called. The pyuaf.client.Client.notificationsMissing() method (which you may override) will also always be called, regardless of the callbacks you register.

Parameters:
  • callback –

    A callback function. This function should have three input arguments:

    • first argument will be a SessionInformation instance, describing the subscription that has missing notifications.
    • second argument will be an int representing the sequence number of the last notification just before notifications went missing.
    • third argument will be an int representing the sequence number of the first notification just after notifications went missing.
  • onlyClientSubscriptionHandle (int) – Optional argument: provide this argument if you don’t want to listen to the missing notifications of all subscriptions, but only listen to the missing notifications for the single subscription identified by the given unique clientSubscriptionHandle.
registerSubscriptionStatusCallback(callback, onlyClientSubscriptionHandle=None)

Register a callback to receive connection status changes.

You can register multiple callbacks: all of them will be called. The pyuaf.client.Client.subscriptionStatusChanged() method (which you may override) will also always be called, regardless of the callbacks you register.

Parameters:
  • callback – A callback function. This function should have one input argument, to which the changed SessionInformation instance will be passed.
  • onlyClientSubscriptionHandle (int) – Optional argument: provide this argument if you don’t want to listen to the status changes of all subscriptions, but only listen to the subscription changes for the single subscription identified by the given unique clientSubscriptionHandle.
registerUntrustedServerCertificateCallback(callback)

Register a callback function to handle untrusted certificates during the connection process.

If you register a callback function, this callback function will be called instead of the untrustedServerCertificateReceived() function (so the latter function will NOT be called anymore!).

The callback function should have:

The signature of this method (and the meaning of these input arguments and returned value) is exactly the same as untrustedServerCertificateReceived().

Parameters:callback – A callback function for handling untrusted certificates.
serversFound()

Get a list of the application descriptions of the servers found in the discovery process.

The discovery is periodically being run in the background, so the returned list may change. The cycle time is of the discovery is configurable via the ClientSettings.

Returns:A list of the application descriptions that were found.
Return type:list of pyuaf.util.ApplicationDescription
serversOnNetworkFound()

Get a list of the server descriptions of the servers found by querying the LDS.

The discovery is periodically being run in the background, so the returned list may change. The cycle time is of the discovery is configurable via the ClientSettings.

Returns:A list of the servers that were found.
Return type:list of pyuaf.util.ServerOnNetwork
sessionInformation(clientConnectionId)

Get information about the specified session.

Parameters:

clientConnectionId (int) – The client connection id (always assigned by the UAF, not by the user!).
Returns:

Information about the specified session.
Return type:

pyuaf.client.SessionInformation
Raises:
setClientSettings(settings)

Change the client settings.

Parameters:settings (pyuaf.client.settings.ClientSettings) – The new settings.
setMonitoringMode(clientHandles, monitoringMode, serviceSettings=None)

Set the monitoring mode for the specified monitored items.

This is the preferred way to temporarily stop receiving notifications for certain monitored items (e.g. because a tab in a User Interface is not visible). See the example below.

Note that clientHandles instead of MonitoredItemIds are used to identify a monitored item. ClientHandles are assigned by the client and are therefore static, while MonitoredItemIds are assigned by the server, so they may change over time (e.g. after restarting the server, of after failover to a redundant server). The UAF will keep track of the mapping between both. This means that your monitored items are always identified in the same way (by their clientHandles), no matter what happens on the server-side. The UAF takes care of the conversion automatically, so you don’t have to worry about it.

Example:

>>> import pyuaf
>>> from pyuaf.util.errors import UafError, CreateMonitoredItemsError
>>> from pyuaf.util import Address, NodeId
>>> from pyuaf.client import Client
>>> from pyuaf.util import monitoringmodes 
>>> 
>>> myClient     = Client("myClient", ["opc.tcp://localhost:4841"])
>>>
>>> nameSpaceUri = "http://mycompany.com/mymachine"
>>> serverUri    = "http://mycompany.com/servers/plc1"
>>> temperature  = Address( NodeId("myMachine.temperature", nameSpaceUri), serverUri)
>>> pressure     = Address( NodeId("myMachine.pressure", nameSpaceUri), serverUri)
>>>
>>> def updateTemperatureWidget(notification):
...      temperatureIndicator.display("%.1f K" %notification.data.value)
>>>
>>> def updatePressureWidget(notification):
...      pressureIndicator.display("%.1f Bar" %notification.data.value)
>>>
>>> try:
...     result = myClient.createMonitoredData(
...                 addresses = [temperature, pressure], 
...                 notificationCallbacks = [updateTemperatureWidget, updatePressureWidget])
...     # store the clientHandles:
...     clientHandles = [ target.clientHandle for target in result.targets ]
... except CreateMonitoredItemsError, e:
...     # The monitored items could not be created, because there was some failure
...     #  (maybe the server is off-line?).
...     # Nevertheless, the client handles were already assigned, and we can get them like this: 
...     clientHandle = e.assignedClientHandles[0]
... except UafError, e:
...     print("Oops, an unexpected error!")
>>> 
>>> def uiTabChangedState(visible):
...     if visible:
...          monitoringMode = monitoringmodes.Sampling
...     else:
...          monitoringMode = monitoringmodes.Reporting
...     try:
...         statuses = myClient.setMonitoringMode(clientHandles, monitoringMode)
...         for i in xrange(len(statuses)):
...             if not statuses[i].isGood():
...                 print("Could not set monitoring mode of widget %d: %s" %(i, statuses[i])) 
...     except UafError, e:
...         print("Couldn't set the new monitoring mode: %s" %e)
Parameters:
Returns:

A list of statuses, one for each client handle.
Return type:

StatusVector.
Raises:

pyuaf.util.errors.UafError – Base exception, catch this to handle any UAF errors.
setPublishingMode(clientSubscriptionHandle, publishingEnabled, serviceSettings=None)

Set the publishing mode, by specifying a subscription handle.

Note that a subscription handle may not be known at the time when you create the monitored items. E.g. when you call createMonitoredData() or createMonitoredEvents(), it can happen that the server that hosts the monitored items is not on-line yet. In this case, the ClientSubscriptionHandle is not assigned yet, but ClientHandles are assigned yet. Therefore it makes sense to first call monitoredItemInformation() of your monitored item, and get the subscription handle from there.

E.g. like this:

>>> import pyuaf
>>> from pyuaf.util.errors import UafError, CreateMonitoredItemsError
>>> from pyuaf.util import Address, NodeId
>>> from pyuaf.client import Client
>>> 
>>> myClient     = Client("myClient", ["opc.tcp://localhost:4841"])
>>>
>>> nameSpaceUri = "http://mycompany.com/mymachine"
>>> serverUri    = "http://mycompany.com/servers/plc1"
>>> address = Address( NodeId("myMachine.myVariable", nameSpaceUri), serverUri)
>>>
>>> def myCallback(notification):
...      print("A data change was received: %s" %notification)
>>>
>>> try:
...     result = myClient.createMonitoredData([address], 
...                                           notificationCallbacks = [myCallback])
...     clientHandle = result.targets[0].clientHandle
... except CreateMonitoredItemsError, e:
...     # The monitored items could not be created, because there was some failure
...     #  (maybe the server is off-line?).
...     # Nevertheless, the client handles were already assigned, and we can get them like this: 
...     clientHandle = e.assignedClientHandles[0]
... except UafError, e:
...     print("Oops, an unexpected error!")
>>> 
>>> 
>>> info = myClient.monitoredItemInformation(clientHandle)
>>>
>>> if info.monitoredItemState == pyuaf.client.monitoreditemstates.Created:
...     # enable the subscription that hosts the monitored item:
...     myClient.setPublishingMode(info.clientSubscriptionHandle, True)
...         
...     # ... do some stuff ...
...         
...     # disable the subscription that hosts the monitored item:
...     myClient.setPublishingMode(info.clientSubscriptionHandle, False)
Parameters:
  • clientSubscriptionHandle (int) – The handle identifying the subscription.
  • publishingEnabled (bool) – True to enable the publishing mode, false to disable.
  • serviceSettings (pyuaf.client.settings.ServiceSettings) – The service settings to be used (leave None for default settings).
Raises:
structureDefinition(dataTypeId)

Get a structure definition for the given datatype NodeId.

Parameters:

dataTypeId (NodeId.) – NodeId of the datatype.
Returns:

The definition of this datatype.
Return type:

StructureDefinition.
Raises:
subscriptionInformation(clientSubscriptionHandle)

Get information about the specified subscription.

Parameters:

clientSubscriptionHandle (int) – The client subscription handle (always assigned by the UAF, not by the user!).
Returns:

Information about the specified subscription.
Return type:

SubscriptionInformation
Raises:
subscriptionStatusChanged(info)

Override this method to receive subscription status changes.

Alternatively, you can also register callback functions which you defined yourself, by registering them using pyuaf.client.Client.registerSubscriptionStatusCallback().

Parameters:info (SubscriptionInformation) – Updated subscription information.
unregisterConnectErrorCallback()

Unregister a callback function to stop handling connect errors.

If you unregister a callback function, the connect error will be send to connectErrorReceived() instead.

unregisterLoggingCallback()

Unregister a callback function to stop receiving all log messages.

If you unregister a callback function, and callback logging is still enabled (via the client settings), the log messages will be sent to the :meth:logMessageReceived method (so you can virtually override this method to receive the log messages).

unregisterUntrustedServerCertificateCallback()

Unregister a callback function to stop handling untrusted certificates.

If you unregister a callback function, the untrusted certificates will be send to untrustedServerCertificateReceived() instead (so you can override this method to receive the certificates).

untrustedServerCertificateReceived(certificate, cause)

Override this method if you want to handle an untrusted certificate.

This method is called by the UAF whenever an untrusted (e.g. unknown) server certificate must be checked at the application level (as part of the connection step, before a communication channel is established). Note that this has nothing to do with signed or encrypted communication! Even if you don’t want to connect to a secured endpoint, you’re advised to verify the certificate of the server to make sure you’re talking to the right one.

It will not be called however when you registered a callback function via registerUntrustedServerCertificateCallback(). So you must choose how to handle untrusted server certificates: - either by overriding untrustedServerCertificateReceived() - or by registering a callback via registerUntrustedServerCertificateCallback().

This method will be called by the UAF, so you must override it. It is called by the UAF whenever it thinks that it should verify the certificate of the server (i.e. during (re)connection).

Typically, during the first connection to a server, the certificate of the server is not known to the client yet. By overriding this method, you can therefore show the certificate to the user of your software, and ask him/her whether or not he/she thinks the certificate can be trusted.

Three options are available:

  • Action_Reject: don’t trust the certificate, and therefore don’t try to connect.
  • Action_AcceptTemporarily: trust the certificate temporarily, i.e. don’t store it in the trust list but just -for now- allow connection to the server. If the UAF must reconnect at some point to the server and the server certificate must be checked again, the user shall again have to confirm the certificate.
  • Action_AcceptPermanently: store the certificate in the trust list (as defined by the certificateTrustListLocation: setting) and accept the connection. Since the certificate is stored on disk in the trust list, the client application will automatically trust the certificate in the future (until the certificate expires, of course).

Warning

You must always return one of the following integers:

Warning

By default, Action_AcceptTemporarily is returned, which means that all untrusted certificates will be accepted by default! Admittingly that doesn’t sound very safe, but it simply implies that by default a pyuaf Client will be able to connect to any (unknown) server without needing to override this method. If you don’t trust the servers in your network, you should override this method.

See also

Check out example “how_to_connect_to_a_secured_endpoint.py” for more information.

Parameters:
  • certificate (pyuaf.util.PkiCertificate) – The untrusted certificate.
  • cause (pyuaf.util.Status) – The reason why it was untrusted (mostly because it is simply not found in the trust list, but it may also be that it’s not trusted because e.g. the trust list could not be opened).
Returns:

either Action_Reject or Action_AcceptTemporarily or Action_AcceptPermanently.
Return type:

int
write(addresses, data, attributeId=13, **kwargs)

Write a number of node attributes synchronously.

This is a convenience function for calling processRequest with a WriteRequest as its first argument. For full flexibility, use that function.

Parameters:
Returns:

The result of the write request.
Return type:

WriteResult
Raises:

pyuaf.util.errors.UafError – Base exception, catch this to handle any UAF errors.
writeComplete(result)

Override this method to catch the result of asynchronous write requests.

This method will only be called by the UAF if you didn’t provide an “external” callback function already when you began the asynchronous write request.

In other words, there are two ways how you can catch the result of asynchronous write requests:

  • either by calling processRequest() or :meth:~pyuaf.client.Client.beginWrite without providing an external callback function –> then you need to override writeComplete()
  • or by calling processRequest() with providing an external callback function –> then only the external callback function will be called.
Parameters:result (WriteResult) – The asynchronously received write result.

class MonitoredItemInformation

class pyuaf.client.MonitoredItemInformation(*args)

A MonitoredItemInformation object contains information about a monitored item.

  • Methods:

    __init__(*args)

    Construct a new MonitoredItemInformation object.

    __str__(*args)

    Get a string representation.

  • Attributes:

    monitoredItemState

    An int representing the state of the monitored item (e.g. Created).

    The possible states are defined in the pyuaf.client.monitoreditemstates module.

    clientConnectionId

    The id of the session that hosts the subscription (which in turn hosts the monitored item), as a long.

    clientSubscriptionHandle

    The handle of the subscription that hosts the monitored item, as a long.

    clientHandle

    The handle of the monitored item, as a long.

    settings

    The settings of this particular monitored item, as an instance of type MonitoredItemSettings.

class MonitoredItemNotification

class pyuaf.client.MonitoredItemNotification(*args)

A MonitoredItemNotification is the common superclass class of DataChangeNotification and EventNotification.

  • Methods:

    __init__(*args)

    Construct a new MonitoredItemNotification.

    You’ll never need to create notifications like this yourself because:
    __str__(*args)

    Get a string representation.

  • Attributes:

    clientHandle

    A clientHandle is a 32-bit number assigned by the UAF to newly created monitored items. Essentially, it allows you to identify the monitored item of which you receive this notification.

    You can store the client handle when you created the monitored item, see for example the use case example at pyuaf.client.results.CreateMonitoredDataResultTarget.clientHandle().

    If you use “notification callbacks”, you don’t need to worry about client handles (because the notifications will be automatically mapped to your callback functions that implement behavior for a specific monitored item.

class DataChangeNotification

class pyuaf.client.DataChangeNotification(*args)

A DataChangeNotification is a notification for a monitored data item.

class EventNotification

class pyuaf.client.EventNotification(*args)

An EventNotification is a notification for a monitored event item.

class KeepAliveNotification

class pyuaf.client.KeepAliveNotification(*args)

A KeepAliveNotification is sent by the server to notify the client that the subscription is still alive.

It is sent when the data that is monitored by the client has not changed for a while. E.g. suppose a client wants to monitor some data, and it specifies a publishingIntervalSec of 1.0 seconds and a maxKeepAliveCount of 5. As a result, when the monitored data changes rapidly, the client will be notified once per second. But every time the monitored data remains constant for 1.0 * 5 = 5.0 seconds, a KeepAliveNotification will be sent instead to notify the client that everything is still OK.

class SessionInformation

class pyuaf.client.SessionInformation(*args)

A SessionInformation object contains information about a session such as the state of the session, the server URI of the server to which it is connected, etc.

  • Methods:

    __init__(*args)

    Construct a new SessionInformation object.

    __str__(*args)

    Get a string representation.

  • Attributes:

    clientConnectionId

    The id of the session, as a long.

    sessionState

    An int representing the state of the session (e.g. Connected).

    serverState

    An int representing the state of the server (e.g. Running).

    The possible states are defined in the pyuaf.util.serverstates module.

    serverUri

    The URI of the server to which the session should be connected, as a str.

    lastConnectionAttemptStep

    The step of the connection process (corresponding to the lastConnectionAttemptStatus), as an int.

    The possible steps are defined in the pyuaf.client.connectionsteps module.

    lastConnectionAttemptStatus

    The status of the last connection attempt, as a Status instance.

    sessionSettings

    The session settings of the session (type: SessionSettings).

class SubscriptionInformation

class pyuaf.client.SubscriptionInformation(*args)

A SubscriptionInformation object contains information about a subscription such as the state of the subscription, the handle, etc.

  • Methods:

    __init__(*args)

    Construct a new SubscriptionInformation object.

    __str__(*args)

    Get a string representation.

  • Attributes:

    clientConnectionId

    The id of the session that hosts the subscription, as a long.

    clientSubscriptionHandle

    The handle of the subscription, as a long.

    subscriptionState

    An int representing the state of the subscription (e.g. Created).

    The possible states are defined in the pyuaf.client.subscriptionstates module.

    subscriptionSettings

    The subscription settings of the subscription (type: SubscriptionSettings).