IFileOperation interface (shobjidl_core.h)
Exposes methods to copy, move, rename, create, and delete Shell items as well as methods to provide progress and error dialogs. This interface replaces the SHFileOperation function.
Inheritance
The IFileOperation interface inherits from the IUnknown interface. IFileOperation also has these types of members:
Methods
The IFileOperation interface has these methods.
| IFileOperation::Advise Enables a handler to provide status and error information for all operations. |
| IFileOperation::ApplyPropertiesToItem Declares a single item whose property values are to be set. |
| IFileOperation::ApplyPropertiesToItems Declares a set of items for which to apply a common set of property values. |
| IFileOperation::CopyItem Declares a single item that is to be copied to a specified destination. |
| IFileOperation::CopyItems Declares a set of items that are to be copied to a specified destination. |
| IFileOperation::DeleteItem Declares a single item that is to be deleted. |
| IFileOperation::DeleteItems Declares a set of items that are to be deleted. |
| IFileOperation::GetAnyOperationsAborted Gets a value that states whether any file operations initiated by a call to IFileOperation::PerformOperations were stopped before they were complete. The operations could be stopped either by user action or silently by the system. |
| IFileOperation::MoveItem Declares a single item that is to be moved to a specified destination. |
| IFileOperation::MoveItems Declares a set of items that are to be moved to a specified destination. |
| IFileOperation::NewItem Declares a new item that is to be created in a specified location. |
| IFileOperation::PerformOperations Executes all selected operations. |
| IFileOperation::RenameItem Declares a single item that is to be given a new display name. |
| IFileOperation::RenameItems Declares a set of items that are to be given a new display name. All items are given the same name. |
| IFileOperation::SetOperationFlags Sets parameters for the current operation. |
| IFileOperation::SetOwnerWindow Sets the parent or owner window for progress and dialog windows. |
| IFileOperation::SetProgressDialog Specifies a dialog box used to display the progress of the operation. |
| IFileOperation::SetProgressMessage Not implemented. (IFileOperation.SetProgressMessage) |
| IFileOperation::SetProperties Declares a set of properties and values to be set on an item or items. |
| IFileOperation::Unadvise Terminates an advisory connection previously established through IFileOperation::Advise. |
Remarks
A Shell item can be any object in the namespace, including file system objects such as files and folders, but also virtual objects. In the IFileOperation method topics, the term "item" is used to refer generically to any namespace object.
IFileOperation offers many advantages over the older SHFileOperation function.
- Use of IShellItem to identify items rather than string paths. SHFileOperation required path and destination strings to terminate in two null characters rather than the standard single null character, which itself was used to delimit multiple paths in the string. Identifying an item through IShellItem is more robust and less prone to programming errors. It also allows you to access non-file system items such as virtual folders. Multiple items in one operation can be passed as an IShellItemArray, IDataObject, or a collection accessed through IEnumShellItems rather than as a string.
- More accurate error reporting through HRESULT values in conjunction with an API such as FormatMessage. Return codes from SHFileOperation could be misleading or inaccurate.
- Extensibility. As a Component Object Model (COM) interface, IFileOperation can have its capabilities extended by a third-party to meet their specific needs, although this should be a very rare case. Windows provides a default implementation of IFileOperation that should meet the needs of most users.
- Better progress feedback. Detailed operation progress, including notifications when specific operations begin and end on individual items as well as the overall progress, can be received during the operation. While SHFileOperation did provide progress UI, it was not as detailed.
- More functionality. In addition to the copy, delete, move, and rename functionality provided by SHFileOperation, IFileOperation allows you to apply property values and create new items.
- More control over the operation. In addition to the operation flags recognized by SHFileOperation, new flags are recognized in IFileOperation::SetOperationFlags that specify extended operation options.
- Different operations can be performed in one call. For instance, you can move a set of files, copy others, rename a folder, and apply properties to yet another item all in one operation. SHFileOperation could only do one operation—copy, move, rename, or delete—at a time.
- Optional. Set up the event sink for progress status and error notifications through Advise and Unadvise.
- Set the operation state using the following as needed:
- Specify which operations to perform on which items using the following as needed.
- Execute the operations by calling PerformOperations
A full sample that demonstrates the extension of IFileOperation is included in the Windows Software Development Kit (SDK). In a default installation, it can be found at %ProgramFiles%\Microsoft SDKs\Windows\v6.0\Samples\WinUI\Shell\AppPlatform\FileOperations.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows Vista [desktop apps only] |
| Minimum supported server | Windows Server 2008 [desktop apps only] |
| Target Platform | Windows |
| Header | shobjidl_core.h (include Shobjidl.h) |