Enumerando dispositivos filho e métodos de controle
Em um namespace acpi, um objeto que é um dispositivo , por exemplo, um dispositivo chamado 'ABCD'-- pode ter objetos filho que são dispositivos filho do dispositivo ou que são métodos de controle compatíveis com o dispositivo. Qualquer objeto filho que seja um dispositivo filho de um dispositivo pai pode, por sua vez, ter recursivamente objetos filho que são dispositivos filho ou métodos de controle.
Por exemplo, no namespace de ACPI simplificado a seguir, a raiz do namespace ACPI é designada por '\' e o objeto 'ABCD' é um dispositivo que é um filho imediato da raiz do namespace ACPI. Além disso, o dispositivo 'ABCD' tem dois dispositivos filho imediatos chamados 'CHL1' e 'CHL2' e um objeto filho que é um método de controle chamado '_FOO'. Além disso, o dispositivo filho 'CHL2' tem um dispositivo filho chamado 'CHL3' e o dispositivo "CHL3" tem um objeto filho que é um método de controle chamado '_FOO'.
\ root of ACPI namespace
ABCD parent device
CHL1 child device of ABCD
CHL2 child device of ABCD
CHL3 child device of CHL2
_FOO control method
_FOO control method
Para usar IOCTL_ACPI_EVAL_METHOD_EX ou IOCTL_ACPI_ASYNC_EVAL_METHOD_EX, um driver para um dispositivo fornece o caminho e o nome do método de controle em um namespace ACPI. Para ajudar a obter o caminho e o nome de um dispositivo e objetos filho de um dispositivo, o Windows dá suporte à solicitação IOCTL_ACPI_ENUM_CHILDREN . Referindo-se ao namespace de ACPI simplificado fornecido nesta seção como exemplo, um driver na pilha de dispositivos do dispositivo 'ABCD' pode usar essa solicitação para fazer o seguinte:
Enumerar o dispositivo 'ABCD' e os dispositivos filho imediatos de 'ABCD'. Por exemplo, a solicitação pode ser usada para retornar '\ABCD', '\ABCD. CHL1' e '\ABCD. CHL2.
Enumerar recursivamente todos os dispositivos no namespace 'ABCD'. Por exemplo, a solicitação pode ser usada para retornar '\ABCD', '\ABCD. CHL1",' '\ABCD. CHL2' e '\ABCD. CHL2. CHL3.
Enumerar recursivamente todos os objetos filho descendentes de 'ABCD' de um nome fornecido. O nome fornecido atua como um filtro para que somente os objetos filho que têm o mesmo nome sejam enumerados. Por exemplo, para um nome fornecido '_FOO', a solicitação pode ser usada para retornar '\ABCD._FOO' e '\ABCD. CHL2. CHL3._FOO.
Depois que um driver obtém o caminho e o nome de um método de controle, ele pode fornecer o caminho e o nome como entrada para IOCTL_ACPI_EVAL_METHOD_EX ou IOCTL_ACPI_ASYNC_EVAL_METHOD_EX, conforme descrito em Avaliando métodos de controle ACPI de forma síncrona.
Uma solicitação de IOCTL_ACPI_ENUM_CHILDREN usa como entrada uma estrutura de ACPI_ENUM_CHILDREN_INPUT_BUFFER de comprimento variável alocada por driver que contém os seguintes membros:
Signature
A assinatura do buffer de entrada, que deve ser definida como ACPI_ENUM_CHILDREN_INPUT_BUFFER_SIGNATURE.
Flags
Um sinalizador que determina quais objetos no namespace ACPI de um dispositivo que o driver ACPI enumera. O driver ACPI retorna o caminho completo e o nome do objeto enumerado começando com a raiz do namespace ACPI. O sinalizador deve ser definido como um dos seguintes valores:
| Sinalizador | Descrição |
|---|---|
| ENUM_CHILDREN_IMMEDIATE_ONLY | Enumera o dispositivo e enumera os dispositivos filho imediatos do dispositivo. |
| ENUM_CHILDREN_MULTILEVEL | Enumera o dispositivo e enumera recursivamente todos os dispositivos filho do dispositivo. |
| ENUM_CHILDREN_NAME_IS_FILTER | Um OR bit a bit de ENUM_CHILDREN e ENUM_CHILDREN_NAME_IS_FILTER enumera os objetos filho do dispositivo cujo nome é idêntico ao fornecido pelo membro Name . |
NameLength
O número de caracteres ASCII que a matriz Name contém.
Name
Uma matriz ASCII de quatro caracteres terminada em NULL que contém o nome de um objeto filho que o driver ACPI usa para restringir a enumeração de objetos filho aos objetos que têm o mesmo nome.
A solicitação IOCTL_ACPI_ENUM_CHILDREN retorna o caminho e o nome dos objetos filho em um ACPI_ENUM_CHILDREN_OUTPUT_BUFFER de comprimento variável alocado pelo driver que contém os seguintes membros:
Signature
A assinatura do buffer de saída, que deve ser definida como ACPI_ENUM_CHILDREN_OUTPUT_BUFFER_SIGNATURE.
NumberOfChildren
O número de elementos do tipo ACPI_ENUM_CHILD na matriz Children .
Children
Uma matriz de elementos do tipo ACPI_ENUM_CHILD. O membro Name de uma estrutura ACPI_ENUM_CHILD contém o caminho e o nome do objeto filho, e o membro Flags indica se o objeto filho tem objetos filho.
Se o buffer de saída alocado pelo driver não for grande o suficiente para retornar todos os nomes filho enumerados, o driver ACPI não retornará nomes filho e definirá o membro Status do IO_STATUS_BLOCK para que a solicitação STATUS_BUFFER_OVERFLOW. Nesse caso, se o tamanho, em bytes, do buffer de saída for pelo menos sizeof(ACPI_ENUM_CHILDREN_OUTPUT_BUFFER_SIGNATURE), o driver ACPI também definirá NumberOfChildren como o tamanho, em bytes, necessário para recuperar os caminhos e nomes solicitados.