WdmlibIoCreateDeviceSecure 関数 (wdmsec.h)

[アーティクル]
08/08/2023

WdmlibIoCreateDeviceSecure 関数 (または IoCreateDeviceSecure) は、名前付きデバイスオブジェクトを作成し、指定されたセキュリティ設定を適用します。

構文

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
);

パラメーター

[in] DriverObject

呼び出し元のドライバーオブジェクトへのポインター。各ドライバーは、 DriverEntry ルーチンへのパラメーターでドライバーオブジェクトへのポインターを受け取ります。 WDM 関数とフィルタードライバーは、 AddDevice ルーチンでドライバーオブジェクトポインターも受け取ります。

[in] DeviceExtensionSize

デバイスオブジェクトのデバイス拡張機能に割り当てるドライバーによって決定されたバイト数を指定します。デバイス拡張機能の内部構造はドライバー定義です。

[in, optional] DeviceName

必要に応じて、デバイスオブジェクトに名前を付ける null で終わる Unicode 文字列を含むバッファーを指します。文字列は完全なパス名である必要があります。名前を指定しない場合は、FILE_AUTOGENERATED_DEVICE_NAME フラグが DeviceCharacteristics パラメーターに存在する必要があります。 (名前のないデバイスオブジェクトを作成するには、 IoCreateDevice ルーチンを使用します)。

[in] DeviceType

デバイスの種類 (FILE_DEVICE_DISK、FILE_DEVICE_KEYBOARDなど) を示すシステム定義のFILE_DEVICE_XXX 定数、または新しい種類のデバイスのベンダー定義値のいずれかを指定します。詳細については、「デバイスの種類の指定」を参照してください。 (バスドライバーにはデバイスの種類に関する情報がない可能性があるため、 PDO のデバイスの種類の値を INF AddReg ディレクティブで指定できます)。

[in] DeviceCharacteristics

ドライバーのデバイスに関する追加情報を提供する 1 つ以上のシステム定義定数 ORed をまとめて指定します。使用可能なデバイス特性の一覧については、「 DEVICE_OBJECT」を参照してください。デバイス特性を指定する方法の詳細については、「デバイス特性の指定」を参照してください。ほとんどのドライバーは、このパラメーターのFILE_DEVICE_SECURE_OPENを指定します。

[in] Exclusive

デバイスオブジェクトが排他デバイスを表すかどうかを指定します。ほとんどのドライバーでは、この値を FALSE に設定 します。詳細については、「デバイスオブジェクトへの排他アクセスの指定」を参照してください。

[in] DefaultSDDLString

デバイスオブジェクトの既定のセキュリティ設定の文字列表現を指定します。デバイスオブジェクトに適用されるセキュリティは、システム管理者が DeviceClassGuid パラメーターで識別されるレジストリのセクションにオーバーライドを配置しない限り、この文字列から派生します。

セキュリティ設定は、セキュリティ記述子定義言語 (SDDL) のサブセットで指定されます。定義済みの定数 (SDDL_DEVOBJ_XXX) のセットも用意されています。詳細については、「デバイスオブジェクトのセキュリティ保護」を参照してください。

[in, optional] DeviceClassGuid

DefaultSDDLString、DeviceType、DeviceCharacteristics、Exclusive パラメーターに対して可能なオーバーライドを含むレジストリのセクションを識別する GUID へのポインター。

メモカスタムクラス GUID は常に指定する必要があります。既存のクラス GUID は指定しないでください。既存のクラス GUID を指定すると、既存のクラス GUID を指定しようとする他のドライバーがインストールに失敗したり、正しくないセキュリティ設定でインストールされたりする可能性があります。

DeviceObject

新しく作成された DEVICE_OBJECT 構造体へのポインターを受け取る変数へのポインター。 DEVICE_OBJECT構造体は、非ページプールから割り当てられます。

戻り値

WdmlibIoCreateDeviceSecure は、成功した場合はSTATUS_SUCCESS、失敗した場合は適切な NTSTATUS エラーコードを返します。この関数によって返される可能性があるエラーコードの一部の一覧は次のとおりです。

注釈

WdmlibIoCreateDeviceSecure は、名前付きデバイスオブジェクトを作成し、指定されたセキュリティ設定を適用して、オブジェクトへのポインターを返します。呼び出し元は、 IoDeleteDevice を呼び出すことによって不要になったときにオブジェクトを削除します。

このルーチンは、オペレーティングシステムの一部ではありません。ドライバーは、Microsoft Windows 2000 以降のバージョンの Windows で Wdmsec.lib にリンクすることで、ルーチンを使用できます。 (Wdmsec.lib ライブラリは、最初にドライバー開発キット [DDK] の Microsoft Windows XP Service Pack 1 [SP1] および Windows Server 2003 エディションに付属し、Windows ドライバーキット [WDK] にも付属しています)。

INF ファイルによってセキュリティ記述子が設定されるとは限らない名前付きデバイスオブジェクトを作成するドライバーは、 WdmlibIoCreateDeviceSecure を使用する必要があります。詳細については、「デバイスオブジェクトの作成」を参照してください。呼び出し元は、返されたデバイスオブジェクトの特定のメンバーを設定する役割を担います。詳細については、「デバイスオブジェクトの初期化」およびデバイスのデバイスの種類固有のドキュメントを参照してください。

適切なパラメーターで DeviceType と DeviceCharacteristics の値を 指定するように注意してください。どちらのパラメーターもシステム定義のFILE_XXX 定数を使用し、一部のドライバーライターは間違って間違ったパラメーターの値を指定します。

呼び出し元は、返されたデバイスオブジェクトの特定のフィールド ( Flags フィールドなど) を設定し、ドライバーで定義された情報を使用してデバイス拡張機能を初期化する役割を担います。新しいデバイスオブジェクトに必要なその他の操作については、「デバイスオブジェクトの初期化」およびデバイスのデバイスの種類固有のドキュメントを参照してください。

DeviceClassGuid パラメーターで指定された GUID によって、デバイスオブジェクトのデバイスセットアップクラスが決まります。 (デバイスセットアップクラスの詳細については、「デバイスセットアップクラス」を参照してください)。呼び出し元は、システム管理者がデバイスのセキュリティ設定を変更できるように値を指定する必要があります (たとえば、特定のユーザーへのアクセスを拒否するため)。詳細については、「インストール後のデバイスオブジェクトレジストリプロパティの設定」を参照してください。

WDM 以外のドライバーは、既存のデバイスセットアップクラスでまだ使用されていない新しい GUID を指定します。 Microsoft Windows SDKに含まれている GuidGen.exe ツールを使用して、新しい GUID を生成します。

生モード対応デバイスを処理する WDM バスドライバーは、デバイスのデバイスセットアップクラスを指定できますが、そのクラスが既に作成されていることが保証されている場合にのみ指定できます。それ以外の場合は、新しい GUID を作成します。

ディスク、テープ、CD-ROM、RAM ディスクのデバイスオブジェクトには、ボリュームがデバイスにマウントされていないことを示すために初期化されたボリュームパラメーターブロック (VPB) が与えられます。

WdmlibIoCreateDeviceSecure へのドライバーの呼び出しでエラーが返された場合、ドライバーはそのデバイスに割り当てられたリソースを解放する必要があります。

要件

要件	値
サポートされている最小のクライアント	「解説」を参照してください。
対象プラットフォーム	デスクトップ
Header	wdmsec.h (Wdmsec.h を含む)
Library	Wdmsec.lib
IRQL	PASSIVE_LEVEL
DDI コンプライアンス規則	AddDevice(wdm)、 HwStorPortProhibitedDDIs(storport)、 IrqlIoPassive1(wdm)、MiniportOnlyWdmDevice