WdmlibIoCreateDeviceSecure-Funktion (wdmsec.h)

Artikel
02/07/2025

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

Zeigen Sie auf das Treiberobjekt für den Aufrufer. Jeder Treiber empfängt 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 treiberbestimmte 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 mit Null beendete Unicode-Zeichenfolge 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 angeben (z. B. FILE_DEVICE_DISK, FILE_DEVICE_KEYBOARD usw.) oder einen vom Anbieter definierten Wert für einen neuen Gerätetyp. Weitere Informationen finden Sie unter Angeben von Gerätetypen. (Da ein Bustreiber möglicherweise keine Informationen über den Typ eines Geräts hat, kann ein Gerätetypwert für eine PDO- in einer INF-AddReg-Direktiveangegeben werden.)

[in] DeviceCharacteristics

Gibt eine oder mehrere vom System definierte Konstanten zusammen an, die zusätzliche Informationen zum Gerät des Treibers bereitstellen. Eine Liste der möglichen Gerätemerkmale 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ätdarstellt. 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 platziert eine Außerkraftsetzung im Abschnitt der Registrierung, die vom DeviceClassGuid Parameter identifiziert wird.

Die Sicherheitseinstellung wird in einer Teilmenge der Sicherheitsbeschreibungsdefinitionssprache (Security Descriptor Definition Language, SDDL) angegeben. Es werden auch eine Reihe vordefinierter Konstanten (SDDL_DEVOBJ_XXX-) 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 Außerkraftsetzungen für die DefaultSDDLString, DeviceType, DeviceCharacteristicsund Exclusive Parameter 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 versuchen, anzugeben, dass vorhandene Klassen-GUID möglicherweise nicht installiert oder mit falschen Sicherheitseinstellungen installiert werden kann.

DeviceObject

Zeiger auf eine Variable, die einen Zeiger auf die neu erstellte DEVICE_OBJECT Struktur empfängt. Die DEVICE_OBJECT Struktur wird aus nicht seitengebundenen Pools zugeordnet.

Rückgabewert

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

Bemerkungen

WdmlibIoCreateDeviceSecure erstellt ein benanntes Geräteobjekt, wendet die angegebenen Sicherheitseinstellungen an und gibt einen Zeiger auf das Objekt zurück. Der Aufrufer ist dafür verantwortlich, das Objekt zu löschen, wenn es nicht mehr benötigt wird, indem IoDeleteDeviceaufgerufen wird.

Diese Routine ist nicht Teil des Betriebssystems. Treiber können die Routine verwenden, indem sie mit Wdmsec.lib unter Microsoft Windows 2000 und höheren Versionen von Windows verknüpfen. (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, das nicht garantiert seine Sicherheitsbeschreibung durch die INF-Datei festgelegt hat, muss WdmlibIoCreateDeviceSecureverwenden. Weitere Informationen finden Sie unter Creating a Device Object. Der Aufrufer ist für das Festlegen bestimmter Elemente des zurückgegebenen Geräteobjekts verantwortlich. Weitere Informationen finden Sie unter Initialisieren eines Geräteobjekts und der gerätetypspezifischen Dokumentation für Ihr Gerät.

Achten Sie darauf, die DeviceType- und DeviceCharacteristics Werte in den richtigen Parametern anzugeben. Beide Parameter verwenden systemdefinierte FILE_XXX Konstanten, und einige Treiberautoren 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 treiberdefinierten Informationen. Weitere Vorgänge, die für neue Geräteobjekte erforderlich sind, finden Sie unter Initialisieren eines Geräteobjekts und 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ätesetupklassen finden Sie unter Gerätesetupklassen.) Anrufer müssen einen Wert bereitstellen, damit Systemadministratoren die Sicherheitseinstellungen für das Gerät ändern können (z. B. um den Zugriff auf bestimmte Benutzer zu verweigern). Weitere Informationen finden Sie unter Festlegen der Registrierungseigenschaften des Geräteobjekts nach der Installation.

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

WDM-Bustreiber, die unformatierte 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, Tapes, CD-ROMs und RAM-Datenträger erhalten einen Volume Parameter Block (VPB), der initialisiert wird, um anzugeben, dass das Volume nie auf dem Gerät bereitgestellt wurde.

Wenn ein Treiberaufruf an WdmlibIoCreateDeviceSecure einen Fehler zurückgibt, sollte der Treiber alle Ressourcen freigeben, die ihm für dieses Gerät zugewiesen wurden.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Siehe Abschnitt "Hinweise".
Zielplattform-	Desktop
Header-	wdmsec.h (include Wdmsec.h)
Library	Wdmsec.lib
IRQL-	PASSIVE_LEVEL
DDI-Complianceregeln	AddDevice(wdm), HwStorPortProhibitedDIs(storport), IrqlIoPassive1(wdm), MiniportOnlyWdmDevice