IoInitializeRemoveLock macro (wdm.h)
The IoInitializeRemoveLock routine initializes a remove lock for a device object.
Syntax
void IoInitializeRemoveLock(
[in] Lock,
[in] Tag,
[in] Maxmin,
[in] HighWater
);
Parameters
[in] Lock
Pointer to a caller-supplied IO_REMOVE_LOCK structure that this routine initializes with information about the lock, including a counter and a synchronization event. A driver writer must allocate this structure as part of the device object's device extension.
[in] Tag
Specifies a tag to identify the creator of the lock. Driver writers typically use a 4-character string, specified in reverse order, like the tags used for ExAllocatePoolWithTag.
The I/O system uses this parameter if Driver Verifier is enabled. The caller should always supply a nonzero tag value for this parameter.
[in] Maxmin
Specifies the maximum number of minutes that this lock should be held. A value of zero means there is no limit. This value is typically used during debugging to identify a driver routine that holds the lock longer than expected.
The I/O system uses this parameter if Driver Verifier is enabled.
[in] HighWater
Specifies the maximum number of outstanding acquisitions allowed on the lock. Use 0 to specify no maximum. HighWatermark must be <= 0x7FFFFFFF.
The I/O system uses this parameter if Driver Verifier is enabled.
Return value
None
Remarks
A driver can use a remove lock to track outstanding I/O operations on a device and to determine when the driver can delete its device object in response to an IRP_MN_REMOVE_DEVICE request.
Before calling IoInitializeRemoveLock, a driver should allocate an IO_REMOVE_LOCK structure in its device extension. A driver typically calls IoInitializeRemoveLock in its AddDevice routine, when the driver initializes the rest of the device extension for a device object.
After the IoReleaseRemoveLockAndWait routine returns, the driver should consider the device to be in a state in which it is ready to be removed and cannot perform I/O operations. Therefore, the driver must not call IoInitializeRemoveLock to re-initialize the remove lock. Violation of this rule while the driver is being verified by Driver Verifier will result in a bug check.
Because the driver stores the IO_REMOVE_LOCK structure in the device extension of a device object, the remove lock is deleted when the driver deletes the device extension as part of processing an IRP_MN_REMOVE_DEVICE request.
For more information, see Using Remove Locks.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Available starting with Windows 2000. |
| Target Platform | Desktop |
| Header | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| Library | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |