SetupDiGetCustomDevicePropertyW 関数 (setupapi.h)

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

SetupDiGetCustomDeviceProperty 関数は、レジストリから指定されたカスタムデバイスプロパティを取得します。

構文

WINSETUPAPI BOOL SetupDiGetCustomDevicePropertyW(
  [in]            HDEVINFO         DeviceInfoSet,
  [in]            PSP_DEVINFO_DATA DeviceInfoData,
  [in]            PCWSTR           CustomPropertyName,
  [in]            DWORD            Flags,
  [out, optional] PDWORD           PropertyRegDataType,
  [out]           PBYTE            PropertyBuffer,
  [in]            DWORD            PropertyBufferSize,
  [out, optional] PDWORD           RequiredSize
);

パラメーター

[in] DeviceInfoSet

カスタムデバイスプロパティを取得するデバイスを表すデバイス情報要素を含むデバイス情報セットへのハンドル。

[in] DeviceInfoData

DeviceInfoSet のデバイス情報要素を指定するSP_DEVINFO_DATA構造体へのポインター。

[in] CustomPropertyName

カスタムプロパティを表すレジストリ値の名前。

[in] Flags

要求された情報を返す方法を示すフラグ値。フラグには、0 または次のいずれかを指定できます。

DICUSTOMDEVPROP_MERGE_MULTISZ

設定した場合、この関数は、デバイスインスタンス固有のプロパティ値とハードウェア ID 固有のプロパティ値の両方を取得し、REG_MULTI_SZ型指定の文字列として連結します。 (詳細については、このリファレンスページの 「解説 」セクションを参照してください)。

[out, optional] PropertyRegDataType

取得したプロパティのデータ型を受け取る DWORD 型の変数へのポインター。データ型は、レジストリデータ型を表すREG_プレフィックス付き定数の 1 つとして指定されます。このパラメーターは省略可能であり、 NULL にすることができます。

[out] PropertyBuffer

要求されたプロパティ情報を受け取るバッファーへのポインター。

[in] PropertyBufferSize

PropertyBuffer バッファーのサイズ (バイト単位)。

[out, optional] RequiredSize

要求された情報を受信するために必要なバッファーサイズ (バイト単位) を受け取る DWORD 型の変数へのポインター。このパラメーターは省略可能であり、 NULL にすることができます。このパラメーターを指定すると、PropertyBuffer バッファーが要求された情報を受信するのに十分な大きさであるかどうかに関係なく、SetupDiGetCustomDeviceProperty は必要なサイズを返します。

戻り値

操作が成功した場合、 SetupDiGetCustomDeviceProperty はTRUE を返します。それ以外の場合、関数は FALSE を 返し、ログに記録されたエラーを GetLastError の呼び出しで取得できます。 PropertyBuffer バッファーが要求された情報を受信するのに十分な大きさでない場合、SetupDiGetCustomDeviceProperty は FALSE を返し、その後の GetLastError の呼び出しはERROR_INSUFFICIENT_BUFFERを返します。

注釈

SetupDiGetCustomDeviceProperty は、1 つのデバイスインスタンスまたは特定のハードウェア ID に一致するすべてのデバイスに関連付けられているデバイスプロパティを取得します。 (ハードウェア ID の詳細については、「デバイス識別文字列」を参照してください)。

ベンダーは、INF DDInstall.HW セクションで INF AddReg ディレクティブを使用し、HKR レジストリルートを指定することで、デバイスインスタンスのプロパティを設定できます。

ハードウェア ID のプロパティを設定できるのは、システムだけです。システムは、一部のハードウェア ID に対して "Icon" プロパティを提供します。

関数は最初に、指定したデバイスインスタンスに対して指定したプロパティが存在するかどうかを確認します。その場合、プロパティの値が返されます。そうでない場合、関数は、指定されたデバイスインスタンスのハードウェア ID に一致するすべてのデバイスに対してプロパティが存在するかどうかを確認します。その場合、プロパティの値が返されます。 DICUSTOMDEVPROP_MERGE_MULTISZ が Flags で設定されている場合、この関数は、デバイスインスタンスとハードウェア ID の両方に関連付けられているプロパティ値 (両方が存在する場合) を返します。

注意

setupapi.h ヘッダーは、Unicode プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択するエイリアスとして SetupDiGetCustomDeviceProperty を定義します。エンコードに依存しないエイリアスをエンコードニュートラルでないコードと組み合わせて使用すると、コンパイルまたはランタイムエラーが発生する不一致が発生する可能性があります。詳細については、「関数プロトタイプの規則」を参照してください。

要件

要件	値
サポートされている最小のクライアント	Windows XP 以降のバージョンの Windows で使用できます。
対象プラットフォーム	デスクトップ
Header	setupapi.h (Setupapi.h を含む)
Library	Setupapi.lib
[DLL]	Setupapi.dll