Creating Copy Hook Handlers

Normally, users and applications can copy, move, delete, or rename folders with few restrictions. By implementing a copy hook handler, you can control whether or not these operations take place. For instance, implementing such a handler allows you to prevent critical folders from being renamed or deleted. Copy hook handlers can also be implemented for printer objects.

Copy hook handlers are global. The Shell calls all registered handlers every time an application or user attempts to copy, move, delete, or rename a folder or printer object. The handler does not perform the operation itself. It only approves or vetoes it. If all handlers approve, the Shell does the operation. If any handler vetoes the operation, it is canceled and the remaining handlers are not called. Copy hook handlers are not informed of the success or failure of the operation, so they cannot be used to monitor file operations.

The general procedures for implementing and registering a Shell extension handler are discussed in Creating Shell Extension Handlers. This document focuses on those aspects of implementation that are specific to copy hook handlers.

• Registering Copy Hook Handlers
• Implementing Copy Hook Handlers

Registering Copy Hook Handlers

Copy hook handlers for folders are registered under the HKEY_CLASSES_ROOT\Directory\shellex\CopyHookHandlers key. Create a subkey of CopyHookHandlers named for the handler, and set the subkey's default value to the string form of the handler's class identifier (CLSID) GUID.

The following example adds the MyCopyHandler subkey to the Shell's list of copy hook handlers.

HKEY_CLASSES_ROOT

Directory

shellex

CopyHookHandlers

• MyCopyHandler

Copy hook handlers for printer objects are registered in essentially the same way. The only difference is that you must register them under the HKEY_CLASSES_ROOT\Printers key.

Implementing Copy Hook Handlers

Like all Shell extension handlers, copy hook handlers are in-process Component Object Model (COM) objects implemented as DLLs. They export one interface in addition to IUnknown: ICopyHook. The Shell initializes the handler directly, so there is no need for an initialization interface such as IShellExtInit.

The ICopyHook interface has a single method, CopyCallback. When a folder is about to be moved, the Shell calls this method. It passes in a variety of information, including:

• The folder's name.
• The folder's destination or new name.
• The operation that is being attempted.
• The attributes of the source and destination folders.
• A window handle that can be used to display a user interface.

When your handler's CopyCallback method is called, it returns one of the three following values to indicate to the Shell how it should proceed.

Value	Description
IDYES	Allows the operation.
IDNO	Prevents the operation on this folder. The Shell can continue with any other operations that have been approved, such as a batch copy operation.
IDCANCEL	Prevents the current operation and cancels any pending operations.