IoCreateDevice 関数 (wdm.h)
IoCreateDevice ルーチンは、ドライバーで使用するデバイス オブジェクトを作成します。
構文
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
);
パラメーター
[in] DriverObject
呼び出し元のドライバー オブジェクトへのポインター。 各ドライバーは、 DriverEntry ルーチンへのパラメーターでドライバー オブジェクトへのポインターを受け取ります。 WDM 関数とフィルター ドライバーは、 AddDevice ルーチンでドライバー オブジェクト ポインターも受け取ります。
[in] DeviceExtensionSize
デバイス オブジェクトの デバイス拡張機能 に割り当てるドライバーによって決定されたバイト数を指定します。 デバイス拡張機能の内部構造はドライバー定義です。
[in, optional] DeviceName
必要に応じて、デバイス オブジェクトに名前を付ける null で終わる Unicode 文字列を含むバッファーを指します。 文字列は完全なパス名である必要があります。 WDM フィルタードライバーと関数ドライバーでは、デバイス オブジェクトの名前は付けられません。 詳細については、「 名前付きデバイス オブジェクト」を参照してください。
デバイス名が指定されていない場合 (つまり、 DeviceName が NULL の場合)、IoCreateDevice によって作成されたデバイス オブジェクトには、随意アクセス制御リスト (DACL) が関連付けられません (また、関連付けられません)。 詳細については、「 セキュリティ記述子」を参照してください。
[in] DeviceType
デバイスの種類 (FILE_DEVICE_DISKやFILE_DEVICE_KEYBOARDなど) を示すシステム定義のFILE_DEVICE_XXX 定数、または新しい種類のデバイスのベンダー定義値のいずれかを指定します。 詳細については、「 デバイスの種類の指定」を参照してください。
[in] DeviceCharacteristics
ドライバーのデバイスに関する追加情報を提供する 1 つ以上のシステム定義定数 ORed をまとめて指定します。 使用可能なデバイス特性の一覧については、「 DEVICE_OBJECT」を参照してください。 デバイス特性を指定する方法の詳細については、「デバイス特性 の指定」を参照してください。 ほとんどのドライバーは、このパラメーターのFILE_DEVICE_SECURE_OPENを指定します。
[in] Exclusive
デバイス オブジェクトが 排他デバイスを表すかどうかを指定します。 ほとんどのドライバーでは、この値を FALSE に設定 します。 排他アクセスの詳細については、「 デバイス オブジェクトへの排他アクセスの指定」を参照してください。
[out] DeviceObject
新しく作成された DEVICE_OBJECT 構造体へのポインターを受け取る変数へのポインター。 DEVICE_OBJECT構造体は、非ページ プールから割り当てられます。 デバイス オブジェクトのデバイス拡張機能はゼロになります。
戻り値
IoCreateDevice は、成功した場合はSTATUS_SUCCESS、失敗した場合は適切な NTSTATUS エラー コードを返します。 この関数によって返されるエラー コードの一部の一覧には、次のものが含まれます。
STATUS_INSUFFICIENT_RESOURCES
STATUS_OBJECT_NAME_COLLISION
注釈
IoCreateDevice は、デバイス オブジェクトを作成し、オブジェクトへのポインターを返します。 呼び出し元は、 IoDeleteDevice を呼び出すことによって不要になったときにオブジェクトを削除します。
IoCreateDevice は、名前のないデバイス オブジェクト、または INF ファイルによってセキュリティ記述子が設定される名前付きデバイス オブジェクトを作成する場合にのみ使用できます。 それ以外の場合、ドライバーは IoCreateDeviceSecure を使用して名前付きデバイス オブジェクトを作成する必要があります。 詳細については、「 デバイス オブジェクトの作成」を参照してください。 呼び出し元は、返されたデバイス オブジェクトの特定のメンバーを設定する役割を担います。 詳細については、「 デバイス オブジェクトの初期化 」およびデバイスのデバイスの種類固有のドキュメントを参照してください。
適切なパラメーターで DeviceType と DeviceCharacteristics の値を 指定するように注意してください。 どちらのパラメーターもシステム定義のFILE_XXX 定数を使用し、一部のドライバー ライターは間違って間違ったパラメーターの値を指定します。
ネットワーク リダイレクターの名前付きデバイス オブジェクトを作成し、 FsRtlRegisterUncProvider を使用して登録するリモート ファイル システムでは、IoCreateDevice の DeviceCharacteristics パラメーターのオプションの 1 つとしてFILE_REMOTE_DEVICEを指定する必要があります。
ディスク、テープ、CD-ROM、RAM ディスクのデバイス オブジェクトには、ボリュームがデバイスにマウントされていないことを示すために初期化されたボリューム パラメーター ブロック (VPB) が与えられます。
IoCreateDevice に対するドライバーの呼び出しでエラーが返された場合、ドライバーはそのデバイスに割り当てられたリソースを解放する必要があります。
要件
| 要件 | 値 |
|---|---|
| 対象プラットフォーム | ユニバーサル |
| Header | wdm.h (Wdm.h、Ntddk.h、Ntifs.h を含む) |
| Library | NtosKrnl.lib |
| [DLL] | NtosKrnl.exe |
| IRQL | IRQL <= APC_LEVEL |
| DDI コンプライアンス規則 | AddDevice(wdm)、 CheckDeviceObjectFlags(wdm)、 HwStorPortProhibitedDDIs(storport)、 IrqlIoPassive1(wdm)、 MiniportOnlyWdmDevice(kmdf) |