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 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 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 una cadena terminada en NULL que representa el nombre del dispositivo en modo kernel subyacente, si el búfer no es NULL y RetrieveDeviceName se realiza correctamente.

[in, out] pdwDeviceNameLength

Puntero a una variable que recibe el número de caracteres, incluido el carácter 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 es NULL, 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 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 pdwDeviceNameLength en el 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 en el número de caracteres necesarios para la cadena.

RetrieveDeviceName devuelve HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER) para indicar que el búfer proporcionado no era NULL 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 podría devolver otros valores HRESULT.

Comentarios

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

IWDFDevice