ObCloseHandle routine

ObCloseHandle routine
The ObCloseHandle routine closes an object handle.
ObCloseHandle例程用来关闭对象句柄。

语法：
NTSTATUS ObCloseHandle(
_In_ HANDLE Handle,
_In_ KPROCESSOR_MODE PreviousMode
);

参数：
Handle [in]
A handle to a system-supplied object of any type.
由系统提供的任意类型的对象句柄。
PreviousMode [in]
Specifies the previous processor mode of the thread that opened the handle.
To close a kernel handle, set this parameter to KernelMode. To close a user handle, set this parameter to UserMode.
For more information about these two handle types, see Remarks.
指定之前打开句柄线程的进程模式。若关闭一个内核句柄，设置此参数为KernelMode,若要关闭一个用户用户，设置此参数为UserMode.
更多关于此句柄类型的信息，请查看备注。

返回值
ObCloseHandle returns STATUS_SUCCESS if the call is successful.
如果调用成功，ObCloseHandle返回STATUS_SUCCESS。
Possible error return values include the following NTSTATUS codes.
调用失败，返回的常见错误码有：

STATUS_INVALID_HANDLE Handle is not a valid handle.句柄无效。
STATUS_HANDLE_NOT_CLOSABLE The calling thread does not have permission to close the handle.执行线程没有足够的权限关闭句柄.

备注：
A kernel-mode driver calls ObCloseHandle to close a handle to any type of object that is created by the Windows kernel.
A driver must close every handle that it opens as soon as the handle is no longer required.
内核模式的驱动调用ObCloseHandle关闭一个由Windows内核创建的任意类型的对象句柄。
任何一个打开的句柄，当它不再被用到的时候，驱动程序都必须关闭它。

After ObCloseHandle closes an object's handle, the caller must treat the handle as invalid and avoid using the handle to access the object.
However, other handles might remain open on the same object.
During an ObCloseHandle call, the system decrements the handle count for the object and checks whether the object can be deleted.
The system does not delete the object until all of the object's handles are closed and all reference-counted pointers to the object are released.
当调用ObCloseHandle关闭一个对象的句柄之后，用户将此句柄视为无效句柄，并且不再用它访问对象。
当然，指向同一个对象的其它句柄，仍然有效。

The PreviousMode parameter specifies whether the handle to be closed is a kernel handle or a user handle.
To close a kernel handle, set PreviousMode to KernelMode. To close a user handle, set PreviousMode to UserMode.
PreviousMode参数指定被关闭的是一个内核句柄或者一个用户句柄。
关闭一个内核句柄，PreviousMode必须设置为KernelMode，关闭一个用户句柄，PreviousMode必须设置为UserMode。

A kernel handle is a handle that is opened by a system thread, or by a kernel-mode driver that assigns the OBJ_KERNEL_HANDLE attribute to the handle.
(For example, see the description of OBJ_KERNEL_HANDLE in ZwCreateFile.)
If a kernel-mode driver opens a handle for its private use, and this driver runs in the context of a user-mode thread, the driver must open the handle with the OBJ_KERNEL_HANDLE attribute.
This attribute ensures that the handle is inaccessible to user-mode applications.
内核句柄是由系统线程打开的，或者是由内核模式驱动程序设置OBJ_KERNEL_HANDLE属性的句柄。
（示例，请见ZwCreateFile函数的OBJ_KERNEL_HANDLE的详细描述）
如果内核模式驱动程序打开一个句柄自己使用，并且驱动运行在用户模式线程的上下文件中，驱动程序必须使用OBJ_KERNEL_HANDLE属性打开句柄。
此属性确保句柄在用户模式应用程序中无法访问。

A user handle is a handle that is opened by a user-mode application,
or by a kernel-mode driver that runs in the context of a user-mode thread but that does not open the handle with the OBJ_KERNEL_HANDLE attribute.
If a driver creates a user handle to be used by a user-mode application,
but an error occurs that requires the driver to close the handle on behalf of the application,
the driver can call ObCloseHandle to close the handle.
用户句柄是用户模式应用程序打开的句柄，或者由内核模式驱动程序运行在用户模式线程上下文件但没有使用OBJ_KERNEL_HANDLE属性来打开的句柄。
如果驱动程序创建一个用户句柄，并用于用户模式应用程序，但当驱动程序代表应用程序关闭句柄时发生错误，驱动程序可以调用ObCloseHandle来关闭句柄。


The ZwClose routine is similar to ObCloseHandle but can close only kernel handles.
The call ZwClose(hObject), which closes kernel handle hObject, has the same effect as the call ObCloseHandle(hObject, KernelMode).
For more information about closing a kernel handle, see ZwClose.
ZwClose例程与ObCloseHandle相似，但只能关闭内核句柄。
调用ZwClose(hObject)关闭内核句柄hObject, 与ObCloseHandle(hObject,KernelMode)效果一样。

To determine whether a handle is a kernel handle or a user handle, a driver that receives a handle can call the ExGetPreviousMode routine.
Or, the driver can read the RequestorMode field from the IRP structure that describes the I/O request.
The I/O manager sets the RequestorMode field to the previous processor mode of the thread that requested the I/O operation.
驱动程序拿到一个句柄，可以调用ExGetPreviousMode例程来判断它是一个内核句柄还是一个用户句柄，
或者，驱动程序可以从描述I/O请求的IPR结构读中读取RequestorMode字段来判断。
I/O管理器设置IRP结构体的RequestorMode字段值为之前发起IO请求线程的进程模式。

Callers of ObCloseHandle should not assume that this routine automatically waits for all pending I/O operations to complete before it returns.
调用ObCloseHandle的用户，不能假设程序返回之前，自动等待所有挂起的IO请求完成。

 

For more information, see Object Handles.
更多信息，请见Object Handles。http://msdn.microsoft.com/en-us/library/windows/hardware/ff557758(v=vs.85).aspx

ObCloseHandle is not declared in a header file. To use this routine in your driver, include the following function declaration in your driver code:
ObCloseHandle没有在头文件中定义 。如果想在驱动程序中使用此例程，需要在驱动程序中包含以下的函数定义。

#if (NTDDI_VERSION >= NTDDI_WIN2K)
NTKERNELAPI
NTSTATUS
ObCloseHandle(
__in HANDLE Handle,
__in KPROCESSOR_MODE PreviousMode
);
#endif

依赖操作系统： Windows 2000.
头文件： 无
库： Ntoskrnl.lib.
IRQL PASSIVE_LEVEL