ホーム › System.WindowsProgramming › GetPrivateProfileStringW

GetPrivateProfileStringW

関数

指定iniファイルから文字列をUnicodeで取得する。

DLLKERNEL32.dll文字セットUnicode (-W)呼出規約winapiSetLastErrorあり対応OSWindows 2000 以降

シグネチャ

// KERNEL32.dll  (Unicode / -W)
#include <windows.h>

DWORD GetPrivateProfileStringW(
    LPCWSTR lpAppName,   // optional
    LPCWSTR lpKeyName,   // optional
    LPCWSTR lpDefault,   // optional
    LPWSTR lpReturnedString,   // optional
    DWORD nSize,
    LPCWSTR lpFileName   // optional
);

パラメーター

名前	型	方向	説明
lpAppName	LPCWSTR	inoptional	キー名を含むセクションの名前。このパラメーターが NULL の場合、 GetPrivateProfileString 関数は、ファイル内のすべてのセクション名を指定されたバッファーにコピーします。
lpKeyName	LPCWSTR	inoptional	取得する文字列に関連付けられたキーの名前。このパラメーターが NULL の場合、lpAppName パラメーターで指定されたセクション内のすべてのキー名が、lpReturnedString パラメーターで指定されたバッファーにコピーされます。
lpDefault	LPCWSTR	inoptional	既定の文字列。lpKeyName のキーが初期化ファイル内に見つからない場合、 GetPrivateProfileString は既定の文字列を lpReturnedString のバッファーにコピーします。このパラメーターが NULL の場合、既定値は空の文字列 "" です。末尾に空白文字を含む既定の文字列は指定しないでください。この関数は、末尾の空白を取り除くために lpReturnedString のバッファーに null 文字を挿入します。
lpReturnedString	LPWSTR	outoptional	取得した文字列を受け取るバッファーへのポインター。
nSize	DWORD	in	lpReturnedString パラメーターが指すバッファーのサイズ (文字数単位)。
lpFileName	LPCWSTR	inoptional	初期化ファイルの名前。このパラメーターにファイルへの完全なパスが含まれていない場合、システムは Windows ディレクトリ内でファイルを検索します。

戻り値の型: DWORD

公式ドキュメント

GetPrivateProfileStringW (Unicode) 関数 (winbase.h) は、初期化ファイル内の指定されたセクションから文字列を取得します。

戻り値

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

lpAppName と lpKeyName のどちらも NULL ではなく、指定されたコピー先バッファーが要求された文字列を格納するには小さすぎる場合、文字列は切り詰められて null 文字が付加され、戻り値は nSize から 1 を引いた値になります。

lpAppName または lpKeyName のいずれかが NULL で、指定されたコピー先バッファーがすべての文字列を格納するには小さすぎる場合、最後の文字列は切り詰められて 2 つの null 文字が付加されます。この場合、戻り値は nSize から 2 を引いた値になります。

lpFileName で指定された初期化ファイルが見つからない場合、または無効な値が含まれている場合、この関数は errorno に '0x2' (File Not Found) の値を設定します。拡張エラー情報を取得するには、GetLastError を呼び出します。

解説(Remarks)

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

[section]
key=string
      .
      .
      .

lpAppName が NULL の場合、 GetPrivateProfileString は、指定されたファイル内のすべてのセクション名を、指定されたバッファーにコピーします。lpKeyName が NULL の場合、この関数は、指定されたセクション内のすべてのキー名を、指定されたバッファーにコピーします。アプリケーションはこの方法を使用して、ファイル内のすべてのセクションとキーを列挙できます。いずれの場合も、各文字列の後には null 文字が続き、最後の文字列の後にはさらにもう 1 つの 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 などのシステムコンポーネントの初期化ファイルを変更する場合に適用される可能性があります。このような場合、関数は初期化ファイルではなくレジストリから情報を取得しますが、格納場所が変わっても関数の動作に影響はありません。

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

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

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

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

例

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

// "Preferred line" という名前のプロファイル文字列を取得し、int に変換します。
GetPrivateProfileString (
      "Preference",
      "Preferred Line",
      gszNULL, 
      szBuffer,
      MAXBUFSIZE,
      gszINIfilename
);

// szBuffer が空でない場合。
if ( lstrcmp ( gszNULL, szBuffer ) )
{
      dwPreferredPLID = (DWORD) atoi( szBuffer );	
}
else	
{
      dwPreferredPLID = (DWORD) -1;
}

メモ

winbase.h ヘッダーは、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI 版または Unicode 版を自動的に選択するエイリアスとして GetPrivateProfileString を定義しています。エンコード中立のエイリアスの使用と、エンコード中立でないコードを混在させると、不一致が生じ、コンパイルエラーまたは実行時エラーの原因となる可能性があります。詳細については、「Conventions for Function Prototypes」を参照してください。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

// KERNEL32.dll  (Unicode / -W)
#include <windows.h>

DWORD GetPrivateProfileStringW(
    LPCWSTR lpAppName,   // optional
    LPCWSTR lpKeyName,   // optional
    LPCWSTR lpDefault,   // optional
    LPWSTR lpReturnedString,   // optional
    DWORD nSize,
    LPCWSTR lpFileName   // optional
);

[DllImport("KERNEL32.dll", CharSet = CharSet.Unicode, SetLastError = true, ExactSpelling = true)]
static extern uint GetPrivateProfileStringW(
    [MarshalAs(UnmanagedType.LPWStr)] string lpAppName,   // LPCWSTR optional
    [MarshalAs(UnmanagedType.LPWStr)] string lpKeyName,   // LPCWSTR optional
    [MarshalAs(UnmanagedType.LPWStr)] string lpDefault,   // LPCWSTR optional
    [MarshalAs(UnmanagedType.LPWStr)] System.Text.StringBuilder lpReturnedString,   // LPWSTR optional, out
    uint nSize,   // DWORD
    [MarshalAs(UnmanagedType.LPWStr)] string lpFileName   // LPCWSTR optional
);

<DllImport("KERNEL32.dll", CharSet:=CharSet.Unicode, SetLastError:=True, ExactSpelling:=True)>
Public Shared Function GetPrivateProfileStringW(
    <MarshalAs(UnmanagedType.LPWStr)> lpAppName As String,   ' LPCWSTR optional
    <MarshalAs(UnmanagedType.LPWStr)> lpKeyName As String,   ' LPCWSTR optional
    <MarshalAs(UnmanagedType.LPWStr)> lpDefault As String,   ' LPCWSTR optional
    <MarshalAs(UnmanagedType.LPWStr)> lpReturnedString As System.Text.StringBuilder,   ' LPWSTR optional, out
    nSize As UInteger,   ' DWORD
    <MarshalAs(UnmanagedType.LPWStr)> lpFileName As String   ' LPCWSTR optional
) As UInteger
End Function

' lpAppName : LPCWSTR optional
' lpKeyName : LPCWSTR optional
' lpDefault : LPCWSTR optional
' lpReturnedString : LPWSTR optional, out
' nSize : DWORD
' lpFileName : LPCWSTR optional
Declare PtrSafe Function GetPrivateProfileStringW Lib "kernel32" ( _
    ByVal lpAppName As LongPtr, _
    ByVal lpKeyName As LongPtr, _
    ByVal lpDefault As LongPtr, _
    ByVal lpReturnedString As LongPtr, _
    ByVal nSize As Long, _
    ByVal lpFileName As LongPtr) As Long
' Unicode(W): 文字列は ByVal As LongPtr とし StrPtr(unicodeStr) を渡す
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

GetPrivateProfileStringW = ctypes.windll.kernel32.GetPrivateProfileStringW
GetPrivateProfileStringW.restype = wintypes.DWORD
GetPrivateProfileStringW.argtypes = [
    wintypes.LPCWSTR,  # lpAppName : LPCWSTR optional
    wintypes.LPCWSTR,  # lpKeyName : LPCWSTR optional
    wintypes.LPCWSTR,  # lpDefault : LPCWSTR optional
    wintypes.LPWSTR,  # lpReturnedString : LPWSTR optional, out
    wintypes.DWORD,  # nSize : DWORD
    wintypes.LPCWSTR,  # lpFileName : LPCWSTR optional
]
# GetLastError: use ctypes.GetLastError() (or ctypes.WinDLL(use_last_error=True))

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('KERNEL32.dll')
GetPrivateProfileStringW = Fiddle::Function.new(
  lib['GetPrivateProfileStringW'],
  [
    Fiddle::TYPE_VOIDP,  # lpAppName : LPCWSTR optional
    Fiddle::TYPE_VOIDP,  # lpKeyName : LPCWSTR optional
    Fiddle::TYPE_VOIDP,  # lpDefault : LPCWSTR optional
    Fiddle::TYPE_VOIDP,  # lpReturnedString : LPWSTR optional, out
    -Fiddle::TYPE_INT,  # nSize : DWORD
    Fiddle::TYPE_VOIDP,  # lpFileName : LPCWSTR optional
  ],
  -Fiddle::TYPE_INT)
# Wide strings: pass str.encode("UTF-16LE") + "\x00\x00"

#[link(name = "kernel32")]
extern "system" {
    fn GetPrivateProfileStringW(
        lpAppName: *const u16,  // LPCWSTR optional
        lpKeyName: *const u16,  // LPCWSTR optional
        lpDefault: *const u16,  // LPCWSTR optional
        lpReturnedString: *mut u16,  // LPWSTR optional, out
        nSize: u32,  // DWORD
        lpFileName: *const u16  // LPCWSTR optional
    ) -> u32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("KERNEL32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
public static extern uint GetPrivateProfileStringW([MarshalAs(UnmanagedType.LPWStr)] string lpAppName, [MarshalAs(UnmanagedType.LPWStr)] string lpKeyName, [MarshalAs(UnmanagedType.LPWStr)] string lpDefault, [MarshalAs(UnmanagedType.LPWStr)] System.Text.StringBuilder lpReturnedString, uint nSize, [MarshalAs(UnmanagedType.LPWStr)] string lpFileName);
"@
$api = Add-Type -MemberDefinition $sig -Name 'KERNEL32_GetPrivateProfileStringW' -Namespace Win32 -PassThru
# $api::GetPrivateProfileStringW(lpAppName, lpKeyName, lpDefault, lpReturnedString, nSize, lpFileName)

#uselib "KERNEL32.dll"
#func global GetPrivateProfileStringW "GetPrivateProfileStringW" wptr, wptr, wptr, wptr, wptr, wptr
; GetPrivateProfileStringW lpAppName, lpKeyName, lpDefault, varptr(lpReturnedString), nSize, lpFileName   ; 戻り値は stat
; lpAppName : LPCWSTR optional -> "wptr"
; lpKeyName : LPCWSTR optional -> "wptr"
; lpDefault : LPCWSTR optional -> "wptr"
; lpReturnedString : LPWSTR optional, out -> "wptr"
; nSize : DWORD -> "wptr"
; lpFileName : LPCWSTR optional -> "wptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "KERNEL32.dll"
#cfunc global GetPrivateProfileStringW "GetPrivateProfileStringW" wstr, wstr, wstr, var, int, wstr
; res = GetPrivateProfileStringW(lpAppName, lpKeyName, lpDefault, lpReturnedString, nSize, lpFileName)
; lpAppName : LPCWSTR optional -> "wstr"
; lpKeyName : LPCWSTR optional -> "wstr"
; lpDefault : LPCWSTR optional -> "wstr"
; lpReturnedString : LPWSTR optional, out -> "var"
; nSize : DWORD -> "int"
; lpFileName : LPCWSTR optional -> "wstr"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "KERNEL32.dll"
#cfunc global GetPrivateProfileStringW "GetPrivateProfileStringW" wstr, wstr, wstr, sptr, int, wstr
; res = GetPrivateProfileStringW(lpAppName, lpKeyName, lpDefault, varptr(lpReturnedString), nSize, lpFileName)
; lpAppName : LPCWSTR optional -> "wstr"
; lpKeyName : LPCWSTR optional -> "wstr"
; lpDefault : LPCWSTR optional -> "wstr"
; lpReturnedString : LPWSTR optional, out -> "sptr"
; nSize : DWORD -> "int"
; lpFileName : LPCWSTR optional -> "wstr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。