WritePrivateProfileSectionA 関数 (winbase.h)
初期化ファイル内の指定したセクションのキーと値を置き換えます。
構文
BOOL WritePrivateProfileSectionA(
[in] LPCSTR lpAppName,
[in] LPCSTR lpString,
[in] LPCSTR lpFileName
);
パラメーター
[in] lpAppName
データが書き込まれるセクションの名前。 このセクション名は、通常、呼び出し元のアプリケーションの名前です。
[in] lpString
名前付きセクションに書き込まれる新しいキー名と関連付けられた値。 この文字列は 65,535 バイトに制限されています。
[in] lpFileName
初期化ファイルの名前。 このパラメーターにファイルの完全なパスが含まれていない場合、関数は Windows ディレクトリでファイルを検索します。 ファイルが存在せず、 lpFileName に 完全なパスが含まれていない場合、関数は Windows ディレクトリにファイルを作成します。
ファイルが存在し、Unicode 文字を使用して作成された場合、関数は Unicode 文字をファイルに書き込みます。 それ以外の場合、関数は ANSI 文字を使用してファイルを作成します。
戻り値
関数が成功すると、戻り値は 0 以外になります。
関数が失敗した場合は、0 を返します。 詳細なエラー情報を得るには、GetLastError を呼び出します。
解説
lpString パラメーターが指すバッファー内のデータは、1 つ以上の null で終わる文字列で構成され、その後に最後の null 文字が続きます。 各文字列の形式は次のとおりです。
キー=文字列
WritePrivateProfileSection 関数では大文字と小文字は区別されません。lpAppName パラメーターが指す文字列には、大文字と小文字の組み合わせを指定できます。
lpAppName パラメーターが指す文字列と一致するセクション名がない場合、WritePrivateProfileSection は、指定した初期化ファイルの末尾にセクションを作成し、指定したキー名と値のペアで新しいセクションを初期化します。
WritePrivateProfileSection は、名前付きセクションの既存のキーと値を削除し、 lpString パラメーターが指すバッファーにキーの名前と値を挿入します。 関数は、古いキー名と新しいキー名を関連付けようとしません。新しい名前が古い名前とは異なる順序で表示される場合、初期化ファイル内の既存のキーと値に関連付けられているコメントは、誤ったキーと値に関連付けられる可能性があります。
この操作はアトミックです。情報の書き込み中に、指定された初期化ファイルに対する読み取りまたは書き込み操作は許可されません。
システムは、パフォーマンスを向上させるために、最新のレジストリ ファイル マッピングのキャッシュ されたバージョンを保持します。 すべてのパラメーターが NULL の場合、関数はキャッシュをフラッシュします。 システムがキャッシュされたバージョンのファイルを編集している間、ファイル自体を編集するプロセスでは、キャッシュがクリアされるまで元のファイルが使用されます。
システムは、次のレジストリ キーで定義されたマッピングを使用して、ほとんどの .ini ファイル参照をレジストリにマップします。
HKEY_LOCAL_MACHINE SOFTWARE Microsoft Windows NT CurrentVersion IniFileMapping
このマッピングは、アプリケーションがシステム コンポーネントの初期化ファイル (Control.ini、System.ini、Winfile.ini など) を変更する場合に発生する可能性があります。 この場合、関数は初期化ファイルではなくレジストリに情報を書き込みます。ストレージの場所の変更は、関数の動作には影響しません。
プロファイル関数では、次の手順を使用して初期化情報を検索します。
- IniFileMapping キーの下にある初期化ファイルの名前をレジストリで探します。
- lpAppName で指定されたセクション名を探します。 これは、初期化ファイルの名前を持つキーの名前付き値、またはこの名前を持つサブキーになります。または、名前が値またはサブキーとして存在しません。
- lpAppName で指定されたセクション名が名前付き値の場合、その値はレジストリ内のセクションのキーを検索する場所を指定します。
- lpAppName で指定されたセクション名がサブキーの場合、そのサブキーの名前付き値は、レジストリ内のセクションのキーを検索する場所を指定します。 探しているキーが名前付き値として存在しない場合は、キーを検索するレジストリの既定の場所を指定する名前のない値 (名前>なし)< が表示されます。
- lpAppName で指定されたセクション名が名前付き値またはサブキーとして存在しない場合は、名前のない値 (名前>なしとして<表示) があり、レジストリ内でセクションのキーを検索する既定の場所を指定します。
- セクション名のサブキーまたはエントリがない場合は、ディスク上の実際の初期化ファイルを探し、その内容を読み取ります。
- ! - この文字により、すべての書き込みがレジストリとディスク上の .ini ファイルの両方に強制的に移動されます。
- # - この文字により、新しいユーザーがセットアップ後に初めてログインしたときに、レジストリ値が Windows 3.1 .ini ファイルの値に設定されます。
- @ - この文字は、要求されたデータがレジストリに見つからない場合に、ディスク上の .ini ファイルに読み取りが行われるのを防ぎます。
- USR: - このプレフィックスは HKEY_CURRENT_USERを表し、プレフィックスの後のテキストはそのキーに対して相対的です。
- SYS: - このプレフィックスは HKEY_LOCAL_MACHINE\SOFTWAREを表し、プレフィックスの後のテキストはそのキーに対して相対的です。
注意
winbase.h ヘッダーは、WritePrivateProfileSection をエイリアスとして定義し、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択します。 encoding-neutral エイリアスの使用を encoding-neutral ではないコードと混在すると、コンパイル エラーまたはランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「 関数プロトタイプの規則」を参照してください。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows 2000 Professional [デスクトップ アプリのみ] |
| サポートされている最小のサーバー | Windows 2000 Server [デスクトップ アプリのみ] |
| 対象プラットフォーム | Windows |
| ヘッダー | winbase.h (Windows.h を含む) |
| Library | Kernel32.lib |
| [DLL] | Kernel32.dll |