SetupScanFileQueue

The SetupScanFileQueue function scans a setup file queue, performing an operation on each node in its copy list. The operation is specified by a set of flags. This function can be called either before or after the queue has been committed

BOOL SetupScanFileQueue(
  HSPFILEQ FileQueue,     // handle to the file queue
  DWORD Flags,            // control scan operation
  HWND Window,            // optional, specifies a parent window
  PSP_FILE_CALLBACK CallbackRoutine,
                          // optional, callback routine to use
  PVOID CallbackContext,  // optional, callback routine context
  PDWORD Result           // receives scan result
);
 

Parameters

FileQueue

Supplies a handle to the setup file queue whose copy list is to be scanned/iterated.

Flags

Values that control how the scan operation is carried out. Flags can be a combination of the following values:

SPQ_SCAN_FILE_PRESENCE

Determine whether all target files in the copy queue are already present on the target.

SPQ_SCAN_USE_CALLBACK

For each node of the queue, call the callback routine. If the callback routine returns non-0, queue processing stops and SetupScanFileQueue returns zero immediately.

Either SPQ_SCAN_FILE_PRESENCE, or SPQ_SCAN_USE_CALLBACK must be specified.

SPQ_SCAN_INFORM_USER

If this flag is specified and all the files in the queue pass the presence/validity check, SetupScanFileQueue informs the user that the operation being attempted requires files but they are already present on the target. This flag is ignored if SPQ_SCAN_FILE_PRESENCE is not specified.

Window

This optional parameter specifies the window to own dialog boxes that are presented. The Window parameter is not used if the Flags parameter does not contain SPQ_SCAN_FILE_PRESENCE or if Flags does not contain SPQ_SCAN_INFORM_USER.

CallbackRoutine

This optional parameter specifies a callback function to be called on each node of the copy queue. The notification code passed to the callback function is SPFILENOTIFY_QUEUESCAN. This parameter is required if Flags includes SPQ_SCAN_USE_CALLBACK.

Note You must supply the callback routine specified by CallbackRoutine. The default queue callback routine does not support SetupScanFileQueue.

CallbackContext

This optional parameter points to a context that contains caller-defined data passed to the callback routine pointed to by CallbackRoutine.

Result

Supplies a pointer to a caller-supplied variable in which this function returns the result of the scan operation.

Return Values

The function returns a non-zero value if all nodes in the queue were processed.

If the SPQ_SCAN_USE_CALLBACK flag was set, the value in Result is 0. The callback routine specified by CallbackRoutine is sent the notification SPFILENOTIFY_QUEUESCAN. CallbackRoutine.Param1 specifies a pointer to an array that contains the target path information. The pointer has been cast to an unsigned integer and must be recast to an TCHAR array of MAX_PATH elements before a callback routine can access the information. CallbackRoutine.Param2 is set to SPQ_DELAYED_COPY if the current queue node is in use and cannot be copied until the system is rebooted. Otherwise, CallbackRoutine.Param2 takes the value 0.

If SPQ_SCAN_USE_CALLBACK was not set, Result indicates whether the queue passed the presence/validity check as shown in the following table.

The function returns zero if an error occurred or the callback function returned non-0. If Result is non-0, it is the value returned by the callback function that stopped queue processing. If Result is 0, extended error information can be retrieved by a call to GetLastError.

QuickInfo

  Windows NT: Use version 4.0 and later.
  Windows: Use Windows 95 and later.
  Windows CE: Unsupported.
  Header: Declared in setupapi.h.
  Import Library: Link with setupapi.lib.

See Also

Overview, Functions, SetupCommitFileQueue, SetupDefaultQueueCallback