SHRegGetValueA 関数 (shlwapi.h)

[アーティクル]
03/05/2024

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

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

構文

LSTATUS SHRegGetValueA(
  [in]      HKEY   hkey,
  [in]      LPCSTR pszSubKey,
  [in]      LPCSTR 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

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

[in] pszValue

型: LPCTSTR

値の名前を含む 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 終端が含まれるか、または考慮されます。たとえば、 pvData が NULL でない場合、そのバッファーで返されるデータは null で終了します。 pcbData が NULL でない場合、それが指すバッファーサイズには、終端の null 文字を保持するために必要なバイトが含まれます。

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

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

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

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

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

注意

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

要件

要件	値
サポートされている最小のクライアント	WINDOWS XP と SP2 [デスクトップアプリのみ]
サポートされている最小のサーバー	Windows Server 2003 (デスクトップアプリのみ)
対象プラットフォーム	Windows
ヘッダー	shlwapi.h
Library	Shlwapi.lib
[DLL]	Shlwapi.dll (バージョン 6.0 以降)

こちらもご覧ください

RegQueryValueEx