SetupCommitFileQueueW function (setupapi.h)

Article
02/09/2023

[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 SetupCommitFileQueue function performs file operations queued on a setup file queue.

The best practice is to collect all the required file operations for the file queue and commit the queue only once because a file queue cannot be reused after it has been committed. If additional processing of the queue is required after it has been committed, the handle to the queue should be closed and a new file queue created. For more information, see Committing a Queue.

If a file is modified, the caller of this function is required have privileges to write into the target directory.

Syntax

WINSETUPAPI BOOL SetupCommitFileQueueW(
  [in] HWND                Owner,
  [in] HSPFILEQ            QueueHandle,
  [in] PSP_FILE_CALLBACK_W MsgHandler,
  [in] PVOID               Context
);

Parameters

[in] Owner

Optional handle to a window to use as the parent of any progress dialog boxes.

[in] QueueHandle

Handle to a setup file queue, as returned by SetupOpenFileQueue.

[in] MsgHandler

Pointer to an optional callback routine to be notified of various significant events that are in the queue processing. For more information, see Default Queue Callback Routine or FileCallback If the callback routine is null, SetupCommitFileQueue returns TRUE and the error is 0 or NO_ERROR.

[in] Context

Value that is passed to the callback function supplied by the MsgHandler parameter. If the default callback routine has been specified as MsgHandler, this context must be the context returned from SetupInitDefaultQueueCallback or SetupInitDefaultQueueCallbackEx.

Return value

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The callback routine specified in MsgHandler should be compatible with the parameters that SetupCommitFileQueue passed to it during a queue commit.

If Unicode is defined in your callback application, and you specify MsgHandler as the default queue callback routine, the callback routine will expect Unicode parameters. Otherwise, the default queue callback routine will expect ANSI parameters.

Note

The setupapi.h header defines SetupCommitFileQueue 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	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