Método IWDFFile2::RetrieveCountedFileName (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 RetrieveCountedFileName recupera el nombre de archivo con recuento completo de un archivo asociado a un dispositivo.

Sintaxis

HRESULT RetrieveCountedFileName(
  [out]     WCHAR *pCountedFileName,
  [in, out] DWORD *pdwCountedFileNameLengthInChars
);

Parámetros

[out] pCountedFileName

Puntero a un búfer asignado por el autor de la llamada. Este búfer recibe una cadena de caracteres terminada en NULL que representa el nombre completo del archivo asociado al dispositivo. Si el puntero es NULL, RetrieveCountedFileName solo recupera la longitud de la cadena.

[in, out] pdwCountedFileNameLengthInChars

Puntero a una variable asignada por el autor de la llamada. En la entrada, el controlador establece la variable en la longitud, en caracteres, del búfer al que apunta pdwCountedFileNameLengthInChars . En la salida, el marco establece la variable en la longitud, en caracteres, de la cadena de caracteres (incluido el carácter NULL de terminación) que colocó en el búfer. Si no existe un nombre de archivo contado, el marco establece la variable en cero.

Valor devuelto

RetrieveCountedFileName devuelve S_OK si la operación se realiza correctamente. De lo contrario, el método podría devolver uno de los siguientes valores:

Código devuelto Descripción
E_POINTER El puntero pdwCountedFileNameLength es NULL.
HRESULT_FROM_WIN32 (ERROR_INVALID_PARAMETER) El nombre de archivo contado no es válido.
E_NOT_SUFFICIENT_BUFFER El búfer al que apunta pCountedFileName es demasiado pequeño.

Este método podría devolver uno de los otros valores de Winerror.h.

Comentarios

Un nombre de archivo con recuento es una cadena que puede incluir caracteres NULL incrustados ('\0') además de un valor NULL de terminación. Para obtener una cadena de nombre sin caracteres NULL incrustados, los controladores pueden llamar a IWDFFile::RetrieveFileName.

Normalmente, un controlador llama a RetrieveCountedFileName dos veces mediante los pasos siguientes:

  1. El controlador llama a RetrieveCountedFileName con el parámetro pCountedFileName establecido en NULL para obtener la longitud del búfer necesaria.
  2. El controlador asigna un búfer del tamaño necesario.
  3. El controlador llama a RetrieveCountedFileName de nuevo para obtener la cadena de nombre de archivo.

Ejemplos

En el ejemplo de código siguiente se obtiene la interfaz IWDFFile2 de la interfaz IWDFFile que recibe la función de devolución de llamada IQueueCallbackCreate::OnCreateFile de un controlador. En el ejemplo se llama a RetrieveCountedFileName dos veces; una vez para obtener la longitud del nombre de archivo y una vez para recuperar la cadena de nombre de archivo.

VOID
STDMETHODCALLTYPE
CMyQueue::OnCreateFile(
    __in IWDFIoQueue *pWdfQueue,
    __in IWDFIoRequest *pWdfRequest,
    __in IWDFFile*  pWdfFileObject
    )
 ...
    IWDFFile2*  pWdfFileObject2 = NULL;
    WCHAR*  countedFileName = NULL;
    DWORD  countedFileNameCch = 0;
    HRESULT  hr = S_OK;
 
    //
    // Obtain IWDFFile2 interface from IWDFFile.
    //
    hr = pWdfFileObject->QueryInterface(IID_PPV_ARGS(&pWdfFileObject2));
    if (!SUCCEEDED(hr))
    {
        goto Done;
    }
    //
    // Get length of counted filename.
    //
    hr = pWdfFileObject2->RetrieveCountedFileName(NULL,
                                                  &countedFileNameCch);
    if (!SUCCEEDED(hr))
    {
        goto Done;
    }
    if (countedFileNameCch != 0)
    {
        //
        // Allocate a buffer.
        //
        countedFileName = new WCHAR[countedFileNameCch];
        if (countedFileName == NULL)
        {
            hr = E_OUTOFMEMORY;
            goto Done;
        }
        //
        // Get counted file name.
        //
        hr = pWdfFileObject2->RetrieveCountedFileName(countedFileName, 
                                                      &countedFileNameCch);
        if (!SUCCEEDED(hr))
        {
            goto Done;
        }
    }
    ...

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,9
Encabezado wudfddi.h (incluya Wudfddi.h)
Archivo DLL WUDFx.dll

Consulte también