Add Notification Event

When given 0x1B as its FunctionCode argument, the NtTraceControl function tells the kernel of an event to signal whenever the process has a notification to retrieve (see function code 0x10). Microsoft’s name for this function code is not known. This note deals only with the function’s behaviour that is specific to this function code. The function’s general behaviour is here taken as assumed knowledge.

The input buffer must provide a handle to the event. Only 32 bits are provided for this handle even on 64-bit Windows. The function returns STATUS_INVALID_PARAMETER if either:

• the input buffer is not exactly 4 bytes;
• the 4 bytes are NULL.

Each process can have only one such event, which is anyway just a refinement of an older mechanism for managing data for notifications. If this mechanism is already initialised, the function returns STATUS_UNSUCCESSFUL. Only now that it looks like the event can be added does the function check that the handle actually does represent an event object and grant EVENT_MODIFY_STATE access. Failure is fatal to the function. If while checking the event and trying to accept it into use, the notification mechanism is meanwhile initialised by other means, the function forgets this event and returns STATUS_ALREADY_REGISTERED.

TO BE DONE?