IWDFFile::RetrieveFileName 메서드(wudfddi.h)
[경고: UMDF 2는 UMDF의 최신 버전이며 UMDF 1을 대체합니다. 모든 새 UMDF 드라이버는 UMDF 2를 사용하여 작성해야 합니다. UMDF 1에 새 기능이 추가되지 않으며 최신 버전의 Windows 10 UMDF 1에 대한 지원이 제한됩니다. 유니버설 Windows 드라이버는 UMDF 2를 사용해야 합니다. 자세한 내용은 UMDF를 사용하여 시작 참조하세요.]
RetrieveFileName 메서드는 기본 커널 모드 디바이스와 연결된 파일의 전체 이름을 검색합니다.
구문
HRESULT RetrieveFileName(
[out] PWSTR pFileName,
[in, out] DWORD *pdwFileNameLengthInChars
);
매개 변수
[out] pFileName
제공된 포인터가 NULL이 아니고 RetrieveFileName이 성공한 경우 기본 커널 모드 디바이스와 연결된 파일의 전체 이름을 나타내는 NULL로 끝나는 문자열을 수신하는 호출자 제공 버퍼에 대한 포인터입니다.
[in, out] pdwFileNameLengthInChars
pFileName이 가리키는 전체 파일 이름의 크기(문자)를 수신하는 호출자 제공 변수에 대한 포인터입니다. pFileName의 버퍼가 NULL이 아닌 경우 프레임워크는 파일 이름 문자열의 크기를 문자 단위로 반환합니다.
입력 시 드라이버는 이 변수를 pFileName 이 가리키는 버퍼의 크기(문자)로 설정합니다. 드라이버가 pFileName에 대해 NULL을 제공하고 pdwFileNameLengthInChars가 가리키는 변수에 대해 0을 제공하는 경우 프레임워크는 변수를 파일 이름 문자열에 필요한 크기(문자)로 설정합니다.
반환 값
RetrieveFileName 은 다음 시나리오에 대한 S_OK 반환합니다.
- pFileName 매개 변수가 가리키는 버퍼는 NULL이 아니고 NULL 문자를 포함하여 이름 문자열을 보유할 수 있을 만큼 큽니다. 프레임워크는 문자열을 제공된 버퍼에 성공적으로 복사하고 pdwFileNameLengthInChars 매개 변수가 가리키는 변수를 문자열의 문자 수로 설정합니다.
- pFileName의 버퍼는 NULL이고, 드라이버는 pdwFileNameLengthInChars에서 변수를 0으로 미리 설정하고, 프레임워크는 pdwFileNameLengthInChars의 변수를 문자열에 필요한 문자 수로 설정합니다.
RetrieveFileName 은 다른 HRESULT 값을 반환할 수도 있습니다.
설명
드라이버가 IQueueCallbackCreate::OnCreateFile 콜백 함수에서 RetrieveFileName을 호출할 수 있습니다. 자세한 내용은 UMDF 드라이버에서 디바이스 인터페이스 사용을 참조하세요.
예제
다음 코드 예제에서는 파일의 이름을 검색하는 방법을 보여 있습니다.
ULONG fileNameCch = 0;
PWSTR fileName = NULL;
ULONG index;
CComObject<CUmdfHidFile> *file = NULL;
HRESULT hr;
// Get the length of the file name to allocate a buffer.
hr = WdfFile->RetrieveFileName(NULL, &fileNameCch);
//
// Allocate the buffer.
//
if (SUCCEEDED(hr))
{
fileName = new WCHAR[fileNameCch];
if (fileName == NULL)
{
hr = E_OUTOFMEMORY;
}
}
//
// Get the file name.
//
if (SUCCEEDED(hr))
{
hr = WdfFile->RetrieveFileName(fileName, &fileNameCch);
}
요구 사항
| 요구 사항 | 값 |
|---|---|
| 지원 종료 | UMDF 2.0 이상에서는 사용할 수 없습니다. |
| 대상 플랫폼 | 데스크톱 |
| 최소 UMDF 버전 | 1.5 |
| 머리글 | wudfddi.h(Wudfddi.h 포함) |
| DLL | WUDFx.dll |