IFileOperation interface

IFileOperation interface

3（共 5）对本文的评价是有帮助 - 评价此主题

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.

Members

The IFileOperation interface inherits from the IUnknown interface. IFileOperation also has these types of members:

• Methods

Methods

The IFileOperation interface has these methods.

Method	Description
Advise	Enables a handler to provide status and error information for all operations.
ApplyPropertiesToItem	Declares a single item whose property values are to be set.
ApplyPropertiesToItems	Declares a set of items for which to apply a common set of property values.
CopyItem	Declares a single item that is to be copied to a specified destination.
CopyItems	Declares a set of items that are to be copied to a specified destination.
DeleteItem	Declares a single item that is to be deleted.
DeleteItems	Declares a set of items that are to be deleted.
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.
MoveItem	Declares a single item that is to be moved to a specified destination.
MoveItems	Declares a set of items that are to be moved to a specified destination.
NewItem	Declares a new item that is to be created in a specified location.
PerformOperations	Executes all selected operations.
RenameItem	Declares a single item that is to be given a new display name.
RenameItems	Declares a set of items that are to be given a new display name. All items are given the same name.
SetOperationFlags	Sets parameters for the current operation.
SetOwnerWindow	Sets the parent or owner window for progress and dialog windows.
SetProgressDialog	Specifies a dialog box used to display the progress of the operation.
SetProgressMessage	Not implemented.
SetProperties	Declares a set of properties and values to be set on an item or items.
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 anIShellItemArray, 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:
   • SetOperationFlags
   • SetOwnerWindow
   • SetProgressDialog
   • SetProgressMessage
   • SetProperties
3. Specify which operations to perform on which items using the following as needed.
   • ApplyPropertiesToItem
   • ApplyPropertiesToItems
   • CopyItem
   • CopyItems
   • DeleteItem
   • DeleteItems
   • MoveItem
   • MoveItems
   • NewItem
   • RenameItem
   • RenameItems
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

Minimum supported client	Windows Vista [desktop apps only]
Minimum supported server	Windows Server 2008 [desktop apps only]
Header	Shobjidl.h
IDL	Shobjidl.idl
DLL	Shell32.dll (version 6.0.6000 or later)

 

 

Send comments about this topic to Microsoft

Build date: 10/12/2013

原文链接:http://msdn.microsoft.com/zh-cn/library/bb775771.aspx