WdfControlDeviceInitAllocate 関数 (wdfcontrol.h)

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

[KMDF にのみ適用]

WdfControlDeviceInitAllocate メソッドは、ドライバーが新しいコントロールデバイスオブジェクトを作成するときに使用するWDFDEVICE_INIT構造体を割り当てます。

構文

PWDFDEVICE_INIT WdfControlDeviceInitAllocate(
  [in] WDFDRIVER            Driver,
  [in] const UNICODE_STRING *SDDLString
);

パラメーター

[in] Driver

フレームワークドライバーオブジェクトへのハンドル。

[in] SDDLString

Unicode 文字列を記述するUNICODE_STRING 構造体へのポインター。この文字列は、セキュリティ記述子のセキュリティ記述子定義言語 (SDDL) 表現です。詳細については、「解説」を参照してください。

戻り値

操作が成功した場合、WdfControlDeviceInitAllocate はフレームワークによって割り当てられたWDFDEVICE_INIT構造体へのポインターを返します。それ以外の場合、メソッドは NULL を返します。

注釈

ドライバーでコントロールデバイスオブジェクトを作成する場合、ドライバーは WdfControlDeviceInitAllocate を呼び出して、WdfDeviceCreate に渡すことができるWDFDEVICE_INIT構造体を取得する必要があります。

ドライバーは、SDDL のサブセットを使用してセキュリティ設定を指定できます。 Wdmsec.h ファイルは、使用できる一連のSDDL_DEVOBJ_Xxx 形式の定数を定義します。セキュリティ記述子と SDDL の詳細については、「デバイスオブジェクトのセキュリティ保護」を参照してください。

WdfDeviceInitAssignSDDLString メソッドは、WdfControlDeviceInitAllocate で指定されているセキュリティ設定 (存在する場合) を上書きします。

WdfControlDeviceInitAllocate の呼び出しの詳細については、「コントロールデバイスオブジェクトの使用」を参照してください。

例

次のコード例では、DEVICE_INIT構造体を割り当て、デバイスオブジェクト名を割り当て、シャットダウン通知コールバック関数を登録し、コントロールデバイスオブジェクトを作成します。 WdfControlDeviceInitAllocate を使用するより複雑な例については、NONPNP サンプルドライバーまたは NDISProt サンプルドライバーを参照してください。

PWDFDEVICE_INIT  deviceInit = NULL;
NTSTATUS  status;
WDF_OBJECT_ATTRIBUTES  objectAttribs;

deviceInit = WdfControlDeviceInitAllocate(
                                          hDriver,
                                          &SDDL_DEVOBJ_SYS_ALL_ADM_RWX_WORLD_RW_RES_R
                                          );
if (deviceInit == NULL) {
    status = STATUS_INSUFFICIENT_RESOURCES;
    goto Error;
}
status = WdfDeviceInitAssignName(
                                 deviceInit,
                                 &ntDeviceName
                                 );
if (!NT_SUCCESS(status)) {
    WdfDeviceInitFree(deviceInit);
    deviceInit = NULL;
    goto Error;
}
WdfControlDeviceInitSetShutdownNotification(
                                            deviceInit,
                                            EvtShutdownNotification,
                                            WdfDeviceShutdown
                                            );
WDF_OBJECT_ATTRIBUTES_INIT(&objectAttribs);

status = WdfDeviceCreate(
                         &deviceInit,
                         &objectAttribs,
                         &controlDevice
                         );
if (!NT_SUCCESS(status)) {
    WdfDeviceInitFree(deviceInit);
    deviceInit = NULL;
    goto Error;
}
WdfControlFinishInitializing(controlDevice);

要件

要件	値
対象プラットフォーム	ユニバーサル
最小 KMDF バージョン	1.0
Header	wdfcontrol.h (Wdf.h を含む)
Library	Wdf01000.sys (「Framework ライブラリのバージョン管理」を参照)。
IRQL	PASSIVE_LEVEL
DDI コンプライアンス規則	ControlDeviceInitAPI(kmdf)、 CtlDeviceFinishInitDeviceAdd(kmdf)、 CtlDeviceFinishInitDrEntry(kmdf)、 DoubleDeviceInitFree(kmdf)、 DriverCreate(kmdf)、 InitFreeDeviceCallback(kmdf)、 InitFreeDeviceCreate(kmdf)、 InitFreeDeviceCreateType2(kmdf)、 InitFreeDeviceCreateType4(kmdf)、 KmdfIrql(kmdf)、 KmdfIrql2(kmdf)、KmdfIrqlExplicit(kmdf)