共用方式為


Framework 物件集合

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

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

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

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

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

  • 建立集合物件。

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

  • 將 物件新增至集合。

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

  • 從集合中移除 物件。

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

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

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

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

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

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

  • 鎖定集合。

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

    呼叫 WdfWaitLockAcquireWdfSpinLockAcquire 並不會防止驅動程式中的其他程式碼同時存取集合,如果該其他程式碼也不會呼叫 WdfWaitLockAcquireWdfSpinLockAcquire

  • 刪除集合。

    若要刪除集合物件,驅動程式可以呼叫 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);