NPA_Register_For_Event_Notification
Registers a procedure to be called prior to specific
system events.
- Thread Context:Blocking
- Requirements:Must be called
only from a blocking process level.
Syntax
LONG NPA_Register_For_Event_Notification (
LONG npaHandle,
LONG *eventHandle,
LONG eventType,
LONG priority,
LONG (*warnRoutine)(
void (*outputRoutine)(void *controlString, ...),
LONG warnParameter),
void (*reportRoutine)(
LONG reportParameter)
);
Parameters
- npaHandle
- (IN) The CDM's or HAM's handle for using the NPA_ APIs,
assigned during NPA_Register_CDM_Module or NPA_Register_HAM_Module, respectively.
- eventType
- (IN) Indicates the type of event for which the caller
wants notification. The following table describes events for which
notification may be received, the type of notification that can
be made (Warn, Report, or both), the thread context of the notification
call (blocking or non-blocking), and the defined use of the input
parameter (warnParameter or reportParameter )
passed to the notification call (warnRoutine or reportRoutine).
- priority
- (IN) The priority used to call this notification
function. Priorities are defined as follows:
- warnRoutine
- (IN) Points to a function that is called when an
event occurs that the OS classifies as a warning. If the warn function
determines the event should not occur, it must output a message
and then return a nonzero value. Most event notification functions
are called at process level, but some are made at interrupt level
(meaning the thread cannot be blocked). The above table of event types
specifies which events must be checked to determine if the event
allows its thread to be blocked and describes which events are classified
as warnings.
- reportRoutine
- (IN) Points to a function that is called when an
event occurs that the OS classifies as a report. Most event notification
functions are called at process level, but some are made at interrupt level
(meaning the thread cannot be blocked). The above table of event
types specifies which events must be checked to determine if the
event allows its thread to be blocked and describes which events
are classified as reports.
- eventHandle
- (OUT) Receives a 32-bit handle to the registered
event. This event handle is passed as an input parameter to NPA_Unregister_Event_Notification.
Return Values
The following table lists return values and descriptions.
Remarks
On some occasions a driver is required to perform some action
prior to the OS terminating, switching to real mode, exiting to
DOS, etc. The driver should call NPA_Register_For_Event_Notification
providing notification procedure pointers as indicated above.
Even though the calls to register and deregister the event
notification are blocking, the actual call to the event notification
procedure provided by the driver is not always made from blocking
process level (the environment varies with the particular event
being reported). The warnRoutine is provided with
two parameters when called. The first is the outputRoutine, which
must be used to output messages (the outputRoutine must
be called with controlString and as many parameters
as the control string indicates), and the second is the parameter
described in each of the event types above. When the reportRoutine is
called it is passed a single parameter. This is the same parameter
described in each of the event types described above.