Función WdfDeviceQueryProperty (wdfdevice.h)

[Se aplica a KMDF y UMDF]

El método WdfDeviceQueryProperty recupera una propiedad de dispositivo especificada.

Sintaxis

NTSTATUS WdfDeviceQueryProperty(
  [in]  WDFDEVICE                Device,
  [in]  DEVICE_REGISTRY_PROPERTY DeviceProperty,
  [in]  ULONG                    BufferLength,
  [out] PVOID                    PropertyBuffer,
  [out] PULONG                   ResultLength
);

Parámetros

[in] Device

Identificador de un objeto de dispositivo de marco.

[in] DeviceProperty

Enumerador con tipo DEVICE_REGISTRY_PROPERTY que identifica la propiedad del dispositivo que se va a recuperar.

[in] BufferLength

Tamaño, en bytes, del búfer al que apunta PropertyBuffer.

[out] PropertyBuffer

Puntero proporcionado por el autor de la llamada a un búfer asignado por el autor de la llamada que recibe la información solicitada. El puntero puede ser NULL si el parámetro BufferLength es cero.

[out] ResultLength

Una ubicación proporcionada por el autor de la llamada que, a cambio, contiene el tamaño, en bytes, de la información que el método almacenado en PropertyBuffer. Si el valor devuelto de la función es STATUS_BUFFER_TOO_SMALL, esta ubicación recibe el tamaño de búfer necesario.

Valor devuelto

Si la operación se realiza correctamente, WdfDeviceQueryProperty devuelve STATUS_SUCCESS. Entre los valores devueltos adicionales se incluyen:

Código devuelto	Descripción
STATUS_BUFFER_TOO_SMALL	El búfer proporcionado es demasiado pequeño para recibir la información.
STATUS_INVALID_PARAMETER_2	El valor deviceProperty especificado no es válido
STATUS_INVALID_DEVICE_REQUEST	Los controladores del dispositivo aún no han notificado las propiedades del dispositivo.

 

El método podría devolver otros valores NTSTATUS.

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

Comentarios

Antes de recibir datos de propiedad del dispositivo, los controladores suelen llamar al método WdfDeviceQueryProperty solo para obtener el tamaño de búfer necesario. Para algunas propiedades, el tamaño de los datos puede cambiar entre cuando se devuelve el tamaño necesario y cuando el controlador llama a WdfDeviceQueryProperty de nuevo. Por lo tanto, los controladores deben llamar a WdfDeviceQueryProperty dentro de un bucle que se ejecuta hasta que el estado devuelto no sea STATUS_BUFFER_TOO_SMALL.

Es mejor usar WdfDeviceQueryProperty solo si el tamaño de búfer necesario se conoce y no cambia, porque en ese caso el controlador tiene que llamar a WdfDeviceQueryProperty solo una vez. Si el tamaño de búfer necesario es desconocido o varía, el controlador debe llamar a WdfDeviceAllocAndQueryProperty.

Como alternativa, puede usar WdfDeviceQueryPropertyEx para acceder a las propiedades del dispositivo que se exponen a través del modelo de propiedades unificado.

Ejemplos

En el ejemplo de código siguiente se obtiene la propiedad DevicePropertyBusTypeGuid de un dispositivo. El ejemplo llama a WdfDeviceQueryProperty en lugar de WdfDeviceAllocAndQueryProperty porque se conoce la longitud de un GUID.

GUID  busTypeGuid;
ULONG  resultLength = 0;
NTSTATUS  status;

status = WdfDeviceQueryProperty( 
                                device,
                                DevicePropertyBusTypeGuid,
                                sizeof(GUID),
                                (PVOID)&busTypeGuid,
                                &resultLength
                                );

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

WdfDeviceAllocAndQueryProperty

WdfFdoInitQueryProperty