Raccolte di oggetti framework

I driver possono raggruppare oggetti framework in raccolte rappresentate da oggetti raccolta framework.

Ad esempio, se un driver riceve un oggetto richiesta framework che rappresenta una richiesta di I/O di grandi dimensioni, il driver potrebbe dover suddividere la richiesta di grandi dimensioni in richieste più piccole che può inviare a una destinazione di I/O. Per suddividere una richiesta di grandi dimensioni in quelle più piccole, il driver deve creare un set di oggetti richiesta che rappresentano le richieste più piccole. Per tenere traccia di questi oggetti richiesta creati dal driver, il driver potrebbe creare un oggetto raccolta e aggiungerli alla raccolta.

In genere, gli oggetti in una raccolta di oggetti sono costituiti da un singolo tipo di oggetto framework, ma un driver può creare una raccolta costituita da diversi tipi di oggetti.

Il driver può anche creare una raccolta di raccolte. Ovvero, una raccolta può essere costituita da un set di oggetti raccolta.

I driver basati su framework possono eseguire le operazioni seguenti sulle raccolte di oggetti:

• Creare un oggetto raccolta.

  Per creare una nuova raccolta, i driver possono chiamare WdfCollectionCreate.

• Aggiungere un oggetto a un insieme.

  Per aggiungere oggetti a una raccolta, i driver possono chiamare WdfCollectionAdd, una o più volte. Ogni chiamata a WdfCollectionAdd aggiunge un oggetto alla fine dell'insieme e incrementa il conteggio dei riferimenti dell'oggetto accodato.

• Rimuovere un oggetto da una raccolta.

  Per rimuovere un oggetto da un insieme e decrementarne il conteggio dei riferimenti, i driver possono chiamare WdfCollectionRemove o WdfCollectionRemoveItem. Quando un oggetto viene rimosso, tutti gli oggetti dopo che quello rimosso avranno automaticamente decrementato l'indice.

• Ottenere il numero di oggetti in una raccolta.

  Per determinare il numero di oggetti contenuti in una raccolta, i driver possono chiamare WdfCollectionGetCount.

• Ottenere un handle per un oggetto nell'insieme.

  Se un driver chiama WdfCollectionGetItem, specificando un valore di indice come argomento di input, il driver riceve un handle per l'oggetto associato al valore di indice. Un valore di indice pari a zero rappresenta il primo oggetto dell'insieme, un valore di indice di uno rappresenta il secondo oggetto e così via come un elenco collegato. Quando il driver rimuove l'elemento i da una raccolta, l'elemento i+1 diventa elemento i.)

  I driver possono anche chiamare WdfCollectionGetFirstItem o WdfCollectionGetLastItem per ottenere un handle al primo o all'ultimo elemento aggiunto alla raccolta.

• Bloccare una raccolta.

  Un driver può chiamare WdfWaitLockAcquire per sincronizzare l'accesso a una raccolta in IRQL = PASSIVE_LEVEL oppure può chiamare WdfSpinLockAcquire sincronizzare l'accesso in IRQL = DISPATCH_LEVEL. Dopo che un driver acquisisce un blocco, l'accesso alla raccolta non può essere eseguito da altro codice nel driver che chiama anche WdfWaitLockAcquire o WdfSpinLockAcquire. Dopo aver completato un'operazione sulla raccolta, il driver deve chiamare WdfWaitLockRelease.

  La chiamata a WdfWaitLockAcquire o WdfSpinLockAcquire non impedisce l'accesso simultaneo ad altri codice nel driver, se tale altro codice non chiama anche WdfWaitLockAcquire o WdfSpinLockAcquire.

• Eliminare una raccolta.

  Per eliminare un oggetto raccolta, i driver possono chiamare WdfObjectDelete. In genere, tuttavia, i driver specificano un oggetto padre quando creano una raccolta e il framework elimina l'oggetto raccolta quando elimina l'oggetto padre.

  Ad esempio, se un driver crea un set di oggetti richiesta in modo che possa suddividere una richiesta di I/O di grandi dimensioni in richieste più piccole, può effettuare l'oggetto richiesta di I/O di grandi dimensioni l'oggetto padre dell'oggetto raccolta. Alla fine la destinazione di I/O del driver chiamerà WdfRequestComplete per completare le richieste più piccole. A questo punto, il driver può chiamare WdfRequestComplete per la richiesta di I/O di grandi dimensioni, causando l'eliminazione dell'oggetto richiesta e del relativo oggetto figlio: l'oggetto raccolta.

  Quando il framework elimina un oggetto raccolta che contiene oggetti che non sono stati rimossi, il framework rimuove gli oggetti dalla raccolta e decrementa i conteggi dei riferimenti, ma elimina solo l'oggetto raccolta.

A volte un driver deve esaminare tutti gli oggetti all'interno di una raccolta. L'esempio di codice seguente illustra questa situazione:

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