ホーム › System.WindowsProgramming › GetProfileSectionW

GetProfileSectionW

関数

win.iniの指定セクション全体をUnicodeで取得する旧式関数。

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

シグネチャ

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

DWORD GetProfileSectionW(
    LPCWSTR lpAppName,
    LPWSTR lpReturnedString,   // optional
    DWORD nSize
);

パラメーター

名前	型	方向	説明
lpAppName	LPCWSTR	in	Win.ini ファイル内のセクションの名前。
lpReturnedString	LPWSTR	outoptional	指定された名前のセクションに関連付けられたキーと値を受け取るバッファーへのポインター。バッファーには 1 つ以上の null 終端文字列が格納され、最後の文字列の後にはもう 1 つの null 文字が続きます。
nSize	DWORD	in	lpReturnedString パラメーターが指すバッファーのサイズ (文字単位)。プロファイルセクションの最大サイズは 32,767 文字です。

名前

型

方向

説明

lpAppName

LPCWSTR

Win.ini ファイル内のセクションの名前。

lpReturnedString

LPWSTR

outoptional

指定された名前のセクションに関連付けられたキーと値を受け取るバッファーへのポインター。バッファーには 1 つ以上の null 終端文字列が格納され、最後の文字列の後にはもう 1 つの null 文字が続きます。

nSize

DWORD

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

プロファイルセクションの最大サイズは 32,767 文字です。

戻り値の型: DWORD

公式ドキュメント

Win.ini ファイルの指定されたセクションにあるすべてのキーと値を取得します。(Unicode)

戻り値

戻り値は、指定されたバッファーにコピーされた文字数 (終端の null 文字は含まない) を示します。指定された名前のセクションに関連付けられたすべてのキーと値を格納するのにバッファーが十分な大きさでない場合、戻り値は nSize で指定されたサイズから 2 を引いた値になります。

解説(Remarks)

返されるキーと値の形式は、1 つ以上の null 終端文字列の後に最後の null 文字が続くというものです。各文字列は次の形式です: key=string

GetProfileSection 関数は大文字と小文字を区別しません。文字列には大文字と小文字を混在させることができます。

この操作はアトミックです。セクションのキーと値がバッファーにコピーされている間、Win.ini ファイルへの更新は許可されません。

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

操作がマップされている場合、 GetProfileSection 関数は初期化ファイルではなくレジストリから情報を取得します。格納場所が変わっても、この関数の動作に影響はありません。

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

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 を表し、プレフィックスの後のテキストはそのキーからの相対パスです。

メモ

winbase.h ヘッダーは、UNICODE プリプロセッサ定数の定義に基づいてこの関数の ANSI 版または Unicode 版を自動的に選択するエイリアスとして GetProfileSection を定義しています。エンコード中立のエイリアスの使用と、エンコード中立でないコードを混在させると、不一致が生じてコンパイルエラーや実行時エラーの原因となる可能性があります。詳細については、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 GetProfileSectionW(
    LPCWSTR lpAppName,
    LPWSTR lpReturnedString,   // optional
    DWORD nSize
);

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

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

' lpAppName : LPCWSTR
' lpReturnedString : LPWSTR optional, out
' nSize : DWORD
Declare PtrSafe Function GetProfileSectionW Lib "kernel32" ( _
    ByVal lpAppName As LongPtr, _
    ByVal lpReturnedString As LongPtr, _
    ByVal nSize As Long) 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

GetProfileSectionW = ctypes.windll.kernel32.GetProfileSectionW
GetProfileSectionW.restype = wintypes.DWORD
GetProfileSectionW.argtypes = [
    wintypes.LPCWSTR,  # lpAppName : LPCWSTR
    wintypes.LPWSTR,  # lpReturnedString : LPWSTR optional, out
    wintypes.DWORD,  # nSize : DWORD
]

require 'fiddle'
require 'fiddle/import'

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

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

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

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

出力引数:

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