ICopyHookW interface (shlobj.h)

Exposes a method that creates a copy hook handler. A copy hook handler is a Shell extension that determines if a Shell folder or printer object can be moved, copied, renamed, or deleted. The Shell calls the ICopyHookW::CopyCallback method prior to performing one of these operations.

Inheritance

The ICopyHookW interface inherits from the IUnknown interface.

Methods

The ICopyHookW interface has these methods.

ICopyHookW::CopyCallback Determines whether the Shell will be allowed to move, copy, delete, or rename a folder or printer object. (Unicode)

Remarks

The copy hook handler, which is an OLE in-process server (a dll), does not perform the task itself, but it does approve or disapprove the action. If the Shell receives approval from the copy hook handler, it performs the file system operation. Copy hook handlers are not informed about the success of an operation, so they cannot monitor actions taken on folder objects unless FindFirstChangeNotification is used.

A folder object can have multiple copy hook handlers. For example, even if the Shell already has a copy hook handler registered for a particular folder object, you can still register one of your own. If two or more copy hook handlers are registered for an object, the Shell simply calls each of them before performing one of the specified file system operations.

The Shell initializes ICopyHookA directly, without using the IShellExtInit interface first.

CopyCallback returns an int value that indicates whether the Shell should perform the operation. The Shell will call each copy hook handler registered for a folder object until all the handlers have been called or until one of them has returned a value other than IDYES. The handler returns IDYES to specify that the operation should be performed, or IDNO or IDCANCEL to specify that the operation should be discontinued.

Implement a copy hook handler when you want to be able to control when, or if, these file system operations are performed on a given object. You might want to use a copy hook handler on shared folders, for example.

You do not call this Shell extension directly. CopyCallback is called by the Shell prior to moving, copying, deleting, or renaming a Shell folder object.

Note

The shlobj.h header defines ICopyHook as an alias that automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that is not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.

Requirements

Requirement	Value
Header	shlobj.h