| Previous | Table of Contents | Next |
//File: DAISAESubscription.idl #ifndef _DAIS_AESUBSCRIPTION_IDL #define _DAIS_AESUBSCRIPTION_IDL #pragma prefix "omg.org"
#include <DAISAEIO.idl>
module DAIS { module AlarmsAndEvents { module Subscription {
struct State { boolean active; unsigned long buffer_time; unsigned long max_size; unsigned long keep_alive_time;
};
struct OPCSourceFilter { ServerItemIdentifications areas; ServerItemIdentifications sources;
};
typedef short SourceFilterType;const SourceFilterType OPC_SOURCE_FILTER_TYPE = 1;const SourceFilterType XPATH_SOURCE_FILTER_TYPE = 2;
union SourceFilter switch(SourceFilterType) { case OPC_SOURCE_FILTER_TYPE : OPCSourceFilter opc_source_filters; case XPATH_SOURCE_FILTER_TYPE
: string xpath_source_filter; };
typedef short CategoryFilterType;const CategoryFilterType OPC_REASON_FILTER_TYPE = 1;const CategoryFilterType XPATH_REASON_FILTER_TYPE= 2;
union CategoryFilter switch(ReasonFilterType) { case OPC_CATEGORY_FILTER_TYPE : ServerItemIdentifications opc_category_filters;
case XPATH_CATEGORY_FILTER_TYPE : string xpath_category_filter; };
struct FilterSpec { EventFormat event_format; CategoryFilter category_filter; unsigned long low_severity; unsigned long high_severity;
SourceFilter source_filter; ResourceIDs type_filter; };
struct PropSelection { ResourceID category; PropertyIDs properties;
};typedef sequence<PropSelection> PropSelections;
enum ReadDirection { READ_FORWARDS, READ_BAKWARDS
};
typedef unsigned long CancelID;
interface Manager
{ exception BusyDueToRefresh{string reason;}; exception HistoryNotImplemented{string reason;};
attribute IO::Callback callback;
void set_filter (in FilterSpec filer_spec) raises (BusyDueToRefresh);
FilterSpec get_filter ();
void select_returned_properties (in PropSelections prop_selections);
PropSelections get_returned_properties (in ResourceIDs categories);
CancelID refresh () raises (BusyDueToRefresh);
CancelID async_read_history ( in DateTime start_time, in unsigned long number_of_events, in ReadDirection direction, in unsigned
long transaction_id
) raises (HistoryNotImplemented);
void cancel (in CancelID cancel_id);
void refresh () raises (BusyDueToRefresh);
void refresh_with_history (in DateTime start_time,in DateTime end_time
) raises (HistoryNotImplemented);
void cancel_refresh ();
State get_state ();
State set_state ( in State subscription_spec
Manager clone ();
void destroy (); };
typedef unsigned longFilter;const Filter FILTER_BY_EVENT_FORMAT = 0x0001;const Filter FILTER_BY_CATEGORY = 0x0002;const Filter FILTER_BY_SEVERITY = 0x0004;const Filter FILTER_BY_AREA = 0x0008;const Filter FILTER_BY_SOURCE = 0x0010;const Filter FILTER_WITH_XPATH = 0x0020;const Filter FILTER_BY_SOURCE_TYPE = 0x0040;
interface IHome{
Filter query_available_filters ();
Manager create_subscription ( in State subscription_spec, out State revised_subscr_spec);
};};};}; #endif // _DAIS_AESUBSCRIPTION_IDL
State
A struct describing the state for the subscription.
| Member | Description | ||||
| active | Indicates if the subscription is active; that is, is sending data on the call back interface. Events that are appearing in the server will be lost for clients connected to inactive subscriptions. | ||||
| buffer_time | The requested buffer time in milliseconds. This is a minimum time - do not send event notifications any faster that this UNLESS max_size is greater than 0, in which case the server will send an event notification sooner to obey the max_size value. A value of 0 for buffer_time means that the server should send event notifications as soon as it gets them. This parameter along with the max_size parameter is used to improve communications efficiency between client and server. This parameter is a recommendation from the client, and the server is allowed to ignore the parameter. The server will return the buffer time it is actually providing in revised_buffer_time. |
max_size The requested maximum number of events that will be sent in a single callback. A value of 0 means that there is no
limit to the number of events that will be sent in a single callback. Note that a value of max_size greater than 0, may cause
the server to make callbacks more frequently than specified by buffer_time when a large number of events are being generated
in order to limit the number of events to the max_size. This parameter is a recommendation from the client and the server
is allowed to ignore this parameter. The server will return the actual number of events it is actually providing in revised_max_size.
keep_alive_time The time in milliseconds for the server to send a callback to client. The intention is to indicate to the
client that the server is alive and avoid the need to "poll" the server to check it is alive. If no data is available an empty
message is sent. If the time is less than the buffer_time the buffer_time is used.
OPCSourceFilter
The struct specifies source filtering by enumerating the areas and sources the way OPC does it.
Member |
Description |
||||
| areas | A sequence of ResourceIDs for the areas that shall be notified. All sources below an area node will be notified. | ||||
| sources | A sequence of ResourceIDs for sources that shall be notified. An empty sequence means all sources shall be notified. |
SourceFilter
The union specifies OPCSourceFiltering or XPath filtering. A prerequisite for XPath filtering is that the area and source
hierarchy has an XML mapping. The same mapping
is used as described in Section 3.1.12, “Logical Expressions and Navigation,? on
page 3-25 with the additional comments:
• an Area corresponds to a Node (Area inherits Node).
• a Source corresponds to a Node (Source inherits Node).
Member |
Description |
||||
| opc_source_filters | An OPCSourceFilter | ||||
| xpath_source_filter | An XPath filter. |
CategoryFilter
The union specifies OPC style filtering or XPath filtering of categories. A prerequisite for XPath filtering is that the resource
hierarchy has an XML mapping. The same
mapping is used as described in Section 3.1.12, “Logical Expressions and Navigation,?
on page 3-25 with the additional comments:
• a Resource corresponds to a Node (Resource inherits Node).
Member |
Description |
||||
| opc_category_filters | An OPCSourceFilter | ||||
| xpath_reason_filter | An XPath filter |
FilterSpec
A struct holding the specification for how the server shall filter notifications sent to the client. The struct is used to
specify the filtering a client wants a server to do for it. All specified filter criterias shall be fulfilled for a notification
to be sent.
| Member | Description | ||||
| event_format | An EventFormat bit mask specifying the event formats to be returned. | ||||
| reasons | A sequence of CategoryFilter for the categories for which the client wants to get notifications. Observe that specifying a main category (for example, Simple, Tracking, Condition) will result in notifications for all sub-categories specified for that main category. | ||||
| low_severity | The client wants all events with greater or equal severity. | ||||
| high_severity | The client wants all events with less or equal severity. | ||||
| sources | A SourceFilter for the sources that shall be notified. | ||||
| types | A sequence of TypeIDs for the types that shall be notified. |
PropSelection
A struct identifying what properties shall be included in an event notification for a specific reason.
Member |
Description |
||||
| reason | The reason for which the property selection is made. | ||||
| properties | A sequence of PropertyIDs for the selected properties. |
ReadDirection
An enumeration that tells if a read of history shall be forward or backwards in time.
Member |
Description |
||||
| READ_FORWARDS | Read events after the given start time. | ||||
| READ_BAKWARDS | Read events before the given start time. |
Manager
An object managing subscription and filtering of event notifications per client.
BusyDueToRefresh
An exception stating that a refresh is already going on.
HistoryNotImplemented
An exception stating that the server does not record the event history.
callback
An attribute holding a reference to the callback object. The client is required to update the attribute with a by the client
implemented callback object to get event notifications from the server. The attribute corresponds to the IConnectionPoint
interface in OPC.
set_filter()
The method updates the filter specification. A try to change the filter spec during an ongoing refresh will give an exception.
The method corresponds to IOPCEventSubscriptionMgt::SetFilter().
Member |
Description |
||||
| filer_spec | The filter specification. | ||||
| return | none. |
get_filter()
The method gets the filter specification. The method corresponds to IOPCEventSubscriptionMgt::GetFilter().
select_returned_properties()
The method sets what properties shall be included in a notification specified per reason. The method corresponds to IOPCEventSubscriptionMgt::SelectReturnedAttributes().
Member |
Description |
||||
| prop_selections | A sequence specifying what properties to include per reason. | ||||
| return | none. |
get_returned_properties()
The method gets what properties currently are included in a notification specified per category. The method corresponds to
IOPCEventSubscriptionMgt::GetReturnedAttributes().
| Member | Description | ||||
| categories | The categories for that shall be used to fetch the properties. | ||||
| return | A sequence specifying what properties currently are included per reason. |
refresh()
The method forces notifications for all currently active source conditions. The notifications will not include the history
but only the current source condition operational state. The method corresponds to IOPCEventSubscriptionMgt::Refresh().
async_read_history()
The method read historic events recorded by the server. If the server does not support recording of alarms and events an exception
is raised. No corresponding method exists in OPC.
| Member | Description | ||||
| start_time | The time where to start the read. An unspecified time (=0) will make the read start from the oldest recorded event. | ||||
| number_of_events | The max number of events to deliver as a response to the read operation. |
| Member | Description | ||||
| direction | Tells if events before or after the start time shall be read. | ||||
| transaction_id | A transaction number unique for the client. The number is returned in the corresponding on_read_complete call. | ||||
| return | A server generated handle that the client can use to cancel the operation. |
cancel()
The method cancels an ongoing refresh operation or async_read_history() operations. It corresponds to IOPCEventSubscriptionMgt::CancelRefresh().
| Member | Description | ||||
| cancel_id | A server generated handle that is given back to the server when a started operation shall be cancelled. | ||||
| return | none. |
get_state()
The method gets the current subscription state and corresponds to IOPCEventSubscriptionMgt::GetState().
set_state()
The method sets the current subscription state and corresponds to IOPCEventSubscriptionMgt::SetState(). The actual parameters
set are returned and an exception is raised if any input parameters are not accepted and hence changed.
Member |
Description |
||||
| subscription_spec | New state wanted for the subscription. | ||||
| return | The accepted subscription state. |
clone()
The method creates a copy of the subscription.
5-22 Data Acquisition from Industrial Systems, v1.1 June 2005
destroy()
The method destroys the subscription object.
Filter
A flag word holding flags specifying the filters that are implemented by the server.
| Flag | Description | ||||
| FILTER_BY_MAIN_CATEGORY | Filtering by main category is supported. | ||||
| FILTER_BY_CATEGORY | Filtering by sub-category is supported. | ||||
| FILTER_BY_SEVERITY | Filtering by severity is supported. | ||||
| FILTER_BY_AREA | Filtering by area is supported. | ||||
| FILTER_BY_SOURCE | Filtering by source is supported. | ||||
| FILTER_WITH_XPATH | XPath as filter description is supported. | ||||
| FILTER_BY_SOURCE_TYPE | Filtering by source type is supported. |
IHome
A factory object for creation of subscription management objects.
query_available_filters()
Gets by the server implemented filter functions. The method corresponds to IOPCEventServer::QuearyAvailableFilters().
create_subscription()
Creates a subscription management object. An invalid state will give an exception.
Set up Subscription
query_available_filters( )
Figure 5-6 Set up subscription interaction
Refresh
Figure 5-7 Refresh interaction