WriteProfileSectionA 関数 (winbase.h)

  • [アーティクル]

Win.ini ファイル内の指定したセクションの内容を、指定したキーと値に置き換えます。 Win.ini Unicode 文字を使用する場合、この関数は Unicode 文字をファイルに書き込みます。 それ以外の場合、関数は ANSI 文字を書き込みます。

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

構文

BOOL WriteProfileSectionA(
  [in] LPCSTR lpAppName,
  [in] LPCSTR lpString
);

パラメーター

[in] lpAppName

セクションの名前。 このセクション名は通常、呼び出し元アプリケーションの名前です。

[in] lpString

名前付きセクションに書き込まれる新しいキー名と関連付けられた値。 この文字列は 65,535 バイトに制限されています。

ファイルが存在し、Unicode 文字を使用して作成された場合、関数は Unicode 文字をファイルに書き込みます。 それ以外の場合、関数は ANSI 文字を使用してファイルを作成します。

戻り値

関数が成功すると、戻り値は 0 以外になります。

関数が失敗した場合は、0 を返します。 詳細なエラー情報を得るには、GetLastError を呼び出します。

解説

lpString バッファー内のキーと値は、1 つ以上の null で終わる文字列の後に最後の null 文字が続きます。 各文字列の形式は、 キー=文字列です。

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

WriteProfileSection は、名前付きセクションの既存のキーと値を削除し、 lpString が指すバッファーにキー名と値を挿入します。 関数は、古いキー名と新しいキー名を関連付けようとしません。新しい名前が古い名前とは異なる順序で表示される場合、初期化ファイル内の既存のキーと値に関連付けられているコメントは、おそらく正しくないキーと値に関連付けられます。

この操作はアトミックです。情報の書き込み中は、初期化ファイルに対して読み取りまたは書き込みを行う他の操作は許可されません。

システムは、パフォーマンスを向上させるために、最新のレジストリ ファイル マッピングのキャッシュされたバージョンを保持します。 すべてのパラメーターが NULL の場合、関数はキャッシュをフラッシュします。 システムがキャッシュされたバージョンのファイルを編集している間、ファイル自体を編集するプロセスでは、キャッシュがクリアされるまで元のファイルが使用されます。

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

HKEY_LOCAL_MACHINE
   SOFTWARE
      Microsoft
         Windows NT
            CurrentVersion
               IniFileMapping

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

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

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

要件

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

関連項目

GetProfileSection

WritePrivateProfileSection