IoCreateDevice-Funktion (wdm.h)

Artikel
08/08/2023

Die IoCreateDevice-Routine erstellt ein Geräteobjekt zur Verwendung durch einen Treiber.

Syntax

NTSTATUS IoCreateDevice(
  [in]           PDRIVER_OBJECT  DriverObject,
  [in]           ULONG           DeviceExtensionSize,
  [in, optional] PUNICODE_STRING DeviceName,
  [in]           DEVICE_TYPE     DeviceType,
  [in]           ULONG           DeviceCharacteristics,
  [in]           BOOLEAN         Exclusive,
  [out]          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. WDM-Filter- und Funktionstreiber nennen ihre Geräteobjekte nicht. Weitere Informationen finden Sie unter Benannte Geräteobjekte.

Wenn kein Gerätename angegeben wird (d. h. DeviceName ist NULL), verfügt das von IoCreateDevice erstellte Geräteobjekt nicht über eine diskretionäre Zugriffssteuerungsliste (DACL). Weitere Informationen finden Sie unter Sicherheitsdeskriptoren.

[in] DeviceType

Gibt eine der systemdefinierten FILE_DEVICE_XXX-Konstanten an, die den Gerätetyp (z. B. FILE_DEVICE_DISK oder FILE_DEVICE_KEYBOARD) oder einen vom Hersteller definierten Wert für einen neuen Gerätetyp angeben. Weitere Informationen finden Sie unter Angeben von Gerätetypen.

[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 zum exklusiven Zugriff finden Sie unter Angeben des exklusiven Zugriffs auf Geräteobjekte.

[out] 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. Die Geräteerweiterung des Geräteobjekts wird auf Null gesetzt.

Rückgabewert

IoCreateDevice 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, umfasst:

STATUS_INSUFFICIENT_RESOURCES
STATUS_OBJECT_NAME_COLLISION

Hinweise

IoCreateDevice erstellt ein Geräteobjekt 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.

IoCreateDevice kann nur verwendet werden, um ein nicht benanntes Geräteobjekt oder ein benanntes Geräteobjekt zu erstellen, für das ein Sicherheitsdeskriptor durch eine INF-Datei festgelegt wird. Andernfalls müssen Treiber IoCreateDeviceSecure verwenden, um benannte Geräteobjekte zu erstellen. 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.

Ein Remotedateisystem, das ein benanntes Geräteobjekt für eine Netzwerkumleitung erstellt und das sich mit FsRtlRegisterUncProvider registriert, muss FILE_REMOTE_DEVICE als eine der Optionen im DeviceCharacteristics-Parameter von IoCreateDevice angeben.

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 IoCreateDevice einen Fehler zurückgibt, sollte der Treiber alle Ressourcen freigeben, die er diesem Gerät zugewiesen hat.

Anforderungen

Anforderung	Wert
Zielplattform	Universell
Header	wdm.h (einschließlich Wdm.h, Ntddk.h, Ntifs.h)
Bibliothek	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	IRQL <= APC_LEVEL
DDI-Complianceregeln	AddDevice(wdm), CheckDeviceObjectFlags(wdm), HwStorPortProhibitedDIs(storport), IrqlIoPassive1(wdm), MiniportOnlyWdmDevice(kmdf)