ObQueryNameString routine

ObQueryNameString routine

ObQueryNameString 例程返回一个调用者指定的对象的名字（如果有）。

Syntax

 

NTSTATUS ObQueryNameString(
  _In_      PVOID                    Object,
  _Out_opt_ POBJECT_NAME_INFORMATION ObjectNameInfo,
  _In_      ULONG                    Length,
  _Out_     PULONG                   ReturnLength
);

 

Parameters

Object [in]

指向请求获取名字的对象的指针，不能为NULL.

ObjectNameInfo [out, optional]

指向调用者申请的缓冲区，接收对象名信息。此缓冲区的原型为:

typedef struct _OBJECT_NAME_INFORMATION {

  UNICODE_STRING Name;

} OBJECT_NAME_INFORMATION, *POBJECT_NAME_INFORMATION;

 

This parameter is optional and can be NULL. 此参数是可选参数可以为NULL如果此参数为NULL，那么下个参数Length 必须为0。

Length [in]

以字节为单位，ObjectNameInfo参数的缓冲区大小。此参数为可选的参数，可以设置为0。如果设置为0，ReturnLength接收存放对象名称所需要的长度(以字节为单位)。一个合理的缓冲区大小为1024字节，这个长度的缓冲区可容纳大部分的对象名。如果Length设置为0，ObjectNameInfo可为NULL

ReturnLength [out]

此指针指向调用者提供的一个变量，它用于存放调用后返回的对象名的长度。对象名（当存在时）包含一个NULL结束符，并且在名字中以"\"分隔所有的路径。如果函数返回STATUS_INFO_LENGTH_MISMATCH，函数设置这个变量的值为容纳名字需要的长度。

Return value

ObQueryNameString 返回STATUS_SUCCESS ，或者是一个下表中的NTSTATUS 值:

Return code	Description
STATUS_INFO_LENGTH_MISMATCH	ObjectNameInfo 的缓冲区长度不够. ReturnLength 指向需要的大小。在这种情况下没有返回任何对象名信息。这是一个错误信息。注意如果 Length 被设置为0, 例程返回STATUS_INFO_LENGTH_MISMATCH

 

Remarks

若给定的对象有名字且成功获得到了名字，返回的字符串是对象名字，且尽可能地返回对象的全路径名。这个情况下，ObQueryNameString 把Name.Buffer设置成指定对象的名称的地址。Name.MaximumLength 为包含NULL 结束符的长度。 Name.Length 为仅对象名的长度。

若对象无名或是未能成功获取对象名 ObQueryNameString 设置 Name.Buffer 为 NULL 并设置Name.Length 和 Name.MaximumLength 为0。

ObjectNameInfo 从 paged 或nonpaged pool中分配都可以。

Requirements

Target platform	Universal
Version	Available in Windows 2000 and later operating systems.
Header	Ntifs.h (include FltKernel.h or Ntifs.h)
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	< DISPATCH_LEVEL

See also

UNICODE_STRING