IoGetDeviceObjectPointer 함수(wdm.h)

아티클
08/08/2023

IoGetDeviceObjectPointer 루틴은 명명된 디바이스 개체 스택의 맨 위 개체에 대한 포인터를 반환하고 개체에 대한 요청된 액세스 권한을 부여할 수 있는 경우 해당 파일 개체에 대한 포인터를 반환합니다.

구문

NTSTATUS IoGetDeviceObjectPointer(
  [in]  PUNICODE_STRING ObjectName,
  [in]  ACCESS_MASK     DesiredAccess,
  [out] PFILE_OBJECT    *FileObject,
  [out] PDEVICE_OBJECT  *DeviceObject
);

매개 변수

[in] ObjectName

디바이스 개체의 이름인 유니코드 문자열이 포함된 버퍼에 대한 포인터입니다.

[in] DesiredAccess

원하는 액세스를 나타내는 ACCESS_MASK 값을 지정합니다. 일반적으로 DesiredAccess 는 FILE_READ_DATA. FILE_WRITE_DATA 또는 FILE_ALL_ACCESS 액세스 권한이 자주 지정됩니다.

[out] FileObject

호출에 성공한 경우 사용자 모드 코드에 해당하는 디바이스 개체를 나타내는 파일 개체에 대한 포인터입니다.

[out] DeviceObject

호출에 성공한 경우 명명된 논리적, 가상 또는 물리적 디바이스를 나타내는 디바이스 개체에 대한 포인터입니다.

반환 값

IoGetDeviceObjectPointer 는 성공하면 STATUS_SUCCESS 반환합니다. 가능한 오류 반환 값에는 다음 상태 코드가 포함됩니다.

STATUS_OBJECT_TYPE_MISMATCH

STATUS_INVALID_PARAMETER

STATUS_PRIVILEGE_NOT_HELD

STATUS_INSUFFICIENT_RESOURCES

STATUS_OBJECT_NAME_INVALID

설명

IoGetDeviceObjectPointer 는 호출자와 다음 하위 수준 드라이버 간에 "연결"을 설정합니다. 성공한 호출자는 반환된 디바이스 개체 포인터를 사용하여 자체 디바이스 개체를 초기화할 수 있습니다. IoAttachDeviceToDeviceStack, IoCallDriver 및 낮은 드라이버에 대한 IRP를 만드는 모든 루틴에 대한 인수로 사용할 수도 있습니다. 반환된 포인터는 IoCallDriver에 대한 필수 인수입니다.

이 루틴은 해당 파일 개체에 대한 포인터도 반환합니다. 언로드할 때 드라이버는 디바이스 개체를 간접적으로 역참조하는 수단으로 파일 개체를 역참조할 수 있습니다. 이를 위해 드라이버는 Unload 루틴에서 ObDereferenceObject 를 호출하여 IoGetDeviceObjectPointer에서 반환된 파일 개체 포인터를 전달합니다. 드라이버의 언로드 루틴에서 디바이스 개체를 역참조하지 않으면 다음 하위 드라이버가 언로드되지 않습니다. 그러나 언로드 프로세스 전에 파일 개체를 닫는 드라이버는 파일 개체를 역참조하기 전에 디바이스 개체에 대한 추가 참조를 가져와야 합니다. 그렇지 않으면 파일 개체를 역참조하면 디바이스 개체가 조기에 삭제됩니다.

파일 시스템 드라이버 스택에서 최상위 드라이버에 대한 포인터를 얻으려면 드라이버가 파일 시스템이 탑재되었는지 확인해야 합니다. 그렇지 않은 경우 이 루틴은 스토리지 디바이스 스택을 트래버스합니다. 파일 시스템이 스토리지 디바이스에 탑재되도록 하려면 드라이버가 DesiredAccess 매개 변수에 FILE_READ_DATA 또는 FILE_WRITE_ATTRIBUTES 같은 적절한 액세스 마스크를 지정해야 합니다. FILE_READ_ATTRIBUTES 지정해도 파일 시스템이 탑재되지는 않습니다.

상위 수준 드라이버가 이 루틴을 성공적으로 호출하여 다른 드라이버에 연결한 후 상위 수준 드라이버는 해당 디바이스 개체의 StackSize 필드를 다음 하위 수준 드라이버의 디바이스 개체에 1을 더한 값으로 설정해야 합니다.

IoGetDeviceObjectPointer의 호출자는 IRQL = PASSIVE_LEVEL 실행 중이어야 합니다.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows 2000부터 사용할 수 있습니다.
대상 플랫폼	유니버설
헤더	wdm.h(Wdm.h, Ntddk.h, Ntifs.h 포함)
라이브러리	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI 규정 준수 규칙	HwStorPortProhibitedDDIs(storport), IrqlIoPassive5(wdm), PowerIrpDDis(wdm)