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_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER)를 반환하여 제공된 버퍼가 NULL 이 아니고 파일 이름을 저장할 공간이 충분하지 않음을 나타냅니다. 프레임워크는 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

추가 정보

IWDFFile