Framework-Objektsammlungen

Treiber können Frameworkobjekte in Sammlungen gruppieren, die von Frameworksammlungsobjekten dargestellt werden.

Wenn ein Treiber beispielsweise ein Frameworkanforderungsobjekt empfängt, das eine große E/A-Anforderung darstellt, muss der Treiber die große Anforderung möglicherweise in kleinere Anforderungen unterteilen, die er an ein E/A-Ziel senden kann. Um eine große Anforderung in kleinere zu unterteilen, muss der Treiber eine Reihe von Anforderungsobjekten erstellen, die die kleineren Anforderungen darstellen. Um diese vom Treiber erstellten Anforderungsobjekte nachzuverfolgen, erstellt der Treiber möglicherweise ein Auflistungsobjekt und fügt es der Auflistung hinzu.

In der Regel bestehen die Objekte in einer Objektauflistung aus einem einzelnen Typ von Frameworkobjekten, aber ein Treiber kann eine Auflistung erstellen, die aus verschiedenen Objekttypen besteht.

Ihr Treiber kann auch eine Sammlung von Sammlungen erstellen. Das heißt, eine Auflistung kann aus einer Reihe von Auflistungsobjekten bestehen.

Frameworkbasierte Treiber können die folgenden Vorgänge für Objektsammlungen ausführen:

• Erstellen Sie ein Auflistungsobjekt.

  Um eine neue Sammlung zu erstellen, können Treiber WdfCollectionCreate aufrufen.

• Fügen Sie einer Auflistung ein Objekt hinzu.

  Um einer Auflistung Objekte hinzuzufügen, können Treiber WdfCollectionAdd mehrmals aufrufen. Jeder Aufruf von WdfCollectionAdd fügt ein -Objekt an das Ende der Auflistung an und erhöht die Verweisanzahl des angefügten Objekts.

• Entfernen eines Objekts aus einer Auflistung

  Um ein Objekt aus einer Auflistung zu entfernen und dessen Verweisanzahl zu verringern, können Treiber WdfCollectionRemove oder WdfCollectionRemoveItem aufrufen. Wenn ein Objekt entfernt wird, wird ihr Index für alle Objekte nach dem entfernten automatisch verringert.

• Rufen Sie die Anzahl der Objekte in einer Auflistung ab.

  Um die Anzahl der Objekte zu bestimmen, die eine Auflistung enthält, können Treiber WdfCollectionGetCount aufrufen.

• Rufen Sie ein Handle für ein Objekt in der Auflistung ab.

  Wenn ein Treiber WdfCollectionGetItem aufruft und einen Indexwert als Eingabeargument angibt, empfängt der Treiber ein Handle für das Objekt, das dem Indexwert zugeordnet ist. (Ein Indexwert von 0 stellt das erste Objekt in der Auflistung dar, ein Indexwert von 1 das zweite Objekt und so wie eine verknüpfte Liste. Wenn der Treiber Element i aus einer Sammlung entfernt, wird element i+1 zu Element i.)

  Treiber können auch WdfCollectionGetFirstItem oder WdfCollectionGetLastItem aufrufen, um ein Handle für das erste oder letzte Element abzurufen, das der Auflistung hinzugefügt wurde.

• Sperren sie eine Sammlung.

  Ein Treiber kann WdfWaitLockAcquire aufrufen, um den Zugriff auf eine Sammlung unter IRQL = PASSIVE_LEVEL zu synchronisieren, oder er kann WdfSpinLockAcquire synchronize access at IRQL = DISPATCH_LEVEL aufrufen. Nachdem ein Treiber eine Sperre erworben hat, kann kein anderer Code im Treiber auf die Sammlung zugreifen, der auch WdfWaitLockAcquire oder WdfSpinLockAcquire aufruft. Nach Abschluss eines Vorgangs für die Auflistung muss der Treiber WdfWaitLockRelease aufrufen.

  Das Aufrufen von WdfWaitLockAcquire oder WdfSpinLockAcquire verhindert nicht, dass anderer Code im Treiber gleichzeitig auf die Auflistung zugreift, wenn dieser andere Code nicht auch WdfWaitLockAcquire oder WdfSpinLockAcquire aufruft.

• Löscht eine Auflistung.

  Um ein Auflistungsobjekt zu löschen, können Treiber WdfObjectDelete aufrufen. In der Regel geben Treiber jedoch ein übergeordnetes Objekt an, wenn sie eine Auflistung erstellen, und das Framework löscht das Auflistungsobjekt, wenn es das übergeordnete Objekt löscht.

  Wenn ein Treiber beispielsweise eine Reihe von Anforderungsobjekten erstellt, damit eine große E/A-Anforderung in kleinere Anforderungen unterteilt werden kann, kann er das Anforderungsobjekt der großen E/A-Anforderung zum übergeordneten Objekt des Auflistungsobjekts machen. Schließlich ruft das E/A-Ziel des Treibers WdfRequestComplete auf, um die kleineren Anforderungen abzuschließen. Zu diesem Zeitpunkt kann der Treiber WdfRequestComplete für die große E/A-Anforderung aufrufen, wodurch das Framework das Anforderungsobjekt und sein untergeordnetes Objekt, das Auflistungsobjekt, löscht.

  Wenn das Framework ein Auflistungsobjekt löscht, das nicht entfernte Objekte enthält, entfernt das Framework die Objekte aus der Auflistung und verringert ihre Verweisanzahl, aber es löscht nur das Auflistungsobjekt.

Manchmal muss ein Treiber alle Objekte in einer Auflistung untersuchen. Im folgenden Codebeispiel wird diese Situation veranschaulicht:

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