SHRegGetValueW 関数 (shlwapi.h)

[アーティクル]
11/20/2024

[SHRegGetValue は、以降のバージョンのオペレーティングシステムまたは製品で変更または使用できない可能性があります。その場所 RegGetValue を使用します。]

レジストリ値を取得します。

構文

LSTATUS SHRegGetValueW(
  [in]      HKEY    hkey,
  [in]      LPCWSTR pszSubKey,
  [in]      LPCWSTR pszValue,
  [in]      SRRF    srrfFlags,
  [in, out] DWORD   *pdwType,
  [out]     void    *pvData,
  [in, out] DWORD   *pcbData
);

パラメーター

[in] hkey

型: HKEY

現在開いているキーへのハンドル、または次の定義済みの値のいずれか。

HKEY_CLASSES_ROOT

HKEY_CURRENT_CONFIG

HKEY_CURRENT_USER

HKEY_LOCAL_MACHINE

HKEY_PERFORMANCE_DATA

HKEY_USERS

[in] pszSubKey

型: LPCTSTR

null-terminated 文字列へのポインター。hkey から値を取得するサブキーへの相対パス指定します。このパラメーターには、NULL または空の文字列をできます。この場合、データは hkey の場所から取得されます。

[in] pszValue

型: LPCTSTR

値の名前を含む -terminated 文字列null へのポインター。このパラメーターには、NULL または空の文字列をできます。この場合、データは既定値から取得されます。

[in] srrfFlags

型: SRRF

取得するデータを制限する 1 つ以上の SRRF フラグ。少なくとも 1 つの型制限 (SRRF_RT) 値を指定する必要があります。

[in, out] pdwType

型: LPDWORD

取得した値に格納されているデータの型を受け取る DWORD へのポインター。既定値を使用する場合、pdwType 入力は既定値の型です。使用可能な値については、「レジストリデータ型」を参照してください。 SRRF_NOEXPAND フラグが設定されていない場合、REG_EXPAND_SZ型は自動的に展開され、REG_SZとして返されます。型情報が不要な場合、このパラメーターは NULLできます。

[out] pvData

型: LPVOID

値のデータを受け取るバッファーへのポインター。データが不要な場合、このパラメーターは NULL できます。たとえば、値の存在のみをテストしていた場合、特定の値データは余分になります。

[in, out] pcbData

型: LPDWORD

エントリ時に、pvData宛先データバッファーのサイズをバイト単位で格納する DWORD へのポインター。この値は、pvData が NULL場合にのみ、NULL できます。終了時に、pcbData はこれらの値のいずれかを指します。

pvData	戻り値	pcbData
NULL	ERROR_SUCCESS	レジストリデータを保持するのに十分なサイズ (バイト単位)。これは正確なサイズであるとは限りませんが、十分なサイズのみであることに注意してください。
非NULL	ERROR_SUCCESS	pvDataに書き込まれた正確なバイト数。
非NULL	ERROR_MORE_DATA	データ全体を保持するために必要なサイズ (バイト単位)。これは正確なサイズであるとは限りませんが、十分なサイズのみであることに注意してください。

戻り値

型: LSTATUS

成功した場合は ERROR_SUCCESS を返し、それ以外の場合は Winerror.h で定義された 0 以外のエラーコードを返します。 FormatMessage 関数を FORMAT_MESSAGE_FROM_SYSTEM フラグと共に使用して、エラーの一般的な説明を取得できます。

備考

SHRegGetValue では、データ型チェック、ブートモードチェック、REG_EXPAND_SZ データの自動拡張、およびREG_SZ、REG_EXPAND_SZ、およびREG_MULTI_SZデータの null終了保証されます。

hkey によって識別されるキーは、セキュリティアクセス KEY_QUERY_VALUE 使用して開かれている必要があります。 pszSubKey NULL または空の文字列されていない場合、そのキーは現在の呼び出し元のコンテキストで KEY_QUERY_VALUE セキュリティアクセスを使用して開くことができる必要もあります。

データの型がREG_SZ、REG_EXPAND_SZ、またはREG_MULTI_SZの場合、返されるデータには、文字列の null-termination が含まれるか、考慮されます。たとえば、pvData が NULLでない場合、そのバッファーで返されるデータは null-terminated されます。 pcbData が NULLされていない場合、指すバッファーサイズには、終端 null 文字を保持するために必要なバイトが含まれます。

SRRF_NOEXPAND フラグが設定されていない限り、REG_EXPAND_SZ型の文字列データは、返される前に自動的に展開されます。展開された文字列の型は、REG_SZ pdwType で報告されます。pcbData パラメーターは、展開された文字列に対して書き込まれたバイト数を指し、pvData 指すバッファーは、展開されたバージョンの文字列を保持します。

パフォーマンスに関する注意事項

pszSubKey が NULL または空の文字列されていない場合、そのキーはアクセスされるたびにこの関数によって開き、閉じられます。アプリケーションで同じサブキーから一連の値を取得する必要がある場合は、SHRegGetValueを呼び出す前に、RegOpenKeyEx を使用してキー開くと、パフォーマンスが向上します。この関数の hkey パラメーターとして RegOpenKey Ex の phkResult パラメーターで返されるキーを使用します。pszSubKey NULL設定します。

データ型がREG_EXPAND_SZされ、SRRF_NOEXPAND フラグが設定されていない場合に、レジストリを追加で呼び出してデータの読み取りまたは再読み取りを行う可能性があります。次の条件は、その追加の呼び出しになります。

pvData が NULL、pcbData が NULL。データは取得されませんが、レジストリを読み取って文字列を取得し、その文字列を展開してデータバッファーの必要なサイズを決定する必要があります。
pvData は NULLされませんが、データを保持するには小さすぎます。データは、完全な文字列を取得するために再読み取りされ、文字列が展開され、必要な合計サイズが決定されます。

手記

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

必要条件

要件	価値
サポートされる最小クライアント	Windows XP と SP2 [デスクトップアプリのみ]
サポートされる最小サーバー	Windows Server 2003 [デスクトップアプリのみ]
ターゲットプラットフォームの	ウィンドウズ
ヘッダー	shlwapi.h
ライブラリ	Shlwapi.lib
DLL	Shlwapi.dll (バージョン 6.0 以降)

次の方法で共有