SetupDiGetActualSectionToInstallExA function (setupapi.h)

Article
02/09/2023

The SetupDiGetActualSectionToInstallEx function retrieves the name of the INF DDInstall section that installs a device for a specified operating system and processor architecture.

Syntax

WINSETUPAPI BOOL SetupDiGetActualSectionToInstallExA(
  [in]            HINF                 InfHandle,
  [in]            PCSTR                InfSectionName,
  [in, optional]  PSP_ALTPLATFORM_INFO AlternatePlatformInfo,
  [out, optional] PSTR                 InfSectionWithExt,
  [in]            DWORD                InfSectionWithExtSize,
  [out, optional] PDWORD               RequiredSize,
  [out, optional] PSTR                 *Extension,
                  PVOID                Reserved
);

Parameters

[in] InfHandle

A handle to the INF file that contains the DDInstall section.

[in] InfSectionName

A pointer to the DDInstall section name (as specified in an INF Models section). The maximum length of the section name, in characters, is 254.

[in, optional] AlternatePlatformInfo

A pointer, if non-NULL, to an SP_ALTPLATFORM_INFO structure. This structure is used to specify an operating system and processor architecture that is different from that on the local computer. To return the DDInstall section name for the local computer, set this parameter to NULL. Otherwise, provide an SP_ALTPLATFORM structure and set its members as follows:

cbSize

Set to the size, in bytes, of an SP_ALTPLATFORM_INFO structure.

Platform

Set to VER_PLATFORM_WIN32_NT for Windows XP and later versions of Windows.

MajorVersion

Not used.

MinorVersion

Not Used.

ProcessorArchitecture

Set one of the following processor architecture constants.

Processor Architecture Constant	Meaning
PROCESSOR_ARCHITECTURE_INTEL	The alternative platform is an x86-based processor architecture.
PROCESSOR_ARCHITECTURE_IA64	The alternative platform is an Itanium-based processor architecture.
PROCESSOR_ARCHITECTURE_AMD64	The alternative platform is an x64-based processor architecture.

Reserved

Set to zero.

[out, optional] InfSectionWithExt

A pointer to a character buffer to receive the DDInstall section name, its platform extension, and a NULL terminator. This is the decorated section name that should be used for installation. If this parameter is NULL, the function returns TRUE and sets RequiredSize to the size, in characters, that is required to return the DDInstall section name, its platform extension, and a terminating NULL character.

[in] InfSectionWithExtSize

The size, in characters, of the buffer that is pointed to by the InfSectionWithExt parameter. The maximum length of a NULL-terminated INF section name, in characters, is MAX_INF_SECTION_NAME_LENGTH.

[out, optional] RequiredSize

A pointer to the variable that receives the size, in characters, that is required to return the DDInstall section name, the platform extension, and a terminating NULL character.

[out, optional] Extension

A pointer to a variable that receives a pointer to the '.' character that marks the start of the extension in the InfSectionWithExt buffer. If the InfSectionWithExt buffer is not supplied or is too small, this parameter is not set. Set this parameter to NULL if a pointer to the extension is not required.

Reserved

Reserved for internal use only. Must be set to NULL.

Return value

If the function is successful, it returns TRUE. Otherwise, it returns FALSE. To get extended error information, call GetLastError.

Remarks

SetupDiGetActualSectionToInstallEx is an extended form of SetupDiGetActualSectionToInstall. These functions support the extensions to DDInstall section names that are used to specify OS-specific and architecture-specific installation actions for a device. For information about these extensions, see Creating INF Files for Multiple Platforms and Operating Systems.

If you do not supply alternative platform information with a call to SetupDiGetActualSectionToInstallEx, the function performs the same operation as SetupDiGetActualSectionToInstall. The latter function searches for the specified install section name using the platform information for the local computer.

If you supply alternative platform information with a call to SetupDiGetActualSectionToInstallEx, the function does the following:

If you specify a platform of VER_PLATFORM_WIN32_NT, the function first searches in the specified INF file for a decorated install section name that matches the name, operating system, and processor architecture that you specify. If, for example, you specify an install section name of InstallSec, the function searches for one of the following decorated names, depending on the specified processor architecture:
- If you specify the x86-based processor architecture, the function searches for the decorated name InstallSec.ntx86.
- If you specify the x64-based processor architecture, the function searches for the decorated name InstallSec.ntamd64.
- If you specify the Itanium-based processor architecture, the function searches for the decorated name InstallSec.ntia64.
If the function finds a match for the name, operating system, and processor architecture, it terminates the search and returns the corresponding decorated name. If the function does not find such a match, the function searches for a section whose name is InstallSec.nt. If the function finds a match for InstallSec.nt, it terminates the search and returns this name. If the function does not find a match for either of the above searches, it returns InstallSec, but does not verify that the INF file contains an install section whose name is InstallSec.

Note

The setupapi.h header defines SetupDiGetActualSectionToInstallEx as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.

Requirements

Requirement	Value
Minimum supported client	Available in Windows XP and later versions of Windows.
Target Platform	Desktop
Header	setupapi.h (include Setupapi.h)
Library	Setupapi.lib