Método IWDFFile::RetrieveFileName (wudfddi.h)

  • Artículo

[Advertencia: UMDF 2 es la versión más reciente de UMDF y sustituye a UMDF 1. Todos los controladores UMDF nuevos deben escribirse con UMDF 2. No se agregan nuevas características a UMDF 1 y hay compatibilidad limitada con UMDF 1 en versiones más recientes de Windows 10. Los controladores universales de Windows deben usar UMDF 2. Para obtener más información, consulta Introducción con UMDF.

El método RetrieveFileName recupera el nombre completo del archivo asociado al dispositivo en modo kernel subyacente.

Sintaxis

HRESULT RetrieveFileName(
  [out]     PWSTR pFileName,
  [in, out] DWORD *pdwFileNameLengthInChars
);

Parámetros

[out] pFileName

Puntero a un búfer proporcionado por el autor de la llamada que recibe una cadena terminada en NULL que representa el nombre completo del archivo asociado al dispositivo en modo kernel subyacente, si el puntero proporcionado no es NULL y RetrieveFileName se realiza correctamente.

[in, out] pdwFileNameLengthInChars

Puntero a una variable proporcionada por el autor de la llamada que recibe el tamaño, en caracteres, del nombre de archivo completo al que apunta pFileName . Si el búfer en pFileName no es NULL, el marco devuelve el tamaño, en caracteres, de la cadena de nombre de archivo.

En la entrada, el controlador establece esta variable en el tamaño, en caracteres, del búfer al que apunta pFileName . Si el controlador proporciona NULL para pFileName y cero para la variable a la que apunta pdwFileNameLengthInChars , el marco establece la variable en el tamaño, en caracteres, que requiere la cadena de nombre de archivo.

Valor devuelto

RetrieveFileName devuelve S_OK para los escenarios siguientes:

  • El búfer al que apunta el parámetro pFileName era no NULL y lo suficientemente grande como para contener la cadena de nombre, incluido el carácter NULL , y el marco copió correctamente la cadena en el búfer proporcionado y estableció la variable a la que apunta el parámetro pdwFileNameLengthInChars al número de caracteres de la cadena.
  • El búfer en pFileName era NULL, el controlador preestablecido la variable en pdwFileNameLengthInChars en 0 y el marco establece la variable en pdwFileNameLengthInChars en el número de caracteres necesarios para la cadena.
RetrieveFileName devuelve HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER) para indicar que el búfer proporcionado no es NULL y no contenía suficiente espacio para contener el nombre de archivo. El marco establece la variable en pdwFileNameLengthInChars en el número de caracteres necesarios para la cadena.

RetrieveFileName también podría devolver otros valores HRESULT.

Comentarios

El controlador puede llamar a RetrieveFileName desde su función de devolución de llamada IQueueCallbackCreate::OnCreateFile . Para obtener más información, consulte Uso de interfaces de dispositivo en controladores UMDF.

Ejemplos

En el ejemplo de código siguiente se muestra cómo recuperar el nombre de un archivo.

    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);
    }

Requisitos

Requisito Value
Finalización del soporte técnico No disponible en UMDF 2.0 y versiones posteriores.
Plataforma de destino Escritorio
Versión mínima de UMDF 1.5
Encabezado wudfddi.h (incluya Wudfddi.h)
Archivo DLL WUDFx.dll

Consulte también

IWDFFile