FltGetVolumeGuidName 함수(fltkernel.h)

아티클
08/07/2023

FltGetVolumeGuidName 은 지정된 볼륨의 볼륨 이름을 GUID(Globally Unique Identifier) 형식으로 가져옵니다.

구문

NTSTATUS FLTAPI FltGetVolumeGuidName(
  [in]               PFLT_VOLUME     Volume,
  [in/out, optional] PUNICODE_STRING VolumeGuidName,
  [out, optional]    PULONG          BufferSizeNeeded
);

매개 변수

[in] Volume

볼륨에 대한 불투명 포인터입니다. 로컬 파일 시스템 볼륨이어야 합니다. 이 매개 변수는 필수이며 NULL일 수 없습니다.

[in/out, optional] VolumeGuidName

STATUS_SUCCESS 반환될 때 볼륨의 GUID 이름을 수신하는 호출자가 할당한 UNICODE_STRING 구조체에 대한 포인터입니다. VolumeGuidName-Buffer>에 대한 풀도 호출자 할당됩니다.

VolumeGuidName이 NULL이고 BufferSizeNeeded가 NULL이 아니면 FltGetVolumeGuidName은 요청된 볼륨 GUID에 필요한 버퍼 크기를 BufferSizeNeeded 매개 변수에 저장하고 STATUS_BUFFER_TOO_SMALL 반환합니다. 설명 부분을 참조하세요.

[out, optional] BufferSizeNeeded

요청된 볼륨 GUID 이름의 크기(바이트)를 수신하는 호출자 할당 변수에 대한 포인터입니다. 이 매개 변수는 선택 사항이며 NULL일 수 있습니다. 그러나 VolumeGuidName이 NULL이면 NULL이 아니어야 FltGetVolumeGuidName이 요청된 볼륨 GUID에 필요한 버퍼 크기를 저장할 수 있습니다.

반환 값

FltGetVolumeGuidName 은 STATUS_SUCCESS 또는 다음 중 하나와 같은 적절한 NTSTATUS 값을 반환합니다.

반환 코드	설명
STATUS_BUFFER_TOO_SMALL	VolumeGuidName이 가리키는 버퍼가 NULL이거나 너무 작아서 볼륨 GUID를 보유할 수 없습니다. 호출자가 BufferSizeNeeded에 대해 NULL이 아닌 값을 제공하는 경우 FltGetVolumeGuidName은 필요한 버퍼 크기를 BufferSizeNeeded에 저장합니다. 볼륨 GUID 이름이 검색되지 않았기 때문에 오류 코드로 간주됩니다.
STATUS_INSUFFICIENT_RESOURCES	FltGetVolumeGuidName 에서 풀 할당 오류가 발생했습니다. 오류 코드입니다.
STATUS_INVALID_DEVICE_REQUEST	Volume 매개 변수는 네트워크 볼륨에 대한 핸들입니다. 오류 코드입니다.
STATUS_FLT_VOLUME_NOT_FOUND	일치하는 볼륨을 찾을 수 없습니다. 오류 코드입니다.

설명

반환된 볼륨 GUID 이름은 다음 형식으로 표현됩니다.

\?? \Volume{GUID}

여기서 GUID 는 볼륨을 식별하는 전역적으로 고유한 식별자입니다. 탑재 관리자에서 사용하는 형식과 동일한 형식은 스토리지 클래스 드라이버에서 탑재 관리자 요청 지원에 설명되어 있습니다.

BufferSizeNeeded를 알 수 없는 경우 FltGetVolumeGuidName을 두 번 호출합니다.

첫 번째 호출에서 VolumeGuidName 을 NULL 로 설정하고 BufferSizeNeeded를NULL이 아닌 값으로 설정합니다. FltGetVolumeGuidName 은 볼륨 이름 GUID에 필요한 바이트 수를 BufferSizeNeeded에 저장하고 STATUS_BUFFER_TOO_SMALL 반환합니다.
두 번째 호출에서 VolumeGuidName 을 첫 번째 호출에서 반환 된 BufferSizeNeeded 값의 크기인 구조를 가리키도록 설정합니다.

FltGetVolumeGuidName 은 탑재 전 또는 탑재 후 콜백에서 안전하게 호출할 수 없습니다. 탑재 후 콜백이 호출되더라도 탑재 처리가 I/O 관리자에 의해 완료되지 않았으므로 안전하게 호출할 수 없습니다. 이로 인해 특정 경우에 탑재 관리자와 교착 상태가 발생합니다.

Windows Vista 이상에서는 모든 탑재 처리가 완료된 후 새 볼륨에 대한 첫 번째 I/O 작업에서 콜백이 호출되므로 미니필터 드라이버는 PFLT_INSTANCE_SETUP_CALLBACK(InstanceSetupCallback 루틴)에서 FltGetVolumeGuidName을 안전하게 호출할 수 있습니다.

Windows Vista 이전의 Windows 운영 체제에서는 탑재 관리자가 잠금을 유지하는 동안 파일 I/O 작업을 실행하여 교착 상태가 발생할 수 있으므로 InstanceSetupCallback 루틴에서 FltGetVolumeGuidName을 안전하게 호출할 수 없습니다.

볼륨 GUID가 볼륨 개체 ID와 동일하지 않다는 점에 유의해야 합니다. 볼륨 GUID 또는 고유한 볼륨 이름은 파일 시스템 독립적 값입니다. 탑재 관리자가 기본 스토리지 볼륨에 할당합니다. 볼륨 개체 ID는 파일 시스템에 의해 파일 시스템 볼륨에 할당됩니다.

볼륨의 볼륨 개체 ID를 가져오려면 ZwQueryVolumeInformationFile을 호출하고 FsInformationClass 매개 변수에 FileFsObjectIdInformation을 지정합니다.

FltGetVolumeGuidName 은 Win32 GetVolumeNameForVolumeMountPoint 함수와 거의 동일합니다. GetVolumeNameForVolumeMountPoint는 Microsoft Windows SDK 설명되어 있습니다.