Previous section.

Systems Management; Event Management Service (XEMS)
Copyright © 1997 The Open Group

CORBA Implementation

Interface Descriptions

This appendix describes the interfaces along with rationale for the implementation, then gives the IDL for the CORBA implementation.

The CORBA implementation adheres stylistically to the specification given in Part 1. The type definitions for EMS data primitives are incorporated in the IDL. The IDL is specified using the C++ mapping. EMS is couched in a module to distinguish it from other constructs. A notification manager and iterator interfaces have been added for the CORBA implementation.

This implementation uses the OMG Common Objects Services (COS) Event Service interface (see reference COS V1) to provide de-coupled communications.

Primitive Data Types

These data types use a prefix to avoid keyword and namespace collisions. The remaining EMS IDL is given in terms of these primitives.
typedef boolean ems_boolean; // 1 byte typedef octet ems_byte; // 1 byte typedef char ems_char; // 1 byte typedef char ems_small_int; // 1 byte typedef char ems_usmall_int; // 1 byte typedef short ems_short_int; // 2 bytes typedef unsigned short ems_ushort_int; // 2 bytes typedef long ems_long_int; // 4 bytes typedef unsigned long ems_ulong_int; // 4 bytes typedef struct ems_hyper_int_rep_s_t { ems_long_int high; ems_ulong_int low; } ems_hyper_int; typedef struct ems_uhyper_int_rep_s_t { ems_ulong_int high; ems_ulong_int low; } ems_uhyper_int; typedef float ems_short_float; // 4 bytes typedef double ems_long_float; // 8 bytes

Composite Data Types

This implementation is based on the COS facilities described in the referenced COS publication. These COS facilities are commercially available from a number of vendors. A given CORBA implementation may use the additional facilities, assuming they will interoperate with the less robust implementations. For example, there is a COS specification for Universal Coordinated Time (utc). This implementation does not use the utc specification, because it had not been widely available in commercial COS implementations at the time of this writing.

A universal unique identifier (uuid) is a tag that can be associated with an entity. The tag is unique. Specifically, the time and sequencing elements provide a unique specification on a given node. The node specification provides uniqueness in a network.

	typedef struct uuid {
		ems_ulong_int		time_low;
		ems_ushort_int		time_mid;
		ems_ushort_int		time_hi_and_version;
		ems_usmall_int		clock_seq_hi_and_reserved;
		ems_usmall_int		clock_seq_low;
		ems_byte		node[6];
	} uuid_t;

The CORBA string is used for EMS strings.

	typedef string			string_t;

	typedef struct string_list_s_t {
		sequence<string_t> strings;
	} string_list_t;

The timestamp is from the X/Open DCE Time Service as articulated in COS V11.

	typedef Time::UtcT		utc_t;

The EMS specification de-couples the security mechanism for the CORBA transport from the EMS security characteristics. This maximizes implementation flexibility, providing avenues for security adapters within an implementation. Such an adapter may bridge the CORBA security model with that of a given operating system.

	typedef enum secobjtype_e_t {
		secobj_server,
		secobj_eventtypes,
		secobj_filters,
		secobj_consumers,
		secobj_suppliers,
		secobj_eventtype,
		secobj_filter
	} secobjtype_t;

	typedef struct secobj {
		secobjtype_t		secobjtype;
		string_t			name;
		uuid_t			uuid;
	} secobj_t;

	typedef struct secperm {
		ems_usmall_int		control;
		ems_usmall_int		delete;
		ems_usmall_int		insert;
		ems_usmall_int		read;
		ems_usmall_int		write;
		ems_usmall_int		execute;
	} secperm_t;

	typedef struct secsubj {
		string_t			name;
		uuid_t			uuid;
	} secsubj_t;

	typedef struct secprin {
		Principal		principal;
	} secprin_t;

Events are composed of attributes (data elements). This implementation uses an untyped event model. The any contains the type code for the attribute, eliminating the need for a separate struct attribute_s_t and attr_value_t:

	typedef any			attribute_t;

An event identifier is a composite consisting of the event type and an instance identifier, that is, a uuid:

	typedef struct eventid_s_t {
		event_type_t		type;
		uuid_t			id;
	} eventid_t;

Suppliers may be adapters, extracting events from one domain and couching them in terms of EMS events. As such, a variety of network naming schemes may be used to describe the event origin:

	typedef enum nameservice_e_t {
		ns_other,
		ns_dns,
		ns_dce,
		ns_x500,
		ns_nis,
		ns_sna
	} nameservice_t;

	typedef struct netaddr_s_t {
		sequence<octet>	name;
	} netaddr_t;

	typedef struct netname_s_t {
		nameservice_t		service;
		netaddr_t		netaddr;
	} netname_t;

The specification of the consumer is unique to the CORBA implementation. This is due to the use of the COS Event Service. This implementation provides support for both push and pull consumers:

	enum ConsumerType {
		PULLCONSUMER,
		PUSHCONSUMER
	} ;

	typedef union EventConsumer switch(ConsumerType) {
		case PULLCONSUMER:
			CosEventComm::PullConsumer pullc;
		case PUSHCONSUMER:
			CosEventComm::PushConsumer pushc;
	} consumer_t;

	typedef struct consumer_list_s_t {
		sequence<consumer_t> consumer;
	} consumer_list_t;

The specification of the supplier is unique to the CORBA implementation. This is due to the use of the COS Event Service. This implementation provides support for both push and pull suppliers:

	enum SupplierType {
		PULLSUPPLIER,
		PUSHSUPPLIER
	} ;

	typedef union EventSupplier switch(SupplierType) {
		case PULLSUPPLIER:
			CosEventComm::PullSupplier pulls;
		case PUSHSUPPLIER:
			CosEventComm::PushSupplier pushs;
	} supplier_t;

	typedef struct supplier_list_s_t {
		sequence<supplier_t> supplier;
	} supplier_list_t;

The event origin retains the structure given in Part 12. The notions of and data type primitives for process, user, and group identifiers vary by operating system. For this implementation, these are assumed to be supplementary fields:

	typedef struct ems_origin_s_t {
		supplier_t		supplier;
		string_t			descname;
		ems_ulong_int		pid;		// supplementary field
		ems_ulong_int		uid;		// supplementary field
		ems_ulong_int		gid;		// supplementary field
	} origin_t;

There are competing notions of event severity and priority classification. Some notions are problem domain specific. This implementation uses the specification in Part 1 for lack of a clear alternative:

	typedef enum severity_e_t {
		sev_info,
		sev_fatal,
		sev_error,
		sev_warning,
		sev_notice,
		sev_notice_verbose,
		sev_debug
	} severity_t;

	typedef ems_ulong_int	priority_t;

These type definitions describe the layout of events. They are in accordance with Part 1 of this specification:

	typedef struct hdr_s_t {
		eventid_t		eventid;
		origin_t			origin;
		severity_t		severity;
		utc_t			received;
		utc_t			delivered;
		priority_t		priority;
	} hdr_t;

	typedef struct event_s_t {
		hdr_t			header;
		sequence<attribute_t> item;
	} event_t;

	typedef struct event_list_s_t {
		sequence<event_t>	event;
	} event_list_t;

	typedef struct event_schema_s_t {
		event_type_t		type;
		string_t			name;
		sequence<attribute_t> attr;
	} event_schema_t;

	typedef struct event_type_list_s_t {
		sequence<event_schema_t> schema;
	} event_type_list_t;

	typedef enum attr_op_e_t {
		c_attr_op_eq,
		c_attr_op_gt,
		c_attr_op_lt,
		c_attr_op_ge,
		c_attr_op_le,
		c_attr_op_ne,
		c_attr_op_bitand,
		c_attr_op_substr
	} attr_op_t;

	typedef struct attrlist_s_t {
		sequence<attribute_t> attr;
	} attrlist_t;

	typedef enum filter_grammar_e_t {
		c_fg_default,
		c_fg_OQL,
		c_fg_other
	} filter_grammar_t;

	typedef struct default_fg_s_t {
		string_t			attr_name;
		attr_op_t		attr_operator;
		attribute_t		attr_value;
	} default_fg_t;

	typedef struct filter_exp_s_t {
		union tagged switch(filter_grammar_t) {
			case c_fg_default:
				default_fg_t def_filter;
			case c_fg_OQL:
				string_t	oql_filter;
			case c_fg_other:
				string_t	other;
		} filter;
	} filter_exp_t;

	typedef struct filter_exp_list_s_t {
		sequence<filter_exp_t> filter_exp;
	} filter_exp_list_t;

	typedef struct filter_s_t {
		string_t			filter_name;
		event_type_t		type;
		filter_exp_list_t		filter_exp_list;
	} filter_t;

	typedef struct filter_list_s_t {
		sequence<filter_t>	filter;
	} filter_list_t;

	typedef struct filtername_list_s_t {
		sequence<string_t>	filter_names;
	} filtername_list_t;

Exceptions

The CORBA implementation uses CORBA user exceptions rather than returning status through and output argument. This retains the spirit of Part 1 of this specification, while conforming to CORBA C++ common practice of using exceptions for status delivery. These are mapped to the status codes specified in Part 1.

ExAlreadyRegistered
a consumer with this name is already registered.

ExConsumerAlreadyStarted
the consumer is already started.

ExConsumerNotStarted
the consumer has not started.

ExEmptyFilterDB
the listed filters could not be returned because the filter database is empty.

ExEventTypeExists
the event type to be added already exists.

ExEventTypeNotFound
the specified event type was not found.

ExFilterExists
the given filter name already exists.

ExFilterInUse
the filter cannot be deleted because it is currently in use.

ExFilterNotFound
the requested filter does not exist.

ExForwardingEventServiceNotThere

the event service to forward to is not available.

ExForwardingEventLoop
the host name introduces a loop condition, where EMS would be forwarding events to itself.

ExInsufficientPermission
the caller does not have sufficient permission to perform the operation.

ExInvalidEventType
the schema for the event type is not valid.

ExInvalidFilter
the input parameters specify an invalid filter.

ExInvalidHandle
the handle parameter is not valid.

ExInvalidName
the name parameter contains invalid characters.

ExNoConsumers
no consumers are registered.

ExNoEvent
tried to pull an event of a specified type, but there are no events to pull.

ExNoEvents
there are no undelivered events.

ExNoMemory
an EMS object could not be allocated.

ExNoSuppliers
no suppliers are registered.

ExNoTypeList
there was no type list in the function invocation.

ExUnknownConsumer
tried to unregister a consumer that was not registered.

ExUnsupportedNameService
unsupported name service on host name.

ExNotRegistered
the user, for example, the consumer, of the service is not registered.

ExNoFilters
no filters exist.

Registration Interface

The registration interface is not required for the CORBA implementation. The CORBA IDL-generated stubs have a bind method used for connecting to a specific host. In addition, each bind is interface-specific, using the CORBA COS Event Service for the connection registration.

Event Type Interface

The event type interface provides support for manipulating the event type repository.

Add

The Add operation adds a new type to the repository. This makes the new event type known to the EMS.

The input parameter contains the schema describing a new event type. This structure includes a string uniquely identifying the event type within the repository and a sequence containing the attributes supported by the new event type. Each attribute in the sequence consists of a name for the attribute, accompanied by an any value, indicating the attribute's type. Note that each event type automatically supports the attributes defined for an event header, so the list of attibutes supplied for the new event type should include any additional attributes.

Syntax
	void Add(in event_schema_t schema)
		raises(ExEventTypeExists, ExInsufficientPermission);

Exceptions
If the event type (based on the unique identifier) already exists in the repository, the ExEventTypeExists exception is raised.

If the caller is not permitted to add event types, the ExInsufficientPermission exception is raised.

Delete

The Delete operation removes an event type from the repository.

The input parameters should be the common name or the unique identifier for an existing event type. The first parameter should be the null string or the human readable name for the event type. The second parameter should be the null unique identifier or the unique identifier for the event type. At least one of the parameters must contain a non-null value. The common name should only be used when the common names are unique within the repository. The action taken for non-unique common names, when a non-unique common name is specified, is not specified. When both the common name and the unique identifier are specified, they must refer to the same event type.

Syntax
	void Delete(in string_t type_name, 
			in event_type_t type)
		raises(ExEventTypeNotFound, ExInvalidName, ExInsufficientPermission);

Exceptions
If the given event type does not exist, then the ExEventTypeNotFound exception is raised.

If both input parameters are specified and they do not refer to an event type, then the ExInvalidName exception is raised.

If the caller is not permitted to remove event types, the ExInsufficientPermission exception is raised.

Get

The Get operation retrieves the schema for the given event type from the repository.

The input parameters should be the common name or the unique identifier for an existing event type. The first parameter should be the null string or the human readable name for the event type. The second parameter should be the null unique identifier or the unique identifier for the event type. At least one of the parameters must contain a non-null value. The common name should only be used when the common names are unique within the repository. The action taken for non-unique common names, when a non-unique common name is specified, is not specified. When both the common name and the unique identifier are specified, they must refer to the same event type.

Syntax
	void Get(in string_t type_name, 
			in event_type_t type,
			out event_schema_t schema)
		raises(ExEventTypeNotFound, ExInvalidName, ExInsufficientPermission);

Exceptions
If the given event type does not exist, then the ExEventTypeNotFound exception is raised.

If both input parameters are specified and they do not refer to an event type, then the ExInvalidName exception is raised.

If the caller is not permitted to remove event types, the ExInsufficientPermission exception is raised.

GetList

The GetList operation returns the list of all event type schemas currently maintained within the repository. Each element within the returned list is a structure of the same type described above for the Add operation.
Syntax
	void GetList(out event_type_list_t type_list)
		raises(ExNoTypeList, ExInsufficientPermission);

Exceptions
If no event type schema exist in the repository, the ExNoTypeList exception is raised.

If the caller is not permitted to retrieve schema from the repository, the ExInsufficientPermission exception is raised.

Event Filter Interface

As described in the general model, the filter repository contains registered filters. Consumers can specify a list of names of registered filters, when registering with the EMS. The filter list is used to determine which events should be forwarded to a given consumer. The event filter interface defines methods supporting the management of filters by an EMS. The FreeFilter, FreeFilterList and FreeNameList operations described in Part 1 are not required for the CORBA implementation.

Add

The Add operation adds a new filter to the repository.

The first parameter should be the name for the event filter. This name must be unique among all filters in the repository. The second parameter should be the identifier for an existing event type. It associates the filter with the event type. The content of this parameter can either be the unique identifier of an event type or the common name of the event type. The third parameter contains the list of filter expressions comprising the new filter.

Syntax
	void Add(in string_t filter_name,
			in event_type_t type,
			in filter_exp_list_t exp_list)
		raises(ExInsufficientPermission, ExFilterExists, 
			ExInvalidFilter, ExEventTypeNotFound, ExInvalidName);

Exceptions
If the caller is not permitted to add the filter, the ExInsufficientPermission exception is raised.

If the filter already exists, the ExFilterExists exception is raised.

If the filter list is not properly composed, the ExInvalidFilter exception is raised.

If the given event type does not exist, the ExEventTypeNotFound exception is raised.

If the filter name contains invalid characters, the ExInvalidName exception is raised.

Append

The Append operation adds a list of filters to an existing filter expression in the filter repository.

The first parameter should specify the name of a filter that already exists within the filter repository. The second input parameter contains a list of filter expressions of the type described above. The filter repository is updated to append the list of supplied filter expressions to the end of the current list of filter expressions associated with the given filter.

Syntax
	void Append(in string_t filter_name,
			in filter_exp_list_t exp_list)
		raises(ExInsufficientPermission, ExInvalidFilter, ExFilterNotFound, 
			ExInvalidName);

Exceptions
If the caller is not permitted to add the filter, the ExInsufficientPermission exception is raised.

If the filter list is not properly composed, the ExInvalidFilter exception is raised.

If the filter does not exist in the repository, the ExFilterNotFound exception is raised.

If the filter name contains invalid characters, the ExInvalidName exception is raised.

Delete

The Delete operation removes an existing filter from the filter repository.

The parameter gives the name of the filter to be removed. This operation will only succeed if there are no users of the filter.

Syntax
	void Delete(in string_t filter_name)
		raises(ExInsufficientPermission, ExFilterNotFound, ExFilterInUse, ExInvalidName);

Exceptions
If the caller is not permitted to delete the filter, the ExInsufficientPermission exception is raised.

If the filter does not exist in the repository, the ExFilterNotFound exception is raised.

If the filter name contains invalid characters, the ExInvalidName exception is raised.

Get

The Get operation returns the filter expressions associated with a given filter in the filter repository.

The first parameter specifies the name of the filter whose filter expressions should be returned. The second parameter is an output parameter that, upon successful completion of the operation, identifies the type of event to which the filter applies. The third parameter is an output parameter that, upon successful, completion of the operation, will contain the list of filter expressions associated with the given filter.

Syntax
	void Get(in string_t filter_name,
			in event_type_t type,
			out filter_exp_list_t filter_exprs)
		raises(ExInsufficientPermission, ExFilterNotFound, ExInvalidName);

Exceptions
If the caller is not permitted to get (read) the filter, the ExInsufficientPermission exception is raised.

If the filter does not exist in the repository, the ExFilterNotFound exception is raised.

If the filter name contains invalid characters, the ExInvalidName exception is raised.

GetList

The GetList operation returns a list of all filters that currently exist in the filter repository.

Each element in the returned list contains the name of a filter, the related event type, and the list of filter expressions associated with the filter.

Syntax
	void GetList(out filter_list_t filter_list)
		raises(ExInsufficientPermission, ExEmptyFilterDB);

Exceptions
If the caller is not permitted to read the list of filter names, the ExInsufficientPermission exception is raised.

If there are no filters in the filter repository, the ExEmptyFilterDB exception is raised.

GetNameList

The GetNameList operation returns the names of the filters in the filter repository.
Syntax
	void GetNameList(out filtername_list_t name_list)
		raises(ExInsufficientPermission, ExEmptyFilterDB);

Exceptions
If the caller is not permitted to read the list of filter names, the filter, the ExInsufficientPermission exception is raised.

If there are no filters in the filter repository, the ExEmptyFilterDB exception is raised.

Consumer Interface

The consumer interface allows event consumers to register and unregister with EMS. Once registered, consumers can add and delete filters, define the interesting events, etc. When EMS receives events from event suppliers, the event is filtered, using the event filter, and only matching events are forwarded to interested consumers.

PushConsumerRegister

The PushConsumerRegister operation registers a new push consumer with the EMS.

The first parameter specifies the object reference of an object which supports the CosEventComm::PushConsumer interface. As described in COS V1 (see reference COS V1), an object supporting this interface will support a push operation which is invoked by an event supplier in order to send the consumer an event. The second input parameter specifies a list of the names of filters that describe which events the new consumer is interesting in receiving. Each filter name in the list should correspond to a filter that exists in the filter repository associated with the EMS. The information about the new consumer and the names of filters that should be applied to events to determine which the new consumer is interested in receiving is maintained in the EMS repository.

Note that from the client's perspective, this operation is invoked on the Consumer interface supported by a particular EMS. Effectively, this operation forms a connection between the target EMS and a consumer. It should be recalled that internally, each EMS manages one or more event channels of the type described COS V1 (see reference COS V1). It is anticipated that during the course of performing this operation the EMS will invoke the appropriate operations to create the push consumer relationship between the appropriate event channel and the input consumer. Any event received by the EMS for which one of the filters in the consumer's filter group evaluates to TRUE will be forwarded by the event channel to the consumer by invoking the push operation supported by the consumer's CosEventComm::PushConsumer interface. The precise relationship between event channels, event suppliers, and event consumers is left as an implementation detail since these aspects will be largely dependent on the specific implementation of the underlying event channels.

Syntax
	void PushConsumerRegister(in CosEventComm::PushConsumer consumer,
				  in filtername_list_t filter_group)
		raises(ExAlreadyRegistered, ExFilterNotFound, ExInsufficientPermissions, 
			ExNoMemory);

Exceptions
If the input consumer is already registered with the target EMS, the ExAlreadyRegistered exception is raised.

If one of the event filters named in the list contained by the second input parameter does not exist in the filter repository associated with the target EMS, the ExFilterNotFound exception is raised. The filter name field of the exception is set to the name of the missing filter from the input list.

If the consumer being registered is not authorized to register with the EMS, the ExInsufficientPermission exception is raised. This exception is also raised when the consumer is not permitted to receive one or more event types contained in the input list.

If there is insufficient memory to allocate to register the connection, the ExNoMemory exception is raised.

PullConsumerRegister

The PullConsumerRegister operation registers a new pull consumer with the EMS.

The first input parameter specifies the object reference of an object which supports the CosEventComm::PullConsumer interface. As described in COS V1 (see reference COS V1), an object supporting this interface will form a connection with an object supporting the CosEventComm::PullSupplier interface. Such an object supports pull and try_pull operations that enable the consumer to receive events available from the supplier through the event channel.

The second input parameter specifies a list of the names of filters that describe which events the new consumer is interested in receiving. Each filter name in the list should correspond to a filter in the repository. The information about the new consumer and the names of filters that should be applied to events to determine which the new consumer is interested in receiving is maintained in the EMS filter repository.

Note that from the client's perspective, this operation is invoked on the Consumer interface of the specific EMS. Effectively, this operation forms a connection between the EMS and the consumer. It should be recalled that internally, each EMS manages one or more event channels of the type described in COS V1 (see reference COS V1). It is anticipated that during the course of performing this operation the EMS will invoke the appropriate event channel and the input consumer. Any event received by the EMS for which one of the filters in the consumer's filter group evaluates to TRUE will be made available for the pulling consumer. This can be done by having the client invoke the Receive operation in the Consumer interface. This operation is likely to be implemented in terms of the pull or try_pull operations supported by an event channel managed by the EMS. The precise relationship between the EMS and the event channels, and how the connections are established between event channels, event suppliers, and event consumers is left as an implementation detail since these aspects will be largely dependent on the specific implementation of the underlying event channels.

Syntax
	void PullConsumerRegister(in CosEventComm::PullConsumer consumer,
			in filtername_list_t filter_group)
		raises(ExAlreadyRegistered, ExFilterNotFound, ExInsufficientPermission, 
			ExNoMemory);

Exceptions
If the input consumer is already registered with the target EMS, the ExAlreadyRegistered exception is raised.

If one of the event filters named in the list contained by the second input parameter does not exist in the filter repository associated with the target EMS, the ExFilterNotFound exception is raised. The filter name field of the exception is set to the name of the missing filter from the input list.

If the consumer being registered is not authorized to register with the EMS, the ExInsufficientPermission exception is raised. This exception is also raised when the consumer is not permitted to receive one or more event types contained in the input list.

If there is insufficient memory to allocate to register the connection, the ExNoMemory exception is raised.

Unregister

The Unregister operation removes knowledge of the consumer from the repository of the targeted EMS.

The input parameter specifies the object reference of the consumer to be unregistered.

Syntax
	void Unregister(in consumer_t consumer)
		raises(ExNotRegistered);

Exceptions
If the input object reference does not indicate a consumer that is registered with the target EMS, the ExNotRegistered exception is raised.

AddFilterToGroup

The AddFilterToGroup operation adds new event filters to a consumer's event filter group. A consumer's event filter group contains all filters that the consumer has registered for, and thus collectively describes all criteria that determine which events will be forwarded to the consumer.

The first input parameter is the object reference of the consumer whose event filter group is being updated. This consumer should be currently registered as a consumer of the target EMS.

The second input parameter contains a sequence of the names of event filters that should be added to the consumer's event filter group. Each element in the sequence should be the name of an event filter that currently exists in the filter repository maintained by the target EMS.

Syntax
	void AddFilterToGroup(in consumer_t consumer, 
			in filtername_list_t event_filters)
		raises(ExInsufficientPermission, ExNotRegistered, ExFilterNotFound);

Exceptions
If the first parameter is not the object reference of a currently registered consumer, the ExNotRegistered exception is raised.

If any of the elements in the second parameter is not the name of a filter, that currently exists in the filter repository, the ExFilterNotFound exceptions is raised with the filter name field of the exception structure set to the first such name encountered in the sequence.

If the input consumer is not authorized to receive events on one or more types indicated by the filters being registered for, the ExInsufficientPermission exception is raised.

DeleteFilterFromGroup

The DeleteFilterFromGroup operation removes a filter from the group of filters of the currently registered consumer.

The first input parameter is the object reference of the consumer whose event filter grop is being updated. This consumer should be currently registered in the target EMS repository.

The second input parameter contains a sequence of the names of event filters that should be removed from the consumer's event filter group. Each element in the sequence should be the name that currently exists in the target EMS filter repository, and is currently one of the event filters in the input consumers filter group.

Syntax
	void DeleteFilterFromGroup(in consumer_t consumer,
			in filtername_list_t filter_name)
		raises(ExInsufficientPermission, ExNotRegistered, ExFilterNotFound);

Exceptions
If the input consumer is not authorized to receive events on one or more types indicated by the filters being registered for, the ExInsufficientPermission exception is raised.

If the first parameter is not the object reference of a currently registered consumer, the ExNotRegistered exception is raised.

If any of the elements in the second parameter is not the name of a filter, that currently exists in the filter repository, the ExFilterNotFound exceptions is raised with the filter name field of the exception structure set to the first such name encountered in the sequence.

GetFilterGroup

The GetFilterGroup operationreturns the list of filters for which the consumer is currently registered.

The first parameter is the object reference of an event consumer that should be currently registered with the target EMS.

Upon return from this operation, the second parameter will contain a list of the names of all event filters for which the consumer is currently registered.

Syntax
	void GetFilterGroup(in consumer_t consumer,
			out filtername_list_t filter_group)
		raises(ExNotRegistered, ExNoFilters);

Exceptions
If the first parameter is not the object reference of a currently registered consumer, the ExNotRegistered exception is raised.

If the consumer is not curently registered for any event filters, the ExNoFilters exception is raised.

GetRegistration

The GetRegistration operation returns object references for current consumers.
Syntax
	void GetRegistration(out consumer_list_t push_consumers,
			 out consumer_list_t pull_consumers)
		raises(ExNoConsumers);

Exceptions
If there are no registered consumers, the ExNoConsumers exception is raised.

Receive

The Receive operation returns an event for a currently registered pull consumer.

The first input parameter is an area to receive the event for a pull consumer.

Syntax
	void Receive(inout event_t event)
		raises(ExNotRegistered);

Exceptions
If the current consumer is not currently registered as a pull consumer, the ExNotRegistered exception is raised.

ConsumerAdmin Interface

The ConsumerAdmin interface is the part of the Administration interface pertaining to the management of consumers. This interface inherits the Consumer interface, permitting the administrator to perform consumer operations with a ConsumerAdmin object reference.

ListConsumers

The ListConsumers operation lists the consumers registered with the target EMS.

Upon successful return, the output parameter contains a sequence of consumers in the consumer repository for the target EMS.

Syntax
	void ListConsumers(out consumer_list_t consumers)
		raises(ExNoConsumers);

Exceptions
If there are no consumers in the consumer repository, the ExNoConsumers exception is raised.

DeleteConsumer

The DeleteConsumer operation removes a consumer from the consumer repository of the target EMS.

At least one of the input parameters must be specified. If both parameters are specified, they must reference the same consumer. The first input parameter specifies the name of the consumer. This parameter is not specified by referencing the null string as the input parameter. The second parameter specifies the identifier of the consumer. This parameter is not specified by referencing the null identifier as the input parameter.

Syntax
	void DeleteConsumer(in string_t consumer,
			in uuid_t uuid)
		raises(ExInvalidName, ExInsufficientPermission);

Exceptions
If the input specification does not reference a consumer in the consumer repository, or the input parameters are both specified and reference different consumers, the ExInvalidName exception is raised.

If the user is not authorized to remove consumers from the consumer repository, the ExInsufficientPermission exception is raised.

AdminDeleteFilterFromGroup

The AdminDeleteFilterFromGroup operation removes a sequence of filters from a registered consumer's filter group. The registered consumer may be retrieved through the Consumer::GetRegistration operation. The sequence of filter names for the registered consumer may be obtained through the Consumer::GetFilterGroup operation.

At least one of the input parameters for the consumer name must be specified. If both parameters are specified, they must reference the same consumer. The first input parameter specifies the name of the consumer. This parameter is not specified by referencing the null string as the input parameter. The second parameter specifies the identifier of the consumer. This parameter is not specified by referencing the null identifier as the input parameter. The third input parameter is the sequence of filter names to be removed from the consumer's filter group. The filter names in the sequence must be members of the consumer's filter group.

Syntax
	void AdminDeleteFilterFromGroup(in string_t consumer,
			in uuid_t uuid,
			in filtername_list_t filter_name)
		raises(ExInvalidName, ExInvalidFilter, ExInsufficientPermission);

Exceptions
If the input specification does not reference a registered consumer for the target EMS, or the input parameters are both specified and reference different consumers, the ExInvalidName exception is raised.

If a filter name is not a member of the registered consumer’s filter group, the ExInvalidFilter exception is raised.

If the user is not authorized to remove filters from the registered consumer’s filter group, the ExInsufficientPermission exception is raised.

AdminAddFilterToGroup

The AdminAddFilterToGroup operation inserts the set of filters into the registered consumer's filter group. The registered consumer may be retrieved through the Consumer::GetRegistration operation. The sequence of filter names for the registered consumer may be obtained through the Consumer::GetFilterGroup operation.

At least one of the input parameters for the consumer name must be specified. If both parameters are specified, they must reference the same consumer. The first input parameter specifies the name of the consumer. This parameter is not specified by referencing the null string as the input parameter. The second parameter specifies the identifier of the consumer. This parameter is not specified by referencing the null identifier as the input parameter. The third input parameter is the sequence of filter names to be added to the consumer's filter group. The filter names in the sequence must not be members of the consumer's filter group.

Syntax
	void AdminAddFilterToGroup(in string_t consumer,
			in uuid_t uuid,
			in filtername_list_t filter_name)
		raises(ExInvalidName, ExInvalidFilter, ExInsufficientPermission);

Exceptions
If the input specification does not reference a registered consumer for the target EMS, or the input parameters are both specified and reference different consumers, the ExInvalidName exception is raised.

If a filter name is a member of the registered consumer’s filter group, the ExInvalidFilter exception is raised.

If the user is not authorized to add filters to the registered consumer’s filter group, the ExInsufficientPermission exception is raised.

AdminGetFilterGroup

The AdminGetFilterGroup operation retrieves a sequence of filter names representing the filter group for the given consumer. The registered consumer may be retrieved through the Consumer::GetRegistration operation.

At least one of the input parameters for the consumer name must be specified. If both parameters are specified, they must reference the same consumer. The first input parameter specifies the name of the consumer. This parameter is not specified by referencing the null string as the input parameter. The second parameter specifies the identifier of the consumer. This parameter is not specified by referencing the null identifier as the input parameter. The third parameter is the sequence of filter names representing the consumer's filter group.

Syntax
	void AdminGetFilterGroup(in string_t consumer,
			in uuid_t uuid,
			out filtername_list_t filter_name)
		raises(ExInvalidName, ExInsufficientPermission, ExNoFilters);

Exceptions
If the input specification does not reference a registered consumer for the target EMS, or the input parameters are both specified and reference different consumers, the ExInvalidName exception is raised.

If there are no members in the registered consumer’s filter group, the ExNoFilters exception is raised.

If the user is not authorized to view the filter group of the registered consumer, the ExInsufficientPermission exception is raised.

Supplier Interface

The Supplier interface provides a means for managed objects to convey events to the EMS.

PushSupplierRegister

The PushSupplierRegister operation registers a new push supplier with the target EMS.

The input parameter specifies the object reference of an object which supports the CosEventComm::PushSupplier interface. As described in COS V1 (see reference COS V1), an object supporting this interface will form a connection with an object supporting the CosEventComm::PushConsumer interface. Such an object which is often an event channel, supports a push operation that enables the supplier to send events to it.

Note that from the client's perspective, this operation is invoked on the Supplier interface for the target EMS. Effectively, this operation forms a connection between the target EMS and a supplier. It should be recalled that internally, each EMS manages one or more event channels of the type described in COS V1 (see reference COS V1). It is anticipated that during the course of performing this operation the target EMS will invoke the appropriate operations to create the push supplier relationship between the appropriate event channel and the input supplier. This will effectively enable the supplier to transmit events through an event channel managed by the target EMS. This is performed transparently whenever the supplier invokes the i.I send operation. The precise relationship between the target EMS and event channels is left as an implementation detail since these aspects will be largely dependent on the specific implementation of the underlying event channels.

Syntax
	void PushSupplierRegister(in CosEventComm::PushSupplier supplier)
		raises(ExAlreadyRegistered, ExInsufficientPermission);

Exceptions
If the input supplier is already registered with the target EMS, the ExAlreadyRegistered exception is raised.

If the input supplier in not authorized to register with the target EMS, the ExInsufficientPermission exception is raised.

PullSupplierRegister

The PullSupplierRegister operation registers a new pull supplier with the target EMS.

The input parameter specifies a reference to an object, supporting the CosEventComm::PullSupplier interface. As described in COS V1 (see reference COS V1), an object supporting this interface will support pull and try_pull operations which are invoked by an event consumer in order to transmit events to the consumer of an event.

Precisely how an EMS will pull events from suppliers registered using this operation is a detail left up to the implementers of this specification. It is envisioned that not all implementations will support this feature.

Syntax
	void PullSupplierRegister(in CosEventComm::PullSupplier supplier)
		raises(ExAlreadyRegistered, ExInsufficientPermission);

Exceptions
If the input supplier is already registered with the target EMS, the ExAlreadyRegistered exception is raised.

If the input supplier is not authorized to register with the target EMS, the ExInsufficientPermission exception is raised.

Unregister

The Unregister operation removes registration knowledge of the supplier from the target EMS.

The input parameter specifies the object reference of the supplier to be unregistered.

Syntax
	void UnRegister(in supplier_t supplier)
		raises(ExNotRegistered, ExInsufficientPermission);

Exceptions
If the input object reference does not indicate a supplier that is already registered with the target EMS, the ExNotRegistered exception is raised.

If the user is not authorized to unregister the supplier, the ExInsufficientPermission exception is raised.

Send

The Send operation transmits a message from a push supplier to an EMS, so that it can be forwarded to all clients registered with a filter that evaluates to TRUE when applied to the event. The supplier sending the message should have previously registered with the target EMS as a push supplier. Prior to invoking this operation, the supplier should set the supplier field of the origin structure in the event header to the object reference it issued when registering with the target EMS as a push supplier.

The input parameter specifies the event to be forwarded to the EMS.

Syntax
	void Send(in event_t event)
		raises(ExNotRegistered, ExInsufficientPermission);

Exceptions
If the supplier invoking this operation is not currently registered as a push supplier with the target EMS, the ExNotRegistered exception is raised.

If the supplier sending the event is not authorized to send events of the type being generated, the ExInsufficientPermission exception is raised.

GetRegistration

The GetRegistration operation returns object references for current suppliers.
Syntax
	void GetRegistration(out supplier_list_t push_suppliers,
			 out supplier_list_t pull_supplier)
		raises(ExNoSuppliers);

Exceptions
If there are no registered suppliers, the ExNoSuppliers exception is raised.

SupplierAdmin

The SupplierAdmin interface is the part of the Administrationinterfacepertainingtothe management of suppliers. This interface inherits the Supplier interface, permitting the administrator to perform supplier operations with a SupplierAdmin object reference.

ListSuppliers

The ListSuppliers operation lists the suppliers registered with the target EMS.

Upon successful return, the output parameter contains a sequence of suppliers in the supplier repository for the target EMS.

Syntax
	void ListSuppliers(out supplier_list_t suppliers)
		raises(ExInsufficientPermission, ExNoSuppliers);

Exceptions
If the user is not authorized to retrieve the sequence of suppliers, the ExInsuficientPermission exception is raised.

If there are no suppliers in the suppliers repository, the ExNoSuppliers exception is raised.

DeleteSupplier

The DeleteSupplier operation removes a supplier from the supplier repository of the target EMS.

At least one of the input parameters must be specified. If both parameters are specified, they must reference the same supplier. The first input parameter specifies the name of the supplier. This parameter is not specified by referencing the null string as the input parameter. The second parameter specifies the identifier of the supplier. This parameter is not specified by referencing the null identifier as the input parameter.

Syntax
	void DeleteSupplier(in string_t supplier,
			in uuid_t uuid)
		raises(ExInvalidName, ExInsufficientPermission);

Exceptions
If the input specification does not reference a supplier in the supplier repository, or the input parameters are both specified and reference different suppliers, the ExInvalidName exception is raised.

If the user is not authorized to remove suppliers from the supplier repository, the ExInsufficientPermission exception is raised.

EventIterator

As larger and more complex systems are built, there quickly becomes the possibility that a large number of events could be stored in the event repository at any given point. The EventIterator interface allows a client to iterate through a list of events - a subset of the events that are stored in the event repository - using the operations described in this interface.

The result of using this interface is increased scalability, usability, and performance.

NextOne

The NextOne operation returns the next event as well as TRUE, showing that there was an event available for the request. If there are no more events, FALSE is returned.
Syntax
	ems_boolean NextOne(out event_t event);

Exceptions
Standard CORBA exceptions.

NextN

The NextN operation returns how_many events (the number of requested events) from the queue. Should there be fewer than how_many events available, the maximum number of events available will be sent back. In this method, the interpretation is that at most, how_many events will be returned. Should there be no more events, FALSE is returned.
Syntax
	ems_boolean NextN(in ems_ulong_int how_many,
			  out event_list_t events);

Exceptions
Standard CORBA exceptions.

Destroy

The Destroy operation destroys the iterator.
Syntax
	void Destroy();

Exceptions
Standard CORBA exceptions.

Registry

The Registry interface is a factory for the Supplier and Consumer interfaces.

ForSupplier

The ForSupplier operation returns a Supplier object reference.
Syntax
	Supplier ForSupplier();

Exceptions
Standard CORBA exceptions.

ForConsumer

The ForConsumer operation returns a Consumer object reference.
Syntax
	Consumer ForConsumer();

Exceptions
Standard CORBA exceptions.

RegistryAdmin

The RegistryAdmin interface allows the administration of the target EMS and associated repositories. This interface inherits the Registry interface, permitting consumer and supplier operations from an object reference for this interface.

ListAttributes

The ListAttributes operation allows the users to retrieve EMS implementation defined registry attributes.
Syntax
	void ListAttributes(out attrlist_t attributes);

Exceptions
Standard CORBA exceptions.

GetUndeliveredEvents

The GetUndeliveredEvents operation permits the retrieval of undelivered events under control of an event filter from the event repository.

The first input parameter specifies the name of an event filter. The null string may be used to indicate no filtering.

The second input parameter indicates the number of events to fetch. This is used in conjunction with the EventIterator object reference returned as the last parameter.

The third parameter is the sequence of events.

The fourth parameter is the object reference for an event iterator object.

Syntax
	void GetUndeliveredEvents(in string filter_name,
			in unsigned long how_many,
			out event_list_t events,
			out EventIterator ei)
		raises(ExNoEvents, ExFilterNotFound, ExInsufficientPermission);

Exceptions
If there are no undelivered events meeting the filter criteria, the ExNoEvents exception is raised.

If the filter name does not specify the name of a filter for the target EMS, the ExFilterNotFound exception is raised.

If the user is not authorized to retrieve undelivered events, the ExInsufficientPermission exception is raised.

DeleteUndeliveredEventsByFilter

The DeleteUndeliveredEventsByFilter operation provides a mechanism for the removal of the set undelivered events meeting the evaluation criteria given by the filter.
Syntax
	void DeleteUndeliveredEventsByFilter(in string filter_name)
		raises(ExNoEvent, ExFilterNotFound, ExInsufficientPermission);

Exceptions
If there are no events meeting the filter criteria (or no undelivered events), the ExNoEvent exception is raised.

If the filter does not exist in the target EMS, the ExFilterNotFound exception is raised.

If the user is not authorized to remove undelivered events, the ExInsufficientPermission exception is raised.

DeleteUndeliveredEvent

The DeleteUndeliveredEvent operation removes the specified event from the target EMS.
Syntax
	void DeleteUndeliveredEvent(in eventid_t event)
		raises(ExNoEvent, ExInsufficientPermission);

Exceptions
If the specified event does not exist in the target EMS, the ExNoEvent exception is raised.

If the user is not authorized to retrieve undelivered events, the ExInsufficientPermission exception is raised.

Forward

The Forward operation indicates that all events satisfying the specified filter at the current EMS are to be forwarded to the EMS at the specified object reference. In effect, this operation creates a supplierinthecurrentEMS.Thefilterspecificationisappliedbythe current EMS in its forwarding supplier.

The first input parameter specifies the sequence of filters to be applied against the forwarding request. The second input parameter specifies the object reference of an object which supports the CosEventComm::PushConsumer interface. As described in COS V1 (see reference COSV1), an object supporting this interface will support a push operation which is invoked by the current EMS (using an event supplier interface) in order to send the target EMS (using a consumer interface) an event.

Syntax
	void Forward(in filtername_list_t filter_group,
			 in consumer_t xems_forward_consumer,
			 out string_t name,
			 out uuid_t uuid)
		raises(ExForwardingEventServiceNotThere,
			ExForwardingEventLoop, ExInsufficientPermission);

Exceptions
If the input host specification does not refer to an EMS or the EMS is not accessible from the current EMS, the ExForwardEventServiceNotThere exception is raised.

If the adding the specified host in conjunction with the given filter specification would cause an event forwarding loop, the ExForwardingEventLoop is raised.

If the user is not authorized to retrieve undelivered events, the ExInsufficientPermission exception is raised.

Security

The Security interface encapsulates the security administrative operations. This interface is security implementation neutral. It may be used with an implementation of the CORBA security service. It may used with other security implementations.

Edit

The Edit operation alters the permission attributes for a subject with regard to an EMS object.

The first input parameter specifies the EMS security object. The second input parameter specifies the security subject, for example, a consumer or a supplier. The third input parameter describes the new permissions. The output parameter contains the old permissions.

Syntax
	void Edit(in secobj_t secobj,
			in secsubj_t subject,
			in secperm_t newperm,
			out secperm_t oldperm)
		raises(ExInvalidName, ExInsufficientPermission);

Exceptions
If the input security object, security subject, or security permissions do not exist, the ExInvalidName exception is raised.

If the user is not authorized to edit the security permissions, the ExInsufficientPermission exception is raised.

Read

The Read operation retrieves the security permissions for the specified object and subject.

The first input parameter specifies the EMS security object. The second input parameter specifies the security subject, for example, a consumer or a supplier. The output parameter contains the current permissions.

Syntax
	void Read(in secobj_t secobj,
			in secsubj_t subject,
			out secperm_t oldperm)
		raises(ExInvalidName, ExInsufficientPermission);

Exceptions
If the input security object or security subject do not exist, the ExInvalidName exception is raised.

If the user is not authorized to retrieve security permissions, the ExInsufficientPermission exception is raised.

SubjAdd

The SubjAdd operation identifies a principal as an EMS subject.

The first input parameter specifies the EMS subject. The second input parameter specifies the principal.

Syntax
	void SubjAdd(in secsubj_t subject,
			in secprin_t principal)
		raises(ExInvalidName, ExInsufficientPermission);

Exceptions
If the input security subject already exists, the ExInvalidName exception is raised.

If the user is not authorized to add security subject/principal associations, the ExInsufficientPermission exception is raised.

SubjDelete

The SubjDelete operation removes the association of a principal with an EMS subject.

The input parameter specifies the name of an existing subject.

Syntax
	void SubjDelete(in secsubj_t subject)
		raises(ExInvalidName, ExInsufficientPermission);

Exceptions
If the input security subject does not exist, the ExInvalidName exception is raised.

If the user is not authorized to remove security subject/principal associations, the ExInsufficientPermission exception is raised.

SubjGet

The SubjGet operation retrieves the subject associated with the specified principal.

The input parameter specifies the principal. The principal may have been obtained through the CORBA get_principal operation. The output parameter contains the EMS subject associated with the principal.

Syntax
	void SubjGet(in secprin_t principal,
		out secsubj_t subject)
	raises(ExInvalidName, ExInsufficientPermission);

Exceptions
If the principal is not associated with a security subject, the ExInvalidName exception is raised.

If the user is not authorized to retrieve security subject/principal associations, the ExInsufficientPermission exception is raised.

Management Interface

The Management interface provides a means to administer various operational aspects of an EMS.

Systems Attribute

The Systems attribute provides a means of identifying a federation of EMS.
Syntax
	typedef sequence<Management> EventManagementSystems;

	readonly attribute EventManagementSystems Systems;

ObtainRegistry

The ObtainRegistry operation returns an object reference to the Registry interface.
Syntax
	Registry ObtainRegistry()
		raises(ExInsufficientPermission);

Exceptions
If the user is not authorized to retrieve the registry object reference, the ExInsufficientPermission exception is raised.

ObtainSecurity

The ObtainSecurity operation returns an object reference to the Security interface.
Syntax
	Security ObtainSecurity()
		raises(ExInsufficientPermission);

Exceptions
If the user is not authorized to retrieve the security object reference, the ExInsufficientPermission exception is raised.

ObtainTypeRepository

The ObtainTypeRepository operation returns the EventType interface object reference.
Syntax
	EventType ObtainTypeRepository()
		raises(ExInsufficientPermission);

Exceptions
If the user is not authorized to retrieve the EventType interface object reference, the ExInsufficientPermission exception is raised.

ObtainFilterRepository

The ObtainFilterRepository operation returns the EventFilter interface object reference.
Syntax
	EventFilter ObtainFilterRepository()
		raises(ExInsufficientPermission);

Exceptions
If the user is not authorized to retrieve the EventFilter interface object reference, the ExInsufficientPermission exception is raised.

IDL

//
// Event Management Service (EMS)
//

#include <CosEventComm.idl>		// COS Event Communications
#include <CosTime.idl>			// COS Time Specification
// #include <SysAdminLifeCycle.idl> EMS Location Specification

//
// eMS data primitives
//
// Note: These are outside the module definition to permit names like ems_char.
//

typedef boolean			ems_boolean;		// 1 byte
typedef octet			ems_byte;		// 1 byte
typedef	char			ems_char;		// 1 byte
typedef char			ems_small_int;		// 1 byte
typedef char			ems_usmall_int;		// 1 byte
typedef short			ems_short_int;		// 2 bytes
typedef unsigned short		ems_ushort_int;		// 2 bytes
typedef long			ems_long_int;		// 4 bytes
typedef unsigned long		ems_ulong_int;		// 4 bytes

typedef struct ems_hyper_int_rep_s_t {
	ems_long_int		high;
	ems_ulong_int		low;
} ems_hyper_int;

typedef struct ems_uhyper_int_rep_s_t {
	ems_ulong_int		high;
	ems_ulong_int		low;
} ems_uhyper_int;

typedef float			ems_short_float;// 4 bytes
typedef double			ems_long_float;	// 8 bytes

module ems {

	//
	// Universal unique identifier
	//

	typedef struct uuid {
		ems_ulong_int		time_low;
		ems_ushort_int		time_mid;
		ems_ushort_int		time_hi_and_version;
		ems_usmall_int		clock_seq_hi_and_reserved;
		ems_usmall_int		clock_seq_low;
		ems_byte		node[6];
	} uuid_t;

	//
	// String representation
	//

	typedef string			string_t;

	typedef struct string_list_s_t {
		sequence<string_t> strings;
	} string_list_t;

	//
	// Timestamp representation
	//

	typedef Time::UtcT		utc_t;

	//
	// Error Status representation
	//

	typedef ems_ulong_int		error_t;

	//
	// Event Type
	//

	typedef uuid_t			event_type_t;

	//
	// Delivery Type
	//

	typedef enum delivery_s_t {
		delivery_push,
		delivery_pull
	} delivery_t;

	//
	// Security Types
	//

	typedef enum secobjtype_e_t {
		secobj_server,
		secobj_eventtypes,
		secobj_filters,
		secobj_consumers,
		secobj_suppliers,
		secobj_eventtype,
		secobj_filter
	} secobjtype_t;

	typedef struct secobj {
		secobjtype_t		secobjtype;
		string_t			name;
		uuid_t			uuid;
	} secobj_t;

	//
	// Permissions Attributes
	//

	typedef struct secperm {
		ems_usmall_int		control;
		ems_usmall_int		delete;
		ems_usmall_int		insert;
		ems_usmall_int		read;
		ems_usmall_int		write;
		ems_usmall_int		execute;
	} secperm_t;

	//
	// Subject Type
	//

	typedef struct secsubj {
		string_t			name;
		uuid_t			uuid;
	} secsubj_t;

	//
	// Principal Type
	//

	typedef struct secprin {
		Principal		principal;
	} secprin_t;

	//
	// Attribute Representation
	//

	typedef any			attribute_t;

	//
	// Event Identifier
	//

	typedef struct eventid_s_t {
		event_type_t		type;
		uuid_t			id;
	} eventid_t;

	//
	// Network Name Types
	//

	typedef enum nameservice_e_t {
		ns_other,
		ns_dns,
		ns_dce,
		ns_x500,
		ns_nis,
		ns_sna
	} nameservice_t;

	typedef struct netaddr_s_t {
		sequence<octet>	name;
	} netaddr_t;

	typedef struct netname_s_t {
		nameservice_t		service;
		netaddr_t		netaddr;
	} netname_t;

	//
	// Consumer Type
	//

	enum ConsumerType {
		PULLCONSUMER,
		PUSHCONSUMER
	} ;

	typedef union EventConsumer switch(ConsumerType) {
		case PULLCONSUMER:
			CosEventComm::PullConsumer pullc;
		case PUSHCONSUMER:
			CosEventComm::PushConsumer pushc;
	} consumer_t;

	typedef struct consumer_list_s_t {
		sequence<consumer_t> consumer;
	} consumer_list_t;

	//
	// Supplier Type
	//

	enum SupplierType {
		PULLSUPPLIER,
		PUSHSUPPLIER
	} ;

	typedef union EventSupplier switch(SupplierType) {
		case PULLSUPPLIER:
			CosEventComm::PullSupplier pulls;
		case PUSHSUPPLIER:
			CosEventComm::PushSupplier pushs;
	} supplier_t;

	typedef struct supplier_list_s_t {
		sequence<supplier_t> supplier;
	} supplier_list_t;

	//
	// Event Origin Type
	//

	typedef struct ems_origin_s_t {
		supplier_t		supplier;
		string_t			descname;
						// SysAdminLifeCycle::Location id;
		ems_ulong_int		pid;        // supplementary field
		ems_ulong_int		uid;        // supplementary field
		ems_ulong_int		gid;        // supplementary field
	} origin_t;

	//
	// Event Severity Type
	//

	typedef enum severity_e_t {
		sev_info,
		sev_fatal,
		sev_error,
		sev_warning,
		sev_notice,
		sev_notice_verbose,
		sev_debug
	} severity_t;

	//
	// Event Priority Type
	//

	typedef ems_ulong_int	priority_t;

	//
	// Event Header
	//

	typedef struct hdr_s_t {
		eventid_t		eventid;
		origin_t			origin;
		severity_t		severity;
		utc_t			received;
		utc_t			delivered;
		priority_t		priority;
	} hdr_t;

	//
	// Event Type
	//

	typedef struct event_s_t {
		hdr_t			header;
		sequence<attribute_t> item;
	} event_t;

	typedef struct event_list_s_t {
		sequence<event_t>	event;
	} event_list_t;

	//
	// Event Schema
	//

	typedef struct event_schema_s_t {
		event_type_t		type;
		string_t			name;
		sequence<attribute_t> attr;
	} event_schema_t;

	//
	// Event Type List
	//

	typedef struct event_type_list_s_t {
		sequence<event_schema_t> schema;
	} event_type_list_t;

	//
	// Attribute Operators
	//

	typedef enum attr_op_e_t {
		c_attr_op_eq,
		c_attr_op_gt,
		c_attr_op_lt,
		c_attr_op_ge,
		c_attr_op_le,
		c_attr_op_ne,
		c_attr_op_bitand,
		c_attr_op_substr
	} attr_op_t;

	typedef struct attrlist_s_t {
		sequence<attribute_t> attr;
	} attrlist_t;

	//
	// Event Filter Grammar
	//

	typedef enum filter_grammar_e_t {
		c_fg_default,
		c_fg_OQL,
		c_fg_other
	} filter_grammar_t;

	//
	// Default Event Filter Grammar
	//

	typedef struct default_fg_s_t {
		string_t			attr_name;
		attr_op_t		attr_operator;
		attribute_t		attr_value;
	} default_fg_t;

	//
	// Event Filter Expression
	//

	typedef struct filter_exp_s_t {
		union tagged switch(filter_grammar_t) {
			case c_fg_default:
				default_fg_t def_filter;
			case c_fg_OQL:
				string_t	oql_filter;
			case c_fg_other:
				string_t	other;
		} filter;
	} filter_exp_t;

	//
	// Event Filter Expression List
	//

	typedef struct filter_exp_list_s_t {
		sequence<filter_exp_t> filter_exp;
	} filter_exp_list_t;

	//
	// Event Filter Type
	//

	typedef struct filter_s_t {
		string_t			filter_name;
		event_type_t		type;
		filter_exp_list_t	filter_exp_list;
	} filter_t;

	typedef struct filter_list_s_t {
		sequence<filter_t>	filter;
	} filter_list_t;

	typedef struct filtername_list_s_t {
		sequence<string_t>	filter_names;
	} filtername_list_t;

	//
	// Exceptions
	//

	exception ExAlreadyRegistered {};
	exception ExConsumerAlreadyStarted {};
	exception ExConsumerNotStarted {};
	exception ExEmptyFilterDB {};
	exception ExEventTypeExists {};
	exception ExEventTypeNotFound {};
	exception ExFilterExists {};
	exception ExFilterInUse {};
	exception ExFilterNotFound {};
	exception ExForwardingEventServiceNotThere {};
	exception ExForwardingEventLoop {};
	exception ExInsufficientPermission {};
	exception ExInvalidEventType {};
	exception ExInvalidFilter {};
	exception ExInvalidHandle {};
	exception ExInvalidName {};
	exception ExNoConsumers {};
	exception ExNoEvent {};
	exception ExNoEvents {};
	exception ExNoMemory {};
	exception ExNoSuppliers {};
	exception ExNoTypeList {};
	exception ExUnknownConsumer {};
	exception ExUnsupportedNameService {};
	exception ExNotRegistered {};
	exception ExNoFilters {};

	//
	// Registration Interface
	//
	// Note: This interface is not required. The stubs have a bind
	//	method used for connecting to a specific host. In addition,
	//	each bind is interface specific.
	//

	//
	// Event Type Interface
	//
	//

	interface EventType {
		void Add(in event_schema_t schema)
			raises(ExEventTypeExists, ExInsufficientPermission);

		void Delete(in string_t type_name,
				    in event_type_t type)
			raises(ExEventTypeNotFound, ExInvalidName,
				   ExInsufficientPermission);

		void Get(in string_t type_name,
				 in event_type_t type,
				 out event_schema_t schema)
			raises(ExEventTypeNotFound, ExInvalidName,
				   ExInsufficientPermission);

		void GetList(out event_type_list_t type_list)
			raises(ExNoTypeList, ExInsufficientPermission);

	} ;

	//
	// Event Filter Interface
	//

	interface EventFilter {
		void Add(in string_t filter_name,
				 in event_type_t type,
				 in filter_exp_list_t exp_list)
			raises(ExInsufficientPermission, ExFilterExists,
				   ExInvalidFilter, ExEventTypeNotFound, ExInvalidName);

		void Append(in string_t filter_name,
					in filter_exp_list_t exp_list)
			raises(ExInsufficientPermission, ExInvalidFilter, ExFilterNotFound, 
				ExInvalidName);

		void Get(in string_t filter_name,
				 in event_type_t type,
				 out filter_exp_list_t filter_exprs)
			raises(ExInsufficientPermission, ExFilterNotFound, ExInvalidName);

		void Delete(in string_t filter_name)
			raises(ExInsufficientPermission, ExFilterNotFound, ExFilterInUse, 
				ExInvalidName);

		void GetNameList(out filtername_list_t name_list)
			raises(ExInsufficientPermission, ExEmptyFilterDB);

		void GetList(out filter_list_t filter_list)
			raises(ExInsufficientPermission, ExEmptyFilterDB);

	} ;

	//
	// Consumer Interface
	//

	interface Consumer {
		void PushConsumerRegister(in CosEventComm::PushConsumer consumer,
					in filtername_list_t filter_group)
			raises(ExAlreadyRegistered, ExFilterNotFound,
			       ExInsufficientPermissions, ExNoMemory);

		void PullConsumerRegister(in CosEventComm::PullConsumer consumer,
					in filtername_list_t filter_group)
			raises(ExAlreadyRegistered, ExFilterNotFound,
			       ExInsufficientPermissions, ExNoMemory);

		void Unregister(in consumer_t consumer)
			raises(ExNotRegistered);

		void AddFilterToGroup(in consumer_t consumer,
					in filtername_list_t event_filters)
			raises(ExInsufficientPermission, ExNotRegistered, ExFilterNotFound);

		void DeleteFilterFromGroup(in consumer_t consumer,
					in filtername_list_t filter_name)
			raises(ExInsufficientPermission, ExNotRegistered, ExFilterNotFound);

		void GetFilterGroup(in consumer_t consumer,
					out filtername_list_t filter_group)
			raises(ExNotRegistered, ExNoFilters);

		void GetRegistration(out consumer_list_t push_consumers,
					out consumer_list_t pull_consumers)
			raises(ExNoConsumers);

		void Receive(inout event_t event)
			raises(ExNotRegistered);

	} ;

    interface ConsumerAdmin: Consumer {
		void ListConsumers(out consumer_list_t consumers)
			raises(ExNoConsumers);

		void DeleteConsumer(in string_t consumer,
					in uuid_t uuid)
			raises(ExInvalidName, ExInsufficientPermission);

		void AdminDeleteFilterFromGroup(in string_t consumer,
					in uuid_t uuid,
					in filtername_list_t filter_name)
			raises(ExInvalidName, ExInvalidFilter, ExInsufficientPermission);

		void AdminAddFilterToGroup(in string_t consumer,
					in uuid_t uuid,
					in filtername_list_t filter_name)
			raises(ExInvalidName, ExInvalidFilter, ExInsufficientPermission);

		void AdminGetFilterGroup(in string_t consumer,
					in uuid_t uuid,
					out filtername_list_t filter_name)
			raises(ExInvalidName, ExInsufficientPermission, ExNoFilters);

	} ;

	//
	// Supplier Interface
	//

	interface Supplier {
		void PushSupplierRegister(in CosEventComm::PushSupplier supplier)
			raises(ExAlreadyRegistered, ExInsufficientPermission);

		void PullSupplierRegister(in CosEventComm::PullSupplier supplier)
			raises(ExAlreadyRegistered, ExInsufficientPermission);

		void UnRegister(in supplier_t supplier)
			raises(ExNotRegistered, ExInsufficientPermission);

		void Send(in event_t event)
			raises(ExNotRegistered, ExInsufficientPermission);

		void GetRegistration(out supplier_list_t push_suppliers,
					out supplier_list_t pull_supplier)
			raises(ExNoSuppliers);

	} ;

    interface SupplierAdmin: Supplier {
		void ListSuppliers(out supplier_list_t suppliers)
			raises(ExInsufficientPermission, ExNoSuppliers);

		void DeleteSupplier(in string_t supplier,
					in uuid_t uuid)
			raises(ExInvalidName, ExInsufficientPermission);

	} ;

	//
	// Event Iterator Interface
	//

	interface EventIterator {
		ems_boolean NextOne(out event_t event);

		ems_boolean NextN(in ems_ulong_int how_many,
					out event_list_t events);

		void Destroy();

	} ;

	//
	// Registry Interface
	//

    interface Registry {
		Supplier ForSupplier();

		Consumer ForConsumer();

	} ;

	interface RegistryAdmin: Registry {
		void ListAttributes(out attrlist_t attributes);

		void GetUndeliveredEvents(in string filter_name,
					in unsigned long how_many,
					out event_list_t events,
					out EventIterator ei)
			raises(ExNoEvents, ExFilterNotFound, ExInsufficientPermission);

		void DeleteUndeliveredEventsByFilter(in string filter_name)
			raises(ExNoEvent, ExFilterNotFound, ExInsufficientPermission);

		void DeleteUndeliveredEvent(in eventid_t event)
			raises(ExNoEvent, ExInsufficientPermission);

		void Forward(in filtername_list_t filter_group,
					 in string_t host,
					 out string_t name,
					 out uuid_t uuid)
			raises(ExForwardingEventServiceNotThere, ExForwardingEventLoop, 
				ExInsufficientPermission);

	} ;

	//
	// Security Interface
	//

	interface Security {
		void Edit(in secobj_t secobj,
				  	in secsubj_t subject,
				 	in secperm_t newperm,
				  	out secperm_t oldperm)
			raises(ExInvalidName, ExInsufficientPermission);

		void Read(in secobj_t secobj,
				  	in secsubj_t subject,
				  	out secperm_t oldperm)
			raises(ExInvalidName, ExInsufficientPermission);

		void SubjAdd(in secsubj_t subject,
					in secprin_t principal)
			raises(ExInvalidName, ExInsufficientPermission);

		void SubjDelete(in secsubj_t subject)
			raises(ExInvalidName, ExInsufficientPermission);

		void SubjGet(in secprin_t principal,
					 out secsubj_t subject)
			raises(ExInvalidName, ExInsufficientPermission);

	} ;

	//
	// Administration Interface
	//

	interface Management;

	typedef sequence<Management> EventManagementSystems;

	interface Management {
		readonly attribute EventManagementSystems Systems;

		Registry ObtainRegistry()
			raises(ExInsufficientPermission);

		Security ObtainSecurityManagement()
			raises(ExInsufficientPermission);

		EventType ObtainTypeRepository()
			raises(ExInsufficientPermission);

		EventFilter ObtainFilterRepository()
			raises(ExInsufficientPermission);

	} ;
} ;


Footnotes

1.
The MAScOTTE project (see Glossary entry for SNMP Event Objects ) has proposed that this should be the definition for CORBA Universal Time. This definition is found in #include <CosTime.idl>.

2.
The MAScoTTE project (see Glossary entry for SNMP Event Objects ) has proposed that the process identifier, the user identifier and the group identifier should be replaced by the SysAdminLifeCycle::Location for the CORBA location description, as defined in the referenced XCMF-V1 specification. This would provide a fixed origin format, enabling interoperability.


Why not acquire a nicely bound hard copy?
Click here to return to the publication details or order a copy of this publication.

Contents Next section Index