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.
To accomplish a file operation using this interface, a sequence of calls must be made.
  1. Optional. Set up the event sink for progress status and error notifications through Advise and Unadvise.
  2. Set the operation state using the following as needed:
  3. Specify which operations to perform on which items using the following as needed.
  4. Execute the operations by calling PerformOperations
IFileOperation can only be applied in a single-threaded apartment (STA) situation. It cannot be used for a multithreaded apartment (MTA) situation. For MTA, you still must use SHFileOperation.

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)