PsSetCreateProcessNotifyRoutine

PsSetCreateProcessNotifyRoutine adds a driver-supplied callback routine to, or removes it from, a list of routines to be called whenever a process is created or deleted.

NTSTATUS
  PsSetCreateProcessNotifyRoutine(
    IN PCREATE_PROCESS_NOTIFY_ROUTINE  NotifyRoutine,
    IN BOOLEAN  Remove
    );

Parameters

NotifyRoutine

Specifies the entry point of a caller-supplied process-creation callback routine.

Remove

Indicates whether the routine specified by NotifyRoutine should be added to or removed from the system's list of notification routines. If FALSE, the specified routine is added to the list. If TRUE, the specified routine is removed from the list.

Include

ntddk.h

Return Value

PsSetCreateProcessNotifyRoutine can return one of the following:

STATUS_SUCCESS

The given NotifyRoutine is now registered with the system.

STATUS_INVALID_PARAMETER

The given NotifyRoutine has already been registered so this is a redundant call, or the system has reached its limit for registering process-creation callbacks.

Comments

Highest-level drivers can call PsSetCreateProcessNotifyRoutine to set up their process-creation notify routines, declared as follows:

VOID
(*PCREATE_PROCESS_NOTIFY_ROUTINE) (
    IN HANDLE  ParentId,
    IN HANDLE  ProcessId,
    IN BOOLEAN  Create
    );

The ParentId and ProcessId parameters identify the process, and the Create parameter indicates whether the process was created (TRUE) or deleted (FALSE).

An IFS or highest-level system-profiling driver might register a process-creation callback to track the system-wide creation and deletion of processes against the driver's internal state. The system can register up to eight process-creation callbacks. Any driver that successfully registers a callback must remain loaded until the system itself is shut down.

After a driver-supplied routine is registered, it is called with Create set to TRUE just after the initial thread is created within the newly created process designated by the input ProcessId handle. The input ParentId handle identifies the parent process of the newly created process if it inherits open handles from its parent.

A driver's process-notify routine is also called with Create set to FALSE, usually when the last thread within a process has terminated and the process address space is about to be deleted. In very rare circumstances, for processes in which no thread was ever created, a driver's process-notify routine is called only at the destruction of the process.

The driver's process-creation notify routine runs at IRQL PASSIVE_LEVEL, either in the context of the initial thread within a newly created process or in the context of a system thread.

Callers of PsSetCreateProcessNotifyRoutine must be running at IRQL PASSIVE_LEVEL.

See Also

PsGetCurrentProcessId, PsSetCreateThreadNotifyRoutine, PsSetLoadImageNotifyRoutine