Framework-objectverzamelingen

Stuurprogramma's kunnen frameworkobjecten groeperen in verzamelingen die worden vertegenwoordigd door framework-verzamelingsobjecten.

Als een stuurprogramma bijvoorbeeld een frameworkaanvraagobject ontvangt dat een grote I/O-aanvraag vertegenwoordigt, moet het stuurprogramma de grote aanvraag mogelijk opsplitsen in kleinere aanvragen die het kan verzenden naar een I/O-doel-. Als u een grote aanvraag wilt opsplitsen in kleinere aanvragen, moet het stuurprogramma een set aanvraagobjecten maken die de kleinere aanvragen vertegenwoordigen. Als u deze door het stuurprogramma gemaakte aanvraagobjecten wilt bijhouden, kan het stuurprogramma een verzamelingsobject maken en deze toevoegen aan de verzameling.

De objecten in een objectverzameling bestaan doorgaans uit één type frameworkobject, maar een stuurprogramma kan een verzameling maken die uit verschillende typen objecten bestaat.

Uw stuurprogramma kan ook een verzameling verzamelingen maken. Dat wil gezegd, een verzameling kan bestaan uit een set verzamelingsobjecten.

Stuurprogramma's op basis van framework kunnen de volgende bewerkingen uitvoeren op objectverzamelingen:

• Maak een verzamelingsobject.

  Om een nieuwe collectie te maken, kunnen bestuurders WdfCollectionCreateaanroepen.

• Voeg een object toe aan een verzameling.

  Als u objecten aan een verzameling wilt toevoegen, kunnen stuurprogramma's WdfCollectionAddaanroepen, een of meer keren. Elke aanroep van WdfCollectionAdd voegt een object toe aan het einde van de verzameling en verhoogt het referentienummer van het toegevoegde object.

• Een object uit een verzameling verwijderen.

  Als u een object uit een verzameling wilt verwijderen en het aantal verwijzingen wilt verlagen, kunnen stuurprogramma's WdfCollectionRemove of WdfCollectionRemoveItemaanroepen. Wanneer een object wordt verwijderd, wordt de index van alle volgende objecten automatisch met één verlaagd.

• Het aantal objecten in een verzameling verkrijgen.

  Om het aantal objecten te bepalen dat een verzameling bevat, kunnen stuurprogramma's WdfCollectionGetCountaanroepen.

• Haal een verwijzing op naar een object in de verzameling.

  Als een stuurprogramma WdfCollectionGetItemaanroept, ontvangt het stuurprogramma een ingang voor het object dat is gekoppeld aan de indexwaarde. (Een indexwaarde van nul vertegenwoordigt het eerste object in de verzameling, een indexwaarde van één vertegenwoordigt het tweede object, enzovoorts, zoals een gekoppelde lijst. Wanneer het stuurprogramma item i uit een verzameling verwijdert, wordt item i+1 item i.)

  Stuurprogramma's kunnen ook WdfCollectionGetFirstItem of WdfCollectionGetLastItem aanroepen om een verwijzing te verkrijgen naar het eerste of laatste element dat aan de verzameling is toegevoegd.

• Een verzameling vergrendelen.

  Een stuurprogramma kan WdfWaitLockAcquire aanroepen om de toegang tot een verzameling te synchroniseren bij IRQL = PASSIVE_LEVEL, of het kan WdfSpinLockAcquire aanroepen om de toegang te synchroniseren bij IRQL = DISPATCH_LEVEL. Nadat een stuurprogramma een vergrendeling heeft verkregen, kan de verzameling niet worden geopend met andere code in het stuurprogramma dat ook WdfWaitLockAcquire of WdfSpinLockAcquireaanroept. Nadat een bewerking voor de verzameling is voltooid, moet het stuurprogramma WdfWaitLockReleaseaanroepen.

  Het aanroepen van WdfWaitLockAcquire of WdfSpinLockAcquire verhindert niet dat andere code in het stuurprogramma tegelijkertijd toegang heeft tot de verzameling, als die andere code niet ook WdfWaitLockAcquire of WdfSpinLockAcquireaanroept.

• Een verzameling verwijderen.

  Als u een verzamelingsobject wilt verwijderen, kunnen stuurprogramma's WdfObjectDeleteaanroepen. Stuurprogramma's specificeren doorgaans een bovenliggend object wanneer ze een verzameling maken, en het framework verwijdert het verzamelingsobject wanneer het bovenliggende object wordt verwijderd.

  Als een stuurprogramma bijvoorbeeld een set aanvraagobjecten maakt, zodat een grote I/O-aanvraag kan worden onderbroken in kleinere aanvragen, kan het aanvraagobject van de grote I/O-aanvraag het bovenliggende object van het verzamelingsobject zijn. Uiteindelijk zal het I/O-doel van de bestuurder WdfRequestComplete aanroepen om de kleinere aanvragen af te handelen. Op dat moment kan het stuurprogramma WdfRequestComplete- aanroepen voor de grote I/O-aanvraag, waardoor het framework het aanvraagobject en het onderliggende object verwijdert: het verzamelingsobject.

  Wanneer het framework een verzamelingsobject verwijdert dat objecten bevat die niet zijn verwijderd, worden de objecten uit de verzameling verwijderd en worden de verwijzingsaantallen verwijderd, maar wordt alleen het verzamelingsobject verwijderd.

Soms moet een stuurprogramma alle objecten in een verzameling onderzoeken. In het volgende codevoorbeeld ziet u deze situatie:

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