IoCreateDevice 関数 (wdm.h)

[アーティクル]
12/21/2024

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設定します。排他アクセスの詳細については、「Device Objectsへの排他アクセスの指定」を参照してください。

[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 に対するドライバーの呼び出しでエラーが返された場合、ドライバーはそのデバイスに割り当てられたリソースを解放する必要があります。

必要条件

要件	価値
ターゲットプラットフォームの	万国
ヘッダー	wdm.h (Wdm.h、Ntddk.h、Ntifs.h を含む)
ライブラリ	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	IRQL <= APC_LEVEL
DDI コンプライアンス規則をする	AddDevice(wdm)、 CheckDeviceObjectFlags(wdm)、 HwStorPortProhibitedDDDIs (storport), IrqlIoPassive1(wdm), MiniportOnlyWdmDevice(kmdf)

次の方法で共有

IoCreateDevice 関数 (wdm.h)

構文

パラメーター

戻り値

備考

必要条件

関連項目

フィードバック

その他のリソース