OPC Studio User's Guide and Reference
RefreshEventSubscription Method (IEasyAEClient)
Example 



OpcLabs.EasyOpcClassicCore Assembly > OpcLabs.EasyOpc.AlarmsAndEvents Namespace > IEasyAEClient Interface : RefreshEventSubscription Method
Event subscription handle as returned by the SubscribeEvents method
Force a refresh for all active conditions and inactive, unacknowledged conditions whose event notifications match the filter of the event subscription.

Clients often need to get the current condition information from the server, particularly at client startup, for things such as a current alarm summary. The OPC Event Server supports this requirement by resending the most recent event notifications which satisfy the filter in the event subscription and which are related to active and/or unacknowledged conditions. The client can then derive the current condition status from the "refreshed" event notifications.
Syntax
'Declaration
 
Sub RefreshEventSubscription( _
   ByVal handle As Integer _
) 
'Usage
 
Dim instance As IEasyAEClient
Dim handle As Integer
 
instance.RefreshEventSubscription(handle)
void RefreshEventSubscription( 
   int handle
)
void RefreshEventSubscription( 
   int handle
) 

Parameters

handle
Event subscription handle as returned by the SubscribeEvents method
Exceptions
ExceptionDescription

One of the arguments provided to a method is not valid.

This is a usage error, i.e. it will never occur (the exception will not be thrown) in a correctly written program. Your code should not catch this exception.

Remarks

When the client needs a refreshed list of active conditions, it will request a "refresh" from the server. The server will send event notifications to that specific client indicating that they are "refresh" instead of "original" event notifications. Since the client only needs to get the current state information for conditions, only condition events will be refreshed. Remark: "Refresh" is not a general "replay" capability since the server is not required to maintain an event history. Refresh is only for updating the client's state information for active or unacknowledged conditions.

In addition to the refresh indicator, there may be other differences between original and refresh event notifications. Specifically, since some attribute information available at the time of the original event notification may be unavailable at the time of the refresh, some attributes in the refresh may be null.

Refresh and original event notifications may be interleaved. Thus, it is the responsibility of the client to check time stamps on the event notifications and put them into the correct order, to ensure correct condition status is obtained.

When sending refresh event notifications, the server indicates if there are more refresh event notifications to send (see the RefreshComplete property of EasyAENotificationEventArgs).

This method is applicable to condition-related events only. Notifications for simple events and tracking events are not returned, even if they would satisfy the filter of the event subscription.

This method is applicable both when the subscription is active and when it is inactive (see the discussion of the Active for the SubscribeEvents and ChangeEventSubscription methods).

 

This method operates (at least in part) asynchronously, with respect to the caller. The actual execution of the operation may be delayed, and the outcome of the operation (if any) is provided to the calling code using an event notification, callback, or other means explained in the text. In a properly written program, this method does not throw any exceptions. You should therefore not put try/catch statements or similar constructs around calls to this method. The only exceptions thrown by this method are for usage errors, i.e. when your code violates the usage contract of the method, such as passing in invalid arguments or calling the method when the state of the object does not allow it. Any operation-related errors (i.e. errors that depend on external conditions that your code cannot reliably check) are indicated by the means the operation returns its outcome (if any), which is described in the text. For more information, see Do not catch any exceptions with asynchronous or multiple-operation methods.
Example
// This example shows how to for a refresh for all active conditions and inactive, unacknowledged conditions.
//
// Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html .
// OPC client and subscriber examples in C# on GitHub: https://github.com/OPCLabs/Examples-QuickOPC-CSharp .
// Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
// a commercial license in order to use Online Forums, and we reply to every post.

using System;
using System.Threading;
using OpcLabs.EasyOpc.AlarmsAndEvents;
using OpcLabs.EasyOpc.AlarmsAndEvents.OperationModel;
using OpcLabs.EasyOpc.DataAccess;
using OpcLabs.EasyOpc.OperationModel;

namespace DocExamples.AlarmsAndEvents._EasyAEClient
{
    class RefreshEventSubscription
    {
        // Instantiate the OPC-A&E client object.
        static readonly EasyAEClient AEClient = new EasyAEClient();

        // Instantiate the OPC-DA client object.
        static readonly EasyDAClient DAClient = new EasyDAClient();

        public static void Main1()
        {
            var eventHandler = new EasyAENotificationEventHandler(AEClient_Notification);
            AEClient.Notification += eventHandler;

            Console.WriteLine("Processing event notifications...");
            var subscriptionFilter = new AESubscriptionFilter
            {
                Sources = new AENodeDescriptor[] { "Simulation.ConditionState1", "Simulation.ConditionState2", "Simulation.ConditionState3" }
            };
            int handle = AEClient.SubscribeEvents("", "OPCLabs.KitEventServer.2", 1000, null, subscriptionFilter);

            // The component will perform auto-refresh at this point, give it time to happen
            Console.WriteLine("Waiting for 10 seconds...");
            Thread.Sleep(10 * 1000);

            // Set some events to active state, which will cause them to appear in refresh
            Console.WriteLine("Activating conditions and waiting for 10 seconds...");
            try
            {
                DAClient.WriteItemValue("", "OPCLabs.KitServer.2", "SimulateEvents.ConditionState1.Activate", true);
                DAClient.WriteItemValue("", "OPCLabs.KitServer.2", "SimulateEvents.ConditionState2.Activate", true);
            }
            catch (OpcException opcException)
            {
                Console.WriteLine("*** Failure: {0}", opcException.GetBaseException().Message);
                return;
            }
            Thread.Sleep(10 * 1000);

            Console.WriteLine("Refreshing subscription and waiting for 10 seconds...");
            AEClient.RefreshEventSubscription(handle);
            Thread.Sleep(10 * 1000);

            AEClient.UnsubscribeEvents(handle);
            AEClient.Notification -= eventHandler;
        }

        // Notification event handler
        static void AEClient_Notification(object sender, EasyAENotificationEventArgs e)
        {
            Console.WriteLine();
            if (!e.Succeeded)
            {
                Console.WriteLine("*** Failure: {0}", e.ErrorMessageBrief);
                return;
            }

            Console.WriteLine("Refresh: {0}", e.Refresh);
            Console.WriteLine("RefreshComplete: {0}", e.RefreshComplete);
            AEEventData eventData = e.EventData;
            if (!(eventData is null))
            {
                Console.WriteLine("Event.QualifiedSourceName: {0}", eventData.QualifiedSourceName);
                Console.WriteLine("Event.Message: {0}", eventData.Message);
                Console.WriteLine("Event.Active: {0}", eventData.Active);
                Console.WriteLine("Event.Acknowledged: {0}", eventData.Acknowledged);
            }
        }
    }
}
' This example shows how to for a refresh for all active conditions and inactive, unacknowledged conditions.
'
' Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html .
' OPC client and subscriber examples in VB.NET on GitHub: https://github.com/OPCLabs/Examples-QuickOPC-VBNET .
' Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
' a commercial license in order to use Online Forums, and we reply to every post.

Imports System.Threading
Imports OpcLabs.EasyOpc.AlarmsAndEvents
Imports OpcLabs.EasyOpc.AlarmsAndEvents.OperationModel
Imports OpcLabs.EasyOpc.DataAccess
Imports OpcLabs.EasyOpc.OperationModel

Namespace AlarmsAndEvents._EasyAEClient

    Friend Class RefreshEventSubscription
        _
        Private Shared ReadOnly AEClient As New EasyAEClient()
        _
        Private Shared ReadOnly DAClient As New EasyDAClient()

        Public Shared Sub Main1()
            Dim eventHandler = New EasyAENotificationEventHandler(AddressOf AEClient_Notification)
            AddHandler AEClient.Notification, eventHandler

            Console.WriteLine("Processing event notifications...")
            Dim subscriptionFilter As New AESubscriptionFilter
            subscriptionFilter.Sources = New AENodeDescriptor() {"Simulation.ConditionState1", "Simulation.ConditionState2", "Simulation.ConditionState3"}
            Dim handle As Integer = AEClient.SubscribeEvents("", "OPCLabs.KitEventServer.2", 1000, Nothing, subscriptionFilter)

            ' The component will perform auto-refresh at this point, give it time to happen
            Console.WriteLine("Waiting for 10 seconds...")
            Thread.Sleep(10 * 1000)

            ' Set some events to active state, which will cause them to appear in refresh
            Console.WriteLine("Activating conditions and waiting for 10 seconds...")
            Try
                DAClient.WriteItemValue("", "OPCLabs.KitServer.2", "SimulateEvents.ConditionState1.Activate", True)
                DAClient.WriteItemValue("", "OPCLabs.KitServer.2", "SimulateEvents.ConditionState2.Activate", True)
            Catch opcException As OpcException
                Console.WriteLine("*** Failure: {0}", opcException.GetBaseException().Message)
                Exit Sub
            End Try
            Thread.Sleep(10 * 1000)

            Console.WriteLine("Refreshing subscription and waiting for 10 seconds...")
            AEClient.RefreshEventSubscription(handle)
            Thread.Sleep(10 * 1000)

            AEClient.UnsubscribeEvents(handle)
            RemoveHandler AEClient.Notification, eventHandler
        End Sub

        ' Notification event handler
        Private Shared Sub AEClient_Notification(ByVal sender As Object, ByVal e As EasyAENotificationEventArgs)
            Console.WriteLine()
            If Not e.Succeeded Then
                Console.WriteLine("*** Failure: {0}", e.ErrorMessageBrief)
                Exit Sub
            End If

            Console.WriteLine("Refresh: {0}", e.Refresh)
            Console.WriteLine("RefreshComplete: {0}", e.RefreshComplete)
            If e.EventData IsNot Nothing Then
                Dim eventData As AEEventData = e.EventData
                Console.WriteLine("Event.QualifiedSourceName: {0}", eventData.QualifiedSourceName)
                Console.WriteLine("Event.Message: {0}", eventData.Message)
                Console.WriteLine("Event.Active: {0}", eventData.Active)
                Console.WriteLine("Event.Acknowledged: {0}", eventData.Acknowledged)
            End If
        End Sub
    End Class
End Namespace
# This example shows how to for a refresh for all active conditions and inactive, unacknowledged conditions.
#
# Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html .
# OPC client and subscriber examples in Python on GitHub: https://github.com/OPCLabs/Examples-QuickOPC-Python .
# Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
# a commercial license in order to use Online Forums, and we reply to every post.
# The QuickOPC package is needed. Install it using "pip install opclabs_quickopc".
import opclabs_quickopc
import time

# Import .NET namespaces.
from OpcLabs.EasyOpc import *
from OpcLabs.EasyOpc.AlarmsAndEvents import *
from OpcLabs.EasyOpc.DataAccess import *
from OpcLabs.EasyOpc.OperationModel import *


# Notification event handler
def notification(sender, e):
    if not e.Succeeded:
        print('*** Failure: ', e.ErrorMessageBrief, sep='')
        return
    print('Refresh: ', e.Refresh, sep='')
    print('RefreshComplete: ', e.RefreshComplete, sep='')
    eventData = e.EventData
    if eventData is not None:
        print('Event.QualifiedSourceName: ', eventData.QualifiedSourceName, sep='')
        print('Event.Message: ', eventData.Message, sep='')
        print('Event.Active: ', eventData.Active, sep='')
        print('Event.Acknowledged: ', eventData.Acknowledged, sep='')


# Instantiate the OPC-A&E client object.
aeClient = EasyAEClient()

# Instantiate the OPC-DA client object.
daClient = EasyDAClient()

#
aeClient.Notification += notification

print('Processing event notifications...')
subscriptionFilter = AESubscriptionFilter()
subscriptionFilter.Sources = [
    AENodeDescriptor('Simulation.ConditionState1'),
    AENodeDescriptor('Simulation.ConditionState2'),
    AENodeDescriptor('Simulation.ConditionState3'),
]
handle = IEasyAEClientExtension.SubscribeEvents(aeClient, '', 'OPCLabs.KitEventServer.2', 1000, None, subscriptionFilter)

# The component will perform auto-refresh at this point, give it time to happen.
print('Waiting for 10 seconds...')
time.sleep(10)

# Set some events to active state, which will cause them to appear in refresh.
print('Activating conditions and waiting for 10 seconds...')
try:
    IEasyDAClientExtension.WriteItemValue(daClient, '', 'OPCLabs.KitServer.2',
                                          'SimulateEvents.ConditionState1.Activate', True)
    IEasyDAClientExtension.WriteItemValue(daClient, '', 'OPCLabs.KitServer.2',
                                          'SimulateEvents.ConditionState2.Activate', True)
except OpcException as opcException:
    print('*** Failure: ' + opcException.GetBaseException().Message)
    exit()
time.sleep(10)

print('Refreshing event subscription and waiting for 10 seconds...')
aeClient.RefreshEventSubscription(handle)
time.sleep(10)

aeClient.UnsubscribeEvents(handle)
aeClient.Notification -= notification

print('Finished.')
Requirements

Target Platforms: .NET Framework: Windows 10 (selected versions), Windows 11 (selected versions), Windows Server 2016, Windows Server 2022; .NET: Linux, macOS, Microsoft Windows

See Also