Using Preview Handlers in Windows Vista

• Download source - 24.7 KB

Introduction - Preview Mechanism in Vista

In Windows Vista, the Explorer supports a new feature to preview files. You can enable or disable this in Explorer.

Outlook 2007 and Vista both use the same preview infrastructure for showing previews. They check the extension of the file being used and then look for any preview handlers installed on the machine for the same. If a preview handler is registered for this extension, then the preview handler is loaded and called to show the preview.

The calling application passes the HWND and the co-ordinates along with the information about the file to be previewed. The previewer puts up a window in the given region and renders the file preview.

Interfaces Used in Preview

The preview mechanism is based on the IPreviewHandler interface. This interface has a method to show the preview. The preview handler needs a way to receive file information. For this, the preview handler needs a IInitializeWithFile or IInitializeWithStream interface. The preview handler will require a class implementing either two or three of the above interfaces.

In summary, the following interfaces are to be kept in mind:

• IInitializeWithStream
• IInitializeWithFile
• IPreviewHandler

Writing Preview Handlers

The Windows SDK sample PreviewHandler is a great place to begin with if you are going to implement a preview handler. We can take this and customize it to our requirements. We can use the documentation and sample easily, and hence this is not discussed here.

Using Preview Handlers in Applications

Using preview handlers in your application now is easy. Just load the right interface and call it. But that requires a class ID; the CLSID of the component.

Browsing the Registry and looking for the preview-able files, you will notice that handlers register themselves under HKEY_CLASSES_ROOT\<extn>\shellex\ {8895b1c6-b41f-4c1c-a562-0d564250836f}. Take the CLSID from there and create an object of type IID_IPreviewHandler.

Now, IID_IPreviewHandler itself does not have any parameter to take the file name. Query this interface for the existence of IInitializeWithFile. If you get the interface, you can initialize this interface with the file path.

if( S_OK == CoCreateInstance(cls, NULL, CLSCTX_INPROC_SERVER |
CLSCTX_LOCAL_SERVER, 
IID_IPreviewHandler,(LPVOID*)&m_pIP) )
{
    if( S_OK == m_pIP->QueryInterface(IID_IInitializeWithFile, 
               (LPVOID*)&m_pIFile ); 
    {
        hr = m_pIFile->Initialize( szFile,STGM_READ); 
    }
}

Many preview handlers do not implement IInitializeWithFile, but instead implement IInitializeWithStream. In this case, an IStream object has to be created and initialized. To create a stream object, use the CreateStreamOnHGlobal API. Read the contents of the file and initialize this stream.

HANDLE hFile = CreateFile(szFile,FILE_READ_DATA, 
                   FILE_SHARE_READ,NULL,OPEN_EXISTING,0,NULL );
if( INVALID_HANDLE_VALUE != hFile )
{
    DWORD dwSize = GetFileSize( hFile,NULL );
    m_hGlobal= GlobalAlloc(GPTR, dwSize );
    BYTE * pByte = (BYTE *)GlobalLock(m_hGlobal);

    if( pByte )
    {
        ReadFile(hFile,pByte,dwSize,&dwSize,NULL);    
        GlobalUnlock(m_hGlobal);

        CreateStreamOnHGlobal(m_hGlobal, TRUE, &m_pStream);    
        hr = m_pIStream->Initialize( m_pStream,STGM_READ);
    }

    CloseHandle( hFile );
}

Now, you are all set to get the preview. Set the window co-ordinates and call the DoPreview method to get your preview.

if( m_pIP )
{
    hr = m_pIP->SetWindow( hWnd , &rectPreview );
    hr = m_pIP->DoPreview( );
}

Managing Associations Between File Names and Handlers

We know that .bat, .cmd, .inf and a few other formats fall in the same category as that of a .txt file. We can just change some Registry keys and change the preview handlers so that these files can be previewed.

Under HKEY_CLASSES_ROOT\<extn>, all extensions that you use normally are listed.

We need to add the "\shellex\ {8895b1c6-b41f-4c1c-a562-0d564250836f}" key and the CLSID of the server which can preview this type of file.

To find the CLSID of the previewers installed on the machine, look for HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\PreviewHandlers. This Registry key has the CLSID and friendly name mappings.

Now, enumerate all the extensions from the HKEY_CLASSES_ROOT key, and display an UI with the friendly names of the previewers so that the user can choose the previewer. On the selection, get the CLSID from the friendly name and use this for setting the previewer.

Where did we reach?

By now:

• We are able to enumerate the available previewers
• Manage the associations
• Preview the files

If we combine all this into a tool, the tool can come handy to manage the previewers and to actually see the preview of the files from a directory. These are the screenshots:

Conclusion

If you have a custom file format, then it calls for writing a preview handler. Writing a preview handler will make the new file format explorer friendly and easy to search.

The preview handling infrastructure of Windows Vista opens up a new feature for applications. Document management, email readers, and printing applications can use the preview mechanism and give great features.

References

Windows SDK documentation.

Build Instructions

1. Install VSTS 2005.
2. Install Windows Vista SDK.
3. Build using VSTS 2005.

Notes

To set the handler, the application needs to be launched as Administrator – the application is not UAC aware.

History

• July 25, 2007 -- Created.