子デバイスと制御メソッドを列挙する
ACPI 名前空間では、デバイスであるオブジェクト ("ABCD" という名前のデバイスなど) には、デバイスの子デバイスまたはデバイスでサポートされている制御メソッドである子オブジェクトを含めることができます。 親デバイスの子デバイスである子オブジェクトは、子デバイスまたは制御メソッドである子オブジェクトを再帰的に持つことができます。
たとえば、次の簡略化された ACPI 名前空間では、ACPI 名前空間のルートは '\' で指定され、オブジェクト 'ABCD' は ACPI 名前空間のルートの直下の子であるデバイスです。 さらに、デバイス 'ABCD' には、'CHL1' と 'CHL2' という名前の 2 つの直下の子デバイスと、'_FOO' という名前の制御メソッドである子オブジェクトがあります。 さらに、子デバイス 'CHL2' には 'CHL3' という名前の子デバイスがあり、デバイス "CHL3" には '_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
IOCTL_ACPI_EVAL_METHOD_EX または IOCTL_ACPI_ASYNC_EVAL_METHOD_EX を使用するには、デバイスのドライバーは、ACPI 名前空間の制御メソッドのパスと名前を提供します。 デバイス パスとデバイス名、そしてデバイスの子オブジェクトを取得するために、Windows は IOCTL_ACPI_ENUM_CHILDREN 要求をサポートしています。 このセクションで提供される簡略化された ACPI 名前空間を例として参照すると、デバイス 'ABCD' のデバイス スタック内のドライバーは、この要求を使用して次の操作を行うことができます。
デバイス 'ABCD' と 'ABCD' の直接の子デバイスを列挙します。 たとえば、要求を使用して '\ABCD'、'\ABCD.CHL1'、および '\ABCD.CHL2' を返すことができます。
'ABCD' の名前空間内のすべてのデバイスを再帰的に列挙します。 たとえば、要求を使用して '\ABCD'、'\ABCD.CHL1'、'\ABCD.CHL2'、'\ABCD.CHL2.CHL3' を返すことができます。
指定した名前の 'ABCD' のすべての子孫の子オブジェクトを再帰的に列挙します。 指定した名前は、同じ名前を持つ子オブジェクトのみが列挙されるようにフィルターとして機能します。 たとえば、指定した名前 '_FOO' の場合、要求を使用して '\ABCD._FOO' と '\ABCD.CHL2.CHL3._FOO' を返すことができます。
ドライバーは、制御メソッドのパスと名前を取得した後、IOCTL_ACPI_EVAL_METHOD_EX または IOCTL_ACPI_ASYNC_EVAL_METHOD_EX への入力としてパスと名前を指定できます (「ACPI 制御メソッドを同期的に評価する」を参照)。
IOCTL_ACPI_ENUM_CHILDREN 要求は、ドライバーが割り当てた可変長の ACPI_ENUM_CHILDREN_INPUT_BUFFER 構造体を入力とし、次のメンバーを含みます。
Signature
入力バッファーのシグネチャ。ACPI_ENUM_CHILDREN_INPUT_BUFFER_SIGNATURE に設定する必要があります。
Flags
ACPI ドライバーが列挙するデバイスの ACPI 名前空間内のオブジェクトを決定するフラグ。 ACPI ドライバーは、ACPI 名前空間のルートで始まる列挙オブジェクトの完全なパスと名前を返します。 このフラグの値は次のいずれかに設定する必要があります。
| フラグ | 説明 |
|---|---|
| ENUM_CHILDREN_IMMEDIATE_ONLY | デバイスを列挙し、デバイスの直接の子デバイスを列挙します。 |
| ENUM_CHILDREN_MULTILEVEL | デバイスを列挙し、デバイスのすべての子デバイスを再帰的に列挙します。 |
| ENUM_CHILDREN_NAME_IS_FILTER | ENUM_CHILDREN と ENUM_CHILDREN_NAME_IS_FILTER のビットごとの OR 演算子は、Name メンバーで指定された名前と同じ名前を持つデバイスの子オブジェクトを列挙します。 |
NameLength
Name 配列に含まれる ASCII 文字の数。
Name
ACPI ドライバーが子オブジェクトの列挙を同じ名前を持つオブジェクトに制限するために使用する、子オブジェクトの名前を含む NULL 終端の 4 文字の ASCII 配列。
IOCTL_ACPI_ENUM_CHILDREN 要求は、次のメンバーを含む、ドライバーが割り当てた可変長 ACPI_ENUM_CHILDREN_OUTPUT_BUFFER 内の子オブジェクトのパスと名前を返します。
Signature
出力バッファーのシグネチャ。ACPI_ENUM_CHILDREN_OUTPUT_BUFFER_SIGNATURE に設定する必要があります。
NumberOfChildren
ACPI_ENUM_CHILD 型 (Children 配列) の要素の数。
Children
ACPI_ENUM_CHILD 型の要素の数。 ACPI_ENUM_CHILD 構造体の Name メンバーは子オブジェクトのパスと名前を含み、Flags メンバーは子オブジェクトに子オブジェクトがあるかどうかを示します。
ドライバーが割り当てる出力バッファーが、列挙されたすべての子名を返すのに十分な大きさでない場合、ACPIドライバーは子の名前を返さず、要求の IO_STATUS_BLOCK の Status メンバーを STATUS_BUFFER_OVERFLOW に設定します。 この場合、出力バッファーのサイズ (バイト単位) が sizeof (ACPI_ENUM_CHILDREN_OUTPUT_BUFFER_SIGNATURE) 以上であれば、ACPI ドライバーは NumberOfChildren にも、要求されたパスと名前を取得するのに必要なサイズ (バイト単位) を設定します。