SetupInitDefaultQueueCallbackEx function (setupapi.h)

Article
10/13/2021

[This function is available for use in the operating systems indicated in the Requirements section. It may be altered or unavailable in subsequent versions. SetupAPI should no longer be used for installing applications. Instead, use the Windows Installer for developing application installers. SetupAPI continues to be used for installing device drivers.]

The SetupInitDefaultQueueCallbackEx function initializes the context used by the default queue callback routine included with the Setup API in the same manner as SetupInitDefaultQueueCallback, except that an additional window is provided to the callback function to accept progress messages.

Syntax

WINSETUPAPI PVOID SetupInitDefaultQueueCallbackEx(
  [in] HWND  OwnerWindow,
  [in] HWND  AlternateProgressWindow,
  [in] UINT  ProgressMessage,
  [in] DWORD Reserved1,
  [in] PVOID Reserved2
);

Parameters

[in] OwnerWindow

Handle to the window to use as the parent of any dialog boxes generated by the default callback routine.

[in] AlternateProgressWindow

Handle to a window that receives the progress messages. To prevent progress messages from being displayed, you can specify this parameter to be INVALID_HANDLE_VALUE.

[in] ProgressMessage

Message that is sent to AlternateProgressWindow when the copy queue is started, and each time a file is copied.

[in] Reserved1

First message parameter that is sent to the AlternateProgressWindow by the default callback routine.

[in] Reserved2

Second message parameter that is sent to the AlternateProgressWindow by the default callback routine.

Return value

SetupInitDefaultQueueCallbackEx returns a pointer to the context used by the default queue callback routine. This function can only fail if there is insufficient memory. If this function fails, it returns NULL and does not set the last-error code for the thread.

Remarks

When the queue starts to commit the copy subqueue, the default queue callback routine sends a message to the window specified in AlternateProgressWindow. Reserved1 has the value 0, and Reserved2 contains a pointer to the number of enqueued file copy operations.

For each file copy operation completed, the default queue callback routine sends a message to AlternateProgressWindow, which can be used to 'tick' the progress bar. Reserved1 has the value 1, and Reserved2 is zero.

SetupInitDefaultQueueCallbackEx can be used to get the default behavior for disk prompting, error handling, and so on, and also provide a gauge embedded in a wizard page or other specialized dialog box.

Regardless of whether you initialized the context used by the default queue callback routine with SetupInitDefaultQueueCallback or SetupInitDefaultQueueCallbackEx, after the queued operations have finished processing, call SetupTermDefaultQueueCallback to release the resources allocated in initializing the context structure. For more information see Initializing and Terminating the Callback Context.

Requirements

Requirement	Value
Minimum supported client	Windows XP [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Target Platform	Windows
Header	setupapi.h
Library	Setupapi.lib
DLL	Setupapi.dll
API set	ext-ms-win-setupapi-classinstallers-l1-1-2 (introduced in Windows 10, version 10.0.14393)