8.1 How Data Handlers Work

only for RuBoard - do not distribute or recompile

Data handlers are activated when a file is copied in the shell. Selecting Copy from Explorer's File menu, selecting Copy from the context menu of the file object itself, pressing Ctrl-C, or pressing Ctrl-Insert will all initiate a registered data handler if one exists. To do this, the shell looks under the following key:

 HKEY_CLASSES_ROOT\     {application identifier}\         shellex\             DataHandler

Once loaded, the shell passes the name of the file being copied to the data handler via the IPersistFile::Load method. We've seen this functionality a few times already (icon handlers and drop handlers). Nothing's different here. Like before, the filename can be stored in a private class member until it is needed at a later time.

The shell then calls IDataObject::QueryGetData repeatedly in an attempt to figure out all of the formats a data handler can use. Each time QueryGetData is called, a pointer to a FORMATETC structure is passed in by the shell. The FORMATETC structure describes the format of the data that will be involved in the data transfer: text, bitmaps, metafiles, etc. We'll talk about this structure later.

Every time the shell calls QueryGetData , it is saying, "If I call GetData with this format, will the call be successful?" In other words, will GetData be able to provide me the data described by this FORMATETC structure? The QueryGetData method is provided by data objects (objects that implement IDataObject ) as a way for the caller to determine what formats the data object can provide. However, the fact that the shell calls this method seems a little odd, because IDataObject has another method called EnumFormatEtc .

EnumFormatEtc provides a way for the shell to retrieve all of the formats that are supported by the data handler. In fact, it is this method that the shell calls right after QueryGetData . This is strange behavior because, rather than ask what formats a data object supports, the shell could just ask for the formats.

After the shell has received all of the valid formats that the data object supports, it will then call IDataObject::GetData to retrieve the data. Whatever this "data" happens to be is completely arbitrary. The data handler can provide whatever it wants when GetData is called. For instance, the example for the chapter will retrieve the name of the animal inside of a .rad file and create a string that says "The ( animal name ) is on the clipboard." We could have just as easily provided a bitmap of the animal or a short biography of the animal's life thus far. The point is that whatever you want to provide is up to you, and GetData is where the work gets done.

So after GetData has been called, the handler is out of the picture. But the show is not over . . .

At this point (with regard to our chapter example), the Paste menu of any program supporting text ( CF_TEXT ) clipboard transfers will be active. Programs supporting CF_TEXT include Notepad and Microsoft Word. When Paste is selected from the menu of one of these programs or a similar program, the contents of the clipboard are transferred to the application.

Programs supporting formats other than CF_TEXT , such as Microsoft Paint, would display a grayed out Paste menu.

only for RuBoard - do not distribute or recompile