Novell Documentation: Storage Architecture Components (incl. Media Manager & NWPA)

NPA_Register_With_EventBus

Registers to produce or consume events prior to interacting with the Novell Event Bus.

Thread Context:Blocking if eventFlags MAY_NOT_SLEEP_BIT is clear or Non-Blocking if eventFlags MAY_NOT_SLEEP_BIT is set.

Syntax

    LONG NPA_Register_With_EventBus (
       LONG   npaHandle,
       LONG   eventType,
       BYTE  *registrationName,
       BYTE  *eventName,
       void  *userParameter,
       LONG   eventFlags,
       LONG   typeFlags,
       LONG   (*esr) (struct EventBlockDef *eventBlock),
       LONG   (*callBack) (struct EventBlockDef *eventBlock),
       LONG  *registrationHandle
    );

Parameters

npaHandle: (IN) The CDM's or HAM's handle for using the NPA APIs. Its value was assigned during NPA_Register_CDM_Module or NPA_Register_HAM_Module, respectively.

eventType

(IN) This defines the type of event user.

Event User (Decimal)	Event User
0	NEB_PRODUCER Produces events.
1	NEB_SECURITY_AUTHORITY_CONSUMER If registered, this consumer puts a security token on an event to allow the event to go or not go on the bus.
2	NEB_AUDITOR_CONSUMER If registered, this is guaranteed to be the last Check Consumer and has final authorization to allow an event to pass to the other consumers.
3	NEB_CHECK_CONSUMER A consumer that is called before any synchronous and asynchronous consumers. It allows the event to be passed to those consumers, prepares to allow those consumers to deal with the event, or rejects the event as not compatible at this time.
4	NEB_SYNCHRONOUS_CONSUMER A consumer that is notified in the order it was loaded and in the producing thread context.
5	NEB_ASYNCHRONOUS_CONSUMER A consumer that is notified whenever it is available and in any thread context.

registrationName

(IN) Points to the name string identifying this registration and has a maximum length of 80 characters including the NULL terminator.

eventName

(IN) Points to the name string of the event. It must match for both producer and consumer to successfully send and receive events.

userParameter

(IN) Custom value to be passed to the consumer when invoked for this event.

eventFlags

(IN) This flag field is used to specify whether the event can block, which direction to call synchronous consumers, and whether the event is consumable. These flags must match for the producer and consumer.

Event Flag (Decimal)	Event Flag
1	MAY_NOT_SLEEP_BIT Consumers of this event cannot relinquish control.
2	REVERSE_ORDER_BIT Instructs the Novell Event Bus to invoke synchronous consumers in reverse order.
4	CONSUMABLE_BIT Instructs the Novell Event Bus that this event can be consumed. If consumed, subsequent consumers marked consumable are not invoked for this event instance, but non-consumable consumers are invoked for this instance event.

Event Flag (Decimal)

Event Flag

MAY_NOT_SLEEP_BIT

Consumers of this event cannot relinquish control.

REVERSE_ORDER_BIT

Instructs the Novell Event Bus to invoke synchronous consumers in reverse order.

CONSUMABLE_BIT

Instructs the Novell Event Bus that this event can be consumed. If consumed, subsequent consumers marked consumable are not invoked for this event instance, but non-consumable consumers are invoked for this instance event.

typeFlags

See the following:

Type Flag (Decimal)	Type Flag
0x00000002	ACCESS_CONTROL_CHECK_BIT The security authority consumer should set this bit to request to be notified during event production. This allows the security authority to implement access control of producers and consumers for specific event data. This bit is valid only for consumers.
0x00000004	CONSUMABLE_CONSUMER_BIT By default the Novell Event Bus invokes all registered synchronous consumers in order of loading. If a consumer is marked a consumable and when invoked, signals that it has consumed the event, the Novell Event Bus does not invoke any other consumers marked as consumable. This bit is valid only for consumers.
0x80000000	MP_ENABLED_BIT This bit should be set if the consumer callback procedure (esr) is multi processor compliant. If this bit is not set, the consumer callback procedure is always called by a single processor.

Type Flag (Decimal)

Type Flag

0x00000002

ACCESS_CONTROL_CHECK_BIT

The security authority consumer should set this bit to request to be notified during event production. This allows the security authority to implement access control of producers and consumers for specific event data. This bit is valid only for consumers.

0x00000004

CONSUMABLE_CONSUMER_BIT

By default the Novell Event Bus invokes all registered synchronous consumers in order of loading. If a consumer is marked a consumable and when invoked, signals that it has consumed the event, the Novell Event Bus does not invoke any other consumers marked as consumable. This bit is valid only for consumers.

0x80000000

MP_ENABLED_BIT

This bit should be set if the consumer callback procedure (esr) is multi processor compliant. If this bit is not set, the consumer callback procedure is always called by a single processor.

esr: The esr, or Event Service Routine, receives system messages from the Novell Event Bus. Can be set to 0 if not needed. See EventBlockStruct.

callBack: Callback function to be called for consumers to receive messages. Producers ignore this field.

registrationHandle: (OUT) Points to a handle that is returned upon successful registration of this event. It is returned when deregistering for this event using NPA_Unregister_With_EventBus.

Return Values

The following table lists return values and descriptions.

0	SUCCESS Registration was valid.
-1	INVALID_PARAMETER The supplied registration information is invalid.
-2	OUT_OF_BOUNDS The NEB was unable to obtain the required system resources to satisfy the request.
-3	EVENT_CONFLICT The specified event flags do not agree with a previously registered party.
-4	CONSUMER_ACCESS_DENIED The security authority has refused the consumer's request to register for this event.
-5	SECURITY_AUTHORITY_ALREADY_REGISTERED An attempt to register a security authority consumer for this event failed because a security authority consumer is already registered.
-6	AUDITOR_ALREADY_REGISTERED An attempt to register an audit consumer for this event failed because an audit consumer is already registered.
-7	DEBUGGER_ALREADY_REGISTERED An attempt to register an event debugger failed because an event debugger is already registered.
-8	INVALID_CONSUMER_TYPE An attempt to register a consumer failed because the consumer type specified is not a valid consumer type.

Remarks

NPA_Register_With_EventBus is used to register as a producer or consumer for an event. After a producer successfully registers, it can get event blocks and send events using NPA_Send_Event. Consumers can receive events.

When a producer sends an event, the consumer's esr is called with a pointer to the event block. The consumer can consume the event (if the consumable bit is set), which does not allow any other consumers with the consumable bit set to be called. All other consumers are called.