ホーム › Devices.DeviceAndDriverInstallation › SetupDiGetActualSectionToInstallA

SetupDiGetActualSectionToInstallA

関数

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

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

シグネチャ

// SETUPAPI.dll  (ANSI / -A)
#include <windows.h>

BOOL SetupDiGetActualSectionToInstallA(
    void* InfHandle,
    LPCSTR InfSectionName,
    LPSTR InfSectionWithExt,   // optional
    DWORD InfSectionWithExtSize,
    DWORD* RequiredSize,   // optional
    LPSTR* Extension   // optional
);

パラメーター

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

戻り値の型: BOOL

公式ドキュメント

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

戻り値

関数が成功した場合は 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  (ANSI / -A)
#include <windows.h>

BOOL SetupDiGetActualSectionToInstallA(
    void* InfHandle,
    LPCSTR InfSectionName,
    LPSTR InfSectionWithExt,   // optional
    DWORD InfSectionWithExtSize,
    DWORD* RequiredSize,   // optional
    LPSTR* Extension   // optional
);

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

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

' InfHandle : void*
' InfSectionName : LPCSTR
' InfSectionWithExt : LPSTR optional, out
' InfSectionWithExtSize : DWORD
' RequiredSize : DWORD* optional, out
' Extension : LPSTR* optional, out
Declare PtrSafe Function SetupDiGetActualSectionToInstallA Lib "setupapi" ( _
    ByVal InfHandle As LongPtr, _
    ByVal InfSectionName As String, _
    ByVal InfSectionWithExt As String, _
    ByVal InfSectionWithExtSize As Long, _
    ByVal RequiredSize As LongPtr, _
    ByVal Extension As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

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

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('SETUPAPI.dll')
SetupDiGetActualSectionToInstallA = Fiddle::Function.new(
  lib['SetupDiGetActualSectionToInstallA'],
  [
    Fiddle::TYPE_VOIDP,  # InfHandle : void*
    Fiddle::TYPE_VOIDP,  # InfSectionName : LPCSTR
    Fiddle::TYPE_VOIDP,  # InfSectionWithExt : LPSTR optional, out
    -Fiddle::TYPE_INT,  # InfSectionWithExtSize : DWORD
    Fiddle::TYPE_VOIDP,  # RequiredSize : DWORD* optional, out
    Fiddle::TYPE_VOIDP,  # Extension : LPSTR* optional, out
  ],
  Fiddle::TYPE_INT)

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

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

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

出力引数:

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