Warning: This HTML rendition of the RFC is experimental. It is programmatically generated, and small parts may be missing, damaged, or badly formatted. However, it is much more convenient to read via web browsers, however. Refer to the PostScript or text renditions for the ultimate authority.

Open Software Foundation R. Cohen (IBM)
Request For Comments: 67.0 G. Wilson (IBM)
January 1996

DCE EVENT MANAGEMENT SERVICE

INTRODUCTION

In both traditional (SNMP and CMIP) and object system management architectures, communications between the managing and managed systems is bidirectional. One or more managing systems can send requests to query and control various aspects of resources being managed. In addition, the managed resource must be capable of sending asynchronous notifications or events to the managing systems. An event marks a change in state of the managed resource that causes a notification to be sent to interested parties. The routing of these events is usually done via an agent on the managed system.

In order to support remote management of DCE resources, enhancements must be made to DCE to support asynchronous event management for use by system management applications. This document describes the DCE Event Management Service (EMS) which provides asynchronous event support for DCE based applications.

EMS uses the concepts of event suppliers and event consumers, and sets up an event channel between them to support asynchronous communication. In the context of DCE, event suppliers are any DCE core service or DCE-based application (client or server), and event consumers can be any application with an interest in receiving asynchronous events from one or more DCE processes. The transmission of events between suppliers and consumers is uncoupled by routing events via EMS which is the implementation of an event channel. EMS also provides a filtering mechanism to allow administrators and consumers control over which events EMS will send.

The initial release of EMS provides integration for DCE clients and servers using the DCE Serviceability (SVC) or Audit interfaces. DCE applications can use the APIs offered in SVC and Audit to become event suppliers. Future releases of EMS will provide full support for application-defined event types.

TARGET

The DCE EMS is targeted for use by system administration applications that enable local or remote monitoring of asynchronous events generated by DCE core and application services. In the initial release, EMS will communicate server events via the SVC or Audit layer to the DCE SNMP subagents.

GOALS

The goals of the DCE EMS are as follows:

The effort involved in writing a DCE event consumer application should be minimized.
The EMS service should have good performance, and should minimize network and system load.
EMS should be designed to be a centralized service, even though the first release will not be centralized.
Event consumer applications should be able to locate and register with one or more EMSs on multiple DCE hosts.
Events should be sent by DCE applications once and only once, via the SVC or Audit Interface, to EMS.
Event consumer applications should be able to control both which DCE host is sending events as well as which event types are sent.
EMS can transmit events from multiple DCE event supplier applications to one or more DCE event consumer applications based on a defined set of event filters within a DCE cell in a secure way.
DCE event supplier applications should not be aware of what DCE consumer applications have registered to receive events.
EMS should provide a remote management API.
EMS should provide reliable delivery of events to consumers and be tolerant of network and machine failures.
EMS should provide the ability to define and extend events and event contents.
The EMS architecture should be based on the OMG Event Service Specification as documented in the Joint Object Services Submission as defined in COSS (see [OMG]).
The first release of EMS should support SVC and Audit events.

Non-Goals

EMS should not be used for monitoring DCE core services start-up failures. EMS uses CDS and Security, and requires them to be running in the cell to start up.
The first release of EMS will not support general message passing, only SVC and Audit events.

TERMINOLOGY

attribute name
A string uniquely identifying an attribute of a given event type.
attribute operator
The operator in a filter expression used in the comparison between the named attribute in the event and the attribute value.
attribute type
The data type of an event attribute. This defines the format of the data in this attribute.
attribute value
The value in a filter expression which is compared, using the attribute operator, against the event value for the specified attribute name.
event
The data to be transmitted between an event supplier and EMS, and EMS and one or more event consumers. An event consists of an event header, and a list of event attributes which contain the event type specific data.
event channel
A service that decouples the communications between event suppliers and event consumers. An event channel is both a supplier and consumer of events.
event consumer
A DCE server application which registers for, defines filters for, receives, and processes event data.
event filter
A collection of one or more filter expressions which are logically ANDed together. An event filter has an event filter name.
event filter expression.
A 3-tuple consisting of an attribute name, attribute operator, and an attribute value, which defines a compare operation.
event filter group
A collection of one or more event filters which are logically ORed together. As many event filter names as desired can be added to a consumer's event filter group to control what events EMS will send to that consumer. Event filter groups can contain event filters which specify heterogeneous event types.
An event must pass one set of the event filters in the event filter group before it will be forwarded to an event consumer.
event log
A collection of events to be sent to consumers. The event log stores events in case EMS cannot forward events to all appropriate event consumers. An event is deleted from the event log after that event is forwarded to all consumers.
event supplier
A DCE based application (including DCE core servers) which emits event data. In the first release, a supplier can be any DCE application that uses SVC or Audit.
event type
A class of events that have the same event format. An event type format is described via an event type schema. An event type is defined by a unique uuid.
event type schema
A description of an event type. It consists of a list of attribute name/type pairs which specify the data format of an event. The event type schema can be used by consumers or EMS administrators to construct event filters and event content.

REQUIREMENTS

EMS should not be required for use of SVC or Audit.
The DCE application developer should be able to send events using the SVC or Audit subsystem without instrumenting directly to EMS.
EMS should be capable of event persistence and event retransmission to the appropriate DCE event consumers in the case of network or system failure.
The initial version of EMS should support a minimally acceptable subset of the total function to assure its timely availability as part of the DCE core product.
All DCE coding requirements should be followed. All code should be internationalized, and should be portable across all DCE platforms.

FUNCTIONAL DEFINITION

The DCE EMS manages event services in a DCE cell. EMS consists of two parts: the emsd server, and the API to access event services.

emsd is a DCE server which, in the first release, will be decentralized, i.e., will reside on every DCE host in the cell from which consumers will request events (future EMS releases will be centralized). Three interfaces are exported by emsd, to support EMS suppliers, consumers, and event services administration. The EMS API provides an interface to the same three interfaces for use by EMS clients.

The following sections describe how EMS works, along with a description of how to define event types, the event flow through EMS, how event filters work, how events get logged, and the security model used to protect both event data, and event filter definitions.

Event Flow Description

EMS sets up an event channel to decouple the communications between the supplier and consumer (see Figure).

+--------------------------------------------------------+
| FIGURE NOT AVAILABLE IN ASCII VERSION OF THIS DOCUMENT |
+--------------------------------------------------------+

line from 2.300,9.637 to 2.300,9.700 to 3.300,9.700 to 3.300,9.325 to 3.237,9.325 line from 2.362,9.700 to 2.362,9.762 to 3.362,9.762 to 3.362,9.387 to 3.300,9.387 "\s10\fRAudit Trail\fP" at 2.737,9.415 box with .sw at (6.74,9.26) width 1.00 height 0.38 line from 6.800,9.637 to 6.800,9.700 to 7.800,9.700 to 7.800,9.325 to 7.737,9.325 line from 6.862,9.700 to 6.862,9.762 to 7.862,9.762 to 7.862,9.387 to 7.800,9.387 "\s10\fRSVC Log File\fP" at 7.237,9.415 box with .sw at (5.36,9.26) width 1.00 height 0.38 "\s10\fRConsole\fP" at 5.862,9.415 box with .sw at (6.42,6.76) width 1.00 height 0.38 "\s10\fREvent Log File\fP" at 6.925,6.915 "\s10\fRSystem\fP" at 2.050,8.353 ljust "\s10\fRBoundary\fP" at 2.050,8.190 ljust box with .sw at (4.49,3.83) width 1.00 height 0.44 "\s10\fREvent Consumer\fP" at 4.987,4.103 "\s10\fR(local process)\fP" at 4.987,3.940 "\s10\fRDCE\fP" at 3.925,9.140 "\s10\fRAudit\fP" at 3.925,8.978 "\s10\fRDCE\fP" at 4.612,9.140 "\s10\fRSVC\fP" at 4.612,8.978 circle at 4.987,6.263 rad 0.750 ellipse at 6.925,5.862 wid 0.875 ht 0.175 ellipse at 6.925,5.362 wid 0.875 ht 0.175 ellipse at 3.050,7.175 wid 0.875 ht 0.200 ellipse at 3.050,6.675 wid 0.875 ht 0.200 ellipse at 3.050,5.862 wid 0.875 ht 0.200 ellipse at 3.050,5.362 wid 0.875 ht 0.200 line from 4.300,9.262 to 4.300,9.262 line -> from 3.612,9.075 to 2.737,9.075 to 2.737,9.262 line -> from 4.987,9.075 to 5.862,9.075 to 5.862,9.262 line -> from 5.862,9.075 to 7.237,9.075 to 7.237,9.262 line -> from 4.300,8.637 to 4.987,7.013 box with .sw at (2.24,5.01) width 5.50 height 2.50 line from 4.300,6.575 to 5.675,6.575 line from 4.300,5.950 to 5.675,5.950 line <-> from 3.487,6.950 to 4.300,6.575 line <-> from 3.487,5.638 to 4.300,5.950 line <-> from 5.675,6.575 to 6.425,6.950 line <-> from 5.675,5.950 to 6.487,5.638 line -> from 4.987,5.513 to 4.987,4.263 line -> from 4.987,4.513 to 6.925,4.513 to 6.925,3.325 box with .sw at (6.42,2.89) width 1.00 height 0.44 line -> from 6.612,3.325 to 6.612,5.013 box with .sw at (2.24,9.26) width 1.00 height 0.38 box with .sw at (2.24,2.89) width 1.00 height 0.44 "\s10\fREvent Management System (EMS)\fP" at 6.425,7.603 line -> from 2.737,3.325 to 2.737,5.013 dashwid = 0.050i box dashed with .sw at (1.99,3.58) width 6.00 height 6.44 line from 5.487,4.013 to 6.612,4.013 line from 2.612,7.200 to 2.612,6.700 line from 2.612,5.888 to 2.612,5.388 box with .sw at (3.61,8.64) width 1.38 height 1.00 line from 3.612,9.262 to 4.987,9.262 line from 3.612,8.887 to 4.987,8.887 line from 4.300,9.262 to 4.300,8.887 line from 3.675,9.637 to 3.675,9.700 to 5.050,9.700 to 5.050,8.700 to 4.987,8.700 line from 3.737,9.700 to 3.737,9.762 to 5.112,9.762 to 5.112,8.762 to 5.050,8.762 dashwid = 0.037i line dotted from 4.737,8.887 to 5.362,8.387 line dotted from 4.112,5.200 to 4.987,5.513 line from 7.362,5.888 to 7.362,5.388 line from 6.487,5.888 to 6.487,5.388 line from 3.487,5.888 to 3.487,5.388 line from 3.487,7.200 to 3.487,6.700 "\s10\fR\&\fP" at 1.488,9.790 "\s10\fRDCE Event Supplier\fP" at 4.300,9.415 "\s10\fREMS API Layer\fP" at 4.300,8.728 "\s10\fRFirst Stage Filtering\fP" at 5.612,8.290 "\s10\fREvents\fP" at 4.362,7.915 "\s10\fRConsumer\fP" at 3.050,6.978 "\s10\fRDatabase\fP" at 3.050,6.815 "\s10\fRDatabase\fP" at 3.050,5.503 "\s10\fRDatabase\fP" at 6.925,5.503 "\s10\fREvent Type\fP" at 3.050,5.665 "\s10\fREvent Filter\fP" at 6.925,5.665 "\s10\fREvent Consumer\fP" at 4.987,6.728 "\s10\fREvent Supplier\fP" at 4.987,5.790 "\s10\fREvent Channel\fP" at 4.987,6.228 "\s10\fRSecond Stage Filtering\fP" at 3.987,5.103 "\s10\fREvent Consumer\fP" at 6.925,3.165 "\s10\fR(remote process)\fP" at 6.925,3.003 "\s10\fREvents\fP" at 4.737,4.728 "\s10\fR(RPC)\fP" at 7.112,4.353 "\s10\fREMS System\fP" at 2.737,3.165 "\s10\fRAdministration\fP" at 2.737,3.003 "\s10\fR(RPC)\fP" at 5.175,5.290 "\s10\fR(RPC)\fP" at 4.612,8.415 "\s10\fRManagement API\fP" at 2.487,4.790 "\s10\fRConsumer API\fP" at 6.487,4.790 "\s10\fR(RPC)\fP" at 6.425,4.103

In order to start receiving events, an event consumer must first register with EMS, then set up an event filter group to tell EMS which events to forward to that consumer. Before a supplier can send an event to EMS, the event must pass through the first stage event filter.

In the first release of EMS, first stage filtering is achieved at the supplier level by using SVC and Audit facilities. See Section 6.3, Event Filters for more details.

Once the event passes through the first stage filter, it is sent to EMS. EMS writes the event to the EMS event log in order to save the event in case the event cannot be immediately delivered.

Once the event reaches EMS, then it must pass through the second stage filter before being forwarded to interested consumers. EMS goes through the list of registered consumers and uses the event type schema from the event type Database and the consumer's event filter group from the consumer Database, and the event filters from the Event Filter Database to determine if this event passes through to be forwarded on for each event consumer. After all appropriate consumers receive the event, then the event is removed from the event log.

Event Type Definition

The format of EMS event types are defined by event type schemas, and are kept in the EMS event Type Database. The event type schemas consist of a list of attribute names along with the attribute type which specifies the data format of the data associated with that attribute. Events consist of a fixed header part, and a variable length data part. The variable length data part consists of N self-defining data items which consist of an attribute type, then the data itself. See Section 7.1.3, Event Attribute. The data elements in the variable length part correspond in order, one for one with the list of attribute name/type pairs defined in the event type schema. The variable length part can have additional unnamed data items at the end of the named data items (i.e., the data items that have attribute names).

The event type schemas are used in several different ways.

A consumer can request a list of supported event types, and pick which events types it wants to receive by using the event type schemas to construct event filters, and to map event data according to attribute names (e.g., an event consumer can reconstruct an SVC message for example by using the attribute names to find the correct data items).

Suppliers use event type schemas to define new event types that they intend to produce.

EMS uses the event type schemas to apply event filters to events.

Generic event types

EMS supports events with type Generic. Such generic events do not have an event type schema. The only way to define filters for generic events is to use filter expressions with event header attributes (See Table 5, Event Header Attributes).

Default event types

Following are the definitions of the SVC and Audit event attribute lists which are contained in their event type schemas. See Section 7.3.1, Event Type Schema, for a definition of the event type schema data structure:

#define CNT_SVC_ATTRS (sizeof(svc)/sizeof(ems_attribute_t))

static ems_attribute_t svc[] = {
    {(unsigned char *)"version",
        {ems_c_attr_ulong_int,0}},
    {(unsigned char *)"t",
        {ems_c_attr_utc,0}},
    {(unsigned char *)"argtypes",
        {ems_c_attr_char_string,0}},
    {(unsigned char *)"table_index",
        {ems_c_attr_ulong_int,0}},
    {(unsigned char *)"attributes",
        {ems_c_attr_ulong_int,0}},
    {(unsigned char *)"message_index",
        {ems_c_attr_ulong_int,0}},
    {(unsigned char *)"format",
        {ems_c_attr_char_string,0}},
    {(unsigned char *)"file",
        {ems_c_attr_char_string,0}},
    {(unsigned char *)"progname",
        {ems_c_attr_char_string,0}},
    {(unsigned char *)"line",
        {ems_c_attr_ulong_int,0}},
    {(unsigned char *)"threadid",
        {ems_c_attr_ulong_int,0}},
    {(unsigned char *)"component_name",
        {ems_c_attr_char_string,0}},
    {(unsigned char *)"sc_name",
        {ems_c_attr_char_string,0}},
    {(unsigned char *)"attribute.debug",
        {ems_c_attr_ushort_int,0}},
    {(unsigned char *)"attribute.severity",
        {ems_c_attr_ushort_int,0}},
    {(unsigned char *)"attribute.actroute",
        {ems_c_attr_ulong_int,0}}
};

#define CNT_AUDIT_ATTRS (sizeof(audit)/sizeof(ems_attribute_t))

ems_attribute_t audit[] = {
    {(unsigned char*)"format",
        {ems_c_attr_ushort_int,0}},
    {(unsigned char*)"server",
        {ems_c_attr_uuid,0}},
    {(unsigned char*)"event",
        {ems_c_attr_ulong_int,0}},
    {(unsigned char*)"outcome",
        {ems_c_attr_ushort_int,0}},
    {(unsigned char*)"authz_st",
        {ems_c_attr_ushort_int,0}},
    {(unsigned char*)"time",
        {ems_c_attr_utc,0}},
    {(unsigned char*)"addr",
        {ems_c_attr_char_string,0} }
};

Several constants have also been defined to use to match against the attribute.severity attribute. They are:

SVC_C_SEV_FATAL
SVC_C_SEV_ERROR
SVC_C_SEV_WARNING
SVC_C_SEV_NOTICE
SVC_C_SEV_NOTICE_VERBOSE

Event Filters

EMS supports the concept of two stage filtering. First stage filtering is applied on the machine that the supplier is running on, to filter out events before they are even sent to EMS; this can also be called supplier-side filtering. Second stage filtering is applied by EMS to events received from suppliers. This stage controls which events get forwarded on to consumers.

The following sections describe the two stages of filtering EMS supports, as well as how to define and organize the event filters.

First and second stage filtering

EMS supports two levels of filtering. The first stage filter is applied at the event supplier, and only events that pass this filter get transmitted to EMS. First stage filtering is also referred to as supplier side filtering.

In the first release of EMS, only SVC and Audit event types are supported. The first stage filter for SVC events will be the SVC routing destination See Section 13.0, Seamless Integration With Audit and SVC for more details on how to route SVC messages to EMS. Only SVC messages that are routed to EMS will be sent through the EMS event channel. For Audit, only audit records that pass through the audit filter mechanism will be sent through the EMS event channel, See the OSF DCE Administration Guide -- Core Components, DCE Audit Service, for more information on how to use Audit filters.

The second stage filter is defined per EMS consumer. This stage associates an event filter group with each event consumer, and that consumer will only receive events that pass through one of the entries in the consumer's event filter group.

Defining event filters

A typical scenario of how an event consumer would start interfacing with EMS would be for the consumer to first query EMS about what event types are supported. From that list of event types, the consumer could then query the event type schema, to construct any event filters for that event type. The event type schemas contain the list of attribute names and attribute types which the consumer would use to construct an event filter. The consumer would then tell EMS to apply the constructed event filter to incoming events by adding it to the consumers event filter group.

EMS filters are constructed at several different levels. The lowest level is the filter expression, which is a 3-tuple consisting of an attribute name, attribute operator, and an attribute value which defines a compare operation. All compare operations evaluate to a boolean value. Only certain attribute operators are allowed on certain attribute types. See Table 8 Filter Expression Operator Table, in Appendix B Valid Filter Expressions.

Following are some examples of a filter expression:

ems_filter_exp_t xmp_SVC, xmp_Audit;

xmp_SVC.attr_name
    = "file";
xmp_SVC.attr_operator
    = ems_c_attr_op_eq;
xmp_SVC.attr_comp_value.type
    = ems_c_attr_char_string;
xmp_SVC.attr_comp_value.tagged_union.char_string
    = "file.c";

xmp_Audit.attr_name
    = "outcome";
xmp_Audit.attr_operator
    = ems_c_attr_op_eq;
xmp_Audit.attr_comp_value.type
    = ems_c_attr_ushort_int;
xmp_Audit.attr_comp_value.tagged_union.ushort_int
    = aud_c_esl_cond_denial;

The first example will evaluate to TRUE if the attribute name "file" of an SVC event type is equal to the string "file.c". In the second example, the filter expression xmp_Audit will evaluate to TRUE if the attribute name "outcome" of an Audit event type is equal to the attribute value aud_c_esl_cond_denial, which means that an Audit event is recording that access was denied for some action (See the OSF DCE Application Development Reference, DCE Security Service, for more info on the outcome attribute).

An event filter is made up of a list of filter expressions that are ANDed together. An event filter has both a name and an event type. The event filter name is used to refer to the event filter in event filter create, delete and update operations. The event filter name is also used by consumers and EMS administrators to add event filters to an event filter group.

A consumer's event filter group is a collection of one or more event filter names. For an event to pass through a consumer's filter group, the event filter associated with each event filter name specified in the event filter group is applied to the event. If all the event filter expressions in the named event filter evaluate to TRUE, then the event is forwarded by EMS to that consumer. If any of the event filter expressions evaluate to FALSE, then the event filter specified by the next event filter name in the event filter group is applied to the event. If none of the event filters in the event filter group evaluate to TRUE, then the event is not forwarded to that consumer.

Using the consumer API, a consumer can define a new event filter, and add it to an event filter group. A consumer can also get a list of existing event filter names, and add one of those event filter names to an event filter group. See Section 9.3, Event Filter Construction Interface for more information on the APIs to retrieve existing event FIlters as well as build new event filters.

Event filter names can be added or deleted from event filter groups by the consumer, as well as by the administrative interface.

Filtering on header information or event type

A predefined set of event header attribute name/type pairs have been defined to allow filtering on the information in the event header. See Table 5, Event Header Attributes, for more details. Filter expressions with event header attributes can be part of filters with event type specific header attributes. Filters with type Generic can only have filter expressions with header attributes.

EMS Event Log

The EMS event log is used to store events in case of EMS failures. EMS writes all events to the event log, and delete the event record once the event has been transmitted to all consumers that are supposed to get the event.

The event log is kept in a file on the machine where emsd is running. Events are stored in a directory specified by the environment variable EMS_EVENTLOG_DIR. See Section 11.6.1, EMS Environment Variables for more information.

An API is provided to examine local event logs. See Section 11.4, EMS Log Information Management Interface.

EMS Security Model

EMS provides for secure manipulation of data in the EMS databases. This includes the Event Filter database, the Event Type database, as well as the list of consumers in the Consumer database. EMS also provides for supplier and consumer authentication and authorization as well as secure transmission of event data.

All ACLs will be associated with names in the DCE namespace, and the emsd server will manage the namespace past the junction:

/.:/hosts/hostname/ems-server/

The ACL associated with this object will control access to the emsd server registered in this namespace. The permissions associated with ems-server are:

+----------+----------+--------------------------+
| Perm bit |   Name   |        Description       |
+==========+==========+==========================+
| `c'      | control  | Modify the ACLs on the   |
|          |          | server                   |
+----------+----------+--------------------------+
| `r'      | read     | Read the attributes for  |
|          |          | this server              |
+----------+----------+--------------------------+
| `s'      | stop     | Stop the EMS server      |
+----------+----------+--------------------------+
| `w'      | write    | Modify the attributes on |
|          |          | this server              |
+----------+----------+--------------------------+

      Table 1: emsd Server Permission Bits

tab(@) box center;

cw(1.0i) | cw(1.0i) | cw(2.5i)

l | l | l.

Perm bit@Name@Description

c@control@T{

Modify the ACLs on the server

r@read@T{

Read the attributes for this server

s@stop@T{

Stop the EMS server

w@write@T{

Modify the attributes on this server

Table 1: \*(lBemsd\*(lE Server Permission Bits\}

Three security objects will be maintained under the ems-server junction. The directories and the databases they represent are:

event-types -- Event type database.
filters -- Filter database.
consumers -- Consumer database.

Each of these databases will have an ACL associated with it, as discussed next.

Event type security management

The Event Type database will be represented by the following name in the DCE name space:

/.:/hosts/hostname/ems-server/event-types

The ACL associated with this object will control access to this database. The permissions associated with event-types are:

+----------+----------+--------------------------+
| Perm bit |   Name   |        Description       |
+==========+==========+==========================+
| `c'      | control  | Modify the ACLs on the   |
|          |          | event type               |
+----------+----------+--------------------------+
| `d'      | delete   | Delete an event type     |
|          |          | schema                   |
+----------+----------+--------------------------+
| `i'      | insert   | Add an event type schema |
+----------+----------+--------------------------+
| `r'      | read     | Read the contents of     |
|          |          | event type schemas       |
+----------+----------+--------------------------+

   Table 2: Event Type Database Permission Bits
      (Only `c', `r' supported in release 1.)

tab(@) box center;

cw(1.0i) | cw(1.0i) | cw(2.5i)

l | l | l.

Perm bit@Name@Description

c@control@T{

Modify the ACLs on the event type

d@delete@T{

Delete an event type schema

i@insert@T{

Add an event type schema

r@read@T{

Read the contents of event type schemas

Table 2: Event Type Database Permission Bits (Only c, r supported in release 1.)\}

EMS event data access can be granted per event type. Authority on event data of a given event type can be granted by modifying the ACL on:

/.:/hosts/hostname/ems-server/event-types/event_type_name

where event_type_name is the event type name which appears in the event type schema (see data structures section which describes the event type schema). The names will be recognized for SVC and Audit events are:

/.:/hosts/hostname/ems-server/events/SVC
/.:/hosts/hostname/ems-server/events/Audit

The permissions associated with event_type_name are:

+----------+----------+--------------------------+
| Perm bit |   Name   |        Description       |
+==========+==========+==========================+
| `c'      | control  | Modify the ACLs on the   |
|          |          | event type               |
+----------+----------+--------------------------+
| `d'      | delete   | Delete this event type   |
+----------+----------+--------------------------+
| `r'      | read     | Read (consume) an event  |
|          |          | of this type             |
+----------+----------+--------------------------+
| `w'      | write    | Write (supply) an event  |
|          |          | of this type             |
+----------+----------+--------------------------+

       Table 3: Event Type Permission Bits
   (Only `c', `r', `w' supported in release 1.)

tab(@) box center;

cw(1.0i) | cw(1.0i) | cw(2.5i)

l | l | l.

Perm bit@Name@Description

c@control@T{

Modify the ACLs on the event type

d@delete@T{

Delete this event type

r@read@T{

Read (consume) an event of this type

w@write@T{

Write (supply) an event of this type

Table 3: Event Type Permission Bits (Only c, r, w supported in release 1.)\}

A supplier's rights will be verified on the first event send to EMS, and the consumer's rights will be verified before forwarding events to that consumer. Authenticated RPC will be used to access the EMS supplier and consumer Remote API.

Event Filter Security Management

The Filter database will be represented by the following name in the DCE name space:

/.:/hosts/hostname/ems-server/filters

The ACL associated with this object will control access to this database. The permissions associated with filters are:

+----------+----------+--------------------------+
| Perm bit |   Name   |        Description       |
+==========+==========+==========================+
| `c'      | control  | Modify the ACLs on       |
|          |          | filters                  |
+----------+----------+--------------------------+
| `d'      | delete   | Delete an event filter   |
+----------+----------+--------------------------+
| `i'      | insert   | Add an event filter      |
+----------+----------+--------------------------+
| `r'      | read     | Get a list, or contents, |
|          |          | of event filters         |
+----------+----------+--------------------------+

     Table 4: Filter Database Permission Bits

tab(@) box center;

cw(1.0i) | cw(1.0i) | cw(2.5i)

l | l | l.

Perm bit@Name@Description

c@control@T{

Modify the ACLs on filters

d@delete@T{

Delete an event filter

i@insert@T{

Add an event filter

r@read@T{

Get list, or contents, of event filters

Table 4: Filter Database Permission Bits\}

Event filter access control can be granted per event filter. Authority on filter access for a given event filter can be granted by modifying the ACL on:

/.:/hosts/hostname/ems-server/filters/filter_name

where filter_name is the event filter name given the event filter on the call to ems_filter_add() (See Section 9.3.1, Add an Event Filter).

The permissions associated with event filters are:

+----------+----------+--------------------------+
| Perm bit |   Name   |        Description       |
+==========+==========+==========================+
| `c'      | control  | Modify the ACL on the    |
|          |          | event filter             |
+----------+----------+--------------------------+
| `d'      | delete   | Delete the event filter  |
+----------+----------+--------------------------+
| `w'      | write    | Modify the contents of   |
|          |          | an event filter          |
+----------+----------+--------------------------+

      Table 5: Event Filter Permission Bits

tab(@) box center;

cw(1.0i) | cw(1.0i) | cw(2.5i)

l | l | l.

Perm bit@Name@Description

c@control@T{

Modify the ACL on the event filter

d@delete@T{

Delete the event filter

w@write@T{

Modify the contents of an event filter

Table 5: Event Filter Permission Bits\}

When a consumer creates an event filter, that consumer principal automatically gets cdw permissions on the created event filter.

Consumer security management

The Consumer database will be represented by the following name in the DCE name space:

/.:/hosts/hostname/ems-server/consumers

The ACL associated with this object will control access to this database. The permissions associated with consumers are:

+----------+----------+--------------------------+
| Perm bit |   Name   |        Description       |
+==========+==========+==========================+
| `c'      | control  | Modify the ACLs on       |
|          |          | `consumers'              |
+----------+----------+--------------------------+
| `d'      | delete   | Delete a consumer        |
+----------+----------+--------------------------+
| `i'      | insert   | Add (register) a         |
|          |          | consumer                 |
+----------+----------+--------------------------+
| `r'      | read     | List consumer            |
|          |          | information              |
+----------+----------+--------------------------+
| `w'      | write    | Modify a consumer,       |
|          |          | including filter group   |
+----------+----------+--------------------------+

     Table 6: Consumer Database Permission Bits

tab(@) box center;

cw(1.0i) | cw(1.0i) | cw(2.5i)

l | l | l.

Perm bit@Name@Description

c@control@T{

Modify the ACLs on consumers

d@delete@T{

Delete a consumer

i@insert@T{

Add (register) a consumer

r@read@T{

List consumer information

w@write@T{

Modify a consumer, including filter group

Table 6: Consumer Database Permission Bits\}

EMS security initialization

When EMS is configured, several security groups will be created by default. The groups are ems-admin, ems-consumer, and ems-supplier. The default permissions will be:

/.:/hosts/hostname/ems-server

Object ACL:

ems-admin:crws
hosts/hostname/self:rws
any_other:r

/.:/hosts/hostname/ems-server/event-types
1. Object ACL:
```
ems-admin:cri
ems-consumer:r
ems-supplier:ri
any_other:r
```
2. Initial object ACL (/.:/hosts/hostname/ems-server/event-types/event_type_name):
```
ems-admin:cdw
ems-consumer:r
ems-supplier:w
```
/.:/hosts/hostname/ems-server/filters
1. Object ACL:
```
ems-admin:crdi
ems-consumer:ir
any_other:r
```
2. Initial object ACL (/.:/hosts/hostname/ems-server/filters/filter_name):
```
ems-admin:cw
```
/.:/hosts/hostname/ems-server/consumers
1. Object ACL:
```
ems-admin:cdrw
ems-consumer:irw
any_other:r
```

By setting these permissions for the ems_admin group, each new event filter and event type created will automatically inherit the same permissions.

Administrators can add principals to each of these groups to give them access to all emsd's running in a cell. If tighter security is desired, the group can be removed from the respective ACL, and principals can be added.

When transmitting events of type Audit, EMS will always use authenticated RPC set to DCE Security Protection Level strong integrity (rpc_c_protect_level_pkt_integrity).

Writing Consumers

Consumers are not simple clients. They have to be implemented as servers. This means that EMS consumers have certain requirements.

Consumers must:

Call consumer_start(). This creates the consumer UUID, and then registers the EMS Transmit to Consumer interface (See Section 10.4, EMS Transmit To Consumer Interface).
Call ems_consumer_handler_register(). This sets up an incoming consumer queue, and initializes the event handler function to call the handle function specified.
Register with the various emsd's that it wants to receive events from. One event consumer can register to receive events from multiple emsds on different hosts.
Set up event filters. Consumers must set up event filters before any events will be sent.
Call rpc_server_listen(). This sets the consumer up to wait for incoming events.

EMS Recovery After Restart

EMS stores all state data in the following repositories:

Consumer Database -- Contains list of all suppliers, and all consumers as well as the list of filters in the consumer filter group.
Event Type Database \(*(EM Contains the schemas for all the known event types.
Event Filter Database -- Contains all the current filter definitions.

When an emsd is restarted, the following steps are performed:

All databases get restored.
All consumers are told to reregister or reconnect.
The event queue is restored from the event log files.
Event transmission proceeds.

Cross-Cell Access

EMS provides full access across DCE cells for consumers only. If a consumer wishes to register with an EMS in another cell, a valid hostname (See Section 7.2.3, Network Name) must be passed to the ems_consumer_register() routine (See Section 9.4.4, Consumer Register).

Iternationalization Support in EMS

EMS supports byte data streams when passing data in an event as an event attribute. This allows I18N data to be passed from supplier to consumer. EMS restricts names to the Portable Character Set (PCS). This includes:

Consumer names.
Filter Names.
Event Type Names.
Event Attribute Names.

When a name that contains characters that are not in the PCS is passed into one of the EMS routines as an argument, that routine returns a status code of ems_s_invalid_name().

DATA STRUCTURES

EMS Event Attributes

Event attribute types

The event attribute type is used to specify the data type of an event attribute. The attribute type specifies what format the data is in the event attribute value union (ems_attr_value_t).

All event attribute types are defined as:

typedef unsigned16 ems_attr_type_t;

An event attribute type can be one of the following:

+--------------------------+-------------------+----------+
|      Attribute Type      |     Data Type     |   Size   |
+==========================+===================+==========+
| `ems_c_attr_small_int'   | `idl_small_int'   | 1 byte   |
+--------------------------+-------------------+----------+
| `ems_c_attr_short_int'   | `idl_short_int'   | 2 bytes  |
+--------------------------+-------------------+----------+
| `ems_c_attr_long_int'    | `idl_long_int'    | 4 bytes  |
+--------------------------+-------------------+----------+
| `ems_c_attr_hyper_int'   | `idl_hyper_int'   | 8 bytes  |
+--------------------------+-------------------+----------+
| `ems_c_attr_usmall_int'  | `idl_usmall_int'  | 1 bytes  |
+--------------------------+-------------------+----------+
| `ems_c_attr_ushort_int'  | `idl_ushort_int'  | 2 bytes  |
+--------------------------+-------------------+----------+
| `ems_c_attr_ulong_int'   | `idl_ulong_int'   | 4 bytes  |
+--------------------------+-------------------+----------+
| `ems_c_attr_uhyper_int'  | `idl_uhyper_int'  | 8 bytes  |
+--------------------------+-------------------+----------+
| `ems_c_attr_short_float' | `idl_short_float'  | 4 bytes |
+--------------------------+-------------------+----------+
| `ems_c_attr_long_float'  | `idl_long_float'  | 8 bytes  |
+--------------------------+-------------------+----------+
| `ems_c_attr_boolean'     | `idl_boolean'     | 1 byte   |
+--------------------------+-------------------+----------+
| `ems_c_attr_uuid'        | `uuid_t'          | 16 bytes |
+--------------------------+-------------------+----------+
| `ems_c_attr_utc'         | `utc_t'           | 16 bytes |
+--------------------------+-------------------+----------+
| `ems_c_attr_severity'    | `ems_severity_t'  | 2 bytes  |
+--------------------------+-------------------+----------+
| `ems_c_attr_acl'         | `sec_acl_t *'     | variable |
+--------------------------+-------------------+----------+
| `ems_c_attr_byte_string' | `idl_byte *'      | variable |
+--------------------------+-------------------+----------+
| `ems_c_attr_char_string' | `idl_char *'      | variable |
+--------------------------+-------------------+----------+
| `ems_c_attr_bytes'       | (see structure)   | variable |
+--------------------------+-------------------+----------+
| `ems_c_attr_octet_array' | `ems_netaddr_t *' | variable |
+--------------------------+-------------------+----------+

        Table 7: Event Attribute Type Specifiers

tab(@) box center;

cw(2.25i) | cw(1.75i) | cw(0.75i)

l | l | l.

Attribute Type@Data Type@Size

ems_c_attr_small_int@idl_small_int@1 byte

ems_c_attr_short_int@idl_short_int@2 bytes

ems_c_attr_long_int@idl_long_int@4 bytes

ems_c_attr_hyper_int@idl_hyper_int@8 bytes

ems_c_attr_usmall_int@idl_usmall_int@1 bytes

ems_c_attr_ushort_int@idl_ushort_int@2 bytes

ems_c_attr_ulong_int@idl_ulong_int@4 bytes

ems_c_attr_uhyper_int@idl_uhyper_int@8 bytes

ems_c_attr_short_float@idl_short_float@4 bytes

ems_c_attr_long_float@idl_long_float@8 bytes

ems_c_attr_boolean@idl_boolean@1 byte

ems_c_attr_uuid@uuid_t@16 bytes

ems_c_attr_utc@utc_t@16 bytes

ems_c_attr_severity@ems_severity_t@2 bytes

ems_c_attr_acl@sec_acl_t *@variable

ems_c_attr_byte_string@idl_byte *@variable

ems_c_attr_char_string@idl_char *@variable

ems_c_attr_bytes@(see structure)@variable

ems_c_attr_octet_array@ems_netaddr_t *@variable

Table 7: Event Attribute Type Specifiers\}

Byte strings and character strings are terminated with a 0 (zero) byte. The pickling service of the IDL compiler can be used to encode complex data types into byte strings that are to be included in an EMS event.

Event attribute values

The event attribute value union is a self-defining data structure which has an attribute type specifier (type) which tells what type of data is in the union, and then appropriate union members to hold the value of the data specified:

typedef struct ems_bytes_s_t {
    unsigned32          size;    /* size of byte data */
    [size_is(size)]
    byte *              data;    /* byte data */
} ems_bytes_t;

typedef union switch (ems_attr_type_t format) {
    case ems_c_attr_small_int:
        small int small_int;
    case ems_c_attr_short_int:
        short int short_int;
    case ems_c_attr_long_int:
        long int long_int;
    case ems_c_attr_hyper_int:
        hyper int hyper_int;
    case ems_c_attr_usmall_int:
        unsigned small int usmall_int;
    case ems_c_attr_ushort_int:
        unsigned short int ushort_int;
    case ems_c_attr_ulong_int:
        unsigned long int ulong_int;
    case ems_c_attr_uhyper_int:
        unsigned hyper int uhyper_int;
    case ems_c_attr_short_float:
        float short_float;
    case ems_c_attr_long_float:
        double long_float;
    case ems_c_attr_boolean:
        boolean bool;
    case ems_c_attr_uuid:
        uuid_t uuid;
    case ems_c_attr_utc:
        utc_t utc;
    case ems_c_attr_severity:
        ems_severity_t severity;
    case ems_c_attr_acl:
        sec_acl_t * acl;
    case ems_c_attr_byte_string:
        [string] byte * byte_string;
    case ems_c_attr_char_string:
        [string] char * char_string;
    case ems_c_attr_bytes:
        ems_bytes_t * bytes;
    case ems_c_attr_octet_array:
        ems_netaddr_t * octet_array;
    default:
        /*empty*/ ;
} ems_attr_value_t;

Event attribute

Event attributes contain an event attribute name/type pair (attr_name, attr_type) which define an event attribute. Event attributes can be used in defining event types in event type schemas, and in defining event filters in event filter expressions. The attr_name specifies the attribute's name, and the attr_type specifies the format of the attribute's value:

typedef struct ems_attribute_s_t {
    ems_string         name;    /* event attribute name */
    ems_attr_value_t   value;   /* event attribute type */
} ems_attribute_t;

EMS Event Structure

Event type

An event type specifies the unique ID for a given event type:

typedef uuid_t       ems_event_type_t;

+----------------------+-----------------+
|     Event Type       | Event Type Name |
+======================+=================+
| `ems_c_generic_type' | Generic         |
+----------------------+-----------------+
| `ems_c_svc_type'     | SVC             |
+----------------------+-----------------+
| `ems_c_aud_type'     | Audit           |
+----------------------+-----------------+

      Table 8: Default Event Types

tab(@) box center;

cw(2.0i) | cw(1.5i)

l | l.

Event Type@Event Type Name

ems_c_generic_type@Generic

ems_c_svc_type@SVC

ems_c_aud_type@Audit

Table 8: Default Event Types\}

Events of type Generic do not have event type schemas associated with them, and can only be filtered by expressions with header attributes in them (See Table 5: Event Header Attributes).

Event identifier

An event identifier uniquely identifies a given event. Each event has both an event type, which is unique to all events of this type, and an event ID, which is unique to a specific event:

typedef struct ems_eventid_s_t {
    ems_event_type_t    type;    /* event type */
    uuid_t              id;      /* unique event identifier */
} ems_eventid_t;

Network name

A network name identifies the network name of a given host machine.

The name service specifies which name service recognizes the given network name:

typedef enum ems_nameservice_s_t {
    ems_ns_other = 0,    /* name service other than listed */
    ems_ns_dns,          /* DNS name service */
    ems_ns_dce,          /* DCE CDS name Service */
    ems_ns_x500,         /* X500 */
    ems_ns_nis,          /* NIS */
    ems_ns_sna           /* SNA network */
} ems_nameservice_t;

The ems_netaddr_t structure specifies the actual network name. It can be interpreted according to the name service specified:

typedef char ems_octet_t;    /* used for NLS support */

typedef struct ems_netaddr_s_t {
    unsigned short    len;
    [size_is(len)]
    ems_octet_t       name[];  /* name in appropriate format */
} ems_netaddr_t;

typedef struct ems_netname_s_t {
    ems_nameservice_t      service;  /* name service used
                                        for netname */
    [ptr] ems_netaddr_t *  netaddr;  /* network name/address */
} ems_netname_t;

For a DCE hostname, the following example will set the ems_netname_t structure:

static char *  dce_hostname = "/.:/hosts/eagle.austin.ibm.com";

ems_netname_t  netname;

    netname.service = ems_ns_dce;
    netname.netaddr->len = strlen(dce_hostname)+1;
    netname.netaddr->name =
                          (char *)malloc(netname.netaddr->len);
    strcpy(netname.netaddr->name, dce_hostname);

Note that the netname.netaddr->name is used as a character string (char *) in this example, and that the NULL terminating byte is included in the length (netname.netaddr->len).

Event origin

The event origin specifies where the event originated (i.e., the supplier). The origin specifies the network name of the host where the supplier is running, the name of the supplier, desciptive name, and supplier process identification (pid, uid, gid). These values may not be valid for all hosts:

typedef struct ems_origin_s_t {
    ems_netname_t     netname;   /* network name of originator
                                    host */
    [string] char *   descname;  /* descriptive name of
                                    supplier */
    unsigned32        pid;       /* process ID of originator */
    unsigned32        uid;       /* user ID of originator */
    unsigned32        gid;       /* group ID of originator */
} ems_origin_t;

Event severity

The event severity specifies the severity of the event. The names have a one-to-one correspondence to DCE SVC severity attribute values. (See OSF DCE Application Development Guide -- Core Components:

typedef enum ems_severity_e_t {
    ems_sev_info=0,            /* information event */
    ems_sev_fatal,             /* fatal event */
    ems_sev_error,             /* alert event */
    ems_sev_warning,           /* warning event */
    ems_sev_notice,            /* notice event */
    ems_sev_notice_verbose,    /* notice verbose event */
    ems_sev_debug              /* debug event */
} ems_severity_t

Event header

The event header describes the fixed part of the event data structure. The header contains the event identifier, origin of the event, severity, along with the time the event was both received at EMS and delivered to the consumer:

typedef struct ems_hdr_s_t {
    ems_eventid_t   eventid;    /* event identifier */
    ems_origin_t    origin;     /* event origin */
    ems_severity_t  severity;   /* event Severity */
    utc_t           received;   /* event received timestamp */
    utc_t           delivered;  /* event delivered timestamp */
} ems_hdr_t;

A set of filter attributes are provided for event header filtering. The following names can be used for the filter attribute in an event filter expressions:

+--------------------------+--------------------------+
|     Attribute Name       |     Attribute Type       |
+==========================+==========================+
| `eventid.id'             | `ems_c_attr_uuid'        |
+--------------------------+--------------------------+
| `eventid.type'           | `ems_c_attr_uuid'        |
+--------------------------+--------------------------+
| `origin.netname.service' | `ems_c_attr_ulong'       |
+--------------------------+--------------------------+
| `origin.netname.netaddr' | `ems_c_attr_bytes'       |
+--------------------------+--------------------------+
| `origin.descname'        | `ems_c_attr_char_string' |
+--------------------------+--------------------------+
| `origin.pid'             | `ems_c_attr_ulong'       |
+--------------------------+--------------------------+
| `origin.uid'             | `ems_c_attr_ulong'       |
+--------------------------+--------------------------+
| `origin.gid'             | `ems_c_attr_ulong'       |
+--------------------------+--------------------------+
| `severity'               | `ems_c_attr_severity'    |
+--------------------------+--------------------------+
| `received'               | `ems_c_attr_utc'         |
+--------------------------+--------------------------+
| `received.tod'           | `ems_c_attr_char_string' |
+--------------------------+--------------------------+
| `received.mday'          | `ems_c_attr_ushort_int'  |
+--------------------------+--------------------------+
| `received.mon'           | `ems_c_attr_ushort_int'  |
+--------------------------+--------------------------+
| `received.year'          | `ems_c_attr_ushort_int'  |
+--------------------------+--------------------------+
| `received.wday'          | `ems_c_attr_ushort_int'  |
+--------------------------+--------------------------+
| `received.yday'          | `ems_c_attr_ushort_int'  |
+--------------------------+--------------------------+

           Table 9: Event Header Attributes

tab(@) box center;

cw(2.0i) | cw(2.0i)

l | l.

Attribute Name@Attribute Type

eventid.id@ems_c_attr_uuid

eventid.type@ems_c_attr_uuid

origin.netname.service@ems_c_attr_ulong

origin.netname.netaddr@ems_c_attr_bytes

origin.descname@ems_c_attr_char_string

origin.pid@ems_c_attr_ulong

origin.uid@ems_c_attr_ulong

origin.gid@ems_c_attr_ulong

severity@ems_c_attr_severity

received@ems_c_attr_utc

received.tod@ems_c_attr_char_string

received.mday@ems_c_attr_ushort_int

received.mon@ems_c_attr_ushort_int

received.year@ems_c_attr_ushort_int

received.wday@ems_c_attr_ushort_int

received.yday@ems_c_attr_ushort_int

Table 9: Event Header Attributes\}

The header attribute names correspond to elements of the event header. Additional support is provided for the received time value to allow for filtering on different parts of the received time. All received time attribute values are evaluted in GMT, and it is the responsibility of the filter creator to convert values to GMT. Following is a list of the received time attributes and how to specify them:

received.tod -- Time in format HH[[MM]SS] where HH is the Hour (00\(mi23), MM is the Minute (00\(mi59), and SS specifies seconds (00\(mi59). If HH and/or SS is not specified, then the value 00 is assumed.
received.mday -- Day of month (1\(mi31).
received.mon -- Month of year (1\(mi12).
received.year -- Year.
received.wday -- Day of week (Sunday = 0).
received.yday -- Day of year (0\(mi365).

Event

The ems_event_t structure contains a fixed part (the event header), and a variable part (the event data items). Each data item is a self-defining value which contains an attribute type and attribute date. Count specifies how many data items are in the event:

typedef struct ems_event_s_t {
    ems_hdr_t              header;   /* fixed event header */
    unsigned32             count;    /* number of data items */
    [size_is(count)]
        ems_attribute_t    item[];   /* data items */
} ems_event_t;

EMS Event Types

The EMS Event Type structures are used to define the EMS Event types.

Event type schema

The event type schema is used to define an event type. It consists of an event type ID, type, a name field which specifies the name of the event type, and a list of event type attributes describing the format of this event type. Size specifies the number of attributes in an event type. The event type schemas only specifies the fixed part of an event. An event can have as many unnamed attributes following the list of attributes specified here:

typedef struct ems_event_type_schema_s_t {
    ems_event_type_t     type;         /* EMS event type */
    [string] char *      name;         /* event type name */
    long                 size;         /* number of
                                          attributes */
    [size_is(size)]
        ems_attribute_t  attribute[];  /* event type
                                          attributes */
} ems_event_type_schema_t;

Event type list

The event type list contains a list of event type schemas:

typedef [ptr] ems_event_schema_t *    ems_schema_ptr_t;

typedef struct ems_event_type_list_s_t {
    long                    size;       /* number of event type
                                           schemas */
    [size_is(size)]
        ems_schema_ptr_t    schema[];   /* ptr to event type
                                           schemas */
} ems_event_type_list_t;

EMS Event Filters

The event filter data structures allow the definition of both event filters and event filter lists.

Attribute operators

+------------------------+------------------------------------+
|   Attribute Operator   | Description of Attribute Operator  |
+========================+====================================+
| `ems_c_attr_op_eq'     | TRUE if `attr_name' equal to (==)  |
|                        | `attr_value'                       |
+------------------------+------------------------------------+
| `ems_c_attr_op_gt'     | TRUE if `attr_name' greater than   |
|                        | (>) `attr_value'                   |
+------------------------+------------------------------------+
| `ems_c_attr_op_lt'     | TRUE if `attr_name' less than (<)  |
|                        | `attr_value'                       |
+------------------------+------------------------------------+
| `ems_c_attr_op_ge'     | TRUE if `attr_name' greater than   |
|                        | or equal to (>=) `attr_value'      |
+------------------------+------------------------------------+
| `ems_c_attr_op_le'     | TRUE if `attr_name' less than or   |
|                        | equal to (<=) `attr_value'         |
+------------------------+------------------------------------+
| `ems_c_attr_op_ne'     | TRUE if `attr_name' not equal to   |
|                        | (!=, <>) `attr_value'              |
+------------------------+------------------------------------+
| `ems_c_attr_op_bitand' | TRUE if `attr_name' bitwise ANDed  |
|                        | with `attr_value' is greater than  |
|                        | 0                                  |
+------------------------+------------------------------------+
| `ems_c_attr_op_substr' | TRUE if `attr_name' contains the   |
|                        | string value specified by          |
|                        | `attr_value'                       |
+------------------------+------------------------------------+

                Table 10: Attribute Operators

tab(@) box center;

cw(1.5i) | cw(3.0i)

l | l.

Attribute Operator@Description of Attribute Operator

ems_c_attr_op_eq@T{

TRUE if attr_name equal to (==) attr_value

ems_c_attr_op_eq@T{

TRUE if attr_name equal to (==) attr_value

ems_c_attr_op_gt@T{

TRUE if attr_name greater than (>) attr_value

ems_c_attr_op_lt@T{

TRUE if attr_name less than (<) attr_value

ems_c_attr_op_ge@T{

TRUE if attr_name greater than or equal to (>=)

attr_value

ems_c_attr_op_le@T{

TRUE if attr_name less than or equal to (<=)

attr_value

ems_c_attr_op_ne@T{

TRUE if attr_name not equal to (!=, <>)

attr_value

ems_c_attr_op_bitand@T{

TRUE if attr_name bitwise ANDed with attr_value

is greater than 0

ems_c_attr_op_substr@T{

TRUE if attr_name contains the string value specified by

attr_value

Table 10: Attribute Operators\}

Attribute operators define the boolean operation to perform on the attribute name and the attribute value in the event filter expression. The attribute operator type is defined as:

typedef unsigned16 ems_attr_op_t;

Event filter expression

The event filter expression structure contains the elements of an event filter expression that is used to build an event filter. Event filter expressions contain an attribute name, operator, value triplet which defines a boolean filter expression:

typedef struct ems_filter_exp_s_t {
    [string] char *    attr_name;      /* attribute name */
    ems_attr_op_t      attr_operator;  /* attribute operator */
    ems_attr_value_t   attr_value;     /* attribute value */
} ems_filter_exp_t;

Event filter expression list

An event filter expression list groups a list of filter expressions together in a list to form an ANDed filter expression used in defining an event filter:

typedef struct ems_filter_exp_list_s_t {
    long                  size;           /* number of filter
                                             expressions */
    [size_is(size)]
        ems_filter_exp_t  filter_exps[];  /* filter expressions
                                             in list */
} ems_filter_exp_list_t;

Event filter

An event filter specifies a series of event filter expressions that will be ANDed together to perform a filter operation. The event filter contains a name which will be entered in the CDS name space, and a list of filter expressions:

typedef struct ems_filter_s_t {
    ems_string_t            filter_name;      /* event filter
                                                 name */
    ems_event_type_t        type,             /* type of event
                                                 filter */
    ems_filter_exp_list_t   filter_exp_list;  /* list of filter
                                                 expressions */
} ems_filter_t;

Filters with event type of Generic can only have filter expressions with header attribute names in them (See Table 5: Event Header Attributes).

Event filter name list

An event filter list contains a list of event filter names;

typedef [string] char *                 ems_string_t;

typedef struct ems_filtername_list_s_t {
    long                size;             /* number of event
                                             filter names */
    [size_is(size)]
        ems_string_t    filter_names[];   /* event filter names
                                             in group  */
} ems_filtername_list_t;

Event filter list

The event filter list structure contains a list of size filters:

typedef struct ems_filter_list_s_t {
    long                  size;         /* number of event
                                           filters */
    [size_is(size)]
        ems_filter_t *    filters[];    /* event filter
                                           list */
} ems_filter_list_t;

EMS Consumer Data Structures

Consumer

The consumer data structure defines an EMS consumer. Each consumer has a name which is entered in CDS, a hostname where the consumer is running, and a UUID unique to that consumer:

typedef struct ems_consumer_s_t {
    [string] char *   name;      /* DCE name of consumer */
    ems_netname_t *   hostname;  /* DCE hostname of consumer */
    uuid_t            uuid;      /* consumer's UUID */
} ems_consumer_t;

Consumer list

The consumer list structure contains a list of size consumer entries:

typedef struct ems_consumer_list_s_t {
    long                  size;          /* number of consumer
                                            entries */
    [size_is(size)]
        ems_consumer_t    consumer[];    /* consumer info */
} ems_consumer_list_t;

EMS Server Data Structure

Attribute list

The attribute list data structure defines a list of server attributes. Each attribute is a value maintained by an emsd server, and the attribute list can be used to query and set those values:

typedef struct ems_attrlist_s_t {
    long                   size;    /* number of attributes */
    [size_is(size)]
        ems_attribute_t    attr[];  /* event type attributes */
} ems_attrlist_t;

EMS Event Service Handle

Event service handle

ems_handle_t is a pointer to an opaque data structure which contains information used to allow users of EMS to connect to an Event Service on a specific DCE host. Once connected, the EMS handle is used on all subsequent Event Service operations:

typedef struct ems_handle_priv_s_t *    ems_handle_t;

USER INTERFACE CONSIDERATIONS

The design of EMS facilitates developing an Event Management user interface to consumer applications. A consumer could use the ems_get_event_types() call to get a list of the event type schemas for all the event types that suppliers will send to EMS, and first present the event types to register for, then the event type attributes to use to build event filters to provide finer control of what events the consumer could receive.

EMS APPLICATION PROGRAMMING INTERFACES

The following list of routines is a summary of the EMS API:

ems_register()
Obtain an EMS handle for future calls to EMS routines.
ems_unregister()
Frees the resources obtained by an ems_register() call.
ems_event_type_add()
Add a new event type schema to the Event Type Database.
ems_event_type_delete()
Delete an event type schema from the Event Type Database.
ems_event_type_get()
Get an event type schema from the Event Type Database.
ems_event_type_get_list()
Get a list of event type schemas from the Event Type Database.
ems_event_type_free_list()
Free the list of event type schemas.
ems_svc_supplier_send()
Send an event to EMS (only used by SVC).
ems_aud_supplier_send()
Send an event to EMS (only used by Audit).
ems_supplier_send()
Send an event to EMS.
ems_filter_add()
Add a filter to the Event Filter Database.
ems_filter_append()
Append filter expressions to the Event Filter Database.
ems_filter_get()
Get the contents of an event filter.
ems_filter_free()
Free storage for an event filter.
ems_filter_delete()
Delete a filter from the Event Filter Database.
ems_filter_get_namelist()
Get a list of the names of all filters in the Event Filter Database.
ems_filter_free_namelist()
Free the storage for a filter namelist.
ems_filter_get_list()
Get a list of all the filters in the Event Filter Database.
ems_filter_free_list()
Free the list of filters.
ems_consumer_start()
Called to start an event consumer.
ems_consumer_stop()
Called to stop an event consumer.
ems_consumer_handler_register()
Register a consumer event handler.
ems_consumer_register()
Register a consumer with EMS.
ems_consumer_unregister()
Unregister a consumer with EMS.
ems_add_filter_to_group()
Add a filter name to a consumer's event filter group.
ems_delete_filter_from_group()
Delete a filter name from a consumer's event filter group.
ems_get_filter_group()
Get the list of filter names that comprise a consumer's event filter group.

Register with EMS

SYNOPSIS:

#include <dce/ems.h>

void ems_register(
    ems_netname_t *     hostname,   /* DCE host name */
    ems_handle_t *      handle,     /* EMS handle */
    error_status_t *    status);    /* mgmt request status */

DESCRIPTION:

This routine registers with EMS, and obtains an EMS binding handle. This routine can be used by a management application that will be using the EMS Management API (See Section 11.3, EMS Remote Management Interface) or by event suppliers that wish to add new event types (See Section 9.1, Event Type Interface).

PERMISSION REQUIRED:

None.

PARAMETERS:

Input:
hostname -- The name of the DCE host machine where emsd is running. If the hostname is NULL, then the local host is assumed.
Output:
handle -- Returns an EMS handle to use for future calls to EMS routines.
status -- Returns the status code from this routine which indicates whether the routine completed successfully or, if not, why not.

POSSIBLE STATUS CODES AND THEIR MEANING:

error_status_ok -- Success.
ems_s_no_memory -- An EMS handle cannot be allocated.
ems_s_unsupported_nameservice -- Hostname contains an unsupported name service.

Unregister with EMS

SYNOPSIS:

#include <dce/ems.h>

void ems_unregister(
    ems_handle_t *      handle,     /* EMS handle */
    error_status_t *    status);    /* mgmt request status */

DESCRIPTION:

This routine unregisters and frees up the resources used by an EMS handle. This routine should be called with a handle obtained by the ems_register() routine.

PERMISSION REQUIRED:

None.

PARAMETERS:

Input:
handle -- An EMS handle obtained from the ems_register() routine.
Output:
handle -- Sets the value of handle to NULL.
status -- Returns the status code from this routine which indicates whether the routine completed successfully or, if not, why not.

POSSIBLE STATUS CODES AND THEIR MEANING:

error_status_ok -- Success.
ems_s_invalid_handle -- An invalid handle was passed.

Event Type Interface

Add an event type

SYNOPSIS:

#include <dce/ems.h>

void ems_event_type_add(
    ems_handle_t          handle,     /* EMS handle */
    ems_event_schema_t *  schema,     /* event type schema to
                                         add */
    error_status_t *      status);    /* request status */

DESCRIPTION:

This routine is used by an event supplier to add new event types to the EMS event type Database. A supplier can add a new event type, then start producing that event type by transmitting events to EMS.

PERMISSION REQUIRED:

(i) on /.:/hosts/hostname/ems-server/event-types

PARAMETERS:

Input:
handle -- A handle returned from a call to ems_register call.
Output:
schema -- Is an EMS event type schema which describes the format of an event type.
status -- Returns the status code from this routine which indicates whether the routine completed successfully or, if not, why not.

POSSIBLE STATUS CODES AND THEIR MEANING:

error_status_ok -- Success.
ems_s_invalid_handle -- Handle parameter is not valid.
ems_s_event_type_exists -- The event type already exists.
ems_s_insufficient_permission -- The caller does not have permission to perform this operation.
ems_s_invalid_event_type -- The event schema is not valid.
ems_s_not_supported -- Not supported in this release.

This routine is not supported in release 1.

Delete an event type

SYNOPSIS:

#include <dce/ems.h>

void ems_event_type_delete(
    ems_handle_t          handle,      /* EMS handle */
    char *                type_name,   /* event type name */
    ems_event_type_t *    type,        /* event type ID */
    error_status_t *      status);     /* request status */

DESCRIPTION:

This routine is used by an event supplier to delete an event types in the EMS event type Database.

PERMISSION REQUIRED:

(d) on /.:/hosts/hostname/ems-server/event-types, or
(d) on /.:/hosts/hostname/ems-server/event-types/type_name

PARAMETERS:

Input:
handle -- A handle returned from a call to ems_register().
type_name -- Is the name of an EMS event type.
type -- Event type ID of type to delete.
Output:
status -- Returns the status code from this routine which indicates whether the routine completed successfully or, if not, why not.

POSSIBLE STATUS CODES AND THEIR MEANING:

error_status_ok -- Success.
ems_s_invalid_handle -- Handle parameter is not valid.
ems_s_insufficient_permission -- The caller does not have permission to perform this operation.
ems_s_event_type_not_found -- The specified event type was not found.
ems_s_invalid_name -- The event type name specified an name that is not valid.
ems_s_not_supported -- Not supported in this release
The caller of this routine must have appropriate authority on /.:/subsys/ems/events. See Section 6.5.1, Event Type Security Management.

This routine is not supported in release 1.

Get an event type

SYNOPSIS:

#include <dce/ems.h>

void ems_event_type_get(
   ems_handle_t            handle,     /* EMS handle */
   char *                  type_name,  /* event type name */
   ems_event_type_t *      type,       /* event type ID */
   ems_event_schema_t **   schema,     /* event type schema */
   error_status_t *        status);    /* request status */

DESCRIPTION:

This routine is used to retrieve event type schemas from the event type database.
PERMISSION REQUIRED:
(r) on /.:/hosts/hostname/ems-server/event-types

PARAMETERS:
Input:
handle -- Should be the handle returned from a call to ems_consumer_register call().
type_name -- The event type name to retreive from the event type database.
type -- The event type ID to retreive from the event type database.
Output:
schema -- Returns the requested event type schema.
status -- Returns the status code from this routine which indicates whether the routine completed successfully or, if not, why not.

POSSIBLE STATUS CODES AND THEIR MEANING:
error_status_ok -- Success.
ems_s_invalid_handle -- Handle parameter is not valid.
ems_s_insufficient_permission -- The caller does not have permission to perform this operation.
ems_s_invalid_name -- The event type name specified a name that is not valid.
ems_s_event_type_not_found -- The requested event type was not found.

This routine is not supported in release 1.

Get event types list

SYNOPSIS:
#include <dce/ems.h>

void ems_event_type_get_list(
    ems_handle_t               handle,    /* EMS handle */
    ems_event_type_list_t **   type_list, /* list of event
                                             types */
    error_status_t *           status);   /* request status */
DESCRIPTION:

This routine is used by EMS event consumers to find out what event types are available to register for. The consumer can then set up filters for attributes in one of the available event types.

PERMISSION REQUIRED:
(r) on /.:/hosts/hostname/ems-server/event-types

PARAMETERS:
Input:
handle -- Should be the handle returned from a call to ems_consumer_register() call.
Output:
type_list -- Returns the list of available event types.
status -- Returns the status code from this routine which indicates whether the routine completed successfully or, if not, why not.

POSSIBLE STATUS CODES AND THEIR MEANING:
error_status_ok -- Success.
ems_s_invalid_handle -- Handle parameter is not valid.
ems_s_insufficient_permission -- The caller does not have permission to perform this operation.
ems_s_no_type_list -- There is no event type list available.

Free event types list

SYNOPSIS:
#include <dce/ems.h>

void ems_event_type_free_list(
    ems_event_type_list_t **   type_list, /* list of event
                                             types */
    error_status_t *           status);   /* request status */
DESCRIPTION:

This routine is used by callers of ems_get_event_types to free the storage used by an event type list.

PERMISSION REQUIRED:
None.

PARAMETERS:
Input:
type_list -- An event type list as returned by ems_event_type_get_list. type_list will be set to NULL by this routine.
Output:
status -- Returns the status code from this routine which indicates whether the routine completed successfully or, if not, why not.

POSSIBLE STATUS CODES AND THEIR MEANING:
error_status_ok -- Success.

Event Supplier Interface

Supplier send

SYNOPSIS:
void ems_svc_supplier_send(
    ems_handle_t        handle,     /* EMS handle */
    dce_svc_prolog_t    prolog,     /* svc prolog */
    error_status_t *    status,     /* send status */
    va_list             args);      /* svc arguments */

void ems_aud_supplier_send(
    ems_handle_t             handle, /* EMS handle */
    dce_aud_hdr_t            header, /* Audit record header */
    aud_log_ev_info_list_t * tailp,  /* Audit record data */
    error_status_t *         status);/* send status */

#include <dce/ems.h>

void ems_supplier_send(
    ems_handle_t            handle,  /* EMS handle */
    ems_event_t *           event,   /* event data */
    error_status_t *        status); /* send status */
DESCRIPTION:
This routine is called by event suppliers to send events to EMS. The two additional routines, ems_aud_supplier_send and ems_svc_supplier_send, were designed to be called by the DCE Audit and SVC subsystem respectively, and are not designed to be called by the general EMS supplier.

PERMISSION REQUIRED:
(w) on /.:/hosts/hostname/ems-server/event-types/type_name

PARAMETERS:
Input:
handle -- Should be the handle returned from a call to the ems_register() call.
event -- Contains the actual event data. For the content of the event messages, see the Data Structures section.
Output:
status -- Returns the status code from this routine which indicates whether the routine completed successfully or, if not, why not.

POSSIBLE STATUS CODES AND THEIR MEANING:
error_status_ok -- Success.
ems_s_invalid_handle -- A handle that has not been initialized or that is invalid was used.
ems_s_insufficient_permission -- The caller does not have permission to perform this operation.
ems_s_no_memory -- Ems server received an error allocating memory.
ems_s_queue_full -- The EMS Input Queue is full, event was not transmitted.

Event Filter Construction Interface

EMS provides several routines to construct event filters. These are routines to add, delete and update an event filter.

Add an event filter

SYNOPSIS:
#include <dce/ems.h>

void ems_filter_add(
    ems_handle_t            handle,      /* EMS handle */
    ems_string_t            filter_name, /* event filter name
                                            */
    ems_event_type_t        type,        /* filter event type
                                            */
    ems_filter_exp_list_t * exp_list;    /* filter expression
                                            list */
    error_status_t *        status);     /* Filter construction
                                            status */
DESCRIPTION:
This routine is used to add a new event filter to the EMS Event Filter Database.

PERMISSION REQUIRED:
(i) on /.:/hosts/hostname/ems-server/filters

PARAMETERS:
Input:
handle -- A handle returned from a call to ems_consumer_register() call.
filter_name -- Specifies the event filter name for this event filter. This name can be used to add the event filter to a consumers event filter group.
type -- Specifies the event type that this filter will be applier against.
exp_list -- A list of filter expressions which are part of the event filter filter_name.
Output:
status -- Returns the status code from this routine which indicates whether the routine completed successfully or, if not, why not.

POSSIBLE STATUS CODES AND THEIR MEANING:
error_status_ok -- Success.
ems_s_invalid_handle -- Handle parameter is not valid.
ems_s_insufficient_permission -- The caller does not have permission to perform this operation.
ems_s_filter_exists -- The given filter name already exists.
ems_s_invalid_name -- The name specified is not a valid EMS name..
ems_s_invalid_filter -- The input parameters specifies an invalid filter.

Append to an event filter

SYNOPSIS:
#include <dce/ems.h>

void ems_filter_append(
    ems_handle_t            handle,       /* EMS handle */
    ems_string_t            filter_name,  /* event filter name
                                             */
    ems_filter_exp_list_t * exp_list,     /* filter exprs to
                                             add */
    error_status_t *        status);      /* filter
                                             construction
                                             status */
DESCRIPTION:

This routine is used to add filter expressions to an event filter. The filter expressions are added to the end of the current list of filter expressions in the event filter.

PERMISSION REQUIRED:
(w) on /.:/hosts/hostname/ems-server/filters/filter_name

PARAMETERS:
Input:
handle -- Should be the handle returned from a call to ems_consumer_register() call.
filter_name -- Specifies the name of the event filter to add the filter expressions to.
exp_list -- A list of filter expressions which will be added to the end of event filter filter_name.
Output:
status -- Returns the status code from this routine which indicates whether the routine completed successfully or, if not, why not.

POSSIBLE STATUS CODES AND THEIR MEANING:
error_status_ok -- Success.
ems_s_invalid_handle -- Handle parameter is not valid.
ems_s_insufficient_permission -- The caller does not have permission to perform this operation.
ems_s_invalid_name -- The name specified is not a valid EMS name.
ems_s_filter_not_found -- Given filter name not found in filter database.
ems_s_invalid_filter -- The input parameters specifies an invalid filter.

Get an event filter

SYNOPSIS:
#include <dce/ems.h>

void ems_filter_get(
    ems_handle_t             handle,      /* EMS handle */
    ems_string_t             filter_name, /* event filter name
                                             */
    ems_event_type_t *       type,        /* filter event type
                                             */
    ems_filter_exp_list_t ** exp_list,    /* returned filter
                                             exp list */
    error_status_t *         status);     /* Filter
                                             construction
                                             status */
DESCRIPTION:

This routine is used to get the filter expressions in an event filter.

PERMISSION REQUIRED:
(r) on /.:/hosts/hostname/ems-server/filters

PARAMETERS:
Input:
handle -- Should be the handle returned from a call to ems_consumer_register() call.
filter_name -- Specifies the name of the event filter to get.
Output:
type -- Specifies the event type of the filter.
exp_list -- The list of filter expressions which are part of event filter filter_name. filter_name can be freed by using the ems_filter_free() routine.
status -- Returns the status code from this routine which indicates whether the routine completed successfully or, if not, why not.

POSSIBLE STATUS CODES AND THEIR MEANING:
error_status_ok -- Success.
ems_s_invalid_handle -- Handle parameter is not valid.
ems_s_insufficient_permission -- The caller does not have permission to perform this operation.
ems_s_invalid_name -- The name specified is not a valid EMS name.
ems_s_filter_not_found -- Given filter name not found in filter database.

Free an event filter

SYNOPSIS:
#include <dce/ems.h>

void ems_filter_free(
    ems_filter_exp_list_t ** exp_list,    /* filter exp list to
                                             free */
    error_status_t *         status);     /* Filter
                                             construction
                                             status */
DESCRIPTION:

This routine is used to free an event filter expression list obtained by a call to ems_filter_get().

PERMISSION REQUIRED:
None.

PARAMETERS:
Input:
exp_list -- The list of filter expressions to free. This list should have been obtained by a call to ems_fitler_get().
Output:
status -- Returns the status code from this routine which indicates whether the routine completed successfully or, if not, why not.

POSSIBLE STATUS CODES AND THEIR MEANING:
error_status_ok -- Success.

Delete an event filter

SYNOPSIS:
#include <dce/ems.h>

void ems_filter_delete(
    ems_handle_t         handle,      /* EMS handle */
    ems_string_t         filter_name, /* event filter name */
    error_status_t *     status);     /* filter construction
                                         status */
DESCRIPTION:

This routine is used to delete an event filter from the Event Filter Database. The name filter_name cannot appear in any consumers event filter group when this routine is called.

PERMISSION REQUIRED:
(d) on /.:/hosts/hostname/ems-server/filters/filter_name, or (d) on /.:/hosts/hostname/ems-server/filters

PARAMETERS:
Input:
handle -- Should be the handle returned from a call to ems_consumer_register() call.
filter_name -- Specifies the name of the event filter to delete.
Output:
status -- Returns the status code from this routine which indicates whether the routine completed successfully or, if not, why not.

POSSIBLE STATUS CODES AND THEIR MEANING:
error_status_ok -- Success.
ems_s_invalid_handle -- Handle parameter is not valid.
ems_s_insufficient_permission -- The caller does not have permission to perform this operation.
ems_s_invalid_name -- The name specified is not a valid EMS name.
ems_s_filter_not_found -- Given filter name not found in filter database
ems_s_filter_in_use -- filter_name appears in a consumer's event filter group

List event filter names

SYNOPSIS:
#include <dce/ems.h>

void ems_filter_get_namelist(
    ems_handle_t              handle,       /* EMS handle */
    ems_filtername_list_t **  name_list,    /* event filter
                                               name list */
    error_status_t *          status);      /* filter
                                               construction
                                               status */
DESCRIPTION:

This routine is used to get a list of the names of the event filters in the Event Filter Database.

PERMISSION REQUIRED:
(r) on /.:/hosts/hostname/ems-server/filters

PARAMETERS:
Input:
handle -- Should be the handle returned from a call to ems_consumer_register() call.
Output:
name_list -- Will contain a list of all the event filter names in the Event Filter Database. The routine ems_event_filter_get() can be used to find out the contents of each event filter. Free name_list using the ems_filter_free_namelist() routine.
status -- Returns the status code from this routine which indicates whether the routine completed successfully or, if not, why not.

POSSIBLE STATUS CODES AND THEIR MEANING:
error_status_ok -- Success.
ems_s_invalid_handle -- Handle parameter is not valid.
ems_s_insufficient_permission -- The caller does not have permission to perform this operation.
ems_s_empty_filter_db -- No filters exist in the database.

Free an event filter name list

SYNOPSIS:
#include <dce/ems.h>

void ems_filter_free_namelist(
    ems_filtername_list_t **  name_list,   /* event filter name
                                              list */
    error_status_t *          status);     /* free status */
DESCRIPTION:

This routine is used to free a filter namelist returned by various routines. The routines that return a filter namelist are ems_filter_get_namelist(), ems_get_filter_group(), and ems_mgmt_get_filter_group().

PERMISSION REQUIRED:
None.

PARAMETERS:
Input:
name_list -- the filter namelist to free. name_list can be obtained by any of the three routines mentioned above.
Output:
status -- Returns the status code from this routine which indicates whether the routine completed successfully or, if not, why not.

POSSIBLE STATUS CODES AND THEIR MEANING:
error_status_ok -- Success.

Get event filter list

SYNOPSIS:
#include <dce/ems.h>

void ems_filter_get_list(
    ems_handle_t          handle,        /* EMS handle */
    ems_filter_list_t **  filter_list,   /* list of filters */
    error_status_t *      status);       /* filter construction
                                            status */
DESCRIPTION:

This routine is used to get a list of the event filters in the Event Filter Database.

PERMISSION REQUIRED:
(r) on /.:/hosts/hostname/ems-server/filters/filter_name

PARAMETERS:
Input:
handle -- a handle returned from a call to ems_consumer_register call.
Output:
filter_list -- will contain a list of all the event filters in the Event Filter Database. This list should be freed using ems_filter_free_list(). status returns the status code from this routine which indicates whether the routine completed successfully or, if not, why not.

POSSIBLE STATUS CODES AND THEIR MEANING:
error_status_ok -- Success.
ems_s_invalid_handle -- Handle parameter is not valid.
ems_s_insufficient_permission -- The caller does not have permission to perform this operation.
ems_s_empty_filter_db -- No filters exist in the database.

Free event filter list

SYNOPSIS:
#include <dce/ems.h>

void ems_filter_free_list(
    ems_filter_list_t **  filter_list,  /* event filter list */
    error_status_t *      status);      /* request status */
DESCRIPTION:

This routine is used by callers of ems_get_event_filter_database() to free the storage used by an Event Filter Database (ems_filter_db_t) structure.

PERMISSION REQUIRED:
None.

PARAMETERS:
Input:
filter_list -- a list of event filters that make up the Event Filter Database as returned by the routine ems_filter_get_list().
Output:
filter_list -- will be set to NULL.
status -- Returns the status code from this routine which indicates whether the routine completed successfully or, if not, why not.

POSSIBLE STATUS CODES AND THEIR MEANING:
error_status_ok -- Success.

Event Consumer Interface

The EMS event consumer interface consists of two parts. One part is used by the consumer to set itself up as a consumer, and the other is used to register with EMS.
All event consumers have to make calls to the EMS event consumer setup routines before receiving EMS events. These routines set up the consumers with the DCE RPC mechanism, and set up the consumers event handler routines.
The event consumer interface allows event consumers to register and unregister with EMS. Once registered, consumers can add and delete event filters define what events they are interested in. When EMS receives events from event suppliers, the event will be filtered using the event filter, and only the matching events will be forwarded on to the interested consumers.
EMS supports the ability to queue events in a buffer per event consumer to handle cases of event overload from multiple event suppliers and conditions where the event consumer is not responding to transmit requests. EMS ensures that no event is sent to the same consumer more than once.
If an event consumer's event queue becomes too large, implying some significant problem at the event consumer, EMS will unregister the consumer, and flush the queue. EMS stores information on consumers and suppliers registered, as well as filters defined in backing store. This data is used to restart EMS.

Consumer start

SYNOPSIS:
#include <dce/ems.h>

void ems_consumer_start(
    char *                consumer,  /* consumer name */
    unsigned32             flags,    /* consumer start flags */
    error_status_t *      status);   /* start status */
DESCRIPTION:

This routine should be called at the beginning of each event consumer before making any register calls. It will create an object uuid to uniquely identify this event consumer and register its endpoint so that EMS can send this consumer event data. This routine does not make any RPC calls to EMS.

PERMISSION REQUIRED:
None.

PARAMETERS:
Input:
consumer -- specifies the consumer name. This name must be unique, and will be registered in the CDS namespace under /.:/hosts/hostname/ems/consumers. The name will be used by the administrative interface to refer to this consumer.
flags -- reserved for future use.
Output:
status -- Returns the status code from this routine which indicates whether the routine completed successfully or, if not, why not.

POSSIBLE STATUS CODES AND THEIR MEANING:
error_status_ok -- Success.
ems_s_no_memory -- Error allocating memory
ems_s_consumer_already_started -- a call has already been made to this routine.
ems_s_invalid_name -- The name specified is not a valid EMS name.

Consumer stop

SYNOPSIS:
#include <dce/ems.h>

void ems_consumer_stop(
    error_status_t        *status);   /* stop status */
DESCRIPTION:

This routine should be called at the end of each event consumer. It will unregister the endpoint of this event consumer and kill the thread that was created by the consumer's event handler interface to receive all events from EMS. This routine does not make any RPC calls to EMS.

PERMISSION REQUIRED:
None.

PARAMETERS:
Output
status -- Returns the status code from this routine which indicates whether the routine completed successfully or, if not, why not.

POSSIBLE STATUS CODES AND THEIR MEANING:
error_status_ok -- Success.
ems_s_consumer_not_started -- The routine ems_consumer_start() has not been called

Consumer event handler register

SYNOPSIS:
#include <dce/ems.h>

void ems_consumer_handler_register(
    ems_handler_t       hfunc,     /* event handler function */
    error_status_t *    status);   /* stop status */
DESCRIPTION:

This routine declares the event consumer's event handler. The event consumer developer is responsible for providing the handler to process events. This routine does not make any RPC calls to EMS.

PERMISSION REQUIRED:
None.

PARAMETERS:
Input:
hfunc -- specifies the name of the event handler function. The handler's signature should be:
typedef void (*ems_handler_t) (
    ems_event_t *     event,   /* received event */
    error_status_t *  status); /* return status */
Output:
status -- Returns the status code from this routine which indicates whether the routine completed successfully or, if not, why not.
POSSIBLE STATUS CODES AND THEIR MEANING:
error_status_ok -- Success.
ems_s_no_memory -- Error allocating memory.
ems_s_mutex_init -- Error initializing event queue.
ems_s_cond_variable_init -- Error initializing event queue.
ems_s_pthread_create -- Error initializing event queue.
ems_s_consumer_not_started -- The routine ems_consumer_start() has not been called.

Consumer register

SYNOPSIS:
#include <dce/ems.h>

void ems_consumer_register(
    ems_netname_t *          hostname,      /* emsd hostname */
    ems_filtername_list_t *  filter_group,  /* event filter
                                               group */
    ems_handle_t *           handle,        /* EMS handle */
    error_status_t *         status);       /* register
                                               status */
DESCRIPTION:

This routine is used by EMS event consumers to register with EMS. This routine should be called once for each DCE host that this consumer wants to receive events from.

PERMISSION REQUIRED:
(i) on /.:/hosts/hostname/ems-server/consumers

PARAMETERS:
Input:
hostname -- The name of the DCE host machine where emsd is running. If the hostname is NULL, then the local host is assumed.
filter_group -- A list of event filter names which will define this consumers initial event filter group. If filter_group is empty, no filter group is specified, and EMS will not forward any events to this consumer until the consumer makes a call to ems_add_event_to_group().
Output:
handle -- Returns an EMS handle which can be used on subsequent calls to EMS routines.
status -- Returns the status code from this routine which indicates whether the routine completed successfully or, if not, why not.

POSSIBLE STATUS CODES AND THEIR MEANING:
error_status_ok -- Success.
ems_s_invalid_handle -- Handle parameter is not valid.
ems_s_insufficient_permission -- The caller does not have permission to perform this operation.
ems_s_no_memory -- Error allocating memory.
ems_s_already_registered -- Consumer with this name already registered.
ems_s_mutex_init -- Error initializing event queue.
ems_s_cond_variable_init -- Error initializing event queue.
ems_s_pthread_create -- Error initializing event queue.
ems_s_consumer_not_started -- The routine ems_consumer_start() has not been called.
ems_s_invalid_name -- The name specified is not a valid EMS name.

Consumer unregister

SYNOPSIS:
#include <dce/ems.h>

void ems_consumer_unregister(
    ems_handle_t *         handle,    /* EMS binding handle */
    error_status_t *       status);   /* unregister status */
DESCRIPTION:

This routine is used by EMS event consumers to unregister with EMS. This routine should be called once for each call to ems_consumer_register(). The event consumer should call this routine before calling the ems_consumer_stop() routine.

PERMISSION REQUIRED:
(d) on /.:/hosts/hostname/ems-server/consumers.

PARAMETERS:
Input:
handle -- a handle returned from a call to ems_consumer_register() call. This routine will free up memory used by handle, and set handle to NULL.
Output:
status -- Returns the status code from this routine which indicates whether the routine completed successfully or, if not, why not.

POSSIBLE STATUS CODES AND THEIR MEANING:
error_status_ok -- Success.
ems_s_invalid_handle -- Handle parameter is not valid.
ems_s_insufficient_permission -- The caller does not have permission to perform this operation.
ems_s_unknown_consumer -- Tried to unregister a consumer that was not registered.

Add event filter to group

SYNOPSIS:
#include <dce/ems.h>

void ems_add_filter_to_group(
    ems_handle_t             handle,         /* EMS handle */
    ems_filtername_list_t *  event_filters,  /* event filter
                                                names to add */
    error_status_t *         status);        /* filter request
                                                status */
DESCRIPTION:

This routine is used by EMS event consumers to add event filter names to a consumer's event filter group. This routine can be called multiple times for each consumer.

PERMISSION REQUIRED:
(w) on /.:/hosts/hostname/ems-server/consumers

PARAMETERS:
Input:
handle -- Must contain a valid consumer handle obtained from ems_consumer_register().
event_filters -- Contains a list of one or more event filter names to add to this consumer's event filter group. Consumers can use the names of new event filters after building them with the ems_filter_add() routine, or existing filters which can be obtained by using the ems_filter_get_namelist() routine.
Output:
status -- Returns the status code from this routine which indicates whether the routine completed successfully or, if not, why not.

POSSIBLE STATUS CODES AND THEIR MEANING:

error_status_ok -- Success.
ems_s_invalid_handle -- Handle parameter is not valid.
ems_s_insufficient_permission -- The caller does not have permission to perform this operation.
ems_s_filter_list_empty -- event_filters parameter contains no event filter names.
ems_s_no_memory -- Error allocating memory.
ems_s_filtername_exists -- An event filter in the filter list already exists in the consumer's event filter group.
ems_s_invalid_name -- A name specified is not a valid EMS name.

Delete event filter from group

SYNOPSIS:
#include <dce/ems.h>

void ems_delete_filter_from_group(
    ems_handle_t            handle,      /* EMS handle */
    ems_filtername_list_t * filter_name, /* event filter
                                            name(s) */
    error_status_t *        status);     /* filter request
                                            status */
DESCRIPTION:

This routine is used by EMS event consumers to delete event filter names from consumer event filter groups.

PERMISSION REQUIRED:
(w) on /.:/hosts/hostname/ems-server/consumers

PARAMETERS:
Input:
handle -- Must contain a valid consumer handle obtained from ems_consumer_register().
filter_name -- Specifies the event filter name(s) to delete from the consumers event filter group.
Output:
status -- Returns the status code from this routine which indicates whether the routine completed successfully or, if not, why not.

POSSIBLE STATUS CODES AND THEIR MEANING:
error_status_ok -- Success.
ems_s_invalid_handle -- Handle parameter is not valid.
ems_s_insufficient_permission -- The caller does not have permission to perform this operation.
ems_s_filter_list_empty -- event_filters parameter contains no event filter names.
ems_s_filtername_not_there -- Specified filter name to delete not in consumer's filter group.
ems_s_invalid_name -- A name specified is not a valid EMS name.
ems_s_consumer_not_found -- The specified consumer is not registered.

Get filter group

SYNOPSIS:
#include <dce/ems.h>

void ems_get_filter_group(
    ems_handle_t              handle,         /* EMS handle */
    ems_filtername_list_t **  filter_group,   /* event filter
                                                 group */
    error_status_t *          status);        /* filter request
                                                 status */
DESCRIPTION:

This routine returns a list of event filter names that comprise the consumers event filter group.

PERMISSION REQUIRED:
(r) on /.:/hosts/hostname/ems-server/consumers

PARAMETERS:
Input:
handle -- Must contain a valid consumer handle obtained from ems_consumer_register().
Output:
filter_group -- Will contain the list of event filter names which are in the consumers event filter group. It is up to the requesting consumer to free the storage allocated for filter_group by using the ems_filter_free_namelist() routine.
status -- Returns the status code from this routine which indicates whether the routine completed successfully or, if not, why not.

POSSIBLE STATUS CODES AND THEIR MEANING:

error_status_ok -- Success.
ems_s_invalid_handle -- Handle parameter is not valid.
ems_s_insufficient_permission -- The caller does not have permission to perform this operation.
ems_s_consumer_not_found -- The specified consumer is not registered.
ems_s_no_filter_group_defined -- Consumer does not have a filter group defined.

REMOTE INTERFACES

revent_type_add()
Add an event type to the Event Type Database.

revent_type_delete()
Delete an event type from the Event Type Database.

revent_type_get_list()
Get the list of event types from the Event Type Database.

rsupplier_transmit()
Send an event from a supplier to EMS.

rconsumer_register()
Register a consumer with EMS.

rconsumer_unregister()
Unregister a consumer with EMS.

rconsumer_reregister()
Reregister a consumer with EMS after new emsd start-up.

rconsumer_add_filter_to_group()
Add a filter to a consumer filter group.

rconsumer_del_filter_from_group()
Delete a filter from a consumers filter group.

rconsumer_get_filter_group()
Get the list of filters in a consumers filter group.

ems_transmit()
Transmit an event from emsd to a consumer.

ems_reregister()
Tell a consumer to reregister with EMS after new emsd start-up.

rfilter_add()
Add a filter to the Event Filter Database.

rfilter_delete()
Delete a filter from the Event Filter Database.

rfilter_get()
Get the contents of a filter from the Event Filter Database.

rfilter_append()
Append filter expressions to a filter in the Event Filter Database.

rfilter_get_namelist()
Get a list of all the filter names in the Event Filter Database.

rfilter_get_list()
Get a list of all the filters in the Event Filter Database.

EMS Event Type Interface

Remote event type add

SYNOPSIS:
void revent_type_add(
    [in]        handle_t              handle,
    [in]        ems_event_schema_t *  event_type,
    [out]       error_status_t *      status);
DESCRIPTION:

Add an event type schema to the EMS event type Database.

PERMISSION REQUIRED:
(i) on /.:/hosts/hostname/ems-server/event-types

PARAMETERS:
Input:
handle -- EMS binding handle.
event_type -- Event type schema.
Output:
status -- Returns the status code from this routine which indicates whether the routine completed successfully or, if not, why not.

POSSIBLE STATUS CODES AND THEIR MEANING:
error_status_ok -- Success.
ems_s_not_supported -- Not supported in this release.

Remote event type delete

SYNOPSIS:
void revent_type_delete(
    [in]        handle_t              handle,
    [in]        char *                type_name,
    [out]       error_status_t *      status);
DESCRIPTION:

Delete an event type schema from the EMS Event Type Database.

PERMISSION REQUIRED:
(d) on /.:/hosts/hostname/ems-server/event-types or (d) on /.:/hosts/hostname/ems-server/event-types/type_name

PARAMETERS:
Input:
handle -- EMS binding handle.
type_name -- name of an event type schema.
Output:
status -- Returns the status code from this routine which indicates whether the routine completed successfully or, if not, why not.

POSSIBLE STATUS CODES AND THEIR MEANING:
error_status_ok -- Success.
ems_s_not_supported -- Not supported in this release.

Remote event type get event types list

SYNOPSIS:
void revent_type_get_list(
    [in]        handle_t                  handle,
    [out]       ems_event_type_list_t **  type_list,
    [out]       error_status_t *          status);
DESCRIPTION:

Delete an event type schema to the EMS Event Type Database.

PERMISSION REQUIRED:
(r) on /.:/hosts/hostname/ems-server/event-types

PARAMETERS:
Input:
handle -- EMS binding handle.
Output:
type_list -- List of available event types.
status -- Returns the status code from this routine which indicates whether the routine completed successfully or, if not, why not.

POSSIBLE STATUS CODES AND THEIR MEANING:
error_status_ok -- Success.
ems_s_no_type_list -- There is no event type list available.

EMS Supplier Interface

Remote supplier transmit

SYNOPSIS:
void rsupplier_transmit(
    [in]        handle_t              handle,
    [in]        ems_event_t *         event,
    [out]       error_status_t *      status);
DESCRIPTION:

Transmit an event to EMS.

PERMISSION REQUIRED:
(w) on /.:/hosts/hostname/ems-server/event-types/type_name

PARAMETERS:
Input:
handle -- EMS binding handle.
event -- Transmitted event.
Output:
status -- Returns the status code from this routine which indicates whether the routine completed successfully or, if not, why not.

POSSIBLE STATUS CODES AND THEIR MEANING:
error_status_ok -- Success.
ems_s_no_memory -- EMS server received an error allocating memory.
ems_s_queue_full -- The EMS Input Queue is full, event was not queued.

EMS Consumer Interface

A consumer context handle has the form:
typedef [context_handle] void * cons_context_t;
The consumer context handle is used to maintain context for registered consumers. If EMS loses contact with a consumer, the context rundown routine will unregister the consumer.

Remote consumer register

SYNOPSIS:
void rconsumer_register(
    [in]          handle_t                handle,
    [in]          uuid_t                  uuid,
    [in,string]   char *                  consumer,
    [in]          ems_filtername_list_t * filter_group,
    [out]         cons_context_t *        ch,
    [out]         error_status_t *        status);
DESCRIPTION:

Register consumer with EMS.

PERMISSION REQUIRED:
(i) on /.:/hosts/hostname/ems-server/consumers

PARAMETERS:
Input:
handle -- EMS binding handle.
uuid -- Consumer unique identifier.
consumer -- Consumer name.
filter_group -- Initial consumer event filter group.
Output:
ch -- consumer context handle, to use in future consumer operations.
status -- Returns the status code from this routine which indicates whether the routine completed successfully or, if not, why not.

POSSIBLE STATUS CODES AND THEIR MEANING:
error_status_ok -- Success.
ems_s_insufficient_permission The caller does not have permission to perform this operation.
ems_s_no_memory -- Error allocating memory.
ems_s_already_registered -- Consumer with this name already registered.
ems_s_mutex_init -- Error initializing event queue.
ems_s_cond_variable_init -- Error initializing event queue.
ems_s_pthread_create -- Error initializing event queue.

Remote consumer unregister

SYNOPSIS:
void rconsumer_unregister(
    [in]        handle_t                handle,
    [in,out]    cons_context_t *        ch,
    [in]        uuid_t                  uuid,
    [out]       error_status_t *        status);
DESCRIPTION:

Unregister the specified consumer with EMS. The consumer is identified by its UUID.

PERMISSION REQUIRED:
(d) on /.:/hosts/hostname/ems-server/consumers

PARAMETERS:
Input:
handle -- EMS binding handle.
ch -- Consumer context handle returned by rconsumer_register.
uuid -- Consumer unique identifier.
Output:
ch -- consumer context handle returned by rconsumer_register().
status -- returns the status code from this routine which indicates whether the routine completed successfully or, if not, why not.

POSSIBLE STATUS CODES AND THEIR MEANING:
error_status_ok -- Success.
ems_s_insufficient_permission -- The caller does not have permission to perform this operation.
ems_s_unknown_consumer -- Tried to unregister a consumer that was not registered.

Remote consumer reregister

SYNOPSIS:
void rconsumer_reregister(
    [in]          handle_t            handle,
    [in,out]      cons_context_t *    ch,
    [in]          uuid_t              uuid,
    [in,string]   char *              consumer,
    [out]         error_status_t *    status);
DESCRIPTION:

Reregister the specified consumer with EMS. The consumer is identified by its UUID.

PERMISSION REQUIRED:
(i) on /.:/hosts/hostname/ems-server/consumers

PARAMETERS:
Input:
handle -- EMS binding handle.
ch -- Consumer context handle returned by rconsumer_register().
uuid -- Consumer unique identifier.
consumer -- Consumer name.
Output:
ch -- Consumer context handle.
status -- Returns the status code from this routine which indicates whether the routine completed successfully or, if not, why not.

POSSIBLE STATUS CODES AND THEIR MEANING:
error_status_ok -- Success.
ems_s_insufficient_permission -- The caller does not have permission to perform this operation.
ems_s_consumer_not_found -- Tried to unregister a consumer that was not registered.

Remote consumer add event filters to a group

SYNOPSIS:
void rconsumer_add_filter_to_group(
    [in]        handle_t                  handle,
    [in]        cons_context_t            ch,
    [in]        uuid_t                    uuid,
    [in]        ems_filtername_list_t *   filter_list,
    [out]       error_status_t *          status);
DESCRIPTION:

Add the event filters names in filter_list to a consumers event filter group. The consumer is identified by its UUID.

PERMISSION REQUIRED:
(w) on /.:/hosts/hostname/ems-server/consumers

PARAMETERS:
Input:
handle -- EMS binding handle.
ch -- Consumer context handle returned by rconsumer_register.
uuid -- Consumer unique identifier.
filter_list -- List of event filter names.
Output:
status -- Returns the status code from this routine which indicates whether the routine completed successfully or, if not, why not.

POSSIBLE STATUS CODES AND THEIR MEANING:
error_status_ok -- Success.
ems_s_insufficient_permission -- The caller does not have permission to perform this operation.
ems_s_consumer_not_found -- Could not find specified consumer.
ems_s_filter_list_empty -- Filter list parameter contains no event filter names.
ems_s_no_memory -- Error al

Open Software Foundation		R. Cohen (IBM)
Request For Comments: 67.0		G. Wilson (IBM)
January 1996