ホーム › Devices.DeviceAndDriverInstallation › SetupDiGetActualSectionToInstallW

SetupDiGetActualSectionToInstallW

関数

INFでインストールに使用する実際のセクション名を取得する。

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

シグネチャ

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

BOOL SetupDiGetActualSectionToInstallW(
    void* InfHandle,
    LPCWSTR InfSectionName,
    LPWSTR InfSectionWithExt,   // optional
    DWORD InfSectionWithExtSize,
    DWORD* RequiredSize,   // optional
    LPWSTR* Extension   // optional
);

パラメーター

名前	型	方向	説明
InfHandle	void*	in	DDInstall セクションを含む INF ファイルのハンドル。
InfSectionName	LPCWSTR	in	DDInstall セクション名(INF Models セクションで指定されたもの)へのポインター。セクション名の最大長は 254 文字です。
InfSectionWithExt	LPWSTR	outoptional	DDInstall セクション名、そのプラットフォーム拡張、および NULL 終端文字を受け取る文字バッファーへのポインター。これはインストールに使用すべき装飾付きのセクション名です。このパラメーターが NULL の場合、InfSectionWithExtSize は 0 でなければなりません。このパラメーターが NULL の場合、関数は TRUE を返し、DDInstall セクション名、そのプラットフォーム拡張、および終端の NULL 文字を返すために必要なサイズ(文字数単位)を RequiredSize に設定します。
InfSectionWithExtSize	DWORD	in	InfSectionWithExt バッファーのサイズ(文字数単位)。InfSectionWithExt が NULL の場合、このパラメーターは 0 でなければなりません。
RequiredSize	DWORD*	outoptional	DDInstall セクション名、プラットフォーム拡張、および終端の NULL 文字を返すために必要なサイズ(文字数単位)を受け取る変数へのポインター。
Extension	LPWSTR*	outoptional	InfSectionWithExt バッファー内で拡張の開始を示す '.' 文字へのポインターを受け取る変数へのポインター。InfSectionWithExt バッファーが指定されていない場合、または小さすぎる場合、このパラメーターは設定されません。拡張へのポインターが不要な場合は、このパラメーターに NULL を設定してください。

戻り値の型: BOOL

公式ドキュメント

SetupDiGetActualSectionToInstall 関数は、ローカルコンピューター上でデバイス INF ファイルからデバイスをインストールする際に使用する、適切な INF DDInstall セクションを取得します。(Unicode)

戻り値

関数が成功した場合は TRUE を返します。関数が失敗した場合は FALSE を返します。拡張エラー情報を取得するには、GetLastError を呼び出します。

解説(Remarks)

この関数は、デバイスの OS 固有およびアーキテクチャ固有のインストール動作を指定するために使用される、DDInstall セクション名の拡張をサポートします。これらの拡張については、「Creating INF Files for Multiple Platforms and Operating Systems」を参照してください。SetupDiGetActualSectionToInstall は、以下に説明する方法でローカルコンピューターに一致する DDInstall セクション名を検索します。

関数はまず、指定された INF ファイル内で、指定された名前に一致し、かつローカルコンピューターのオペレーティングシステムとプロセッサアーキテクチャに一致する拡張を持つ、装飾付きのインストールセクション名を検索します。たとえば、セクション名として InstallSec を指定した場合、関数はローカルコンピューターのプロセッサアーキテクチャに応じて、次の装飾付き名のいずれかを検索します。

x86 プロセッサアーキテクチャに基づくコンピューターの場合、関数は装飾付き名 InstallSec.ntx86 を検索します。
x64 プロセッサアーキテクチャに基づくコンピューターの場合、関数は装飾付き名 InstallSec.ntamd64 を検索します。
Itanium プロセッサアーキテクチャに基づくコンピューターの場合、関数は装飾付き名 InstallSec.ntia64 を検索します。

名前、オペレーティングシステム、およびプロセッサアーキテクチャの一致が見つかった場合、関数は検索を終了し、対応する装飾付き名を返します。そのような一致が見つからない場合、関数は名前が InstallSec.NT であるセクションを検索します。InstallSec.NT の一致が見つかった場合、関数は検索を終了し、この名前を返します。上記のいずれの検索でも一致が見つからない場合、関数は InstallSec を返しますが、INF ファイルに InstallSec という名前のインストールセクションが含まれているかどうかは確認しません。

DDInstall セクション名は、Hardware セクション名および Services セクション名のベースとして使用されます。たとえば、見つかった DDInstall セクション名が InstallSec.NTX86 である場合、Services セクション名は InstallSec.NTX86.Services という名前でなければなりません。

ドライバーノードで指定された元の DDInstall セクション名は、ドライバーのレジストリキーの InfSection 値エントリに書き込まれます。見つかった拡張は、REG_SZ 値 InfSectionExt としてそのキーに格納されます。例:

InfSection       : REG_SZ :    "InstallSec"
InfSectionExt    : REG_SZ :    ".NTX86"

指定されたデバイス情報要素に対してドライバーが選択されていない場合は、null ドライバーがインストールされます。関数から戻ると、デバイスの SP_DEVINSTALL_PARAMS 構造体のフラグが、デバイスを開始するためにシステムの再起動またはリブートが必要かどうかを示します。

メモ

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

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

各言語での呼び出し定義

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

BOOL SetupDiGetActualSectionToInstallW(
    void* InfHandle,
    LPCWSTR InfSectionName,
    LPWSTR InfSectionWithExt,   // optional
    DWORD InfSectionWithExtSize,
    DWORD* RequiredSize,   // optional
    LPWSTR* Extension   // optional
);

[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("SETUPAPI.dll", CharSet = CharSet.Unicode, SetLastError = true, ExactSpelling = true)]
static extern bool SetupDiGetActualSectionToInstallW(
    IntPtr InfHandle,   // void*
    [MarshalAs(UnmanagedType.LPWStr)] string InfSectionName,   // LPCWSTR
    [MarshalAs(UnmanagedType.LPWStr)] System.Text.StringBuilder InfSectionWithExt,   // LPWSTR optional, out
    uint InfSectionWithExtSize,   // DWORD
    IntPtr RequiredSize,   // DWORD* optional, out
    IntPtr Extension   // LPWSTR* optional, out
);

<DllImport("SETUPAPI.dll", CharSet:=CharSet.Unicode, SetLastError:=True, ExactSpelling:=True)>
Public Shared Function SetupDiGetActualSectionToInstallW(
    InfHandle As IntPtr,   ' void*
    <MarshalAs(UnmanagedType.LPWStr)> InfSectionName As String,   ' LPCWSTR
    <MarshalAs(UnmanagedType.LPWStr)> InfSectionWithExt As System.Text.StringBuilder,   ' LPWSTR optional, out
    InfSectionWithExtSize As UInteger,   ' DWORD
    RequiredSize As IntPtr,   ' DWORD* optional, out
    Extension As IntPtr   ' LPWSTR* optional, out
) As <MarshalAs(UnmanagedType.Bool)> Boolean
End Function

' InfHandle : void*
' InfSectionName : LPCWSTR
' InfSectionWithExt : LPWSTR optional, out
' InfSectionWithExtSize : DWORD
' RequiredSize : DWORD* optional, out
' Extension : LPWSTR* optional, out
Declare PtrSafe Function SetupDiGetActualSectionToInstallW Lib "setupapi" ( _
    ByVal InfHandle As LongPtr, _
    ByVal InfSectionName As LongPtr, _
    ByVal InfSectionWithExt As LongPtr, _
    ByVal InfSectionWithExtSize As Long, _
    ByVal RequiredSize As LongPtr, _
    ByVal Extension 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

SetupDiGetActualSectionToInstallW = ctypes.windll.setupapi.SetupDiGetActualSectionToInstallW
SetupDiGetActualSectionToInstallW.restype = wintypes.BOOL
SetupDiGetActualSectionToInstallW.argtypes = [
    ctypes.POINTER(None),  # InfHandle : void*
    wintypes.LPCWSTR,  # InfSectionName : LPCWSTR
    wintypes.LPWSTR,  # InfSectionWithExt : LPWSTR optional, out
    wintypes.DWORD,  # InfSectionWithExtSize : DWORD
    ctypes.POINTER(wintypes.DWORD),  # RequiredSize : DWORD* optional, out
    ctypes.c_void_p,  # Extension : LPWSTR* optional, out
]
# GetLastError: use ctypes.GetLastError() (or ctypes.WinDLL(use_last_error=True))

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('SETUPAPI.dll')
SetupDiGetActualSectionToInstallW = Fiddle::Function.new(
  lib['SetupDiGetActualSectionToInstallW'],
  [
    Fiddle::TYPE_VOIDP,  # InfHandle : void*
    Fiddle::TYPE_VOIDP,  # InfSectionName : LPCWSTR
    Fiddle::TYPE_VOIDP,  # InfSectionWithExt : LPWSTR optional, out
    -Fiddle::TYPE_INT,  # InfSectionWithExtSize : DWORD
    Fiddle::TYPE_VOIDP,  # RequiredSize : DWORD* optional, out
    Fiddle::TYPE_VOIDP,  # Extension : LPWSTR* optional, out
  ],
  Fiddle::TYPE_INT)
# Wide strings: pass str.encode("UTF-16LE") + "\x00\x00"

#[link(name = "setupapi")]
extern "system" {
    fn SetupDiGetActualSectionToInstallW(
        InfHandle: *mut (),  // void*
        InfSectionName: *const u16,  // LPCWSTR
        InfSectionWithExt: *mut u16,  // LPWSTR optional, out
        InfSectionWithExtSize: u32,  // DWORD
        RequiredSize: *mut u32,  // DWORD* optional, out
        Extension: *mut *mut u16  // LPWSTR* optional, out
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("SETUPAPI.dll", CharSet = CharSet.Unicode, SetLastError = true)]
public static extern bool SetupDiGetActualSectionToInstallW(IntPtr InfHandle, [MarshalAs(UnmanagedType.LPWStr)] string InfSectionName, [MarshalAs(UnmanagedType.LPWStr)] System.Text.StringBuilder InfSectionWithExt, uint InfSectionWithExtSize, IntPtr RequiredSize, IntPtr Extension);
"@
$api = Add-Type -MemberDefinition $sig -Name 'SETUPAPI_SetupDiGetActualSectionToInstallW' -Namespace Win32 -PassThru
# $api::SetupDiGetActualSectionToInstallW(InfHandle, InfSectionName, InfSectionWithExt, InfSectionWithExtSize, RequiredSize, Extension)

#uselib "SETUPAPI.dll"
#func global SetupDiGetActualSectionToInstallW "SetupDiGetActualSectionToInstallW" wptr, wptr, wptr, wptr, wptr, wptr
; SetupDiGetActualSectionToInstallW InfHandle, InfSectionName, varptr(InfSectionWithExt), InfSectionWithExtSize, varptr(RequiredSize), varptr(Extension)   ; 戻り値は stat
; InfHandle : void* -> "wptr"
; InfSectionName : LPCWSTR -> "wptr"
; InfSectionWithExt : LPWSTR optional, out -> "wptr"
; InfSectionWithExtSize : DWORD -> "wptr"
; RequiredSize : DWORD* optional, out -> "wptr"
; Extension : LPWSTR* optional, out -> "wptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "SETUPAPI.dll"
#cfunc global SetupDiGetActualSectionToInstallW "SetupDiGetActualSectionToInstallW" sptr, wstr, var, int, var, var
; res = SetupDiGetActualSectionToInstallW(InfHandle, InfSectionName, InfSectionWithExt, InfSectionWithExtSize, RequiredSize, Extension)
; InfHandle : void* -> "sptr"
; InfSectionName : LPCWSTR -> "wstr"
; InfSectionWithExt : LPWSTR optional, out -> "var"
; InfSectionWithExtSize : DWORD -> "int"
; RequiredSize : DWORD* optional, out -> "var"
; Extension : LPWSTR* optional, out -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "SETUPAPI.dll"
#cfunc global SetupDiGetActualSectionToInstallW "SetupDiGetActualSectionToInstallW" sptr, wstr, sptr, int, sptr, sptr
; res = SetupDiGetActualSectionToInstallW(InfHandle, InfSectionName, varptr(InfSectionWithExt), InfSectionWithExtSize, varptr(RequiredSize), varptr(Extension))
; InfHandle : void* -> "sptr"
; InfSectionName : LPCWSTR -> "wstr"
; InfSectionWithExt : LPWSTR optional, out -> "sptr"
; InfSectionWithExtSize : DWORD -> "int"
; RequiredSize : DWORD* optional, out -> "sptr"
; Extension : LPWSTR* optional, out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。