Énumération d’appareils enfants et méthodes de contrôle
Dans un espace de noms ACPI, un objet qui est un appareil, par exemple un appareil nommé « ABCD », peut avoir des objets enfants qui sont des appareils enfants de l’appareil ou qui sont des méthodes de contrôle prises en charge par l’appareil. Tout objet enfant qui est un appareil enfant d’un appareil parent peut, à son tour, avoir de manière récursive des objets enfants qui sont des appareils enfants ou des méthodes de contrôle.
Par exemple, dans l’espace de noms ACPI simplifié suivant, la racine de l’espace de noms ACPI est désignée par « \ » et l’objet « ABCD » est un appareil qui est un enfant immédiat de la racine de l’espace de noms ACPI. En outre, l’appareil « ABCD » a deux appareils enfants immédiats nommés « CHL1 » et « CHL2 » et un objet enfant qui est une méthode de contrôle nommée « _FOO ». En outre, l’appareil enfant « CHL2 » a un appareil enfant nommé « CHL3 » et l’appareil « CHL3 » a un objet enfant qui est une méthode de contrôle nommée « _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
Pour utiliser IOCTL_ACPI_EVAL_METHOD_EX ou IOCTL_ACPI_ASYNC_EVAL_METHOD_EX, un pilote pour un appareil fournit le chemin d’accès et le nom de la méthode de contrôle dans un espace de noms ACPI. Pour vous aider à obtenir le chemin d’accès et le nom d’un appareil et des objets enfants d’un appareil, Windows prend en charge la demande IOCTL_ACPI_ENUM_CHILDREN . En référence à l’espace de noms ACPI simplifié fourni dans cette section à titre d’exemple, un pilote dans la pile d’appareils de l’appareil « ABCD » peut utiliser cette demande pour effectuer les opérations suivantes :
Énumérez l’appareil « ABCD » et les appareils enfants immédiats de « ABCD ». Par exemple, la demande peut être utilisée pour retourner « \ABCD », « \ABCD . CHL1 et « \ABCD. CHL2.
Énumérez de manière récursive tous les appareils dans l’espace de noms « ABCD ». Par exemple, la demande peut être utilisée pour retourner « \ABCD », « \ABCD . CHL1 », « \ABCD. CHL2 », et « \ABCD. CHL2. CHL3.
Énumérer de manière récursive tous les objets enfants descendants de 'ABCD' d’un nom fourni. Le nom fourni fait office de filtre afin que seuls les objets enfants portant le même nom soient énumérés. Par exemple, pour un nom fourni « _FOO », la demande peut être utilisée pour retourner « \ABCD._FOO » et « \ABCD . CHL2. CHL3._FOO.
Une fois qu’un pilote a obtenu le chemin d’accès et le nom d’une méthode de contrôle, il peut fournir le chemin d’accès et le nom comme entrée à IOCTL_ACPI_EVAL_METHOD_EX ou IOCTL_ACPI_ASYNC_EVAL_METHOD_EX, comme décrit dans Évaluation synchrone des méthodes de contrôle ACPI.
Une demande de IOCTL_ACPI_ENUM_CHILDREN prend comme entrée une structure de longueur variable allouée par le pilote ACPI_ENUM_CHILDREN_INPUT_BUFFER qui contient les membres suivants :
Signature
Signature de la mémoire tampon d’entrée, qui doit être définie sur ACPI_ENUM_CHILDREN_INPUT_BUFFER_SIGNATURE.
Flags
Indicateur qui détermine les objets de l’espace de noms ACPI d’un appareil énuméré par le pilote ACPI. Le pilote ACPI retourne le chemin d’accès complet et le nom de l’objet énuméré à partir de la racine de l’espace de noms ACPI. L’indicateur doit être défini sur l’une des valeurs suivantes :
| Indicateur | Description |
|---|---|
| ENUM_CHILDREN_IMMEDIATE_ONLY | Énumère l’appareil et énumère les appareils enfants immédiats de l’appareil. |
| ENUM_CHILDREN_MULTILEVEL | Énumère l’appareil et énumère de manière récursive tous les appareils enfants de l’appareil. |
| ENUM_CHILDREN_NAME_IS_FILTER | Un OR au niveau du bit de ENUM_CHILDREN et ENUM_CHILDREN_NAME_IS_FILTER énumère les objets enfants de l’appareil dont le nom est identique à celui fourni par le membre Name . |
NameLength
Nombre de caractères ASCII que contient le tableau De noms .
Name
Tableau ASCII à quatre caractères terminé par NULL qui contient le nom d’un objet enfant que le pilote ACPI utilise pour limiter l’énumération des objets enfants aux objets qui portent le même nom.
La requête IOCTL_ACPI_ENUM_CHILDREN retourne le chemin et le nom des objets enfants dans une ACPI_ENUM_CHILDREN_OUTPUT_BUFFER de longueur variable allouée par le pilote qui contient les membres suivants :
Signature
Signature de la mémoire tampon de sortie, qui doit être définie sur ACPI_ENUM_CHILDREN_OUTPUT_BUFFER_SIGNATURE.
NumberOfChildren
Nombre d’éléments de type ACPI_ENUM_CHILD dans le tableau Enfants .
Children
Tableau d’éléments de type ACPI_ENUM_CHILD. Le membre Name d’une structure ACPI_ENUM_CHILD contient le chemin d’accès et le nom de l’objet enfant, et le membre Flags indique si l’objet enfant a des objets enfants.
Si la mémoire tampon de sortie allouée par le pilote n’est pas assez grande pour renvoyer tous les noms enfants énumérés, le pilote ACPI ne retourne aucun nom enfant et définit le membre Status du IO_STATUS_BLOCK pour la demande de STATUS_BUFFER_OVERFLOW. Dans ce cas, si la taille, en octets, du tampon de sortie est au moins sizeof(ACPI_ENUM_CHILDREN_OUTPUT_BUFFER_SIGNATURE), le pilote ACPI définit également NumberOfChildren sur la taille, en octets, requise pour récupérer les chemins et les noms demandés.