Open Software Foundation R. Cohen (IBM) Request For Comments: 67.0 G. Wilson (IBM) January 1996 DCE EVENT MANAGEMENT SERVICE 1. 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. 2. 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 Cohen, Wilson Page 1 OSF-RFC 67.0 DCE Event Managment Service January 1996 layer to the DCE SNMP subagents. 3. GOALS The goals of the DCE EMS are as follows: (a) The effort involved in writing a DCE event consumer application should be minimized. (b) The EMS service should have good performance, and should minimize network and system load. (c) EMS should be designed to be a centralized service, even though the first release will not be centralized. (d) Event consumer applications should be able to locate and register with one or more EMSs on multiple DCE hosts. (e) Events should be sent by DCE applications once and only once, via the SVC or Audit Interface, to EMS. (f) Event consumer applications should be able to control both which DCE host is sending events as well as which event types are sent. (g) 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. (h) DCE event supplier applications should not be aware of what DCE consumer applications have registered to receive events. (i) EMS should provide a remote management API. (j) EMS should provide reliable delivery of events to consumers and be tolerant of network and machine failures. (k) EMS should provide the ability to define and extend events and event contents. (l) 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]). (m) The first release of EMS should support SVC and Audit events. Cohen, Wilson Page 2 OSF-RFC 67.0 DCE Event Managment Service January 1996 3.1. Non-Goals (a) 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. (b) The first release of EMS will not support general message passing, only SVC and Audit events. 4. TERMINOLOGY (a) *attribute name* A string uniquely identifying an attribute of a given event type. (b) *attribute operator* The operator in a filter expression used in the comparison between the named attribute in the event and the attribute value. (c) *attribute type* The data type of an event attribute. This defines the format of the data in this attribute. (d) *attribute value* The value in a filter expression which is compared, using the attribute operator, against the event value for the specified attribute name. (e) *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. (f) *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. (g) *event consumer* A DCE server application which registers for, defines filters for, receives, and processes event data. Cohen, Wilson Page 3 OSF-RFC 67.0 DCE Event Managment Service January 1996 (h) *event filter* A collection of one or more filter expressions which are logically ANDed together. An event filter has an event filter name. (i) *event filter expression.* A 3-tuple consisting of an attribute name, attribute operator, and an attribute value, which defines a compare operation. (j) *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. (k) *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. (l) *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. (m) *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. (n) *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. Cohen, Wilson Page 4 OSF-RFC 67.0 DCE Event Managment Service January 1996 5. REQUIREMENTS (a) EMS should not be required for use of SVC or Audit. (b) The DCE application developer should be able to send events using the SVC or Audit subsystem without instrumenting directly to EMS. (c) EMS should be capable of event persistence and event retransmission to the appropriate DCE event consumers in the case of network or system failure. (d) 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. (e) All DCE coding requirements should be followed. All code should be internationalized, and should be portable across all DCE platforms. 6. 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. 6.1. 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 | +--------------------------------------------------------+ 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 Cohen, Wilson Page 5 OSF-RFC 67.0 DCE Event Managment Service January 1996 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. 6.2. 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. Cohen, Wilson Page 6 OSF-RFC 67.0 DCE Event Managment Service January 1996 6.2.1. 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"). 6.2.2. 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}} }; Cohen, Wilson Page 7 OSF-RFC 67.0 DCE Event Managment Service January 1996 #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: (a) `SVC_C_SEV_FATAL' (b) `SVC_C_SEV_ERROR' (c) `SVC_C_SEV_WARNING' (d) `SVC_C_SEV_NOTICE' (e) `SVC_C_SEV_NOTICE_VERBOSE' 6.3. 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. 6.3.1. 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. Cohen, Wilson Page 8 OSF-RFC 67.0 DCE Event Managment Service January 1996 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. 6.3.2. 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 Cohen, Wilson Page 9 OSF-RFC 67.0 DCE Event Managment Service January 1996 = 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. 6.3.3. 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' Cohen, Wilson Page 10 OSF-RFC 67.0 DCE Event Managment Service January 1996 can only have filter expressions with header attributes. 6.4. 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". 6.5. 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//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 Cohen, Wilson Page 11 OSF-RFC 67.0 DCE Event Managment Service January 1996 Three security objects will be maintained under the `ems-server' junction. The directories and the databases they represent are: (a) `event-types' -- Event type database. (b) `filters' -- Filter database. (c) `consumers' -- Consumer database. Each of these databases will have an ACL associated with it, as discussed next. 6.5.1. Event type security management The Event Type database will be represented by the following name in the DCE name space: /.:/hosts//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.) 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//ems-server/event-types/ where `' 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: Cohen, Wilson Page 12 OSF-RFC 67.0 DCE Event Managment Service January 1996 /.:/hosts//ems-server/events/SVC /.:/hosts//ems-server/events/Audit The permissions associated with `' 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.) 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. 6.5.2. Event Filter Security Management The Filter database will be represented by the following name in the DCE name space: /.:/hosts//ems-server/filters The ACL associated with this object will control access to this database. The permissions associated with filters are: Cohen, Wilson Page 13 OSF-RFC 67.0 DCE Event Managment Service January 1996 +----------+----------+--------------------------+ | 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 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//ems-server/filters/ where `' 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 When a consumer creates an event filter, that consumer principal automatically gets `cdw' permissions on the created event filter. 6.5.3. Consumer security management The Consumer database will be represented by the following name in the DCE name space: Cohen, Wilson Page 14 OSF-RFC 67.0 DCE Event Managment Service January 1996 /.:/hosts//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 6.5.4. 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: (a) `/.:/hosts//ems-server' (i) Object ACL: ems-admin:crws hosts//self:rws any_other:r (b) `/.:/hosts//ems-server/event-types' (i) Object ACL: ems-admin:cri ems-consumer:r ems-supplier:ri any_other:r (ii) Initial object ACL (`/.:/hosts//ems- server/event-types/'): Cohen, Wilson Page 15 OSF-RFC 67.0 DCE Event Managment Service January 1996 ems-admin:cdw ems-consumer:r ems-supplier:w (c) `/.:/hosts//ems-server/filters' (i) Object ACL: ems-admin:crdi ems-consumer:ir any_other:r (ii) Initial object ACL (`/.:/hosts//ems- server/filters/'): ems-admin:cw (d) `/.:/hosts//ems-server/consumers' (i) 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'). 6.6. Writing Consumers Consumers are not simple clients. They have to be implemented as servers. This means that EMS consumers have certain requirements. Consumers must: (a) 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"). (b) Call `ems_consumer_handler_register()'. This sets up an incoming consumer queue, and initializes the event handler Cohen, Wilson Page 16 OSF-RFC 67.0 DCE Event Managment Service January 1996 function to call the handle function specified. (c) Register with the various `emsd''s that it wants to receive events from. One event consumer can register to receive events from multiple `emsd's on different hosts. (d) Set up event filters. Consumers must set up event filters before any events will be sent. (e) Call `rpc_server_listen()'. This sets the consumer up to wait for incoming events. 6.7. EMS Recovery After Restart EMS stores all state data in the following repositories: (a) Consumer Database -- Contains list of all suppliers, and all consumers as well as the list of filters in the consumer filter group. (b) Event Type Database EM Contains the schemas for all the known event types. (c) Event Filter Database -- Contains all the current filter definitions. When an `emsd' is restarted, the following steps are performed: (a) All databases get restored. (b) All consumers are told to reregister or reconnect. (c) The event queue is restored from the event log files. (d) Event transmission proceeds. 6.8. 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"). 6.9. 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: Cohen, Wilson Page 17 OSF-RFC 67.0 DCE Event Managment Service January 1996 (a) Consumer names. (b) Filter Names. (c) Event Type Names. (d) 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()'. 7. DATA STRUCTURES 7.1. EMS Event Attributes 7.1.1. 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 | Cohen, Wilson Page 18 OSF-RFC 67.0 DCE Event Managment Service January 1996 +--------------------------+-------------------+----------+ | `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. 7.1.2. 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; Cohen, Wilson Page 19 OSF-RFC 67.0 DCE Event Managment Service January 1996 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; 7.1.3. 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; Cohen, Wilson Page 20 OSF-RFC 67.0 DCE Event Managment Service January 1996 7.2. EMS Event Structure 7.2.1. 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 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"). 7.2.2. 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; 7.2.3. 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; Cohen, Wilson Page 21 OSF-RFC 67.0 DCE Event Managment Service January 1996 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'). 7.2.4. 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; Cohen, Wilson Page 22 OSF-RFC 67.0 DCE Event Managment Service January 1996 7.2.5. 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 7.2.6. 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' | +--------------------------+--------------------------+ Cohen, Wilson Page 23 OSF-RFC 67.0 DCE Event Managment Service January 1996 | `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: (a) `received.tod' -- Time in format HH[[MM]SS] where HH is the Hour (00-23), MM is the Minute (00-59), and SS specifies seconds (00-59). If HH and/or SS is not specified, then the value 00 is assumed. (b) `received.mday' -- Day of month (1-31). (c) `received.mon' -- Month of year (1-12). (d) `received.year' -- Year. (e) `received.wday' -- Day of week (Sunday = 0). (f) `received.yday' -- Day of year (0-365). Cohen, Wilson Page 24 OSF-RFC 67.0 DCE Event Managment Service January 1996 7.2.7. 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; 7.3. EMS Event Types The EMS Event Type structures are used to define the EMS Event types. 7.3.1. 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; 7.3.2. 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; Cohen, Wilson Page 25 OSF-RFC 67.0 DCE Event Managment Service January 1996 7.4. EMS Event Filters The event filter data structures allow the definition of both event filters and event filter lists. 7.4.1. 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 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; 7.4.2. 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: Cohen, Wilson Page 26 OSF-RFC 67.0 DCE Event Managment Service January 1996 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; 7.4.3. 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; 7.4.4. 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"). 7.4.5. Event filter name list An event filter list contains a list of event filter names; Cohen, Wilson Page 27 OSF-RFC 67.0 DCE Event Managment Service January 1996 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; 7.4.6. 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; 7.5. EMS Consumer Data Structures 7.5.1. 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; 7.5.2. 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; Cohen, Wilson Page 28 OSF-RFC 67.0 DCE Event Managment Service January 1996 7.6. EMS Server Data Structure 7.6.1. 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; 7.7. EMS Event Service Handle 7.7.1. 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; 8. 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. 9. EMS APPLICATION PROGRAMMING INTERFACES The following list of routines is a summary of the EMS API: (a) `ems_register()' Obtain an EMS handle for future calls to EMS routines. (b) `ems_unregister()' Frees the resources obtained by an `ems_register()' call. Cohen, Wilson Page 29 OSF-RFC 67.0 DCE Event Managment Service January 1996 (c) `ems_event_type_add()' Add a new event type schema to the Event Type Database. (d) `ems_event_type_delete()' Delete an event type schema from the Event Type Database. (e) `ems_event_type_get()' Get an event type schema from the Event Type Database. (f) `ems_event_type_get_list()' Get a list of event type schemas from the Event Type Database. (g) `ems_event_type_free_list()' Free the list of event type schemas. (h) `ems_svc_supplier_send()' Send an event to EMS (only used by SVC). (i) `ems_aud_supplier_send()' Send an event to EMS (only used by Audit). (j) `ems_supplier_send()' Send an event to EMS. (k) `ems_filter_add()' Add a filter to the Event Filter Database. (l) `ems_filter_append()' Append filter expressions to the Event Filter Database. (m) `ems_filter_get()' Get the contents of an event filter. (n) `ems_filter_free()' Free storage for an event filter. (o) `ems_filter_delete()' Cohen, Wilson Page 30 OSF-RFC 67.0 DCE Event Managment Service January 1996 Delete a filter from the Event Filter Database. (p) `ems_filter_get_namelist()' Get a list of the names of all filters in the Event Filter Database. (q) `ems_filter_free_namelist()' Free the storage for a filter namelist. (r) `ems_filter_get_list()' Get a list of all the filters in the Event Filter Database. (s) `ems_filter_free_list()' Free the list of filters. (t) `ems_consumer_start()' Called to start an event consumer. (u) `ems_consumer_stop()' Called to stop an event consumer. (v) `ems_consumer_handler_register()' Register a consumer event handler. (w) `ems_consumer_register()' Register a consumer with EMS. (x) `ems_consumer_unregister()' Unregister a consumer with EMS. (y) `ems_add_filter_to_group()' Add a filter name to a consumer's event filter group. (z) `ems_delete_filter_from_group()' Delete a filter name from a consumer's event filter group. (aa) `ems_get_filter_group()' Cohen, Wilson Page 31 OSF-RFC 67.0 DCE Event Managment Service January 1996 Get the list of filter names that comprise a consumer's event filter group. 9.0.1. Register with EMS SYNOPSIS: #include 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. Cohen, Wilson Page 32 OSF-RFC 67.0 DCE Event Managment Service January 1996 `ems_s_unsupported_nameservice' -- Hostname contains an unsupported name service. 9.0.2. Unregister with EMS SYNOPSIS: #include 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. 9.1. Event Type Interface Cohen, Wilson Page 33 OSF-RFC 67.0 DCE Event Managment Service January 1996 9.1.1. Add an event type SYNOPSIS: #include 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//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. Cohen, Wilson Page 34 OSF-RFC 67.0 DCE Event Managment Service January 1996 `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. 9.1.2. Delete an event type SYNOPSIS: #include 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//ems-server/event-types', or (`d') on `/.:/hosts//ems-server/event- types/' 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. Cohen, Wilson Page 35 OSF-RFC 67.0 DCE Event Managment Service January 1996 `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. 9.1.3. Get an event type SYNOPSIS: #include 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//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. Cohen, Wilson Page 36 OSF-RFC 67.0 DCE Event Managment Service January 1996 `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. 9.1.4. Get event types list SYNOPSIS: #include 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: Cohen, Wilson Page 37 OSF-RFC 67.0 DCE Event Managment Service January 1996 (`r') on `/.:/hosts//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. 9.1.5. Free event types list SYNOPSIS: #include 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: Cohen, Wilson Page 38 OSF-RFC 67.0 DCE Event Managment Service January 1996 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. 9.2. Event Supplier Interface 9.2.1. 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 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: Cohen, Wilson Page 39 OSF-RFC 67.0 DCE Event Managment Service January 1996 (`w') on `/.:/hosts//ems-server/event- types/' 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. 9.3. Event Filter Construction Interface EMS provides several routines to construct event filters. These are routines to add, delete and update an event filter. 9.3.1. Add an event filter SYNOPSIS: Cohen, Wilson Page 40 OSF-RFC 67.0 DCE Event Managment Service January 1996 #include 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//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. Cohen, Wilson Page 41 OSF-RFC 67.0 DCE Event Managment Service January 1996 `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. 9.3.2. Append to an event filter SYNOPSIS: #include 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//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 add the filter expressions to. `exp_list' -- A list of filter expressions which will be added to the end of event filter `filter_name'. Cohen, Wilson Page 42 OSF-RFC 67.0 DCE Event Managment Service January 1996 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. 9.3.3. Get an event filter SYNOPSIS: #include 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//ems-server/filters' Cohen, Wilson Page 43 OSF-RFC 67.0 DCE Event Managment Service January 1996 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. 9.3.4. Free an event filter SYNOPSIS: #include void ems_filter_free( ems_filter_exp_list_t ** exp_list, /* filter exp list to free */ error_status_t * status); /* Filter construction status */ Cohen, Wilson Page 44 OSF-RFC 67.0 DCE Event Managment Service January 1996 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. 9.3.5. Delete an event filter SYNOPSIS: #include 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//ems- server/filters/', or (`d') on `/.:/hosts//ems-server/filters' Cohen, Wilson Page 45 OSF-RFC 67.0 DCE Event Managment Service January 1996 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 9.3.6. List event filter names SYNOPSIS: #include 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: Cohen, Wilson Page 46 OSF-RFC 67.0 DCE Event Managment Service January 1996 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//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. 9.3.7. Free an event filter name list SYNOPSIS: #include void ems_filter_free_namelist( ems_filtername_list_t ** name_list, /* event filter name list */ error_status_t * status); /* free status */ DESCRIPTION: Cohen, Wilson Page 47 OSF-RFC 67.0 DCE Event Managment Service January 1996 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. 9.3.8. Get event filter list SYNOPSIS: #include 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//ems- server/filters/' PARAMETERS: Cohen, Wilson Page 48 OSF-RFC 67.0 DCE Event Managment Service January 1996 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. 9.3.9. Free event filter list SYNOPSIS: #include 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()'. Cohen, Wilson Page 49 OSF-RFC 67.0 DCE Event Managment Service January 1996 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. 9.4. 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. 9.4.1. Consumer start SYNOPSIS: Cohen, Wilson Page 50 OSF-RFC 67.0 DCE Event Managment Service January 1996 #include 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//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. Cohen, Wilson Page 51 OSF-RFC 67.0 DCE Event Managment Service January 1996 9.4.2. Consumer stop SYNOPSIS: #include 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 9.4.3. Consumer event handler register SYNOPSIS: #include 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 Cohen, Wilson Page 52 OSF-RFC 67.0 DCE Event Managment Service January 1996 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. 9.4.4. Consumer register SYNOPSIS: Cohen, Wilson Page 53 OSF-RFC 67.0 DCE Event Managment Service January 1996 #include 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//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. Cohen, Wilson Page 54 OSF-RFC 67.0 DCE Event Managment Service January 1996 `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. 9.4.5. Consumer unregister SYNOPSIS: #include 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//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: Cohen, Wilson Page 55 OSF-RFC 67.0 DCE Event Managment Service January 1996 `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. 9.4.6. Add event filter to group SYNOPSIS: #include 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//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 Cohen, Wilson Page 56 OSF-RFC 67.0 DCE Event Managment Service January 1996 `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. 9.4.7. Delete event filter from group SYNOPSIS: #include 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//ems-server/consumers' Cohen, Wilson Page 57 OSF-RFC 67.0 DCE Event Managment Service January 1996 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. 9.4.8. Get filter group SYNOPSIS: #include 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 */ Cohen, Wilson Page 58 OSF-RFC 67.0 DCE Event Managment Service January 1996 DESCRIPTION: This routine returns a list of event filter names that comprise the consumers event filter group. PERMISSION REQUIRED: (`r') on `/.:/hosts//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. 10. REMOTE INTERFACES (a) `revent_type_add()' Add an event type to the Event Type Database. Cohen, Wilson Page 59 OSF-RFC 67.0 DCE Event Managment Service January 1996 (b) `revent_type_delete()' Delete an event type from the Event Type Database. (c) `revent_type_get_list()' Get the list of event types from the Event Type Database. (d) `rsupplier_transmit()' Send an event from a supplier to EMS. (e) `rconsumer_register()' Register a consumer with EMS. (f) `rconsumer_unregister()' Unregister a consumer with EMS. (g) `rconsumer_reregister()' Reregister a consumer with EMS after new `emsd' start-up. (h) `rconsumer_add_filter_to_group()' Add a filter to a consumer filter group. (i) `rconsumer_del_filter_from_group()' Delete a filter from a consumers filter group. (j) `rconsumer_get_filter_group()' Get the list of filters in a consumers filter group. (k) `ems_transmit()' Transmit an event from `emsd' to a consumer. (l) `ems_reregister()' Tell a consumer to reregister with EMS after new `emsd' start-up. (m) `rfilter_add()' Add a filter to the Event Filter Database. (n) `rfilter_delete()' Cohen, Wilson Page 60 OSF-RFC 67.0 DCE Event Managment Service January 1996 Delete a filter from the Event Filter Database. (o) `rfilter_get()' Get the contents of a filter from the Event Filter Database. (p) `rfilter_append()' Append filter expressions to a filter in the Event Filter Database. (q) `rfilter_get_namelist()' Get a list of all the filter names in the Event Filter Database. (r) `rfilter_get_list()' Get a list of all the filters in the Event Filter Database. 10.1. EMS Event Type Interface 10.1.1. 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//ems-server/event-types' PARAMETERS: Input: `handle' -- EMS binding handle. `event_type' -- Event type schema. Output: Cohen, Wilson Page 61 OSF-RFC 67.0 DCE Event Managment Service January 1996 `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. 10.1.2. 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//ems-server/event-types' or (`d') on `/.:/hosts//ems-server/event-types/' 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. Cohen, Wilson Page 62 OSF-RFC 67.0 DCE Event Managment Service January 1996 10.1.3. 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//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. 10.2. EMS Supplier Interface 10.2.1. Remote supplier transmit SYNOPSIS: void rsupplier_transmit( [in] handle_t handle, [in] ems_event_t * event, [out] error_status_t * status); DESCRIPTION: Cohen, Wilson Page 63 OSF-RFC 67.0 DCE Event Managment Service January 1996 Transmit an event to EMS. PERMISSION REQUIRED: (`w') on `/.:/hosts//ems-server/event- types/' 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. 10.3. 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. 10.3.1. Remote consumer register SYNOPSIS: Cohen, Wilson Page 64 OSF-RFC 67.0 DCE Event Managment Service January 1996 void rconsumer_register( [in] handle_t handle, [in] uuid_t uuid, [in,string] char * cons