Chapter 9. Copy Hook Handlers

only for RuBoard - do not distribute or recompile

Copy hook handlers are invoked every time a shell folder or printer object is moved, deleted, copied , or renamed . Their sole purpose is either to approve or to disapprove the operation in question. They take no part in the operations themselves , and they don't care about the results. When one of the aforementioned processes is initiated, the shell provides the name of the source object, the name of the destination object, and the action being performed to the copy hook handler. The handler merely says, "Yeah, go ahead," or "Stop right there!" That's it. In fact, the copy hook handler is not even notified of whether the action was successful. It is merely a sentry that stands guard over a particular folder or printer.

Copy hook handlers are a little different from the other shell extensions we have discussed. First and foremost, they are not associated with file types, but rather with shell folders and printer objects. Second, they implement only one interface, ICopyHook . If you remember, the previous shell extensions were first initialized either through IShellExtInit or IPersistFile . In contrast, copy hook handlers depend on neither interface. ICopyHook contains one method, CopyCallback , that provides everything the handler will need, initialization and all. There is another major difference, but we'll need to look at the definition for ICopyHook::CopyCallback to see it:

 UINT CopyCallback(     HWND   hwnd   ,     UINT   wFunc   ,     UINT   wFlags   ,     LPCSTR   pszSrcFile   ,     DWORD   dwSrcAttribs   ,     LPCSTR   pszDestFile   ,     DWORD   dwDestAttribs   );

Notice that CopyCallback returns a UINT instead of an HRESULT . All interface methods , by convention, are supposed to return an HRESULT . Who knows what the designers of this interface were thinking? One thing is certain, there is definitely something suspicious going on here. This is going to cause us a problem later when we try to implement the interface because VB will not accept a method definition that does not return an HRESULT . Of course, by now you can probably guess that we will redefine the interface to return an HRESULT instead of a UINT . Each is 4 bytes wide, so this is feasible , but not without problems. But we'll cross that bridge when we get to it.

Before we can add an interface definition to the type library, we'll need its IID. Herein lies a problem. If you search the Platform SDK for ICopyHook , you will find a description of the interface, a short discourse on copy hook handlers, and so on. But if you search for ICopyHook in the registry (or with OLE View), you will not find it. It seems we have a little bit of a mystery going on here.

Let's search for the interface in shlobj.h . If you don't remember, this is the C/C++ header file that contains most of the interface definitions used by the shell. In this file, you will find references to both ICopyHookA and ICopyHookW . As you should know by now, these represent the ANSI and wide versions of the interface, respectively. Now we're on to something. But we still need the IID.

Most of the IIDs for the shell interfaces are found in a file called shlguid.h . But if you do a search for ICopyHookA or ICopyHookW , you won't find a thing. What is going on here? There's nothing in OLE View either! Apparently, what we have found is a lack of consistency.

Maybe if we search for CopyHook , we will have some luck. Sure enough, if you inspect shlguid.h closely, you will find references to IShellCopyHookA and IShellCopyHookW , along with the IIDs. Whew!

I refer to the interface as ICopyHook throughout the remainder of this chapter. I only distinguish between ICopyHookA and ICopyHookW when necessary.

only for RuBoard - do not distribute or recompile