Función WdfIoTargetQueryTargetProperty (wdfiotarget.h)

Artículo
08/08/2023

[Solo se aplica a KMDF]

El método WdfIoTargetQueryTargetProperty recupera una propiedad de dispositivo especificada para un destino de E/S especificado.

Sintaxis

NTSTATUS WdfIoTargetQueryTargetProperty(
  [in]            WDFIOTARGET              IoTarget,
  [in]            DEVICE_REGISTRY_PROPERTY DeviceProperty,
  [in]            ULONG                    BufferLength,
  [out, optional] PVOID                    PropertyBuffer,
  [out]           PULONG                   ResultLength
);

Parámetros

[in] IoTarget

Identificador de un objeto de destino de E/S local o remoto obtenido de una llamada anterior a WdfDeviceGetIoTarget o WdfIoTargetCreate, o a partir de un método que proporciona un destino de E/S especializado.

[in] DeviceProperty

Valor de 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, optional] PropertyBuffer

Puntero a un búfer asignado por el autor de la llamada que recibe la información de la propiedad del dispositivo solicitada. Este puntero puede ser NULL si BufferLength es cero.

[out] ResultLength

Puntero a una ubicación que, a cambio, contiene el tamaño, en bytes, de la información a la que WdfIoTargetQueryTargetProperty almacena en el búfer al que Apunta PropertyBuffer . Si WdfIoTargetQueryTargetProperty devuelve STATUS_BUFFER_TOO_SMALL, esta ubicación recibe el tamaño de búfer necesario.

Valor devuelto

WdfIoTargetQueryTargetProperty devuelve STATUS_SUCCESS si la operación se realiza correctamente. De lo contrario, este método podría devolver uno de los siguientes valores:

Código devuelto	Descripción
STATUS_BUFFER_TOO_SMALL	El búfer al que apunta el parámetro PropertyBuffer era demasiado pequeño para recibir la información solicitada.
STATUS_INVALID_PARAMETER_2	El valor que especificó el parámetro DeviceProperty no era válido.
STATUS_INVALID_DEVICE_REQUEST	Los controladores del dispositivo aún no han notificado las propiedades del dispositivo.

Este método también 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 que los controladores reciban datos de propiedad del dispositivo, normalmente llaman al método WdfIoTargetQueryTargetProperty 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 WdfIoTargetQueryTargetProperty de nuevo. Por lo tanto, los controladores deben llamar a WdfIoTargetQueryTargetProperty dentro de un bucle que se ejecuta hasta que el estado devuelto no sea STATUS_BUFFER_TOO_SMALL.

En lugar de llamar a WdfIoTargetQueryTargetProperty, el controlador puede llamar a WdfIoTargetAllocAndQueryTargetProperty, que asigna un búfer y coloca la información de propiedad en el búfer.

Para obtener más información sobre WdfIoTargetQueryTargetProperty, vea Obtener información sobre un destino de E/S general.

Para obtener más información sobre los destinos de E/S, consulte Uso de destinos de E/S.

Ejemplos

En el ejemplo de código siguiente se obtiene la propiedad DevicePropertyUINumber de un dispositivo. El ejemplo llama a WdfIoTargetQueryTargetProperty en lugar de WdfIoTargetAllocAndQueryTargetProperty porque se conoce la longitud de un número de interfaz de usuario.

ULONG targetUINumber, resultLength;
NTSTATUS status;

status = WdfIoTargetQueryTargetProperty(
                                        target,
                                        DevicePropertyUINumber,
                                        sizeof(targetNumber),
                                        &targetUINumber,
                                        &resultLength
                                        );

Requisitos

Requisito	Value
Plataforma de destino	Universal
Versión mínima de KMDF	1.0
Encabezado	wdfiotarget.h (incluya Wdf.h)
Library	Wdf01000.sys (consulte Control de versiones de la biblioteca de marcos).
IRQL	PASSIVE_LEVEL
Reglas de cumplimiento de DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)