Función WdfDeviceRetrieveDeviceInterfaceString (wdfdevice.h)

  • Artículo

[Se aplica a KMDF y UMDF]

El método WdfDeviceRetrieveDeviceInterfaceString recupera el nombre de vínculo simbólico que el sistema operativo asignó a una interfaz de dispositivo que el controlador registró para un dispositivo especificado.

Sintaxis

NTSTATUS WdfDeviceRetrieveDeviceInterfaceString(
  [in]           WDFDEVICE        Device,
  [in]           const GUID       *InterfaceClassGUID,
  [in, optional] PCUNICODE_STRING ReferenceString,
  [in]           WDFSTRING        String
);

Parámetros

[in] Device

Identificador de un objeto de dispositivo de marco.

[in] InterfaceClassGUID

Puntero a un GUID que identifica la clase de interfaz de dispositivo.

[in, optional] ReferenceString

Puntero a una estructura de UNICODE_STRING que describe una cadena de referencia para la interfaz del dispositivo. Este parámetro es opcional y puede ser NULL si el controlador no especificó una cadena de referencia cuando llamó a WdfDeviceCreateDeviceInterface.

[in] String

Identificador de un objeto de cadena de marco. El marco asignará la cadena Unicode del nombre de vínculo simbólico al objeto de cadena.

Valor devuelto

WdfDeviceRetrieveDeviceInterfaceString devuelve STATUS_SUCCESS 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
STATUS_INVALID_DEVICE_REQUEST

No se llamó a WdfDeviceRetrieveDeviceInterfaceString en IRQL = PASSIVE_LEVEL.
STATUS_INVALID_PARAMETER
 Se especificó un parámetro no válido.
STATUS_INVALID_DEVICE_REQUEST
 WdfControlDeviceInitAllocate inicializó el objeto de dispositivo especificado.
STATUS_OBJECT_NAME_NOT_FOUND
 No se encontró una interfaz de dispositivo que coincida con el GUID especificado y la cadena de referencia.
STATUS_INVALID_DEVICE_STATE
 El controlador llamado WdfDeviceCreateDeviceInterface , pero el sistema aún no ha asignado un nombre de vínculo simbólico a la interfaz del dispositivo.
 

WdfDeviceRetrieveDeviceInterfaceString también puede devolver otros valores NTSTATUS.

Se produce una comprobación de errores si el controlador proporciona un identificador de objeto no válido.

Comentarios

Para obtener más información sobre las interfaces de dispositivo, consulte Uso de interfaces de dispositivo.

Ejemplos

En el ejemplo de código siguiente se crea un objeto de cadena y, a continuación, se recupera el nombre de vínculo simbólico de una interfaz de dispositivo especificada.

NTSTATUS status;
WDFSTRING string;

status = WdfStringCreate(
                         NULL,
                         WDF_NO_OBJECT_ATTRIBUTES,
                         &string
                         );
if (NT_SUCCESS(status)) {
    status = WdfDeviceRetrieveDeviceInterfaceString(
                         Device,
                         &GUID_DEVINTERFACE_DDI_TEST1,
                         NULL,
                         string
                         );
    if (!NT_SUCCESS(status)) {
        return status;
    }
}

Requisitos

Requisito Value
Plataforma de destino Universal
Versión mínima de KMDF 1.0
Versión mínima de UMDF 2.0
Encabezado wdfdevice.h (incluya Wdf.h)
Library Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL PASSIVE_LEVEL
Reglas de cumplimiento de DDI DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Consulte también

UNICODE_STRING

WdfControlDeviceInitAllocate

WdfDeviceCreateDeviceInterface

WdfStringCreate