GetProfileStringA 関数 (winbase.h)

  • [アーティクル]

Win.ini ファイルの指定したセクションのキーに関連付けられている文字列を取得します。

メモ この関数は、16 ビットの Windows ベースのアプリケーションとの互換性のためにのみ提供されるため、この関数はサーバー コードから呼び出さないでください。 アプリケーションでは、レジストリに初期化情報を格納する必要があります。
 

構文

DWORD GetProfileStringA(
  [in]  LPCSTR lpAppName,
  [in]  LPCSTR lpKeyName,
  [in]  LPCSTR lpDefault,
  [out] LPSTR  lpReturnedString,
  [in]  DWORD  nSize
);

パラメーター

[in] lpAppName

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

[in] lpKeyName

関連付けられた文字列を取得するキーの名前。 このパラメーターが NULL の場合、関数は指定されたセクション内のすべてのキーを指定されたバッファーにコピーします。 各文字列の後に null 文字が続き、最後の文字列の後に 2 番目の null 文字が続きます。

[in] lpDefault

既定の文字列。 初期化ファイルに lpKeyName キーが見つからない場合、 GetProfileString は既定の文字列を lpReturnedString バッファーに コピーします。 このパラメーターが NULL の場合、既定値は空の文字列 "" です。

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

[out] lpReturnedString

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

[in] nSize

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

戻り値

戻り値は、 null 終端文字を含まない、バッファーにコピーされた文字数です。

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

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

注釈

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

GetProfileString 関数では、大文字と小文字は区別されません。文字列には、大文字と小文字の組み合わせを含めることができます。

Win.ini ファイルのセクションには、次の形式が必要です。

[section]
key=string
      .
      .
      .

アプリケーションは GetPrivateProfileString 関数を使用して、指定された初期化ファイルから文字列を取得できます。

lpDefault パラメーターは、文字列が空の場合 (つまり、最初の文字が null 文字であっても) 有効な文字列を指す必要があります。

Windows Server 2003 および Windows XP/2000: プロファイル関数の呼び出しは、初期化ファイルではなくレジストリにマップできます。 このマッピングは、次のキーの下でレジストリで初期化ファイルとセクションが指定されている場合に発生します。

Hkey_local_machine\ソフトウェア\マイクロソフト\\ Windows NT CurrentVersion\IniFileMapping

操作がマップされると、 GetProfileString 関数は初期化ファイルからではなく、レジストリから情報を取得します。ストレージの場所の変更は、関数の動作には影響しません。

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

  1. IniFileMapping キーの下にある初期化ファイルの名前をレジストリで探します。
  2. lpAppName で指定されたセクション名を探します。 これは、初期化ファイルの名前を持つキーの名前付き値、またはこの名前を持つサブキーになります。または、名前が値またはサブキーとして存在しません。
  3. lpAppName で指定されたセクション名が名前付き値の場合、その値はレジストリ内のセクションのキーを検索する場所を指定します。
  4. lpAppName で指定されたセクション名がサブキーの場合、そのサブキーの名前付き値は、レジストリ内のセクションのキーを検索する場所を指定します。 探しているキーが名前付き値として存在しない場合は、キーを検索するレジストリの既定の場所を指定する名前のない値 (名前>なし)< が表示されます。
  5. lpAppName で指定されたセクション名が名前付き値またはサブキーとして存在しない場合は、名前のない値 (名前>なしとして<表示) があり、レジストリ内でセクションのキーを検索する既定の場所を指定します。
  6. セクション名のサブキーまたはエントリがない場合は、ディスク上の実際の初期化ファイルを探し、その内容を読み取ります。
他のレジストリの場所を指定するレジストリ内の値を見ると、.ini ファイル マッピングの動作を変更するプレフィックスがいくつかあります。
  • ! - この文字により、すべての書き込みがレジストリとディスク上の .ini ファイルの両方に強制的に移動されます。
  • # - この文字により、新しいユーザーがセットアップ後に初めてログインしたときに、レジストリ値が Windows 3.1 .ini ファイルの値に設定されます。
  • @ - この文字は、要求されたデータがレジストリに見つからない場合に、ディスク上の .ini ファイルに読み取りが行われるのを防ぎます。
  • USR: - このプレフィックスは HKEY_CURRENT_USERを表し、プレフィックスの後のテキストはそのキーに対して相対的です。
  • SYS: - このプレフィックスは HKEY_LOCAL_MACHINE\SOFTWAREを表し、プレフィックスの後のテキストはそのキーに対して相対的です。

注意

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

要件

要件 値
サポートされている最小のクライアント Windows 2000 Professional [デスクトップ アプリのみ]
サポートされている最小のサーバー Windows 2000 Server [デスクトップ アプリのみ]
対象プラットフォーム Windows
ヘッダー winbase.h (Windows.h を含む)
Library Kernel32.lib
[DLL] Kernel32.dll

関連項目

GetPrivateProfileString

WriteProfileString