Framework 物件集合

驅動程式可以將架構物件分組為 架構集合物件所代表的集合。

例如，如果驅動程式收到代表大型 I/O 要求的架構要求物件，驅動程式可能必須將大型要求分成較小的要求，以便傳送至 I/O 目標。 若要將大型要求分成較小的要求，驅動程式必須建立一組代表較小要求的要求物件。 若要追蹤這些驅動程式建立的要求物件，驅動程式可能會建立集合物件，並將其新增至集合。

一般而言，物件集合中的物件是由單一類型的架構物件所組成，但驅動程式可以建立由不同類型的物件組成的集合。

您的驅動程式也可以建立集合的集合。 也就是說，集合可以包含一組集合物件。

架構型驅動程式可以在物件集合上執行下列作業：

• 建立集合物件。

  若要建立新的集合，驅動程式可以呼叫 WdfCollectionCreate。

• 將 物件新增至集合。

  若要將物件新增至集合，驅動程式可以呼叫 WdfCollectionAdd，一或多次。 對 WdfCollectionAdd的每個呼叫都會將物件附加至集合結尾，並遞增附加物件的參考計數。

• 從集合中移除 物件。

  若要從集合中移除物件並遞減其參考計數，驅動程式可以呼叫 WdfCollectionRemove 或 WdfCollectionRemoveItem。 移除物件時，移除之後的所有物件都會自動遞減其索引。

• 取得集合中的 物件數目。

  若要判斷集合包含的物件數目，驅動程式可以呼叫 WdfCollectionGetCount。

• 取得集合中物件的控制碼。

  如果驅動程式呼叫 WdfCollectionGetItem，提供索引值做為輸入引數，驅動程式就會收到與索引值相關聯的物件的控制碼。 (零的索引值代表集合中的第一個物件、一個的索引值代表第二個物件，依此類同的連結清單。當驅動程式從集合中移除專案 i 時，專案 i+1 會變成專案 i.)

  驅動程式也可以呼叫 WdfCollectionGetFirstItem 或 WdfCollectionGetLastItem ，以取得新增至集合之第一個或最後一個專案的控制碼。

• 鎖定集合。

  驅動程式可以呼叫 WdfWaitLockAcquire 來同步存取 IRQL = PASSIVE_LEVEL的集合，或者它可以在 IRQL = DISPATCH_LEVEL 呼叫 WdfSpinLockAcquire 同步存取。 在驅動程式取得鎖定之後，驅動程式中的其他程式碼無法存取集合，該程式碼也會呼叫 WdfWaitLockAcquire 或 WdfSpinLockAcquire。 完成集合上的作業之後，驅動程式必須呼叫 WdfWaitLockRelease。

  呼叫 WdfWaitLockAcquire 或 WdfSpinLockAcquire 並不會防止驅動程式中的其他程式碼同時存取集合，如果該其他程式碼也不會呼叫 WdfWaitLockAcquire 或 WdfSpinLockAcquire。

• 刪除集合。

  若要刪除集合物件，驅動程式可以呼叫 WdfObjectDelete。 不過，驅動程式通常會在建立集合時指定父物件，而架構會在刪除父物件時刪除集合物件。

  例如，如果驅動程式建立一組要求物件，讓它可以將大型 I/O 要求分成較小的要求，它可以讓大型 I/O 要求的要求物件成為集合物件的父物件。 驅動程式的 I/O 目標最終會呼叫 WdfRequestComplete 來完成較小的要求。 此時，驅動程式可以針對大型 I/O 要求呼叫 WdfRequestComplete ，導致架構刪除要求物件及其子物件：集合物件。

  當架構刪除包含尚未移除之物件的集合物件時，架構會從集合中移除物件，並遞減其參考計數，但只會刪除集合物件。

有時候驅動程式必須檢查集合中的所有物件。 下列程式碼範例示範這種情況：

WdfWaitLockAcquire(CollectionLockHandle, NULL);
ItemCount = WdfCollectionGetCount(CollectionHandle);
for (i=0; i<ItemCount; i++) {
    ObjectHandle = WdfCollectionGetItem(CollectionHandle, i);
    // 1. Call object-specific methods to obtain object properties.
    // 2. Perform object-specific operations.
    }
WdfWaitLockRelease(CollectionLockHandle);