SetupInitDefaultQueueCallbackEx function

[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


PVOID SetupInitDefaultQueueCallbackEx(
  _In_ HWND  OwnerWindow,
  _In_ HWND  AlternateProgressWindow,
  _In_ UINT  ProgressMessage,
  _In_ DWORD Reserved1,
  _In_ PVOID Reserved2
);

Parameters

OwnerWindow [in]

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

AlternateProgressWindow [in]

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.

ProgressMessage [in]

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

Reserved1 [in]

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

Reserved2 [in]

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

Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

Setupapi.h

Library

Setupapi.lib

DLL

Setupapi.dll

See also

Overview
Functions
SetupInitDefaultQueueCallback

 

 

Show: