WdfDeviceRetrieveDeviceInterfaceString 関数 (wdfdevice.h)

  • [アーティクル]

[KMDF と UMDF に適用]

WdfDeviceRetrieveDeviceInterfaceString メソッドは、ドライバーが指定したデバイスに登録したデバイス インターフェイスにオペレーティング システムが割り当てたシンボリック リンク名を取得します。

構文

NTSTATUS WdfDeviceRetrieveDeviceInterfaceString(
  [in]           WDFDEVICE        Device,
  [in]           const GUID       *InterfaceClassGUID,
  [in, optional] PCUNICODE_STRING ReferenceString,
  [in]           WDFSTRING        String
);

パラメーター

[in] Device

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

[in] InterfaceClassGUID

デバイス インターフェイス クラスを識別する GUID へのポインター。

[in, optional] ReferenceString

デバイス インターフェイスの参照文字列を記述する UNICODE_STRING 構造体へのポインター。 このパラメーターは省略可能であり、ドライバーが WdfDeviceCreateDeviceInterface を呼び出したときに参照文字列を指定しなかった場合は NULL にすることができます。

[in] String

フレームワーク文字列オブジェクトへのハンドル。 フレームワークは、シンボリック リンク名の Unicode 文字列を文字列オブジェクトに割り当てます。

戻り値

操作が成功した場合、WdfDeviceRetrieveDeviceInterfaceString はSTATUS_SUCCESSを返します。 それ以外の場合、メソッドは次のいずれかの値を返す可能性があります。

リターン コード 説明
STATUS_INVALID_DEVICE_REQUEST

WdfDeviceRetrieveDeviceInterfaceString は IRQL = PASSIVE_LEVELで呼び出されませんでした。
STATUS_INVALID_PARAMETER
 無効なパラメーターが指定されました。
STATUS_INVALID_DEVICE_REQUEST
 指定したデバイス オブジェクトが WdfControlDeviceInitAllocate によって初期化されました。
STATUS_OBJECT_NAME_NOT_FOUND
 指定した GUID と参照文字列に一致するデバイス インターフェイスが見つかりませんでした。
STATUS_INVALID_DEVICE_STATE
 WdfDeviceCreateDeviceInterface というドライバーが、システムでデバイス インターフェイスにシンボリック リンク名がまだ割り当てられていません。
 

WdfDeviceRetrieveDeviceInterfaceString は 、他の NTSTATUS 値も返す場合があります。

ドライバーが無効なオブジェクト ハンドルを提供すると、バグ チェックが発生します。

注釈

デバイス インターフェイスの詳細については、「デバイス インターフェイスの 使用」を参照してください。

例

次のコード例では、文字列オブジェクトを作成し、指定したデバイス インターフェイスのシンボリック リンク名を取得します。

NTSTATUS status;
WDFSTRING string;

status = WdfStringCreate(
                         NULL,
                         WDF_NO_OBJECT_ATTRIBUTES,
                         &string
                         );
if (NT_SUCCESS(status)) {
    status = WdfDeviceRetrieveDeviceInterfaceString(
                         Device,
                         &GUID_DEVINTERFACE_DDI_TEST1,
                         NULL,
                         string
                         );
    if (!NT_SUCCESS(status)) {
        return status;
    }
}

要件

要件 値
対象プラットフォーム ユニバーサル
最小 KMDF バージョン 1.0
最小 UMDF バージョン 2.0
Header wdfdevice.h (Wdf.h を含む)
Library Wdf01000.sys (KMDF);WUDFx02000.dll (UMDF)
IRQL PASSIVE_LEVEL
DDI コンプライアンス規則 DriverCreate(kmdf)、 KmdfIrql(kmdf)、 KmdfIrql2(kmdf)、KmdfIrqlExplicit(kmdf)

こちらもご覧ください

UNICODE_STRING

WdfControlDeviceInitAllocate

WdfDeviceCreateDeviceInterface

WdfStringCreate