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 WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER que identifica una descripción de identificación secundaria.

[in, optional] AddressDescription

Puntero a una estructura 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 puede asignar una descripción secundaria.

Este método también podría devolver otros valores NTSTATUS.

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

Comentarios

El método WdfChildListAddOrUpdateChildDescriptionAsPresent busca en la lista secundaria especificada una lista secundaria 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 identificación y direcció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 su actualización.
Llama 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 llama a WdfChildListEndScan antes de actualizar la lista secundaria e informa 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 WdfChildListAddOrUpdateChildDescriptionAsPresent, el marco llama a la función de devolución de llamada EvtChildListCreateDevice del controlador 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 conmutador 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	Value
Plataforma de destino	Universal
Versión mínima de KMDF	1.0
Encabezado	wdfchildlist.h (incluya Wdf.h)
Library	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)