by Ross Comer
Development Lead, Microsoft Office Compatible
June 1996
This article provides a detailed description of the Document Properties feature of Office Compatible, and the steps necessary to implement this feature into your custom application. It also provides sample code for a C/C++ interface. An OLE Automation interface is only available for this feature through the Application Object Model of the Office applications.
Document properties are a collection of properties attached to files that use the OLE Storage mechanism. There are both “Built-in” and “Custom” property sets defined. Built-in document properties are items such as Author, Keywords, and Last Modified Date. Custom properties are properties defined by an application or user. For example, Company XYZ has a custom property, DeptHomePage, which lists the Intranet home page of the department which created the document. Authors put this property in their document, then display it in a footer so whoever reads the document can go directly to the Intranet home page of that department.
Office Compatible provides OLE Automation and C interfaces to allow applications to take advantage of Document Property technology and to bring up the Document Property dialogs.
The Properties dialog allows the user to view standard, pre-defined properties for a document using the General, Summary, Statistics, and Contents tabs.
Using the Custom tab of the Properties dialog, the user can view custom properties already created for the document, or create new ones. Custom properties can also be created programmatically.
To use the Document Property functionality, you will need to get the Document Property Interface.
Use the PidpCreateDocProps() method in the IOfficeCompatible to get the Document Property Interface.. If the result of this call is non-NULL, the call succeeded and you are holding a new Document Property object. Once you have the object, you can manipulate its properties as needed.
// Get the Document Properties Interface
IMsocDocProps *pDocProps = pOC->PidpCreateDocProps();
Use the Release method of the Document Property to release the object.
Load and Save can take either an OLE Storage or a filename. The filename must be a complete filename, including filepath, and must point to an existing file that is an OLE Storage. Msocf can be one of the following: msocfDefault, msocfSaveAs95, or msocfSaveAs97. For typical applications, use MsocfDefault. Use msocfSaveAs95 when saving to a document that is to be read by an Office ’95 document.
HRESULT Load(LPSTORAGE lpStg);
HRESULT Save(LPSTORAGE lpStg, UINT msocf);
HRESULT Load(LPCWSTR wzFileName); // LoadFile in C
HRESULT Save(LPCWSTR wzFileName, UINT msocf) // SaveFile in C
The next three interfaces get pointers to the Built-in and Custom document objects along with the Hyperlink objects.
HRESULT GetBuiltinDocProps(IMsocBuiltinDocProps** ppBltDocProps);
HRESULT GetCustomDocProps(IMsocCustomDocProps** ppCustDocProps);
IMsocHLinks* PihlGetHLinks();
The following interface lets you know if the properties were loaded from a 97 document or later, allowing forward compatibility in your application.
BOOL FLoadedAs97();
HRESULT ShowDialog(HWND hwndParent, LPWSTR wzCaption, LPWSTR wzFileName, DWQUERYLD pfnDwQuery);
HRESULT Release();
The IMsocBuiltinDocProps object allows access to the built-in document properties and the thumbnail image of a document.
GetProp and SetProp are used to get and set the values of individual properties.
HRESULT GetProp(UINT uProp, VARIANT* pvarValue);
HRESULT SetProp(UINT uProp, VARIANT* pvarValue);
The uProp value of GetProp and SetProp is one of the following:
PROP_TITLE
PROP_SUBJECT
PROP_AUTHOR
PROP_KEYWORDS
PROP_COMMENTS
PROP_TEMPLATE
PROP_LASTAUTH
PROP_REVISION // PROP_REVISION is a number formated as a string
PROP_APPNAME
// Times
PROP_TOTALEDIT
PROP_LASTPRINT
PROP_CREATION
PROP_LASTSAVE
// Integer stats
PROP_PAGES
PROP_WORDS
PROP_CHARS
PROP_SECURITY
PROP_VERSION
//// Office Extended Document properties
// Strings
PROP_CATEGORY
PROP_FORMAT
PROP_MANAGER
PROP_COMPANY
PROP_GUID
PROP_LINKBASE
// Integer statistics
PROP_BYTES
PROP_LINES
PROP_PARAS
PROP_SLIDES
PROP_NOTES
PROP_HIDDENSLIDES
PROP_MMCLIPS
PROP_CCHWSPACES // count of characters including spaces
// Booleans
PROP_SHAREDDOC
PROP_HYPERLINKSCHANGED
Get, Set, and Free Thumbnail can be used to view and modify the thumbnail image of a document.
HRESULT GetThumbnail(LPSINAIL *lplpThumbnail);
HRESULT SetThumbnail(LPSINAIL lpThumbnail);
// FreeThumbnail must be used to free
// the lpThumbnail returned from GetThumbnail()
VOID FreeThumbnail(LPSINAIL lpThumbnail);
The Thumbnail should be in the following format:
typedef struct tagSINAIL
{
DWORD cbData; // size of *pdata
DWORD cftag; // either 0,-1,-2,-3, or positive. This decides the size of pFMTID.
BYTE *pbFMTID; // bytes representing the FMTID
BYTE *pbData; // bytes representing the data
} SINAIL;
typedef SINAIL FAR * LPSINAIL;
The IMsocCustomDocProp object allows access to the custom document properties of a document.
Get and set the property name
HRESULT SetName(LPWSTR wzName);
HRESULT GetName(LPWSTR wzName, UINT cbMax);
Get and set the property value
HRESULT SetValue(VARIANT* pvarValue);
HRESULT GetValue(VARIANT** ppvarValue);
Get and set a string that the application uses as a “source” to the linked value
DWORD CchLinkSource();
HRESULT GetLinkSource(LPWSTR wzLink, UINT cbMax);
HRESULT SetLinkSource(LPWSTR wzLink);
Whether a link exists to the document
BOOL FGetLinkToContent();
HRESULT SetLinkToContent(BOOL fLink);
Is the link still valid (exists, available, etc)
BOOL FGetLinkValidity();
HRESULT SetLinkValidity(BOOL fValidLink);
Whether it is visible in the dialog
BOOL FGetVisible();
HRESULT SetVisible(BOOL fVisible);
HRESULT Delete(); // Deletes this property from CustomDocumentProperties set
HRESULT Release(); // release and free this object
The IMsocHLink object allows access to the hyperlink properties of a document. It is not possible to add a hyperlink or physically delete a hyperlink, although you may use MarkAsDeleted to mark a hyperlink as deleted, and it will be removed when the document is loaded by the application the next time.
Get and set the address and sub-address of the hyperlink properties
DWORD CchAddress();
HRESULT SetAddress(LPWSTR wz);
HRESULT GetAddress(LPWSTR wz);
DWORD CchSubAddress();
HRESULT GetSubAddress(LPWSTR wz);
HRESULT SetSubAddress(LPWSTR wz);
DWORD GetStatus();
HRESULT MarkAsDeleted();
DWORD DwGetAppData();
DWORD SetAppData(DWORD dwData);
HRESULT Release();
// Get the OfficeCompatible interface IOfficeCompatible *pOC = CreateOfficeCompatible(L”SampleApp”, L”SampleAplication”) if (pOC != NULL) { // Create a Document Property Object IMsocDocProps *pDocProps = pOC->PidpCreateDocProps(); if (pDocProps == NULL) return(); if (FAILED(pDocProps->Load(L”\test.doc”))) { pDocProps->Release(); return(); } pDocProps->ShowDialog(hwndParent, L”Caption”, L”\test.doc”, NULL); IMsocBuiltinDocProps** pBuiltInDocProps = pDocProps->GetBuiltinDocProps(pBuiltInDocProps); if (pBuiltInDocProps == NULL) { pDocProps->Release(); return(); } VARIANT var; GetProp(PROP_TITLE, &var);}
DocumentProperties are also available through the OfficeCompatible Automation interfaces. OfficeCompatible uses the same automation as Office. Documentation, and sample code for Document Property automation can be found in the Office help files.