Kolekce objektů rámce

Ovladače mohou seskupit objekty architektury do kolekcí, které jsou reprezentovány objekty kolekce architektury.

Pokud například ovladač obdrží objekt požadavku architektury, který představuje velký vstupně-výstupní požadavek, ovladač může muset rozdělit velký požadavek na menší požadavky, které může odeslat do V/V cíle. Aby bylo možné rozdělit velký požadavek na menší, musí ovladač vytvořit sadu objektů požadavku, které představují menší požadavky. Aby bylo možné sledovat tyto objekty žádosti vytvořené ovladačem, může ovladač vytvořit objekt kolekce a přidat je do kolekce.

Objekty v kolekci objektů se obvykle skládají z jednoho typu objektu architektury, ale ovladač může vytvořit kolekci, která se skládá z různých typů objektů.

Ovladač může také vytvořit kolekci kolekcí. To znamená, že kolekce se může skládat ze sady objektů kolekce.

Ovladače založené na rozhraní můžou s kolekcemi objektů provádět následující operace:

• Vytvořte objekt kolekce.

  Chcete-li vytvořit novou kolekci, ovladače mohou volat WdfCollectionCreate.

• Přidání objektu do kolekce

  Chcete-li přidat objekty do kolekce, ovladače mohou volat WdfCollectionAdd, jednou nebo vícekrát. Každé volání WdfCollectionAdd připojí objekt na konec kolekce a zvýší počet odkazů připojeného objektu.

• Odeberte objekt z kolekce.

  Chcete-li odebrat objekt z kolekce a snížit jeho referenční počet, ovladače mohou volat WdfCollectionRemove nebo WdfCollectionRemoveItem. Když se objekt odebere, všechny objekty po odebrání budou mít index automaticky dekrementovaný.

• Získejte počet objektů v kolekci.

  Chcete-li určit počet objektů, které kolekce obsahuje, ovladače mohou volat WdfCollectionGetCount.

• Získejte popisovač objektu v kolekci.

  Pokud ovladač volá WdfCollectionGetItem, zadává hodnotu indexu jako vstupní argument, ovladač obdrží popisovač objektu, který je přidružen k hodnotě indexu. (Hodnota indexu nula představuje první objekt v kolekci, indexová hodnota jednoho představuje druhý objekt a tak dále propojený seznam. Když ovladač odebere položku i z kolekce, položka i+1 se změní na položku i.)

  Ovladače mohou také volat WdfCollectionGetFirstItem nebo WdfCollectionGetLastItem, aby získaly popisovač první nebo poslední položky, která byla přidána do kolekce.

• Uzamkněte kolekci.

  Ovladač může volat WdfWaitLockAcquire pro synchronizaci přístupu ke kolekci v IRQL = PASSIVE_LEVEL, nebo může volat WdfSpinLockAcquire synchronizovat přístup v IRQL = DISPATCH_LEVEL. Jakmile ovladač získá zámek, nemůže k kolekci získat přístup jiný kód v ovladači, který také volá WdfWaitLockAcquire nebo WdfSpinLockAcquire. Po dokončení operace v kolekci musí ovladač volat WdfWaitLockRelease.

  Volání WdfWaitLockAcquire nebo WdfSpinLockAcquire nebrání tomu, aby jiný kód v ovladači současně přistupoval ke kolekci, pokud tento jiný kód také nevolá WdfWaitLockAcquire nebo WdfSpinLockAcquire.

• Odstraňte kolekci

  Chcete-li odstranit objekt kolekce, ovladače mohou volat WdfObjectDelete. Častěji však ovladače určují nadřazený objekt při vytváření kolekce a architektura odstraní objekt kolekce při odstranění nadřazeného objektu.

  Pokud například ovladač vytvoří sadu objektů požadavků, aby mohl rozdělit velký vstupně-výstupní požadavek na menší, může učinit objekt velkého vstupně-výstupního požadavku nadřazeným objektem kolekce. Nakonec cíl vstupně-výstupních operací ovladače zavolá WdfRequestComplete, aby dokončil menší požadavky. V tomto okamžiku může ovladač volat WdfRequestComplete pro velký vstupně-výstupní požadavek, což způsobí, že architektura odstraní objekt požadavku a jeho podřízený objekt: objekt kolekce.

  Když architektura odstraní objekt kolekce, který obsahuje objekty, které nebyly odebrány, rozhraní odebere objekty z kolekce a sníží jejich počet odkazů, ale odstraní pouze objekt kolekce.

Někdy musí ovladač prozkoumat všechny objekty v kolekci. Následující příklad kódu ukazuje tuto situaci:

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);