Knowing what you are trying to accomplish is the first step to using the property system.  Property handlers provide a specific set of services which support specific behaviors in the Windows shell.  So let's delve into the role of a property handler and how it relates to other components.

As a data flow diagram, a property handler is pretty simple:

The input is a file stream.  The output is a set of properties.  Yup, that simple. 

Notice that although property handlers interpret files, they don't open the files themselves.  The layer above it does!  There are good reasons for this which I'll discuss another time.  To prepare the property handler, the file system namespace creates the file stream, creates the property handler, and passes the stream to the property handler via the IInitializeWithStream interface.  Once the property stack is completed, the application is free to read and write properties through the stack.  If the layers above the property handler don't answer a question, they'll pass it down to the property handler.

It is also very important to understand what property handlers do not do.  Applying a bit of logic, we can reason out much of the role a property handler plays:

• A single property handler gets created per file.  Thus...
  • A property handler must be the authority on the layout of the file stream it is handed. 
  • It is not possible to "augment" the set of properties on a file.
• The property handler must glean its properties from the file stream itself.  Thus...
  • The property system, in general, cannot store properties on every file.  Not all files allow storing properties inside them.
  • Not all properties can get written to all file types.  Bummer.
• The caller is not guaranteed to ask the property handler for properties.  This means...
  • To be considerate, the property handler should intialize quickly, delaying heavy work until it is actually needed.
• The property handler is dealing with files.  This means...
  • For large files, if you have control over the file layout, consider making it stream-friendly. 
    • Reserve extra space in the property section.
    • Clump things together so that the handler doesn't have to read the whole disk to piece together data.
• Property handlers are an extensibility point of the file system namespace.  Thus...
  • Other namespaces may have different extensibility mechanisms (or none at all).
  • Other namespaces may be able to delegate to the file system namespace when it comes to properties.  (The search results do this)
  • Other namespaces may choose to reuse the same extensibility mechanism.  (ZIP folders do this).
• Property handlers just provide values.  Thus...
  • Although they provide the data, the windows shell controls the way it gets displayed.
  • It is not directly possible to customize the way the data is visualized(1)
  • When I say "property handlers" make the shell do this or that, I really mean that the shell will do "this or that" in the presense of a property handler that provides the right set of data.

Ok, so that's a big dose of reality for one post.  Despite our best wishes, property handlers are not magic.  They provide specific functionality to enable specific behaviors.  As a reminder, the upside of the role of a property handler is that it enables the great integration with the Windows user interface.

-Ben Karas

(1) Property descriptions contain hints about how to display a value (e.g. using a stars or a text box).  Property descriptions are system-wide and therefore a handler only can set the hints for properties it introduced to the system.