GetPrivateProfileString

https://msdn.microsoft.com/ja-jp/library/cc410902.aspx

指定された .ini ファイル(初期化ファイル)の指定されたセクション内にある、指定されたキーに関連付けられている文字列を取得します。

注意  この関数は、16 ビット Windows ベースのアプリケーションとの互換性を保つ目的でのみ提供されています。Win32 ベースのアプリケーションでは、初期化情報をレジストリに格納してください。

DWORD GetPrivateProfileString(
  LPCTSTR lpAppName,        // セクション名
  LPCTSTR lpKeyName,        // キー名
  LPCTSTR lpDefault,        // 既定の文字列
  LPTSTR lpReturnedString,  // 情報が格納されるバッファ
  DWORD nSize,              // 情報バッファのサイズ
  LPCTSTR lpFileName        // .ini ファイルの名前
);

パラメータ

lpAppName
目的のキーが所属しているセクションの名前を保持している、NULL で終わる文字列へのポインタを指定します。NULL を指定すると、この関数は、lpFileName パラメータで指定したファイル内のすべてのセクション名をバッファへコピーします。
lpKeyName
1 個のキーの名前を保持している、NULL で終わる文字列へのポインタを指定します。このキーに関連付けられている文字列が、バッファに格納されます。NULL を指定すると、この関数は、lpAppName パラメータで指定したセクション内にあるすべてのキー名を、lpReturnedString パラメータで指定したバッファに格納します。
lpDefault
NULL で終わる既定の文字列へのポインタを指定します。lpKeyName パラメータで指定したキーが .ini ファイル内に見つからなかった場合、GetPrivateProfileString 関数はこの既定の文字列を、lpReturnedString パラメータが指すバッファへコピーします。lpDefault パラメータで NULL を指定することはできません。

半角スペースで終わる文字列を既定の文字列として指定することは避けてください。この関数は、lpReturnedString パラメータが指すバッファへ文字列をコピーする際に、文字列の最後に NULL を追加しますが、このとき、文字列の最後にある任意の数の半角スペースは削除されます。

Windows 95:lpDefault は定数パラメータ(LPTSTR ではなく LPCTSTR)と宣言されていますが、システムは lpDefault パラメータが指す文字列に NULL を追加した上で、lpReturnedString パラメータが指すバッファへこの文字列をコピーすることにより、文字列の最後にある任意の数の半角スペースを削除します。

Windows NT/2000:システムは、lpDefault パラメータが指す文字列に変更を加えません。既定の文字列の最後に半角スペースが存在する場合、 関数を使って lpReturnedString lpDefault の各文字列を比較すると、これらの文字列が一致しないことを意味します。

lpReturnedString
1 個のバッファへのポインタを指定します。関数から制御が返ると、このバッファに、取得した文字列が格納されます。
nSize
lpReturnedString パラメータが指すバッファのサイズを、TCHAR 単位で指定します。
lpFileName
.ini ファイルの名前を保持している、NULL で終わる文字列へのポインタを指定します。ファイルのフルパス名を指定しなかった場合、システムは Windows ディレクトリ内でこのファイルを検索します。

戻り値

関数が成功すると、バッファに格納された文字数が返ります(終端の NULL 文字は含まない)。

lpAppName lpKeyName パラメータのどちらも NULL ではない場合、バッファのサイズが不足して、要求された文字列全体を格納できないと、文字列は途中で切り捨てられ、最後に 1 個の NULL 文字が追加され、戻り値は nSize-1 の値になります。

lpAppName または lpKeyName パラメータのどちらかが NULL の場合、バッファのサイズが不足して、要求された文字列全体を格納できないと、文字列は途中で切り捨てられ、最後に 2 個の NULL 文字が追加され、戻り値は nSize-2 の値になります。

解説

GetPrivateProfileString 関数は、指定された .ini ファイル内で、lpAppName パラメータで指定されたセクションの見出しの下から、lpKeyName パラメータで指定された名前に一致するキーを検索します。キーが見つかった場合、そのキーに対応する文字列をバッファへコピーします。キーが見つからなかった場合、lpDefault パラメータで指定された既定の文字列をコピーします。.ini ファイル内のセクションは、次の形式で記述しなければなりません。

[section]
key=string
      .
      .
      .

lpAppName パラメータで NULL を指定すると、GetPrivateProfileString 関数はファイル内のすべてのセクション名を、指定されたバッファへコピーします。lpKeyName パラメータで NULL を指定すると、指定されたセクション内のすべてのキー名を、指定されたバッファへコピーします。アプリケーションはこれらの方法を使うと、特定のファイル内のすべてのセクションとキーを列挙できます。どちらの場合でも、各文字列の後に 1 個の NULL が追加され、最後の文字列の後にはもう 1 個の NULL が追加されます。指定されたコピー先のバッファが小さすぎて一部の文字列を格納できない場合、最後の文字列は切り捨てられ、最後に 2 個の NULL が追加されます。

lpKeyName パラメータで指定したキー名に関連付けられている文字列が引用符(')または二重引用符(")で囲まれている場合、GetPrivateProfileString 関数はその文字列を取得する際にこれらの引用符を取り除きます。

GetPrivateProfileString 関数は、大文字と小文字を区別しません。文字列では、大文字と小文字の任意の組み合わせを指定できます。

アプリケーションは GetProfileString 関数を使うと、Win.ini ファイルから文字列を取得できます。

Windows NT/2000:特定の .ini ファイルを使う代わりに、プライベートプロファイル関数を、レジストリへマッピングすることもできます。レジストリの次のキーで .ini ファイルとセクションを指定すると、このようなマッピングが発生します。

HKEY_LOCAL_MACHINE\Software\Microsoft\
        Windows NT\CurrentVersion\IniFileMapping

アプリケーションが、Control.ini、System.ini、Winfile.ini のようなシステムコンポーネントの .ini ファイルを変更する場合に、一般的にこのマッピングを行います。このような状況では、GetPrivateProfileString 関数は .ini ファイルではなくレジストリから情報を取得します。情報の格納場所(取得元)が .ini ファイルからレジストリになっても、この関数の動作に変化はありません。

Win32 のプロファイル関数(Get/WriteProfile* Get/WritePrivateProfile*)は、次の手順に従って初期化情報を検索します。

1.Win32 のプロファイル関数は、レジストリの IniFileMapping キーの中で、指定された .ini ファイル、たとえば myFile.ini を検索します。

HKEY_LOCAL_MACHINE\Software\Microsoft\
        Windows NT\CurrentVersion\IniFileMapping\myfile.ini

2.lpAppName パラメータで指定されたセクション名を検索します。このセクション名が見つかった場合、そのセクション名は、myfile.ini ファイル内の名前付きの値(エントリ)、または myfile.ini のサブキーです。ほかに、このセクション名が見つからないこともあります。

3.lpAppName パラメータで指定したセクション名が myfile.ini 内の名前付きの値である場合、その値が示すレジストリ内の特定の場所(マップ先)で、そのセクションに所属するキーの検索を行います。

4.lpAppName パラメータで指定したセクション名が myfile.ini のサブキーである場合、そのサブキー内の名前付きの値が示すレジストリ内の特定の場所(マップ先)で、キーの検索を行います。検索対象のキーが名前付きの値として存在していない場合、名前なしの値(<No Name>、日本語版では <名前なし>)が示すレジストリ内の既定の場所で、キーの検索を行います。

5.lpAppName パラメータで指定したセクション名が、myfile.ini 内の名前付きの値としてもサブキーとしても存在していない場合、myfile.ini 内の名前なしの値(<No Name>、日本語版では <名前なし>)が示すレジストリ内の既定の場所で、そのセクションに所属するキーの検索を行います。

6.myfile.ini 内にサブキーが存在せず、指定したセクション名に対応するエントリも存在しない場合は、ディスク上で実際の myfile.ini ファイルを検索し、その内容を読み取ります。

レジストリ内の特定のレジストリエントリが、レジストリ内の他の場所を指定している場合、次の各プレフィックスは、.ini ファイルのマッピングの動作方法に変更を加えます。

レジストリエディタ(Regedt32.exe または Regedit.exe)は、ここで言う「レジストリエントリ」を「値」(英語版は Value)と呼んでいます。どちらも同じものを意味していて、「名前」(レジストリエントリ名)と「データ」(レジストリエントリのデータ)で構成されています。

•! - すべての変更結果を、レジストリとディスク上のファイルの両方へ書き込みます。

•# - セットアップ後に新しいユーザーが初めてログオンする際に、Windows 3.1 の .ini ファイルの値に合わせて、レジストリエントリのデータを設定します。

•@ - 要求された値がレジストリ内に見つからない場合、ディスク上の .ini ファイルからその値を読み取りません。

•USR: - このプレフィックスは、HKEY_CURRENT_USER を意味します。それ以降のテキストは、このキーを基準とする相対キーを意味します。

•SYS: - このプレフィックスは、HKEY_LOCAL_MACHINE\SOFTWARE を意味します。それ以降のテキストは、このキーを基準とする相対キーを意味します。

対応情報

Windows NT/2000:Windows NT 3.1 以降
Windows 95/98:Windows 95 以降
ヘッダー:Winbase.h 内で宣言、Windows.h をインクルード
インポートライブラリ:Kernel32.lib を使用
Unicode:Windows NT/2000 は Unicode 版と ANSI 版を実装

参照

GetProfileString, WritePrivateProfileString

表示: