Función WdfChildListAddOrUpdateChildDescriptionAsPresent (wdfchildlist.h)

Artículo
08/08/2023

[Solo se aplica a KMDF]

El método WdfChildListAddOrUpdateChildDescriptionAsPresent agrega una nueva descripción secundaria a una lista de elementos secundarios o actualiza una descripción secundaria existente.

Sintaxis

NTSTATUS WdfChildListAddOrUpdateChildDescriptionAsPresent(
  [in]           WDFCHILDLIST                                 ChildList,
  [in]           PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER IdentificationDescription,
  [in, optional] PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER        AddressDescription
);

Parámetros

[in] ChildList

Identificador de un objeto de lista secundario de marco.

[in] IdentificationDescription

Puntero a una estructura de WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER que identifica una descripción de identificación secundaria.

[in, optional] AddressDescription

Puntero a una estructura de WDF_CHILD_ADDRESS_DESCRIPTION_HEADER que identifica una descripción de dirección secundaria. Si no se necesita una descripción de dirección, este parámetro puede ser NULL.

Valor devuelto

WdfChildListAddOrUpdateChildDescriptionAsPresent devuelve STATUS_SUCCESS, u otro valor de estado con tipo NTSTATUS para el que NT_SUCCESS(status) es igual a TRUE, 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	Un parámetro de entrada no era válido.
STATUS_INVALID_DEVICE_REQUEST	El tamaño de la descripción de identificación o la descripción de la dirección no era correcto.
STATUS_OBJECT_NAME_EXISTS	Ya existe un elemento secundario con la descripción de identificación proporcionada. En este caso, el marco copia la descripción de dirección proporcionada en el elemento secundario existente.
STATUS_INSUFFICIENT_RESOURCES	Se podría asignar una descripción secundaria.

Este método también puede devolver otros valores de NTSTATUS.

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

Observaciones

El método WdfChildListAddOrUpdateChildDescriptionAsPresent busca en la lista secundaria especificada un elemento secundario que coincida con la descripción de identificación proporcionada. Si se encuentra una coincidencia, el marco actualiza la descripción de la dirección del elemento secundario, si se proporciona y devuelve STATUS_OBJECT_NAME_EXISTS. Si no se encuentra ninguna coincidencia, el marco crea un nuevo elemento secundario mediante las descripciones de direcciones y identificación proporcionadas.

Un controlador puede llamar a WdfChildListAddOrUpdateChildDescriptionAsPresent para agregar o actualizar una sola descripción secundaria. El marco actualiza inmediatamente la lista secundaria e informa al administrador de Plug and Play (PnP) de que se han realizado cambios.

Como alternativa, el controlador puede hacer lo siguiente:

Llame a WdfChildListBeginScan para preparar la lista secundaria para actualizarla.
Llame a WdfChildListAddOrUpdateChildDescriptionAsPresent varias veces para agregar o actualizar las descripciones secundarias de todos los elementos secundarios del dispositivo primario.
Llame a WdfChildListEndScan para procesar los cambios en la lista secundaria.

Si el controlador usa este procedimiento alternativo, el marco espera hasta que el controlador llame a WdfChildListEndScan antes de actualizar la lista secundaria e informar al administrador de PnP de que se han realizado cambios. Cuando el controlador llama a WdfChildListBeginScan, el marco marca todos los dispositivos notificados anteriormente como ya no están presentes. Por lo tanto, el controlador debe llamar a WdfChildListAddOrUpdateChildDescriptionAsPresent para todos los elementos secundarios, no solo para los elementos secundarios recién detectados.

En algún momento después de que un controlador llame a WdfChildAddOrUpdateChildDescriptionAsPresent, el marco llama al evtChildListCreateDevice función de devolución de llamada para que el controlador pueda crear un objeto de dispositivo llamando a WdfDeviceCreate.

Para obtener más información sobre las listas secundarias, vea enumeración dinámica.

Ejemplos

El ejemplo de código siguiente se basa en el código que contiene el ejemplo de kmdf_fx2. En el ejemplo se agregan descripciones secundarias a la lista secundaria predeterminada de un dispositivo. Recupera la configuración del modificador que el controlador almacenó previamente en el espacio de contexto de un objeto de dispositivo y, a continuación, llama a WdfChildListAddOrUpdateChildDescriptionAsPresent para cada modificador establecido.

PDEVICE_CONTEXT  pDeviceContext;
WDFCHILDLIST  list;
UCHAR  i;
NTSTATUS  status;

pDeviceContext = GetDeviceContext(Device);
list = WdfFdoGetDefaultChildList(Device);

WdfChildListBeginScan(list);
 
for (i = 0; i < RTL_BITS_OF(UCHAR); i++) {
    if (pDeviceContext->CurrentSwitchState & (1<<i)) {
        PDO_IDENTIFICATION_DESCRIPTION description;
        WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER_INIT(
                                                 &description.Header,
                                                 sizeof(description)
                                                 );
        description.SwitchNumber = i; 
 
        status = WdfChildListAddOrUpdateChildDescriptionAsPresent(
                                                 list, 
                                                 &description.Header, 
                                                 NULL
                                                 );
        if (!NT_SUCCESS(status) && (status != STATUS_OBJECT_NAME_EXISTS)) {
            break;
        }
    }
}
WdfChildListEndScan(list);

Requisitos

Requisito	Valor
de la plataforma de destino de	Universal
versión mínima de KMDF	1.0
encabezado de	wdfchildlist.h (incluya Wdf.h)
biblioteca de	Wdf01000.sys (consulte Control de versiones de la biblioteca de marcos).
irQL	<= DISPATCH_LEVEL
reglas de cumplimiento de DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)