Función WdfDeviceRetrieveDeviceInterfaceString (wdfdevice.h)

[Se aplica a KMDF y UMDF]

El método WdfDeviceRetrieveDeviceInterfaceString recupera el nombre simbólico del vínculo 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 UNICODE_STRING que describe una cadena de referencia para la interfaz del dispositivo. Este parámetro es opcional y se puede NULL si el controlador no especificó una cadena de referencia cuando llamó a WdfDeviceCreateDeviceInterface.

[in] String

Identificador de un objeto de cadena de marco de . El marco asignará la cadena Unicode del nombre del 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	El objeto de dispositivo especificado se inicializó mediante WdfControlDeviceInitAllocate.
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 podría devolver otros valores de NTSTATUS.

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

Observaciones

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

Ejemplos

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

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	Valor
de la plataforma de destino de	Universal
versión mínima de KMDF	1.0
versión mínima de UMDF	2.0
encabezado de	wdfdevice.h (incluya Wdf.h)
biblioteca de	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