IoCreateDevice-Funktion (wdm.h)
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
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 mit einer mit Null beendeten Unicode-Zeichenfolge, die das Geräteobjekt benennt. Die Zeichenfolge muss ein vollständiger Pfadname sein. WDM-Filter- und Funktionstreiber benennen ihre Geräteobjekte nicht. Weitere Informationen finden Sie unter named Device Objects.
Wenn kein Gerätename angegeben wird (d. h., DeviceName-NULL-ist), wird das von IoCreateDevice erstellte Geräteobjekt nicht (und kann) keine diskrete Zugriffssteuerungsliste (DACL) zugeordnet haben. Weitere Informationen finden Sie unter Sicherheitsdeskriptoren.
[in] DeviceType
Gibt eine der vom System definierten FILE_DEVICE_XXX Konstanten an, die den Gerätetyp (z. B. FILE_DEVICE_DISK oder FILE_DEVICE_KEYBOARD) oder einen vom Anbieter definierten Wert für einen neuen Gerätetyp angeben. Weitere Informationen finden Sie unter Angeben von Gerätetypen.
[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 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 nicht seitengebundenen Pools zugeordnet. Die Geräteerweiterung des Geräteobjekts ist null.
Rückgabewert
IoCreateDevice gibt STATUS_SUCCESS bei Erfolg oder den entsprechenden NTSTATUS-Fehlercode beim Fehler zurück. Eine partielle Liste der von dieser Funktion zurückgegebenen Fehlercodes umfasst:
STATUS_INSUFFICIENT_RESOURCES
STATUS_OBJECT_NAME_COLLISION
Bemerkungen
IoCreateDevice erstellt ein Geräteobjekt 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.
IoCreateDevice kann nur zum Erstellen eines nicht benannten Geräteobjekts oder eines benannten Geräteobjekts verwendet werden, für das ein Sicherheitsdeskriptor von einer INF-Datei festgelegt wird. Andernfalls müssen Treiber IoCreateDeviceSecure- verwenden, um benannte Geräteobjekte zu erstellen. 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.
Ein Remotedateisystem, das ein benanntes Geräteobjekt für einen Netzwerkumleitung erstellt und mit FsRtlRegisterUncProviderregistriert wird, muss FILE_REMOTE_DEVICE als eine der Optionen im DeviceCharacteristics Parameter von IoCreateDevice angeben.
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 der Aufruf eines Treibers an IoCreateDevice einen Fehler zurückgibt, sollte der Treiber alle Ressourcen freigeben, die ihm für dieses Gerät zugewiesen wurden.
Anforderungen
| Anforderung | Wert |
|---|---|
| Zielplattform- | Universal |
| Header- | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| Library | NtosKrnl.lib |
| DLL- | NtosKrnl.exe |
| IRQL- | IRQL-<= APC_LEVEL |
| DDI-Complianceregeln | AddDevice(wdm), CheckDeviceObjectFlags(wdm), HwStorPortProhibitedDIs(storport), IrqlIoPassive1(wdm), MiniportOnlyWdmDevice(kmdf) |