GetPrivateProfileString 関数 (winbase.h)

初期化ファイル内の指定したセクションから文字列を取得します。

構文

DWORD GetPrivateProfileString(
  [in]  LPCTSTR lpAppName,
  [in]  LPCTSTR lpKeyName,
  [in]  LPCTSTR lpDefault,
  [out] LPTSTR  lpReturnedString,
  [in]  DWORD   nSize,
  [in]  LPCTSTR lpFileName
);

パラメーター

[in] lpAppName

キー名を含むセクションの名前。 このパラメーターが NULL の場合、 GetPrivateProfileString 関数は、ファイル内のすべてのセクション名を指定されたバッファーにコピーします。

[in] lpKeyName

関連付けられた文字列を取得するキーの名前。 このパラメーターが NULL の場合、 lpAppName パラメーターで指定されたセクション内のすべてのキー名が lpReturnedString パラメーターで指定されたバッファーにコピーされます。

[in] lpDefault

既定の文字列。 初期化ファイルに lpKeyName キーが見つからない場合、 GetPrivateProfileString は既定の文字列を lpReturnedString バッファーに コピーします。

このパラメーターが NULL の場合、既定値は空の文字列 "" です。

末尾に空白文字を含む既定の文字列を指定しないでください。 この関数は、lpReturnedString バッファーに null 文字を挿入して、末尾の空白を取り除きます。

[out] lpReturnedString

取得した文字列を受け取るバッファーへのポインター。

[in] nSize

lpReturnedString パラメーターが指すバッファーのサイズ (文字単位)。

[in] lpFileName

初期化ファイルの名前。 このパラメーターにファイルへの完全なパスが含まれていない場合、システムは Windows ディレクトリ内のファイルを検索します。

戻り値

戻り値は、バッファーにコピーされた文字数であり、終端の null 文字は含まれません。

lpAppName も lpKeyName も NULL でもなく、指定された宛先バッファーが小さすぎて要求された文字列を保持できない場合、文字列は切り捨てられ、その後に null 文字が続き、戻り値は nSize から 1 を引いた値になります。

lpAppName または lpKeyName が NULL で、指定された宛先バッファーが小さすぎてすべての文字列を保持できない場合、最後の文字列は切り捨てられ、その後に 2 つの null 文字が続きます。 この場合、戻り値は nSize から 2 を引いた値と等しくなります。

lpFileName で指定された初期化ファイルが見つからない場合、または無効な値が含まれている場合、GetLastError を呼び出すと '0x2' (ファイルが見つかりません) が返されます。 拡張エラー情報を取得するには、 GetLastError を呼び出します。

注釈

GetPrivateProfileString 関数は、lpAppName パラメーターで指定されたセクション見出しの下にある lpKeyName パラメーターで指定された名前と一致するキーを、指定された初期化ファイルで検索します。 キーが見つかると、関数は対応する文字列をバッファーにコピーします。 キーが存在しない場合、関数は lpDefault パラメーターで指定された既定の文字列をコピーします。 初期化ファイルのセクションには、次の形式が必要です。

[section]
key=string
      .
      .
      .

lpAppName が NULL の場合、GetPrivateProfileString は指定されたファイル内のすべてのセクション名を指定されたバッファーにコピーします。 lpKeyName が NULL の場合、関数は指定されたセクション内のすべてのキー名を指定されたバッファーにコピーします。 アプリケーションでは、このメソッドを使用して、ファイル内のすべてのセクションとキーを列挙できます。 どちらの場合も、各文字列の後に null 文字が続き、最後の文字列の後に 2 番目の null 文字が続きます。 指定された宛先バッファーが小さすぎてすべての文字列を保持できない場合、最後の文字列は切り捨てられ、その後に 2 つの null 文字が続きます。

lpKeyName に関連付けられている文字列が単一引用符または二重引用符で囲まれている場合、GetPrivateProfileString 関数が文字列を取得すると、マークは破棄されます。

GetPrivateProfileString 関数では大文字と小文字は区別されません。文字列には、大文字と小文字の組み合わせを使用できます。

Win.ini ファイルから文字列を取得するには、 GetProfileString 関数を使用します。

システムは、次のレジストリ キーで定義されているマッピングを使用して、ほとんどの .ini ファイル参照をレジストリにマップします:HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\IniFileMapping

このマッピングは、アプリケーションがシステム コンポーネントの初期化ファイル (Control.ini、System.ini、Winfile.ini など) を変更する場合に発生する可能性があります。 このような場合、関数は初期化ファイルからではなく、レジストリから情報を取得します。ストレージの場所の変更は、関数の動作には影響しません。

プロファイル関数では、次の手順を使用して初期化情報を検索します。

1. IniFileMapping キーの下にある初期化ファイルの名前をレジストリで探します。
2. lpAppName で指定されたセクション名を探します。 これは、初期化ファイルの名前を持つキーの名前付き値、またはこの名前を持つサブキーになります。または、名前が値またはサブキーとして存在しません。
3. lpAppName で指定されたセクション名が名前付き値の場合、その値はレジストリ内のセクションのキーを検索する場所を指定します。
4. lpAppName で指定されたセクション名がサブキーの場合、そのサブキーの名前付き値は、レジストリ内のセクションのキーを検索する場所を指定します。 探しているキーが名前付き値として存在しない場合は、キーを検索するレジストリの既定の場所を指定する名前のない値 (名前>なし)< が表示されます。
5. lpAppName で指定されたセクション名が名前付き値またはサブキーとして存在しない場合は、名前のない値 (名前>なしとして<表示) があり、レジストリ内でセクションのキーを検索する既定の場所を指定します。
6. セクション名のサブキーまたはエントリがない場合は、ディスク上の実際の初期化ファイルを探し、その内容を読み取ります。

• ! - この文字により、すべての書き込みがレジストリとディスク上の .ini ファイルの両方に強制的に移動されます。
• # - この文字により、新しいユーザーがセットアップ後に初めてログインしたときに、レジストリ値が Windows 3.1 .ini ファイルの値に設定されます。
• @ - この文字は、要求されたデータがレジストリに見つからない場合に、ディスク上の .ini ファイルに読み取りが行われるのを防ぎます。
• USR: - このプレフィックスは HKEY_CURRENT_USERを表し、プレフィックスの後のテキストはそのキーに対して相対的です。
• SYS: - このプレフィックスは HKEY_LOCAL_MACHINE\SOFTWAREを表し、プレフィックスの後のテキストはそのキーに対して相対的です。

例

次の例では、 GetPrivateProfileString の使用方法を示します。

// Gets a profile string called "Preferred line" and converts it to an int.
GetPrivateProfileString (
      "Preference",
      "Preferred Line",
      gszNULL, 
      szBuffer,
      MAXBUFSIZE,
      gszINIfilename
);

// if szBuffer is not empty.
if ( lstrcmp ( gszNULL, szBuffer ) )
{
      dwPreferredPLID = (DWORD) atoi( szBuffer );	
}
else	
{
      dwPreferredPLID = (DWORD) -1;
}

要件

関連項目

GetProfileString

WritePrivateProfileString