列舉子裝置和控制方法

  • 發行項

在 ACPI 命名空間中，屬於裝置的物件，例如，名為 'ABCD' 的裝置可以有子物件，這些物件是裝置的子裝置，或是裝置所支援的控制方法。 任何屬於父裝置子裝置子裝置的子物件，都可以以遞迴方式具有子裝置或控制方法的子物件。

例如，在下列簡化的 ACPI 命名空間中，ACPI 命名空間的根目錄是由 '\' 指定，而物件 'ABCD' 是 ACPI 命名空間根目錄的立即子系裝置。 此外，裝置 'ABCD' 有兩個名為 'CHL1' 和 'CHL2' 的立即子裝置，以及名為 '_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

Null 終止的四個字元 ASCII 陣列，其中包含 ACPI 驅動程式用來將子物件列舉限制為具有相同名稱的子物件名稱。

IOCTL_ACPI_ENUM_CHILDREN要求會傳回驅動程式配置的可變長度ACPI_ENUM_CHILDREN_OUTPUT_BUFFER中子物件的路徑和名稱，其中包含下列成員：

Signature

輸出緩衝區的簽章，必須設定為 ACPI_ENUM_CHILDREN_OUTPUT_BUFFER_SIGNATURE。

NumberOfChildren

Children陣列中類型ACPI_ENUM_CHILD的專案數目。

Children

類型 為 ACPI_ENUM_CHILD的專案陣列。 ACPI_ENUM_CHILD 結構的 Name 成員包含子物件的路徑和名稱， 而 Flags 成員會指出子物件是否有子物件。

如果驅動程式配置的輸出緩衝區不夠大，無法傳回所有列舉的子名稱，ACPI 驅動程式不會傳回任何子名稱，並將要求 的狀態成員設定 為 IO_STATUS_BLOCK STATUS_BUFFER_OVERFLOW。 在此情況下，如果輸出緩衝區的大小以位元組為單位至少為 sizeof (ACPI_ENUM_CHILDREN_OUTPUT_BUFFER_SIGNATURE) ，ACPI 驅動程式也會將 NumberOfChildren 設定為大小，以位元組為單位，這是擷取要求的路徑和名稱所需的大小。

另請參閱

傳送IOCTL_ACPI_ENUM_CHILDREN要求。