IWDFDevice::RetrieveDeviceName 메서드(wudfddi.h)
[경고: UMDF 2는 UMDF의 최신 버전이며 UMDF 1을 대체합니다. 모든 새 UMDF 드라이버는 UMDF 2를 사용하여 작성해야 합니다. UMDF 1에 새 기능이 추가되지 않으며 최신 버전의 Windows 10 UMDF 1에 대한 지원이 제한되어 있습니다. 유니버설 Windows 드라이버는 UMDF 2를 사용해야 합니다. 자세한 내용은 UMDF를 사용하여 시작 참조하세요.]
RetrieveDeviceName 메서드는 기본 커널 모드 디바이스의 이름을 검색합니다.
구문
HRESULT RetrieveDeviceName(
[out] PWSTR pDeviceName,
[in, out] DWORD *pdwDeviceNameLength
);
매개 변수
[out] pDeviceName
버퍼가 NULL이 아니고 RetrieveDeviceName이 성공한 경우 기본 커널 모드 디바이스의 이름을 나타내는 NULL로 끝나는 문자열을 수신하는 버퍼에 대한 포인터입니다.
[in, out] pdwDeviceNameLength
디바이스 이름에 NULL 문자를 포함하여 문자 수를 수신하는 변수에 대한 포인터입니다.
pDeviceName의 버퍼가 NULL이면 드라이버에서 제공하는 값은 0입니다. 그런 다음 프레임워크는 디바이스 이름 문자열에 필요한 크기를 문자로 반환합니다.
pDeviceName의 버퍼가 NULL이 아닌 경우 프레임워크는 디바이스 이름 문자열의 크기를 문자 단위로 반환합니다.
반환 값
RetrieveDeviceName 은 다음 시나리오에 대한 S_OK 반환합니다.
- pDeviceName 매개 변수가 가리키는 버퍼는 NULL이 아니고 NULL 문자를 포함하여 이름 문자열을 보유할 수 있을 만큼 크고 프레임워크는 문자열을 제공된 버퍼에 성공적으로 복사하고 pdwDeviceNameLength가 가리키는 변수를 문자열의 문자 수로 설정합니다.
- pDeviceName의 버퍼는 NULL이고, 드라이버는 pdwDeviceNameLength에서 변수를 0으로 미리 설정하고, 프레임워크는 pdwDeviceNameLength의 변수를 문자열에 필요한 문자 수로 설정합니다.
RetrieveDeviceName 은 HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER)을 반환하여 제공된 버퍼가 NULL 이 아니고 디바이스 이름을 저장할 충분한 공간이 없음을 나타냅니다. 프레임워크는 pdwDeviceNameLength 의 변수를 문자열에 필요한 문자 수로 설정합니다.
RetrieveDeviceName 은 다른 HRESULT 값도 반환할 수 있습니다.
설명
디바이스 이름은 PDO(물리적 디바이스 개체) 이름이 아닙니다. 대신 디바이스 이름은 리플렉터의 이름입니다. 드라이버는 이 디바이스 개체에 대한 모든 I/O를 대상으로 해야 합니다.
예제
다음 코드 예제에서는 기본 커널 모드 디바이스의 이름을 검색하는 방법을 보여줍니다.
PWSTR deviceName = NULL;
DWORD deviceNameCch = 0;
HRESULT hr;
//
// Get the length of the device name to allocate a buffer
//
hr = m_FxDevice->RetrieveDeviceName(NULL, &deviceNameCch);
//
// Allocate the buffer
//
deviceName = new WCHAR[deviceNameCch];
if (deviceName == NULL) {
hr = E_OUTOFMEMORY;
goto Exit1;
}
//
// Get the device name
//
hr = m_FxDevice->RetrieveDeviceName(deviceName,
&deviceNameCch);
// Open the device and get the handle
m_Handle = CreateFile(deviceName,
(GENERIC_READ | GENERIC_WRITE),
0,
NULL,
OPEN_EXISTING,
FILE_FLAG_OVERLAPPED,
NULL);
요구 사항
| 요구 사항 | 값 |
|---|---|
| 지원 종료 | UMDF 2.0 이상에서는 사용할 수 없습니다. |
| 대상 플랫폼 | 데스크톱 |
| 최소 UMDF 버전 | 1.5 |
| 머리글 | wudfddi.h(Wudfddi.h 포함) |
| DLL | WUDFx.dll |