SetupScanFileQueue 6N._P9

[New - Windows NT]

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 FALSE immediately.

Either SPQ_SCAN_FILE_PRESENCE, or SPQ_SCAN_USE_CALLBACK must be specified.

SPQ_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_QUEUESCANHYNU_K. 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 TRUE 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.

Result	Meaning
0	The queue failed the check or it passed the check but SPQ_SCAN_INFORM_USER was specified and the user wants new copies of the files.
1	The queue passed the check and, if SPQ_SCAN_INFORM_USER was specified, the user indicated that copying is not required. The copy queue is empty and there are no elements on the delete or rename queues, so the caller can skip queue commit.
2	The queue passed the check and, if SPQ_SCAN_INFORM_USER was specified, the user indicated that copying is not required. The copy queue is empty but there are elements on the delete or rename queues, so the call cannot skip queue commit.

The function returns FALSE 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 GetLastError11C2VS7.