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



OpcLabs.EasyOpcClassicCore Assembly > OpcLabs.EasyOpc.AlarmsAndEvents Namespace > IEasyAEClient Interface : QueryEventCategories Method
The OPC server involved in the operation.

Because the OpcLabs.EasyOpc.ServerDescriptor has an implicit conversion from System.Guid, System.String and OpcLabs.EasyOpc.ServerElement, in languages that support implicit conversion operators (such as C# or VB.NET), you can simply use a GUID (representing the CLSID of the server), a string (representing the so-called OPC server descriptor string, such as a ProgID or the URL of the server), or a OpcLabs.EasyOpc.ServerElement object (result from OPC browsing), in place of this parameter, and the corresponding OPC server descriptor will be constructed automatically. When the implicit conversion operators are not supported (such as with Python.NET), you can use the FromGuid, FromString or FromServerElement static method instead.

The value of this parameter cannot be null (Nothing in Visual Basic).

One or more event types of interest. See AEEventType constants.

Because the AEEventType has an implicit conversion from System.Int64 and AEEventTypes, in languages that support implicit conversion operators (such as C# or VB.NET), you can simply use a long integer (representing the numerical value of the event types), or an element of the AEEventTypes enumeration (or a combination of AEEventTypes flags) in place of this parameter, and the corresponding event type specification will be constructed automatically. When the implicit conversion operators are not supported (such as with Python.NET), you can use the AEEventType.AEEventType Constructor(Int64) or AEEventType.AEEventType Constructor(AEEventTypes) constructor instead.

The value of this parameter cannot be null (Nothing in Visual Basic).

Finds out events categories supported by the server.

The QueryEventCategories method gives clients a means of finding out the specific categories of events supported by a given server. This method would typically be invoked prior to specifying an event filter. Servers are able to define their own custom event categories, but a list of recommended categories is provided in the OPC specification.

Server descriptor is used for specifying the OPC server. Queries event categories for given event types.

Syntax
'Declaration
 
<NotNullAttribute()>
Function QueryEventCategories( _
   ByVal serverDescriptor As ServerDescriptor, _
   ByVal eventTypes As AEEventType _
) As AECategoryElementCollection
'Usage
 
Dim instance As IEasyAEClient
Dim serverDescriptor As ServerDescriptor
Dim eventTypes As AEEventType
Dim value As AECategoryElementCollection
 
value = instance.QueryEventCategories(serverDescriptor, eventTypes)

Parameters

serverDescriptor
The OPC server involved in the operation.

Because the OpcLabs.EasyOpc.ServerDescriptor has an implicit conversion from System.Guid, System.String and OpcLabs.EasyOpc.ServerElement, in languages that support implicit conversion operators (such as C# or VB.NET), you can simply use a GUID (representing the CLSID of the server), a string (representing the so-called OPC server descriptor string, such as a ProgID or the URL of the server), or a OpcLabs.EasyOpc.ServerElement object (result from OPC browsing), in place of this parameter, and the corresponding OPC server descriptor will be constructed automatically. When the implicit conversion operators are not supported (such as with Python.NET), you can use the FromGuid, FromString or FromServerElement static method instead.

The value of this parameter cannot be null (Nothing in Visual Basic).

eventTypes
One or more event types of interest. See AEEventType constants.

Because the AEEventType has an implicit conversion from System.Int64 and AEEventTypes, in languages that support implicit conversion operators (such as C# or VB.NET), you can simply use a long integer (representing the numerical value of the event types), or an element of the AEEventTypes enumeration (or a combination of AEEventTypes flags) in place of this parameter, and the corresponding event type specification will be constructed automatically. When the implicit conversion operators are not supported (such as with Python.NET), you can use the AEEventType.AEEventType Constructor(Int64) or AEEventType.AEEventType Constructor(AEEventTypes) constructor instead.

The value of this parameter cannot be null (Nothing in Visual Basic).

Return Value

The method returns a keyed collection of OpcLabs.EasyOpc.AlarmsAndEvents.AddressSpace.AECategoryElement values, each containing information about an event category implemented by the server. The keys of the keyed collection are the event category IDs.

This method never returns null (Nothing in Visual Basic).

The individual elements of the returned value are never null (Nothing in Visual Basic).

Exceptions
ExceptionDescription

A null reference (Nothing in Visual Basic) is passed to a method that does not accept it as a valid argument.

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.

The OPC "Classic" (or OPC XML-DA) operation has failed. This operation exception in uniformly used to allow common handling of various kinds of errors. The System.Exception.InnerException always contains information about the actual error cause.

This is an operation error that depends on factors external to your program, and thus cannot be always avoided. Your code must handle it appropriately.

Example
// This example shows how to enumerate all event categories provided by the OPC server. For each category, it displays its Id 
// and description.
//
// 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.Diagnostics;
using OpcLabs.EasyOpc.AlarmsAndEvents;
using OpcLabs.EasyOpc.AlarmsAndEvents.AddressSpace;
using OpcLabs.EasyOpc.OperationModel;

namespace DocExamples.AlarmsAndEvents._EasyAEClient
{
    class QueryEventCategories 
    { 
        public static void Main1()
        {
            // Instantiate the client object.
            var client = new EasyAEClient();

            AECategoryElementCollection categoryElements;
            try
            {
                categoryElements = client.QueryEventCategories("", "OPCLabs.KitEventServer.2");
            }
            catch (OpcException opcException)
            {
                Console.WriteLine("*** Failure: {0}", opcException.GetBaseException().Message);
                return;
            }

            foreach (AECategoryElement categoryElement in categoryElements)
            {
                Debug.Assert(categoryElement != null);
                Console.WriteLine("CategoryElements[\"{0}\"].Description: {1}", categoryElement.CategoryId, categoryElement.Description);
            }
        }
    } 
}
' This example shows how to enumerate all event categories provided by the OPC server. For each category, it displays its Id 
' and description.
'
' 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 OpcLabs.EasyOpc.AlarmsAndEvents
Imports OpcLabs.EasyOpc.AlarmsAndEvents.AddressSpace
Imports OpcLabs.EasyOpc.OperationModel

Namespace AlarmsAndEvents._EasyAEClient

    Friend Class QueryEventCategories
        Public Shared Sub Main1()
            Dim client = New EasyAEClient()

            Dim categoryElements As AECategoryElementCollection
            Try
                categoryElements = client.QueryEventCategories("", "OPCLabs.KitEventServer.2")
            Catch opcException As OpcException
                Console.WriteLine("*** Failure: {0}", opcException.GetBaseException().Message)
                Exit Sub
            End Try

            For Each categoryElement As AECategoryElement In categoryElements
                Debug.Assert(categoryElement IsNot Nothing)
                Console.WriteLine("CategoryElements[""{0}""].Description: {1}", categoryElement.CategoryId, categoryElement.Description)
            Next categoryElement
        End Sub
    End Class

End Namespace
# This example shows how to enumerate all event categories provided by the OPC server. For each category, it displays
# its Id and description.
#
# 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 .NET namespaces.
from OpcLabs.EasyOpc import *
from OpcLabs.EasyOpc.AlarmsAndEvents import *
from OpcLabs.EasyOpc.OperationModel import *


# Instantiate the client object
client = EasyAEClient()

# Perform the operation
try:
    categoryElements = IEasyAEClientExtension.QueryEventCategories(client, '', 'OPCLabs.KitEventServer.2')
except OpcException as opcException:
    print('*** Failure: ' + opcException.GetBaseException().Message)
    exit()

# Display results
for categoryElement in categoryElements:
    assert categoryElement is not None
    print('CategoryElements[', categoryElement.CategoryId, '].Description: ', categoryElement.Description, sep='')
// This example shows how to work with Software Tolbox TOP Server 5 Alarms and Events.
// Use simdemo_WithA&E.opf configuration file and write a value above 1000 to Channel1.Device1.Tag1 or Channel1.Device1.Tag2.
//
// 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.Diagnostics;
using System.Threading;
using OpcLabs.EasyOpc.AlarmsAndEvents;
using OpcLabs.EasyOpc.AlarmsAndEvents.AddressSpace;
using OpcLabs.EasyOpc.AlarmsAndEvents.OperationModel;
using OpcLabs.EasyOpc.OperationModel;

namespace DocExamples.AlarmsAndEvents.SWToolbox
{
    class TOPServer_AE
    {
        public static void Main1()
        {
            // Instantiate the client object.
            var client = new EasyAEClient();

            // Browse for some areas and sources

            AENodeElementCollection areaElements;
            try
            {
                areaElements = client.BrowseAreas("", "SWToolbox.TOPServer_AE.V5", "");
            }
            catch (OpcException opcException)
            {
                Console.WriteLine("*** Failure: {0}", opcException.GetBaseException().Message);
                return;
            }

            foreach (AENodeElement areaElement in areaElements)
            {
                Debug.Assert(!(areaElement is null));
                Debug.Assert(!(areaElement.QualifiedName is null));

                Console.WriteLine("areaElements[\"{0}\"]:", areaElement.Name);
                Console.WriteLine("    .QualifiedName: {0}", areaElement.QualifiedName);

                AENodeElementCollection sourceElements =
                    client.BrowseSources("", "SWToolbox.TOPServer_AE.V5", areaElement.QualifiedName);
                foreach (AENodeElement sourceElement in sourceElements)
                {
                    Debug.Assert(sourceElement != null);

                    Console.WriteLine("    sourceElements[\"{0}\"]:", sourceElement.Name);
                    Console.WriteLine("        .QualifiedName: {0}", sourceElement.QualifiedName);
                }
            }

            // Query for event categories

            AECategoryElementCollection categoryElements;
            try
            {
                categoryElements = client.QueryEventCategories("", "SWToolbox.TOPServer_AE.V5");
            }
            catch (OpcException opcException)
            {
                Console.WriteLine("*** Failure: {0}", opcException.GetBaseException().Message);
                return;
            }

            foreach (AECategoryElement categoryElement in categoryElements)
            {
                Debug.Assert(categoryElement != null);
                Console.WriteLine("CategoryElements[\"{0}\"].Description: {1}", categoryElement.CategoryId,
                                  categoryElement.Description);
            }

            // Subscribe to events, wait, and unsubscribe

            var eventHandler = new EasyAENotificationEventHandler(client_Notification);
            client.Notification += eventHandler;

            int handle = client.SubscribeEvents("", "SWToolbox.TOPServer_AE.V5", 1000);

            Console.WriteLine("Processing event notifications for 1 minute...");
            Thread.Sleep(60 * 1000);

            client.UnsubscribeEvents(handle);
        }

        // Notification event handler
        static void client_Notification(object sender, EasyAENotificationEventArgs e)
        {
            if (!(e.Exception is null)) Console.WriteLine("e.Exception.Message: {0}", e.Exception.Message);
            if (!(e.Exception is null)) Console.WriteLine("e.Exception.Source: {0}", e.Exception.Source);
            Console.WriteLine("e.Refresh: {0}", e.Refresh);
            Console.WriteLine("e.RefreshComplete: {0}", e.RefreshComplete);
            if (!(e.EventData is null)) Console.WriteLine("e.EventData.QualifiedSourceName: {0}", e.EventData.QualifiedSourceName);
            if (!(e.EventData is null)) Console.WriteLine("e.EventData.Time: {0}", e.EventData.Time);
            if (!(e.EventData is null)) Console.WriteLine("e.EventData.Message: {0}", e.EventData.Message);
            if (!(e.EventData is null)) Console.WriteLine("e.EventData.EventType: {0}", e.EventData.EventType);
            if (!(e.EventData is null)) Console.WriteLine("e.EventData.CategoryId: {0}", e.EventData.CategoryId);
            if (!(e.EventData is null)) Console.WriteLine("e.EventData.Severity: {0}", e.EventData.Severity);
            if (!(e.EventData is null)) Console.WriteLine("e.EventData.ConditionName: {0}", e.EventData.ConditionName);
            if (!(e.EventData is null)) Console.WriteLine("e.EventData.SubconditionName: {0}", e.EventData.SubconditionName);
            if (!(e.EventData is null)) Console.WriteLine("e.EventData.Enabled: {0}", e.EventData.Enabled);
            if (!(e.EventData is null)) Console.WriteLine("e.EventData.Active: {0}", e.EventData.Active);
            if (!(e.EventData is null)) Console.WriteLine("e.EventData.Acknowledged: {0}", e.EventData.Acknowledged);
            if (!(e.EventData is null)) Console.WriteLine("e.EventData.Quality: {0}", e.EventData.Quality);
            if (!(e.EventData is null)) Console.WriteLine("e.EventData.AcknowledgeRequired: {0}", e.EventData.AcknowledgeRequired);
            if (!(e.EventData is null)) Console.WriteLine("e.EventData.ActiveTime: {0}", e.EventData.ActiveTime);
        }
    }
}
' This example shows how to work with Software Tolbox TOP Server 5 Alarms and Events.
' Use simdemo_WithA&E.opf configuration file and write a value above 1000 to Channel1.Device1.Tag1 or Channel1.Device1.Tag2.
'
' 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.AddressSpace
Imports OpcLabs.EasyOpc.AlarmsAndEvents.OperationModel
Imports OpcLabs.EasyOpc.OperationModel

Namespace AlarmsAndEvents.SWToolbox

    Friend Class TOPServer_AE
        Public Shared Sub Main1()
            Dim client = New EasyAEClient()

            ' Browse for some areas and sources

            Dim areaElements As AENodeElementCollection
            Try
                areaElements = client.BrowseAreas("", "SWToolbox.TOPServer_AE.V5", "")
            Catch opcException As OpcException
                Console.WriteLine("*** Failure: {0}", opcException.GetBaseException().Message)
                Exit Sub
            End Try

            For Each areaElement As AENodeElement In areaElements
                Debug.Assert(areaElement IsNot Nothing)
                Debug.Assert(areaElement.QualifiedName IsNot Nothing)

                Console.WriteLine("areaElements[""{0}""]:", areaElement.Name)
                Console.WriteLine("    .QualifiedName: {0}", areaElement.QualifiedName)

                Dim sourceElements As AENodeElementCollection = client.BrowseSources("", "SWToolbox.TOPServer_AE.V5", areaElement.QualifiedName)
                For Each sourceElement As AENodeElement In sourceElements
                    Debug.Assert(sourceElement IsNot Nothing)

                    Console.WriteLine("    sourceElements[""{0}""]:", sourceElement.Name)
                    Console.WriteLine("        .QualifiedName: {0}", sourceElement.QualifiedName)
                Next sourceElement
            Next areaElement

            ' Query for event categories

            Dim categoryElements As AECategoryElementCollection
            Try
                categoryElements = client.QueryEventCategories("", "SWToolbox.TOPServer_AE.V5")
            Catch opcException As OpcException
                Console.WriteLine("*** Failure: {0}", opcException.GetBaseException().Message)
                Exit Sub
            End Try

            For Each categoryElement As AECategoryElement In categoryElements
                Debug.Assert(categoryElement IsNot Nothing)
                Console.WriteLine("CategoryElements[""{0}""].Description: {1}", categoryElement.CategoryId, categoryElement.Description)
            Next categoryElement

            ' Subscribe to events, wait, and unsubscribe

            Dim eventHandler = New EasyAENotificationEventHandler(AddressOf client_Notification)
            AddHandler client.Notification, eventHandler

            Dim handle As Integer = client.SubscribeEvents("", "SWToolbox.TOPServer_AE.V5", 1000)

            Console.WriteLine("Processing event notifications for 1 minute...")
            Thread.Sleep(60 * 1000)

            client.UnsubscribeEvents(handle)
        End Sub

        ' Notification event handler
        Private Shared Sub client_Notification(ByVal sender As Object, ByVal e As EasyAENotificationEventArgs)
            If e.Exception IsNot Nothing Then
                Console.WriteLine("e.Exception.Message: {0}", e.Exception.Message)
            End If
            If e.Exception IsNot Nothing Then
                Console.WriteLine("e.Exception.Source: {0}", e.Exception.Source)
            End If
            Console.WriteLine("e.Refresh: {0}", e.Refresh)
            Console.WriteLine("e.RefreshComplete: {0}", e.RefreshComplete)
            If e.EventData IsNot Nothing Then
                Console.WriteLine("e.EventData.QualifiedSourceName: {0}", e.EventData.QualifiedSourceName)
            End If
            If e.EventData IsNot Nothing Then
                Console.WriteLine("e.EventData.Time: {0}", e.EventData.Time)
            End If
            If e.EventData IsNot Nothing Then
                Console.WriteLine("e.EventData.Message: {0}", e.EventData.Message)
            End If
            If e.EventData IsNot Nothing Then
                Console.WriteLine("e.EventData.EventType: {0}", e.EventData.EventType)
            End If
            If e.EventData IsNot Nothing Then
                Console.WriteLine("e.EventData.CategoryId: {0}", e.EventData.CategoryId)
            End If
            If e.EventData IsNot Nothing Then
                Console.WriteLine("e.EventData.Severity: {0}", e.EventData.Severity)
            End If
            If e.EventData IsNot Nothing Then
                Console.WriteLine("e.EventData.ConditionName: {0}", e.EventData.ConditionName)
            End If
            If e.EventData IsNot Nothing Then
                Console.WriteLine("e.EventData.SubconditionName: {0}", e.EventData.SubconditionName)
            End If
            If e.EventData IsNot Nothing Then
                Console.WriteLine("e.EventData.Enabled: {0}", e.EventData.Enabled)
            End If
            If e.EventData IsNot Nothing Then
                Console.WriteLine("e.EventData.Active: {0}", e.EventData.Active)
            End If
            If e.EventData IsNot Nothing Then
                Console.WriteLine("e.EventData.Acknowledged: {0}", e.EventData.Acknowledged)
            End If
            If e.EventData IsNot Nothing Then
                Console.WriteLine("e.EventData.Quality: {0}", e.EventData.Quality)
            End If
            If e.EventData IsNot Nothing Then
                Console.WriteLine("e.EventData.AcknowledgeRequired: {0}", e.EventData.AcknowledgeRequired)
            End If
            If e.EventData IsNot Nothing Then
                Console.WriteLine("e.EventData.ActiveTime: {0}", e.EventData.ActiveTime)
            End If
        End Sub
    End Class

End Namespace
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