Partilhar via

Enumerando dispositivos filho e métodos de controle

Em um namespace ACPI, um dispositivo - por exemplo, um dispositivo chamado 'ABCD' - pode ter objetos filho que são dispositivos subordinados desse dispositivo ou que são métodos de controle suportados pelo próprio dispositivo. Qualquer objeto filho que seja um dispositivo subordinado de um dispositivo pai pode, por sua vez, ter recursivamente objetos filhos que são dispositivos subordinados ou métodos de controle.

Por exemplo, no namespace 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 denominados «CHL1» e «CHL2» e um objeto filho que é um método de controlo denominado «_FOO». Além disso, o dispositivo filho 'CHL2' tem um dispositivo filho chamado 'CHL3', e o dispositivo 'CHL3' possui 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 oferece suporte à solicitação IOCTL_ACPI_ENUM_CHILDREN . Referindo-se ao namespace 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:

  • Enumere o dispositivo 'ABCD' e os dispositivos filhos imediatos de 'ABCD'. Por exemplo, a solicitação pode ser usada para retornar '\ABCD', '\ABCD. CHL1' e '\ABCD. CHL2.»

  • Enumere recursivamente todos os dispositivos no namespace de 'ABCD'. Por exemplo, a solicitação pode ser usada para retornar '\ABCD', '\ABCD. CHL1,'\ABCD. CHL2' e '\ABCD. CHL2. CHL3.»

  • Enumere recursivamente todos os objetos filho descendentes associados a 'ABCD' de um nome fornecido. O nome fornecido atua como um filtro para que apenas os objetos filho que têm o mesmo nome sejam listados. 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 pelo 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

Uma bandeira que determina quais objetos no namespace ACPI de um dispositivo são enumerados pelo driver ACPI. O driver ACPI retorna o caminho completo e o nome do objeto enumerado começando com a raiz do namespace ACPI. O indicador deve ser definido com um dos seguintes valores:

Bandeira Descrição
ENUMERAR_CRIANÇAS_APENAS_IMEDIATAMENTE Enumera o dispositivo e os dispositivos subordinados imediatos do dispositivo.
ENUM_CHILDREN_MULTILEVEL Enumera o dispositivo e enumera recursivamente todos os dispositivos filho do dispositivo.
ENUM_NOME_DOS_FILHOS_É_FILTRO Um ou lógico (bitwise OR) de ENUM_CHILDREN e ENUM_CHILDREN_NAME_IS_FILTER enumera os objetos filhos 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 por NULL que contém o nome de um objeto filho que o driver ACPI usa para restringir a enumeração de objetos filho para os 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 estabelecida como ACPI_ENUM_CHILDREN_OUTPUT_BUFFER_SIGNATURE.

NumberOfChildren

O número de elementos do tipo ACPI_ENUM_CHILD na matriz Filhos .

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 que o driver aloca não for grande o suficiente para retornar todos os nomes filho enumerados, o driver ACPI não retornará nenhum nome filho e definirá o membro Status do IO_STATUS_BLOCK para 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 define NumberOfChildren para o tamanho, em bytes, necessário para recuperar os caminhos e nomes solicitados.

Ver também

Enviar um Pedido IOCTL_ACPI_ENUM_CHILDREN.

  • Last updated on