Función WdfIoTargetAllocAndQueryTargetProperty (wdfiotarget.h)

Artículo
02/27/2024

[Solo se aplica a KMDF]

El método WdfIoTargetAllocAndQueryTargetProperty asigna un búfer y recupera una propiedad de dispositivo especificada para un destino de E/S especificado.

Sintaxis

NTSTATUS WdfIoTargetAllocAndQueryTargetProperty(
  [in]           WDFIOTARGET              IoTarget,
  [in]           DEVICE_REGISTRY_PROPERTY DeviceProperty,
  [in]           POOL_TYPE                PoolType,
  [in, optional] PWDF_OBJECT_ATTRIBUTES   PropertyMemoryAttributes,
  [out]          WDFMEMORY                *PropertyMemory
);

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 desde 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] PoolType

Valor de tipo POOL_TYPE que especifica el tipo de memoria que se va a asignar.

[in, optional] PropertyMemoryAttributes

Puntero a una estructura de WDF_OBJECT_ATTRIBUTES asignada por el autor de la llamada que describe los atributos de objeto para el objeto de memoria que asignará la función. Este parámetro es opcional y puede ser WDF_NO_OBJECT_ATTRIBUTES.

[out] PropertyMemory

Puntero a una ubicación con tipo WDFMEMORY que recibe un identificador de un objeto de memoria de marco.

Valor devuelto

WdfIoTargetAllocAndQueryTargetProperty 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_INVALID_PARAMETER o 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

El método WdfIoTargetAllocAndQueryTargetProperty determina la cantidad de memoria necesaria para contener la propiedad del dispositivo solicitada. Este método asigna suficiente memoria para contener los datos y devuelve un identificador a un objeto de memoria de marco que describe la memoria asignada. Para acceder a los datos, el controlador puede llamar a WdfMemoryGetBuffer.

Para obtener más información sobre WdfIoTargetAllocAndQueryTargetProperty, 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 llama a WdfIoTargetAllocAndQueryTargetProperty para obtener la propiedad DevicePropertyFriendlyName . Después de que se devuelva WdfIoTargetAllocAndQueryTargetProperty , el controlador puede llamar a WdfMemoryGetBuffer para obtener un puntero al búfer que contiene la cadena de nombre.

WDFMEMORY  targetName;
NTSTATUS  status;

status = WdfIoTargetAllocAndQueryTargetProperty(
                                                Target,
                                                DevicePropertyFriendlyName,
                                                NonPagedPool,
                                                WDF_NO_OBJECT_ATTRIBUTES,
                                                &targetName
                                                );

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)