In the first part of my posts for the IFileOperation interface, I wanted to give an overview of what it is used for and leave the real meat for later. Now it’s time for the fun stuff. In this post I want to dig into the use of the IFileOperationProgressSink. In the MSDN docs for IFileOperation, you will notice that some of the methods take an instance of this interface as a parameter. What is this interface and what is it used for?
The IFileOperationProgressSink was created to provide a rich notification system for callers who want to know the details of the operation they are performing. This was a common request of developers who were using the old SHFileOperation API, with which this was simply not possible. The only feedback mechanism used with SHFileOperation was the rarely used SHNAMEMAPPING structure – a source of many headaches for developers.
The below table highlights the methods you must implement for IFileOperationProgressSink:
Method | Description |
StartOperations | Called when the operation has begun |
FinishOperations | Called when the operation has completed |
UpdateProgress | Called when progress of operation is updated (total items involved in the operation and total items completed so far) |
PauseTimer | Called when the progress timer is paused (currently not used) |
ResetTimer | Called when the progress timer is reset (currently not used) |
ResumeTimer | Called when the progress timer is resumed (currently not used) |
PreCopyItem | Called before a copy operation begins for an item |
PostCopyItem | Called after a copy operation completes for an item |
PreDeleteItem | Called before a delete operation begins for an item |
PostDeleteItem | Called after a delete operation completes for an item |
PreRenameItem | Called before a rename operation begins for an item |
PostRenameItem | Called after a rename operation completes for an item |
PreMoveItem | Called before a move operation begins for an item |
PostMoveItem | Called after a move operation completes for an item |
PreNewItem | Called before a new operation begins for an item |
PostNewItem | Called after a new operation completes for an item |
Not only can you get notified of the beginning, end, and overall progress of the entire operation, but you can listen for details of each item involved in the operation. These details include (depending on the operation type): source and destination, new name in the destination, operation flags associated with the operation, as well as the resulting HRESULT of that particular operation. This allows developers to know the specific point where an operation failed.
Using the IFileOperationProgressSink
The IFileOperation interface provides multiple methods which take an instance of an IFileOperationProgressSink as a parameter. To be notified of all progress notifications from the copy engine, you should call IFileOperation::Advise which takes an IFileOperationProgressSink instance and produces a cookie that identifies the sink which can be used in a subsequent call to IFileOperation::Unadvise to remove the sink. If all you are interested in is a particular component of an operation, you can specify the IFileOperationProgressSink instance in call to one of the specific IFileOperation operation methods listed in the table below.
IFileOperation methods that take an IFileOperationProgressSink:
Method | Description |
Advise | Sets the IFileOperationProgressSink implementation to be called into for all sink notifications. The caller must call Unadvise to remove the sink. |
CopyItem | The IFileOperationProgressSink is called into for PreCopyItem and PostCopyItem sink notifications for this operation only. |
MoveItem | The IFileOperationProgressSink is called into for PreMoveItem and PostMoveItem sink notifications for this operation only. |
RenameItem | The IFileOperationProgressSink is called into for PreRenameItem and PostRenameItem sink notifications for this operation only. |
DeleteItem | The IFileOperationProgressSink is called into for PreDeleteItem and PostDeleteItem sink notifications for this operation only. |
NewItem | The IFileOperationProgressSink is called into for PreNewItem and PostNewItem sink notifications for this operation only. |
* If you add your sink in a call to both Advise and any of the other previously mentioned methods, you will receive duplicate progress sink notifications.
Documentation Corrections
At the time of this writing the documentation for this interface on MSDN was not accurate. The documentation writers have been notified and are making the necessary corrections.
The below methods are NOT INCLUDED in the IFileOperationProgressSink interface:
PreLinkItem
PostLinkItem
Building the IFileOperationProgressSink sample
The included sample code shows how to implement the IFileOperationProgressSink and use it with IFileOperation. For simplification, the sample only performs a copy operation with the given source and destination paths and responds only to StartOperations, FinishOperations, UpdateProgress, PreCopyItem, and PostCopyItem. You can extend the code provided in the sample if you wish.
- Download and install the Windows SDK.
- Download the IFileOperationProgressSink_Sample
- Launch FileOperationProgressSinkSample.sln in Visual Studio
- Open the properties for the project
- Add a path to the SDK includes to the C/C++ - General page
- Add a path to the SDK libs to the Linker – General page
- Build
In the above, we specified a copy operation to copy notepad.exe to our test directory. After clicking Copy, the operation ran (via IFileOperation) and our IFileOperationProgressSink was notified with StartOperations, PreCopyItem, PostCopyItem, UpdateProgress, and FinishOperations. We also show some of the details of the notification in the description column. Please see the comments in the code on how to extend the provided implementation to respond to more of the methods of IFileOperationProgressSink.