Método IWDFDevice::RetrieveDeviceName (wudfddi.h)

[Advertencia: UMDF 2 es la versión más reciente de UMDF y sustituye a UMDF 1. Todos los nuevos controladores UMDF deben escribirse mediante 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 a UMDF.]

El método RetrieveDeviceName recupera el nombre de un dispositivo en modo kernel subyacente.

Sintaxis

HRESULT RetrieveDeviceName(
  [out]     PWSTR pDeviceName,
  [in, out] DWORD *pdwDeviceNameLength
);

Parámetros

[out] pDeviceName

Puntero a un búfer que recibe un nullcadena terminada que representa el nombre del dispositivo en modo kernel subyacente, si el búfer no esnull y retrieveDeviceName se realiza correctamente.

[in, out] pdwDeviceNameLength

Puntero a una variable que recibe el número de caracteres, incluido el carácter de NULL, en el nombre del dispositivo.

Si el búfer de pDeviceName es NULL, el valor que proporciona el controlador es cero. A continuación, el marco devuelve el tamaño, en caracteres, que es necesario para la cadena de nombre del dispositivo.

Si el búfer de pDeviceName no esNULL, el marco devuelve el tamaño, en caracteres, de la cadena de nombre del dispositivo.

Valor devuelto

RetrieveDeviceName devuelve S_OK para los escenarios siguientes:

• El búfer al que apunta el parámetro pDeviceName no eraNULL 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 pdwDeviceNameLength al número de caracteres de la cadena.
• El búfer de pDeviceName era NULL, el controlador preestablecido la variable en pdwDeviceNameLength en 0 y el marco establece la variable en pdwDeviceNameLength al número de caracteres necesarios para la cadena.

RetrieveDeviceName devuelve HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER) para indicar que el búfer proporcionado no eranull y no contenía suficiente espacio para contener el nombre del dispositivo. El marco establece la variable en pdwDeviceNameLength en el número de caracteres necesarios para la cadena.

RetrieveDeviceName también puede devolver otros valores HRESULT.

Observaciones

El nombre del dispositivo no es el nombre del objeto de dispositivo físico (PDO). En su lugar, el nombre del dispositivo es el nombre del reflector. El controlador debe tener como destino todas las E/S a este objeto de dispositivo.

Ejemplos

En el ejemplo de código siguiente se muestra cómo recuperar el nombre de un dispositivo en modo kernel subyacente.

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

Requisitos

Requisito	Valor
fin del soporte técnico	No disponible en UMDF 2.0 y versiones posteriores.
de la plataforma de destino de	Escritorio
versión mínima de UMDF	1.5
encabezado de	wudfddi.h (incluya Wudfddi.h)
DLL de	WUDFx.dll

Consulte también

IWDFDevice