WdmlibIoCreateDeviceSecure-Funktion (wdmsec.h)

Artikel
08/08/2023

Die WdmlibIoCreateDeviceSecure-Funktion (oder IoCreateDeviceSecure) erstellt ein benanntes Geräteobjekt und wendet die angegebenen Sicherheitseinstellungen an.

Syntax

NTSTATUS WdmlibIoCreateDeviceSecure(
  [in]           PDRIVER_OBJECT   DriverObject,
  [in]           ULONG            DeviceExtensionSize,
  [in, optional] PUNICODE_STRING  DeviceName,
  [in]           DEVICE_TYPE      DeviceType,
  [in]           ULONG            DeviceCharacteristics,
  [in]           BOOLEAN          Exclusive,
  [in]           PCUNICODE_STRING DefaultSDDLString,
  [in, optional] LPCGUID          DeviceClassGuid,
                 PDEVICE_OBJECT   *DeviceObject
);

Parameter

[in] DriverObject

Zeiger auf das Treiberobjekt für den Aufrufer. Jeder Treiber erhält einen Zeiger auf sein Treiberobjekt in einem Parameter auf seine DriverEntry-Routine . WDM-Funktions- und Filtertreiber erhalten auch einen Treiberobjektzeiger in ihren AddDevice-Routinen .

[in] DeviceExtensionSize

Gibt die vom Treiber bestimmte Anzahl von Bytes an, die für die Geräteerweiterung des Geräteobjekts zugewiesen werden sollen. Die interne Struktur der Geräteerweiterung ist treiberdefiniert.

[in, optional] DeviceName

Zeigt optional auf einen Puffer, der eine Unicode-Zeichenfolge mit Null-Endung enthält, die das Geräteobjekt benennt. Die Zeichenfolge muss ein vollständiger Pfadname sein. Wenn kein Name angegeben wird, muss das FILE_AUTOGENERATED_DEVICE_NAME-Flag im DeviceCharacteristics-Parameter vorhanden sein. (Verwenden Sie zum Erstellen eines nicht benannten Geräteobjekts die IoCreateDevice-Routine .)

[in] DeviceType

Gibt eine der vom System definierten FILE_DEVICE_XXX-Konstanten an, die den Gerätetyp (z. B. FILE_DEVICE_DISK, FILE_DEVICE_KEYBOARD usw.) oder einen vom Hersteller definierten Wert für einen neuen Gerätetyp angeben. Weitere Informationen finden Sie unter Angeben von Gerätetypen. (Da ein Bustreiber möglicherweise keine Informationen zum Gerätetyp hat, kann ein Gerätetypwert für eine PDO in einer INF AddReg-Direktive angegeben werden.)

[in] DeviceCharacteristics

Gibt eine oder mehrere systemdefinierte Konstanten (ORed together) an, die zusätzliche Informationen zum Gerät des Treibers bereitstellen. Eine Liste der möglichen Geräteeigenschaften finden Sie unter DEVICE_OBJECT. Weitere Informationen zum Angeben von Gerätemerkmalen finden Sie unter Angeben von Gerätemerkmalen. Die meisten Treiber geben FILE_DEVICE_SECURE_OPEN für diesen Parameter an.

[in] Exclusive

Gibt an, ob das Geräteobjekt ein exklusives Gerät darstellt. Die meisten Treiber legen diesen Wert auf FALSE fest. Weitere Informationen finden Sie unter Angeben des exklusiven Zugriffs auf Geräteobjekte.

[in] DefaultSDDLString

Gibt eine Zeichenfolgendarstellung für die Standardsicherheitseinstellungen des Geräteobjekts an. Die Sicherheit, die auf das Geräteobjekt angewendet wird, wird von dieser Zeichenfolge abgeleitet, es sei denn, der Systemadministrator legt eine Überschreibung im Abschnitt der Registrierung fest, die durch den DeviceClassGuid-Parameter identifiziert wird.

Die Sicherheitseinstellung wird in einer Teilmenge von Security Descriptor Definition Language (SDDL) angegeben. Eine Reihe vordefinierter Konstanten (SDDL_DEVOBJ_XXX) wird ebenfalls bereitgestellt. Weitere Informationen finden Sie unter Sichern von Geräteobjekten.

[in, optional] DeviceClassGuid

Zeiger auf eine GUID, die einen Abschnitt der Registrierung identifiziert, der mögliche Überschreibungen für die Parameter DefaultSDDLString, DeviceType, DeviceCharacteristics und Exclusive enthält.

Hinweis Sie sollten immer eine benutzerdefinierte Klassen-GUID angeben. Sie sollten keine vorhandene Klassen-GUID angeben. Wenn Sie eine vorhandene Klassen-GUID angeben, können andere Treiber, die angeben möchten, dass die vorhandene Klassen-GUID möglicherweise nicht installiert werden kann, oder möglicherweise mit falschen Sicherheitseinstellungen installiert werden.

DeviceObject

Zeiger auf eine Variable, die einen Zeiger auf die neu erstellte DEVICE_OBJECT-Struktur empfängt. Die DEVICE_OBJECT-Struktur wird aus einem nicht auslagerten Pool zugeordnet.

Rückgabewert

WdmlibIoCreateDeviceSecure gibt bei Erfolg STATUS_SUCCESS oder den entsprechenden NTSTATUS-Fehlercode bei Einem Fehler zurück. Eine partielle Liste der Fehlercodes, die von dieser Funktion zurückgegeben werden können, umfasst:

Hinweise

WdmlibIoCreateDeviceSecure erstellt ein benanntes Geräteobjekt, wendet die angegebenen Sicherheitseinstellungen an und gibt einen Zeiger auf das Objekt zurück. Der Aufrufer ist für das Löschen des Objekts verantwortlich, wenn es nicht mehr benötigt wird, indem Er IoDeleteDevice aufruft.

Diese Routine ist nicht Teil des Betriebssystems. Treiber können die Routine verwenden, indem sie eine Verknüpfung mit Wdmsec.lib unter Microsoft Windows 2000 und höheren Versionen von Windows herstellen. (Die Wdmsec.lib-Bibliothek wurde zuerst mit den Editionen Microsoft Windows XP Service Pack 1 [SP1] und Windows Server 2003 des Driver Development Kit [DDK] ausgeliefert und wird auch mit dem Windows Driver Kit [WDK]) ausgeliefert.)

Jeder Treiber, der ein benanntes Geräteobjekt erstellt, dessen Sicherheitsdeskriptor nicht durch die INF-Datei festgelegt wird, muss WdmlibIoCreateDeviceSecure verwenden. Weitere Informationen finden Sie unter Erstellen eines Geräteobjekts. Der Aufrufer ist für das Festlegen bestimmter Member des zurückgegebenen Geräteobjekts verantwortlich. Weitere Informationen finden Sie unter Initialisieren eines Geräteobjekts und in der gerätetypspezifischen Dokumentation für Ihr Gerät.

Achten Sie darauf, die Werte DeviceType und DeviceCharacteristics in den richtigen Parametern anzugeben. Beide Parameter verwenden systemdefinierte FILE_XXX-Konstanten , und einige Treiberschreiber geben versehentlich die Werte in den falschen Parametern an.

Der Aufrufer ist für das Festlegen bestimmter Felder im zurückgegebenen Geräteobjekt verantwortlich, z. B . das Feld Flags , und für die Initialisierung der Geräteerweiterung mit allen vom Treiber definierten Informationen. Weitere Vorgänge, die für neue Geräteobjekte erforderlich sind, finden Sie unter Initialisieren eines Geräteobjekts und in der gerätetypspezifischen Dokumentation für Ihr Gerät.

Die vom DeviceClassGuid-Parameter angegebene GUID bestimmt die Geräteeinrichtungsklasse für das Geräteobjekt. (Weitere Informationen zu Geräteeinrichtungsklassen finden Sie unter Geräteeinrichtungsklassen.) Anrufer müssen einen Wert angeben, damit Systemadministratoren die Sicherheitseinstellungen für das Gerät ändern können (für instance, um bestimmten Benutzern den Zugriff zu verweigern). Weitere Informationen finden Sie unter Festlegen der Eigenschaften der Geräteobjektregistrierung nach der Installation.

Nicht-WDM-Treiber geben eine neue GUID an, die noch nicht von einer vorhandenen Gerätesetupklasse verwendet wird. Generieren Sie eine neue GUID mithilfe des GuidGen.exe Tools, das im Microsoft Windows SDK enthalten ist.

WDM-Bustreiber, die Raw-Modus-fähige Geräte verarbeiten, können die Geräteeinrichtungsklasse des Geräts angeben, aber nur, wenn diese Klasse garantiert bereits erstellt wurde. Erstellen Sie andernfalls eine neue GUID.

Geräteobjekte für Datenträger, Bänder, CD-ROMs und RAM-Datenträger erhalten einen Volume-Parameterblock (Volume Parameter Block, VPB), der initialisiert wird, um anzugeben, dass das Volume noch nie auf dem Gerät eingebunden wurde.

Wenn der Aufruf eines Treibers von WdmlibIoCreateDeviceSecure einen Fehler zurückgibt, sollte der Treiber alle Ressourcen freigeben, die er für dieses Gerät zugewiesen hat.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Weitere Informationen finden Sie im Abschnitt mit den Hinweisen.
Zielplattform	Desktop
Kopfzeile	wdmsec.h (einschließen von Wdmsec.h)
Bibliothek	Wdmsec.lib
IRQL	PASSIVE_LEVEL
DDI-Complianceregeln	AddDevice(wdm), HwStorPortProhibitedDIs(storport), IrqlIoPassive1(wdm), MiniportOnlyWdmDevice