RunSetupCommand function

Article
08/15/2017

Executes an install section in an information (INF) file, or execute a program. Supports advanced INF files.

Syntax

HRESULT WINAPI RunSetupCommand(
  _In_       HWND   hWnd,
  _In_       LPCSTR szCmdName,
  _In_       LPCSTR szInfSection,
  _In_       LPCSTR szDir,
  _In_       LPCSTR szTitle,
  _In_       HANDLE *phEXE,
  _In_       DWORD  dwFlags,
  _Reserved_ LPVOID pvReserved
);

Parameters

hWnd [in]

Handle to parent window, or NULL. (See RSC_FLAG_QUIET below.)

szCmdName [in]

String that specifies the executable or INF file to launch. (See RSC_FLAG_INF below.)

szInfSection [in]

String that specifies the INF file section to install, or NULL to use [DefaultInstall] section.

szDir [in]

String that specifies the path to extracted files. May be relative to the current directory.

szTitle [in]

String that specifies the title for all dialogs.

phEXE [in]

Address of a variable that receives the handle of the EXE to wait for.

dwFlags [in]

DWORD that specifies a combination of the following values.

RSC_FLAG_INF (1)

Execute szCmdName as an INF file install.

RSC_FLAG_SKIPDISKSPACECHECK (2)

Not implemented. Currently does nothing.

RSC_FLAG_QUIET (4)

Suppress user interface ("Quiet Mode"). Pass NULL in hWnd parameter.

RSC_FLAG_NGCONV (8)

Do not run Windows Progman Group Converter (GrpConv) utility.

RSC_FLAG_UPDHLPDLLS (16)

Force Advpack, SetupAPI or Setupx DLLs to self-update.

RSC_FLAG_DELAYREGISTEROCX (512)

Force delay of OCX registration until after reboot.

RSC_FLAG_SETUPAPI (1024)

Always use SetupAPI. If not specified, the system can choose whether to use SetupAPI or Setupx, depending on operating system version and other setup parameters.

pvReserved [in]

Reserved. Must be set to NULL.

Return value

Returns one of the following values.

Return code	Description
S_OK	Successful exit. No reboot required.
S_ASYNCHRONOUS	Please wait for phEXE to exit.
ERROR_SUCCESS_REBOOT_REQUIRED	Successful exit. System reboot required.
E_INVALIDARG	NULL specified in szCmdName or szDir.
HRESULT_FROM_WIN32(ERROR_OLD_WIN_VERSION)	Operating system version does not support INF files.
E_UNEXPECTED	Catastrophic failure (should never happen).

Remarks

In addition to the error codes above, this function may also return an HRESULT derived from GetLastError if it encounters an internal error.

Examples

The following C++ example loads RunSetupCommand from the helper DLL, and executes the INF file section.

#include <advpub.h>

HRESULT RunINFSection(
    LPCSTR szInfFile,
    LPCSTR szInfSection)
{
    HRESULT   hr = E_FAIL;
    HINSTANCE hAdvpack;

    hAdvpack = LoadLibrary(TEXT("advpack.dll"));
    if (hAdvpack != NULL)
    {
        RUNSETUPCOMMAND pfRunSetupCommand =
            (RUNSETUPCOMMAND)GetProcAddress(
                    hAdvpack,
                    "RunSetupCommand");

        if (pfRunSetupCommand != NULL)
        {
            hr = pfRunSetupCommand(NULL,
                    szInfFile,
                    szInfSection,
                    ".",
                    NULL,
                    NULL,
                    RSC_FLAG_INF | RSC_FLAG_QUIET,
                    NULL);            
        }

        FreeLibrary(hAdvpack);
    }
    else
        hr = HRESULT_FROM_WIN32(GetLastError());
        
    return hr;
}

Requirements

Minimum supported client	Windows 2000 Professional
Minimum supported server	Windows 2000 Server
Header	N/A
DLL	Advpack.dll