Icon handlers, drop target handlers, and data object handlers are initialized with the IPersistFile interface, which is used to load and save documents that are stored in disk files (as opposed to objects stored in IStorage instances). Once the document is loaded, the application opens it as needed. IPersistFile itself won't open the file for you; it has no way of knowing what type of data your file contains.
In addition to the standard IUnknown functions, the IPersistFile interface supports six other member functions. Five of these functions—IsDirty, Save, SaveCompleted, GetCurFile, and GetClassID—are part of the IPersistFile interface but are not required for user interface extensions. For each of these functions, you can simply return E_NOTIMPL. First, however, let's look at the Load member function, which does need to be implemented.
This member function loads the document object that is specified in the pszFileName parameter. A user interface extension saves the filename for further processing. For example, an icon handler saves the filename to determine which type of icon to supply for the file.
Unlike the other functions listed here, the Load function is required for user interface extensions. The implementation, as you can see, is trivial:
STDMETHODIMP CIconExt::XPerFile::Load (LPCOLESTR
pszFileName,
DWORD dwMode)
{
METHOD_PROLOGUE (CIconExt, PerFile);
WideCharToMultiByte (
CP_ACP, // codePage
0, // dwFlags
(LPCWSTR)pszFileName, // lpWideCharStr
-1, // cchWideChar
pThis->m_szFile, // lpMultiByteStr
sizeof (pThis->m_szFile), // cchMultiByte,
NULL, // lpDefaultChar,
NULL); // lpUsedDefaultChar
return NOERROR;
}The following member functions, as mentioned earlier, are supported by IPersistFile but are not required by user interface extensions.
The IsDirty function checks a document object for any changes that might have been made since the document was loaded.
This function saves a copy of the object to the given filename.
The SaveCompleted function simply signals that the object has been saved.
This member function returns either the absolute path of the document's currently associated file or the default filename prompt (if no currently associated file exists).
The GetClassID function returns a document's class ID.