WritePrivateProfileStringA 関数 (winbase.h)

[アーティクル]
08/27/2023

初期化ファイルの指定したセクションに文字列をコピーします。

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

構文

BOOL WritePrivateProfileStringA(
  [in] LPCSTR lpAppName,
  [in] LPCSTR lpKeyName,
  [in] LPCSTR lpString,
  [in] LPCSTR lpFileName
);

パラメーター

[in] lpAppName

文字列のコピー先となるセクションの名前。セクションが存在しない場合は作成されます。セクションの名前は大文字と小文字が区別されません。文字列は、大文字と小文字の任意の組み合わせにすることができます。

[in] lpKeyName

文字列に関連付けるキーの名前。指定したセクションにキーが存在しない場合は、キーが作成されます。このパラメーターが NULL場合、セクション内のすべてのエントリを含むセクション全体が削除されます。

[in] lpString

null-terminated 文字列がファイルに書き込まれます。このパラメーターが NULL場合は、lpKeyName パラメーターが指すキーが削除されます。

[in] lpFileName

初期化ファイルの名前。

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

戻り値

関数が初期化ファイルに文字列を正常にコピーした場合、戻り値は 0 以外です。

関数が失敗した場合、または最近アクセスした初期化ファイルのキャッシュされたバージョンをフラッシュした場合、戻り値は 0 になります。拡張エラー情報を取得するには、GetLastError呼び出します。

備考

初期化ファイルのセクションは、次の形式である必要があります。

[section]
key=string
      .
      .
      .

lpFileName パラメーターにファイルの完全なパスとファイル名が含まれていない場合は、WritePrivateProfileString ファイルの Windows ディレクトリを検索します。ファイルが存在しない場合、この関数は Windows ディレクトリにファイルを作成します。

lpFileName に完全なパスとファイル名が含まれており、ファイルが存在しない場合は、WritePrivateProfileString ファイルが作成されます。指定したディレクトリが既に存在している必要があります。

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

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

HKEY_LOCAL_MACHINE
   SOFTWARE
      Microsoft
         Windows NT
            CurrentVersion
               IniFileMapping

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

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

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

他のレジストリの場所を指定するレジストリ内の値を見ると、.ini ファイルマッピングの動作を変更するプレフィックスがいくつかあります。

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

WritePrivateProfileString 関数を使用してレジストリにファイル情報 .ini 入力するアプリケーションは、次のガイドラインに従う必要があります。

指定した名前の .ini ファイルがシステムに存在しないことを確認します。
.ini ファイルを指定するキーエントリがレジストリにあることを確認します。このエントリは、\Microsoft\Windows NT\CurrentVersion\IniFileMappingHKEY_LOCAL_MACHINE\SOFTWARE パスの下にある必要があります。
セクションを指定する .ini ファイル・キー・エントリーの値を指定します。つまり、アプリケーションでは、.ini ファイルまたはレジストリエントリ内に表示されるセクション名を指定する必要があります。 [My Section]の例を次に示します。
システム・ファイルの場合は、追加値として SYS を指定します。
アプリケーションファイルの場合は、追加された値内で USR を指定します。 "My Section: USR: App Name\Section" の例を次に示します。また、USR は HKEY_CURRENT_USER下のマッピングを示しているため、アプリケーションでは、HKEY_CURRENT_USER の下に、追加された値にリストされているアプリケーション名を指定するキーも作成する必要があります。指定した例では、"アプリ名" になります。
前の手順に従った後、アプリケーションセットアッププログラムは、最初の 3 つのパラメーターを NULLに設定し、4 番目のパラメーターを INI ファイル名に設定して、WritePrivateProfileString を呼び出す必要があります。例えば：
WritePrivateProfileString( NULL, NULL, NULL, L"appname.ini" );
このような呼び出しにより、次のシステムの再起動前に .ini ファイルのレジストリへのマッピングが有効になります。システムは、マッピング情報を共有メモリに再読み込みします。アプリケーションの今後の呼び出しで、.ini ファイルのレジストリへのマッピングが表示されるため、ユーザーはアプリケーションをインストールした後にコンピューターを再起動する必要はありません。

例

次のサンプルコードは、上記のガイドラインを示しており、いくつかの前提条件に基づいています。

アプリ名という名前のアプリケーションがあります。
そのアプリケーションは、AppName.iniという名前の .ini ファイルを使用します。

.ini ファイルには、次のようなセクションがあります。

[Section1] 
  FirstKey = It all worked out okay. 
  SecondKey = By golly, it works. 
  ThirdKey = Another test.

ユーザーは、アプリケーションの今後の呼び出しでレジストリへの .ini ファイルのマッピングを確認するために、システムを再起動する必要はありません。

#include <windows.h> 
#include <tchar.h>
#include <stdio.h> 
 
int main() 
{ 
   TCHAR   inBuf[80]; 
   HKEY   hKey1, hKey2; 
   DWORD  dwDisposition; 
   LONG   lRetCode; 
   TCHAR   szData[] = TEXT("USR:App Name\\Section1");
 
   // Create the .ini file key. 
   lRetCode = RegCreateKeyEx ( HKEY_LOCAL_MACHINE, 
       TEXT("SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion\\IniFileMapping\\appname.ini"), 
       0, 
       NULL, 
       REG_OPTION_NON_VOLATILE, 
       KEY_WRITE, 
       NULL, 
       &hKey1, 
       &dwDisposition); 
 
   if (lRetCode != ERROR_SUCCESS)
   { 
      printf ("Error in creating appname.ini key (%d).\n", lRetCode); 
      return (0) ; 
   } 
 
   // Set a section value 
   lRetCode = RegSetValueEx ( hKey1, 
                              TEXT("Section1"), 
                              0, 
                              REG_SZ, 
                              (BYTE *)szData, 
                              sizeof(szData)); 
 
   if (lRetCode != ERROR_SUCCESS) 
   { 
      printf ("Error in setting Section1 value\n"); 
      // Close the key
      lRetCode = RegCloseKey( hKey1 );
      if( lRetCode != ERROR_SUCCESS )
      {
         printf("Error in RegCloseKey (%d).\n", lRetCode);
         return (0) ; 
      }
   } 
 
   // Create an App Name key 
   lRetCode = RegCreateKeyEx ( HKEY_CURRENT_USER, 
                               TEXT("App Name"), 
                               0, 
                               NULL, 
                               REG_OPTION_NON_VOLATILE,
                               KEY_WRITE, 
                               NULL, 
                               &hKey2, 
                               &dwDisposition); 
 
   if (lRetCode != ERROR_SUCCESS) 
   { 
      printf ("Error in creating App Name key (%d).\n", lRetCode); 

      // Close the key
      lRetCode = RegCloseKey( hKey2 );
      if( lRetCode != ERROR_SUCCESS )
      {
         printf("Error in RegCloseKey (%d).\n", lRetCode);
         return (0) ; 
      }
   } 
 
   // Force the system to read the mapping into shared memory 
   // so that future invocations of the application will see it 
   // without the user having to reboot the system 
   WritePrivateProfileStringW( NULL, NULL, NULL, L"appname.ini" ); 
 
   // Write some added values 
   WritePrivateProfileString (TEXT("Section1"), 
                              TEXT("FirstKey"), 
                              TEXT("It all worked out OK."), 
                              TEXT("appname.ini")); 
   WritePrivateProfileString (TEXT("Section1"), 
                              TEXT("SecondKey"), 
                              TEXT("By golly, it works!"), 
                              TEXT("appname.ini")); 
   WritePrivateProfileString (TEXT("Section1"), 
                              TEXT("ThirdKey"), 
                              TEXT("Another test..."), 
                              TEXT("appname.ini")); 

   // Test 
   GetPrivateProfileString (TEXT("Section1"), 
                            TEXT("FirstKey"), 
                            TEXT("Error: GPPS failed"), 
                            inBuf, 
                            80, 
                            TEXT("appname.ini")); 
   _tprintf (TEXT("Key: %s\n"), inBuf); 
 
   // Close the keys
   lRetCode = RegCloseKey( hKey1 );
   if( lRetCode != ERROR_SUCCESS )
   {
      printf("Error in RegCloseKey (%d).\n", lRetCode);
      return(0);
   }

   lRetCode = RegCloseKey( hKey2 );
   if( lRetCode != ERROR_SUCCESS )
   {
      printf("Error in RegCloseKey (%d).\n", lRetCode);
      return(0);
   }
   
   return(1); 
}

手記

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

必要条件

要件	価値
サポートされる最小クライアント	Windows 2000 Professional [デスクトップアプリのみ]
サポートされる最小サーバー	Windows 2000 Server [デスクトップアプリのみ]
ターゲットプラットフォームの	ウィンドウズ
ヘッダー	winbase.h (Windows.h を含む)
ライブラリ	Kernel32.lib
DLL	Kernel32.dll

次の方法で共有

WritePrivateProfileStringA 関数 (winbase.h)

構文

パラメーター

戻り値

備考

例

必要条件

関連項目

フィードバック

その他のリソース