The EventFilter provides for the filtering and content selection of Event Subscriptions.
If an Event Notification conforms to the filter defined by the where parameter of the EventFilter, then the Notification is sent to the Client.
Each Event Notification shall include the fields defined by the selectClauses parameter of the EventFilter. The defined EventTypes are specified in OPC 10000-5.
The selectClauses and whereClause parameters are specified with the SimpleAttributeOperand structure (see 18.104.22.168). This structure requires the NodeId of an EventType supported by the Server and a path to an InstanceDeclaration. An InstanceDeclaration is a Node which can be found by following forward hierarchical references from the fully inherited EventType where the Node is also the source of a HasModellingRule reference. EventTypes, InstanceDeclarations and Modelling Rules are described completely in OPC 10000-3.
In some cases the same SimpleAttributeOperand.browsePath will apply to multiple EventTypes. If the Client specifies the BaseEventType in the SimpleAttributeOperand.typeDefinitionId then the Server shall evaluate the SimpleAttributeOperand.browsePath without considering the SimpleAttributeOperand.typeDefinitionId.
Each InstanceDeclaration in the path shall be Object or Variable Node. The final Node in the path may be an Object Node; however, Object Nodes are only available for Events which are visible in the Server’s AddressSpace.
The SimpleAttributeOperand structure allows the Client to specify any Attribute; however, the Server is only required to support the Value Attribute for Variable Nodes and the NodeId Attribute for Object Nodes. That said, profiles defined in OPC 10000-7 may make support for additional Attributes mandatory.
The SimpleAttributeOperand structure is used in the selectClauses to select the value to return if an Event meets the criteria specified by the whereClause. A null value is returned in the corresponding event field in the Publish response if the selected field is not part of the Event or an error was returned in the selectClauseResults of the EventFilterResult. If the selected field is supported but not available at the time of the event notification, the event field shall contain a StatusCode that indicates the reason for the unavailability. For example, the Server shall set the event field to Bad_UserAccessDenied if the value is not accessible to the user associated with the Session. If a Value Attribute has an uncertain or bad StatusCode associated with it then the Server shall provide the StatusCode instead of the Value Attribute. The Server shall set the event field to Bad_EncodingLimitsExceeded if a value exceeds the maxResponseMessageSize. The EventId, EventType and ReceiveTime cannot contain a StatusCode or a null value.
The Server shall validate the selectClauses when a Client creates or updates the EventFilter. Any errors which are true for all possible Events are returned in the selectClauseResults parameter described in Table 148. Some Servers, like aggregating Servers, may not know all possible EventTypes at the time the EventFilter is set. These Servers do not return errors for unknown EventTypes or BrowsePaths. The Server shall not report errors that might occur depending on the state or the Server or type of Event. For example, a selectClauses that requests a single element in an array would always produce an error if the DataType of the Attribute is a scalar. However, even if the DataType is an array an error could occur if the requested index does not exist for a particular Event, the Server would not report an error in the selectClauseResults parameter if the latter situation existed.
The SimpleAttributeOperand is used in the whereClause to select a value which forms part of a logical expression. These logical expressions are then used to determine whether a particular Event should be reported to the Client. The Server shall use a null value if any error occurs when a whereClause is evaluated for a particular Event. If a Value Attribute has an uncertain or bad StatusCode associated with it, then the Server shall use a null value instead of the Value.
The Server shall validate the whereClause when a Client creates or updates the EventFilter. Any structural errors in the construction of the filter and any errors which are true for all possible Events are returned in the whereClauseResult parameter described in Table 148. Errors that could occur depending on the state of the Server or the Event are not reported. Some Servers, like aggregating Servers, may not know all possible EventTypes at the time the EventFilter is set. These Servers do not return errors for unknown EventTypes or BrowsePaths.
EventQueueOverflowEventType Events are special Events which are used to provide control information to the Client. These Events are only published to the MonitoredItems in the Subscription that produced the EventQueueOverflowEventType Event. These Events bypass the whereClause.
Table 147 defines the EventFilter structure.
Table 147 – EventFilter structure
|selectClauses ||SimpleAttributeOperand||List of the values to return with each Event in a Notification. At least one valid clause shall be specified. See 22.214.171.124 for the definition of SimpleAttributeOperand.|
|whereClause||ContentFilter||Limit the Notifications to those Events that match the criteria defined by this ContentFilter. The ContentFilter structure is described in 7.7.The AttributeOperand structure may not be used in an EventFilter.|
Table 148 defines the EventFilterResult structure. This is the MonitoringFilterResult associated with the EventFilter MonitoringFilter.
Table 148 – EventFilterResult structure
|selectClauseResults ||StatusCode||List of status codes for the elements in the select clause. The size and order of the list matches the size and order of the elements in the selectClauses request parameter. The Server returns null for unavailable or rejected Event fields.|
|selectClauseDiagnosticInfos ||DiagnosticInfo||A list of diagnostic information for individual elements in the select clause. The size and order of the list matches the size and order of the elements in the selectClauses request parameter. This list is empty if diagnostics information was not requested in the request header or if no diagnostic information was encountered in processing of the select clauses.|
|whereClauseResult||ContentFilterResult||Any results associated with the whereClause request parameter.The ContentFilterResult type is defined in 7.7.2.|
Table 149 – EventFilterResult Result Codes
|Bad_TypeDefinitionInvalid||See Table 183 for the description of this result code.The typeId is not the NodeId for BaseEventType or a subtype of it.|
|Bad_NodeIdUnknown||See Table 183 for the description of this result code.The browsePath is specified but it will never exist in any Event.|
|Bad_BrowseNameInvalid||See Table 183 for the description of this result code.The browsePath is specified and contains a null element.|
|Bad_AttributeIdInvalid||See Table 183 for the description of this result code.The node specified by the browse path will never allow the given AttributeId to be returned.|
|Bad_IndexRangeInvalid||See Table 183 for the description of this result code.|
|Bad_TypeMismatch||See Table 183 for the description of this result code.The indexRange is valid but the value of the Attribute is never an array.|