The Great Flying Tortoise : Property System

Code for Previous Blog Posts

benkaras — Wed, 10 Jan 2007 08:55:00 GMT

Someone asked if I had a copy of the code I've been using in my blog so far. Well, I didn't as of 5pm today, so I went back and collected the code into 3 projects:

propreader.exe <file>
- Prints a list of all properties we know about the file
propwriter.exe <file> <property> <value>
- Writes a single value
proplister.exe <file> <proplist>
- Prints all the properties included in a proplist (e.g. System.PropList.PreviewDetails)

I've attached the code here (code.zip).

Enjoy!

-Ben Karas

Choosing your property API

benkaras — Fri, 05 Jan 2007 23:00:00 GMT

It is time that I talk a little about what to do if you want your application to run on XP. There are three sets of APIs, each with subtle differences and caveats, and ultimately your choice requires deciding what platform your application must run on:

Windows Vista:

Call IShellItem2::GetPropertyStore to get an IPropertyStore interface. The output property store includes property handler properties (e.g. Photo dimensions) and innate properties (e.g. Size, Name). This is your one-stop-shop for properties.

Caveat: This technique only works on Vista and later OSes.

Windows XP with Windows Desktop Search 3.x:

You can pass an IShellItem interface to PSGetItemPropertyHandler to get an IPropertyStore interface. Much of the property system works with Windows Desktop Search 3.x, so you can ask for property descriptions and everything. One upshot is that this API works identically on Vista so if you are able to choose to use it, you don't have to detect versions or anything.

Unfortunately, innate properties are only available through methods on IShellFolder and IShellFolder2. So you're on your own for those.

Caveat: Properties written to this API may or may not readable on Vista. [Aside: The full story is more complicated, but I'd like to move on for now] Innate properties like PKEY_Size are not exposed.

Windows XP; Windows XP with Windows Desktop Search 2.x:

Properties on XP are exposed through IPropertySetStorage. The supported technique is to call IShellFolder::BindToStorage(IPropertySetStorage) for the item.

Innate properties such as size and name are exposed through various methods on IShellFolder and IShellFolder2.

Caveats: Properties written with this API may or may not be readable on Vista. Furthermore, on Vista, this technique only works for some namespaces and not others.

Gotcha: Many people mistakenly call StgOpenStorageEx. Don't do that! StgOpenStorageEx is only supported for specific formats like OLE Compound Documents or NTFS secondary stream storage. StgOpenStorageEx doesn't know how to read the EXIF header from a .JPG image. IShellFolder::BindToStorage knows how to do such things.

Best of all worlds:

If you really enjoy coding, you can detect if a given API is present by calling GetProcAddress or QueryInterface [Aside: please don't detect versions... just directly test if the API is present or not], select the best available API, and deliver an application that works better on Vista. Hey, "Works better on Vista" sounds like a marketing slogan -- you could have fun coding and sell more software too!

-Ben Karas

Writing properties #9 - Summary

benkaras — Tue, 21 Nov 2006 23:00:00 GMT

Coding to the Windows SDK
Reading properties #7 - Summary

Writing properties #1 - Simple beginnings
Writing properties #2 - Filetype support?
Writing properties #3 - Which properties are writable?
Writing properties #4 - Which properties are writable?
Writing properties #5 - Property lists
Writing properties #6 - GPS_READWRITE omits read-only data sources
The deal with IPropertyStoreCapabilities
Writing properties #8 - Canonical Values
Gotcha: You must release property stores quickly

----

Writing properties is very simple at the core: you just call SetValue() and then Commit(). But then there are a bunch of details surrounding this task that make it a little more complicated. To close this topic, I want to give one more tip:

The best way to determine if the file/filesystem/filetype itself is writable is to simply call IShellItem2::GetPropertyStore(GPS_READWRITE). This performs the necessary ACL checks, attribute checks, etc. The only downside is that the return value is non-actionable. If you want to display a more specifical error message or offer corrective options, you'll have to program those yourself.

Thus, a property editing user interface will typically do the following:

Test writability by opening the file with GPS_READWRITE and then release that interface
Reopen the file with GPS_DEFAULT
Use a property list to populate the UI
Test writability using IPropertyDescription::GetTypeFlags
Test writability using IPropertyStoreCapabilities::IsPropertyWritable
Release the read-only property store

Then to save changes, it...

Opens the file with GPS_READWRITE
Calls IPropertyStore::SetValue for each change
Calls IPropertyStore::Commit to save the changes
Releases the read-write store

-Ben Karas

ps. There is an even simpler way to write properties using IFileOperation. I'll have to revisit that another time.

Writing properties #8 - Canonical Values

benkaras — Wed, 15 Nov 2006 23:38:00 GMT

There's one last topic I want to touch on before I close this series: Canonical values. So far I've talked about how to determine when the property itself is writable. But once you decide to write a property, how do you figure out what type the value should be? What if you get it wrong?

The first edition of the property system didn't enforce the type of values. As a result, some people used VT_UI4, others VT_I2, and some just used strings for the same property. This led to complicated error-prone code. So we decided to add an enforcement layer that makes sure the value complies with the type specified by the property description and performs some minor cleanup when possible. We dubbed this the "coercion" layer.

To cut to the chase, this layer uses IPropertyDescription::IsCanonicalValue and IPropertyDescription::CoerceToCanonicalValue to enforce the type requirements. So if you are creating a program that writes properties, you might want to add some debug code to see if your values pass the test and to see how they get interpreted by the coercion layer.

Here's a quick summary of what happens in IPropertyDescription::CoerceToCanonicalValue:

Convert "empty" values to VT_EMPTY. This includes VT_NULL, null pointers, and strings with just spaces.
Convert the value to the type given by IPropertyDescription::GetPropertyType
Convert the result to a canonical form (remove leading/trailing spaces, removing duplicates from vectors, etc)

MSDN will eventually get expanded documentation on this function, but you should be able to figure out what's happening through experimentation too.

As a final note, a property handler can decide it doesn't like a value and either reject or truncate it. Unfortunately, it won't tell you why -- it just returns and error or INPLACE_S_TRUNCATED to indicate when this happened.

-Ben Karas

The deal with IPropertyStoreCapabilities

benkaras — Tue, 14 Nov 2006 22:47:00 GMT

Have you ever felt this before? It's the day after you send your product to manufacturing. You step back, look at the big picture, and start to see minor flaws. A dread sinks in when you realize you just blogged about it too! That was Monday morning. :-) The good news is that our analysis shows that the flaws are minor. They are unlikely to affect people in real practice, don't affect the code we wrote, and there are workarounds if you're trying something complicated. So... here's the whirlwind tour of IPropertyStoreCapabilities (IPSC):

We needed a way to mark which properties are writable and which aren't. We looked at a few models and decided we wanted a runtime check for writability. So we invented IPSC to let a property handler declare what properties it supports and those it doesn't. For example, the PNG property handler uses IPSC to tell explorer that it supports writing System.Photo.DateTaken, but nothing else.

Enter the multiplex property store. This is a building block object we wrote to help shell namespaces and property handlers to build their property stores. Like the name suggests, it selects from various inputs. From the start, we found this object hard to design and work with. We had to figure out reasonable ways to select which input to select. We had to decide how to handle writing. How to handle IPSC. To keep things simple, we decided to not have an interface to let the MUX know which store handles what property. Instead...

The MUX is read-only (i.e. IPropertyStore::SetValue returns STG_E_ACCESSDENIED).
IPropertyStore::GetValue would select the first value it finds.
IPSC::IsPropertyWritable queries the first store that implements this interface.

#1 means the store returned by GPS_READWRITE cannot use the MUX. This means if you use IPSC on a GPS_READWRITE store, you don't get the full picture since we're ignoring the read-only data sources.

#2 is interesting, but doesn't affect us much today.

#3 is what made me panic yesterday. Imagine if two stores implemented IPSC and were joined by a MUX. The calling application would only be able to query the first store! So here are the mitigating circumstances:

The filesystem shell namespace extension uses MUX's, but the only implementation of IPropertyStoreCapabilities is the property handler. So this is OK.
None of the filetype property handlers that ship with Windows Vista use MUX's internally. So this is OK.
All other places in Windows Vista that would get in trouble from this are read-only to begin with. So this is OK.
The only time you'd need two stores to implement IPSC is if the filetype is writable and both stores deal with non-innate properties (because this is in the only time you need to provide the distinction). This is less common than other scenarios.
Even if a namespace extension (or property handler) needs to have two stores implement IPSC, they could work around this by having the read-only implementation delegate to the read-write implementation.

So in the end, I am going back to my original recommendation: Use IPropertyStoreCapabilities with GPS_DEFAULT. This is what explorer does, the shipping proprety stores are fine, and other hopefully other developers will find and understand my blog.

-Ben

Writing properties #7 - IPropertyStoreCapabilities requires GPS_READWRITE

benkaras — Fri, 10 Nov 2006 23:00:00 GMT

[Edit: 2006/11/13 - My original post got this topic entirely backwards. I've fixed the title and will provide details about this tomorrow. ]

-Ben Karas

Writing properties #6 - GPS_READWRITE omits read-only data sources

benkaras — Thu, 09 Nov 2006 23:00:00 GMT

You'll recall that there are multiple layers in the property system. In particular, the GPS_DEFAULT property system stack for files in the filesystem namespace looks like this:

[ Application using GPS_DEFAULT ]
[ Coercion Layer ]
[ Shell Item Layer ]*
[ File System Namespace ]*
[ Property Handler ]*

I've starred the layers that provide properties. The thing to notice is that there are multiple sources of properties when you use GPS_DEFAULT.

The non-obvious datum is that GPS_READWRITE contains only a portion of this stack. Notice how the application is talking to just the property handler:

[ Application using GPS_READWRITE ]
[ Coercion Layer ]
[ Property Handler ]*

The repurcussion for applications is that they cannot see data provided by the other data sources when using GPS_READWRITE. They cannot read all the properties like they could using GPS_DEFAULT. So if you are building a details pane like the one in explorer, you'll have to read properties using GPS_DEFAULT, close the store, and then use GPS_READWRITE for writing.

The propsys.idl file concisely mentions this tidbit:

GPS_READWRITE = 0x00000002, // Writable stores will only include handler properties

-Ben Karas

p.s. propsys.idl contains a lot of comments that apparently got stripped out from propsys.h. Ouch. I highly suggest peeking at the IDL files to see if some developer posted a comment there for the interface or structure you are using.

Writing properties #5 - Property lists

benkaras — Tue, 07 Nov 2006 23:00:00 GMT

So if a property handler doesn't enumerate which properties it supports writing, then how does the explorer pick which properties to show? Well, the shell namespace extension containing the item specifies the list of properties it wants to show in a particular piece of UI. To query this property list, call IPropertyStore::GetValue(PKEY_PropList_XXX) on the read-only property store. The shell namespace extension returns a property list similar to L"prop:System.Title;System.Size;System.Keywords" in a VT_LPWSTR propvariant. There are prefixes for each property name which I won't mention yet. For now, just know that you can let the system parse this string by calling PSGetPropertyDescriptionListFromString.

Let's try this out. I am going to modify parts from past programs to write a quick loop through the property list on my goat picture. First, I modified my wmain function to let me specify the PKEY_PropList_XXX from the command line using its canonical name:

int wmain(int argc, WCHAR **argv)
...
                    PCWSTR pszList = argv[2];
                    PROPERTYKEY keyList;
                    hr = PSGetPropertyKeyFromName(pszList, &keyList);
                    if (SUCCEEDED(hr))
                    {
                        hr = _PrintPropertyStore(keyList, pps);
                    }

You've seen that kind of stuff before. Next, _PrintPropertyStore is rewritten to obtain the list and loop over it:

HRESULT _PrintPropertyStore(__in REFPROPERTYKEY keyList, __in IPropertyStore *pps)
{
    // Get the property list ...
    PROPVARIANT propvarList = {0};
    HRESULT hr = pps->GetValue(keyList, &propvarList);
    if (SUCCEEDED(hr))
    {
        // ... in string form
        PCWSTR pszList = PropVariantToStringWithDefault(propvarList, NULL);
        if (pszList)
        {
            // parse the property list string to get an interface
            IPropertyDescriptionList *plist;
            hr = PSGetPropertyDescriptionListFromString(pszList, IID_PPV_ARGS(&plist));
            if (SUCCEEDED(hr))
            {
                // loop through the entries ...
                UINT cProps;
                hr = plist->GetCount(&cProps);
                for (UINT i = 0; SUCCEEDED(hr) && i < cProps; i++)
                {
                    IPropertyDescription *ppropdesc;
                    hr = plist->GetAt(i, IID_PPV_ARGS(&ppropdesc));
                    if (SUCCEEDED(hr))
                    {
                        // ... getting values ...
                        PROPVARIANT propvar = {0};
                        hr = PSGetPropertyValue(pps, ppropdesc, &propvar);
                        if (SUCCEEDED(hr))
                        {
                            PROPERTYKEY key;
                            hr = ppropdesc->GetPropertyKey(&key);
                            if (SUCCEEDED(hr))
                            {
                                // ... checking if it is writable ...
                                if (_IsPropertyValueWritable(pps, key))
                                {
                                    wprintf(L"WRITABLE: ");
                                }
                                // ... and printing the value
                                hr = _PrintPropertyValue(key, propvar);
                            }
                            PropVariantClear(&propvar);
                        }
                        ppropdesc->Release();
                    }
                }
                plist->Release();
            }
        }
        PropVariantClear(&propvarList);
    }
    return hr;
}

This code is pretty straight forward. I get the list in string form, convert it to an interface, and then loop through its entries. Since the list enumerates IPropertyDescription interfaces, I snuck a call in to PSGetPropertyValue which wraps a call to IPropertyStore::GetValue for me. Next, I grab the property key so to pass to _IsPropertyValueWritable() and _PrintPropertyValue(). I thought about modifying these to take an IPropertyDescriptionList, but this seemed simpler.

Anyway, this program shows a more complete picture about what values are present and writable on my test goat:

> propshow4.exe scan0010.jpg System.PropList.PreviewDetails
System.PropList.PreviewDetails properties for 'scan0010.jpg'
WRITABLE: System.Photo.DateTaken: VT_FILETIME: 2006/07/30:00:33:34.000 --> 7/29/2006 4:33 PM
WRITABLE: System.Keywords: VT_VECTOR|VT_LPWSTR == Sol Duc Valley; Wildlife
WRITABLE: System.Rating: VT_UI4: 99 --> 5 Stars
System.Image.Dimensions: VT_LPWSTR == 1139 x 769
System.Size: VT_UI8: 653729 --> 638 KB
WRITABLE: System.Title: VT_LPWSTR == Mountain goat
WRITABLE: System.Author: VT_VECTOR|VT_LPWSTR == Ben Karas
WRITABLE: System.Comment: VT_EMPTY ==
System.OfflineAvailability: VT_EMPTY ==
System.OfflineStatus: VT_EMPTY ==
WRITABLE: System.Photo.CameraManufacturer: VT_LPWSTR == HP
WRITABLE: System.Photo.CameraModel: VT_LPWSTR == HP Scanjet 4370
WRITABLE: System.Subject: VT_EMPTY ==
System.Photo.FNumber: VT_EMPTY ==
System.Photo.ExposureTime: VT_EMPTY ==
WRITABLE: System.Photo.ISOSpeed: VT_EMPTY ==
...[snip]...

System.PropList.PreviewDetails (PKEY_PropList_PreviewDetails) property list controls which properties appear in the details pane of explorer so it's a nice start to listing out the useful writable properties on an item. As you can see, there is a mixture of read-only and editable properties. That's pretty common for property lists. They are UI oriented and not the easiest to work with. But if you have the right building blocks you can figure out what to do.

The details pane from explorer. Notice how the properties are ordered the same as my output.

The other important property lists are:

System.PropList.PreviewTitle - The 2 properties used as a title in the details pane
System.PropList.FullDetails - The list of properties found in the details dialog
System.PropList.InfoTip - The list of properties found in the infotip of the item
See propkey.h for less common property lists

Ok, this was much much longer than I intended. I'll talk about how to register property lists another day.

-Ben Karas

Writing properties #4 - Which properties are writeable?

benkaras — Mon, 06 Nov 2006 23:00:00 GMT

I'm going to make a first stab at printing out a list of properties that are writable for a given file. I'll spoil the fun and let you know that my attempt today will not fully succeed. I'll explain later. For now, let's see some code!

You'll recall I wrote a program to loop through the properties in a file and dump them out. I am going to simply modify that program to only print out those properties that pass my _IsPropertyValueWritable() test from last time. Here's the new function for printing a property store:

HRESULT _PrintPropertyStore(IPropertyStore *pps)
{
    DWORD cProps;
    HRESULT hr = pps->GetCount(&cProps);
    for (DWORD i = 0; SUCCEEDED(hr) && i < cProps; i++)
    {
        PROPERTYKEY key;
        hr = pps->GetAt(i, &key);
        if (SUCCEEDED(hr))
        {
            if (_IsPropertyValueWritable(pps, key))
            {
                PROPVARIANT propvar = {0};
                hr = pps->GetValue(key, &propvar);
                if (SUCCEEDED(hr))
                {
                    hr = _PrintPropertyValue(key, propvar);
                    PropVariantClear(&propvar);
                }
            }
        }
    }
    return hr;
}

Now let's run this on my favorite goat picture:

Writeable Properties for 'scan0010.jpg'
System.Photo.Saturation: VT_UI4: 0 --> Normal
System.Photo.EXIFVersion: VT_LPWSTR == 0220
System.Rating: VT_UI4: 99 --> 5 Stars
System.Photo.DateTaken: VT_FILETIME: 2006/07/30:00:33:34.000 --> 7/29/2006 4:33 PM
System.Photo.CameraManufacturer: VT_LPWSTR == HP
System.Photo.CameraModel: VT_LPWSTR == HP Scanjet 4370
System.Photo.Sharpness: VT_UI4: 0 --> Normal
System.Title: VT_LPWSTR == Mountain goat
System.Author: VT_VECTOR|VT_LPWSTR == Ben Karas
System.Keywords: VT_VECTOR|VT_LPWSTR == Sol Duc Valley; Wildlife

What, that's it? Just ten (10) properties are writable to JPGs? Why, the properties details dialog shows more than that! Obviously something is missing. I'll get into that next time.

Writing properties #1 - Simple beginnings

benkaras — Mon, 16 Oct 2006 22:00:00 GMT

I'm going to be talking about writable properties over the next few days. I know that some of you are itching to try this out yourselves, so here is an overly simplistic program that will write a single property to a file. I have omitted a lot of diagnostic code, so this will not work for all files, all strings, or all properties. I plan to go through those details another day.

int wmain(__in int argc, __in_ecount(argc+1) WCHAR **argv)
{
    HRESULT hr = CoInitializeEx(NULL, COINIT_APARTMENTTHREADED | COINIT_DISABLE_OLE1DDE);
    if (SUCCEEDED(hr))
    {
        if (argc < 3)
        {
            wprintf(L"Usage: %s <filename> <property> <value>\n", argv[0]);
        }
        else
        {
            PCWSTR pszFile = argv[1];
            PCWSTR pszProperty = argv[2];
            PCWSTR pszValue = argv[3];

            PROPERTYKEY key;
            hr = PSGetPropertyKeyFromName(pszProperty, &key);
            if (SUCCEEDED(hr))
            {
                IShellItem2 *psi;
                hr = _GetShellItemFromRelativePath(pszFile, IID_PPV_ARGS(&psi));
                if (SUCCEEDED(hr))
                {
                    IPropertyStore *pps;
                    hr = psi->GetPropertyStore(GPS_READWRITE, IID_PPV_ARGS(&pps));
                    if (SUCCEEDED(hr))
                    {
                        PROPVARIANT propvar = {0};
                        hr = _GetValueFromString(key, pszValue, &propvar);
                        if (SUCCEEDED(hr))
                        {
                            hr = pps->SetValue(key, propvar);
                            if (SUCCEEDED(hr))
                            {
                                hr = pps->Commit();
                            }
                            PropVariantClear(&propvar);
                        }
                        pps->Release();
                    }
                    psi->Release();
                }
            }
            wprintf(L"Wrote %s:%s to %s; hr = 0x%08x\n", pszProperty, pszValue, pszFile, hr);
        }

        CoUninitialize();
    }
}

This code figures out which property to set, opens the store for writing, figures out the value to set, sets it, and commits the changes. Here are the helper functions I'm using:

HRESULT _GetValueFromString(__in REFPROPERTYKEY key, __in PCWSTR pszValue, __out PROPVARIANT *ppropvar)
{
    return InitPropVariantFromString(pszValue, ppropvar); 
}

HRESULT _GetShellItemFromRelativePath(
    __in PCWSTR pszRelative, 
    __in REFIID riid, 
    __deref_out void **ppv)
{
    WCHAR szFile[MAX_PATH];
    HRESULT hr = StringCchCopyW(szFile, ARRAYSIZE(szFile), pszRelative);
    if (SUCCEEDED(hr))
    {
        PathUnquoteSpacesW(szFile);

        WCHAR szDir[MAX_PATH];
        hr = GetCurrentDirectory(ARRAYSIZE(szDir), szDir) ? S_OK : E_FAIL;
        if (SUCCEEDED(hr))
        {
            WCHAR szPath[MAX_PATH];
            hr = PathCombineW(szPath, szDir, szFile) ? S_OK : E_FAIL;
            if (SUCCEEDED(hr))
            {
                hr = SHCreateItemFromParsingName(szPath, NULL, riid, ppv);
            }
        }
    }
    return hr;
}

And here's my output:

C:\> propset.exe scan0010.jpg System.Keywords abc
Wrote System.Keywords:abc to scan0010.jpg; hr = 0x00000000

-Ben Karas

see also: Reading properties

Gotcha: You must release property stores quickly

benkaras — Fri, 13 Oct 2006 22:00:00 GMT

The general rule is that you should minimize the length of time you have a property store open. It is best to acquire the data you need and then release the store.

Read-only property stores lock files for reading using a filesystem oplock. An oplock does more than just lock a file -- it blocks writers until the reader releases the lock. This way a short-lived read operation simply delays a write instead of causing it to fail outright.

Now the gotcha is that the following code will deadlock:

IShellItem2 *psi = ...
IPropertyStore *ppsReadOnly;
psi->GetPropertyStore(GPS_DEFAULT, IID_PPV_ARGS(&ppsReadOnly));

IPropertyStore *ppsReadWrite;
psi->GetPropertyStore(GPS_READWRITE, IID_PPV_ARGS(&ppsReadWrite));

ppsReadWrite->Release();
ppsReadOnly->Release();

The first call to GetPropertyStore creates the oplock. Any writers will block until it is released. Thus the second call to GetPropertyStore blocks. But the reader won't get released until the call completes.

You might ask why was this feature added if it has such a big gotcha? There are several reasons. First, locking a file for reading is an important feature for the code reading the file. We have to lock the file to prevent the data from changing while someone is reading it. Second, since we lock the file anyway, callers should never have the file open long-term anyway. Third, we discovered in testing that Windows often tried to read from a file just around the same time as it wanted to write to a file. This led to error dialogs. Using an oplock eliminates these error dialogs by waiting until the short-lived reader is finished.

-Ben Karas

Properties coding expedition #7 - The final output

benkaras — Thu, 12 Oct 2006 22:00:00 GMT

This coding expedition has developed a tool that can dump out all the properties on a file. If you are curious about the property system, I highly recommend you build this tool and run it on various file types.

Coding to the Windows SDK
Part 1 - Binding to an item
Part 2 - Printing the IPropertyStore
Part 3 - Printing a value
Part 4 - The output
Part 5 - Stripping characters
Part 6 - Developer friendly output

For your pleasure, I ran this tool on a JPG on my system (at right). Here are some highlights:

String properties can be vectors, or single valued. Vectors can have 0, 1 or more values and are formatted with semicolons (;):

System.Author: VT_VECTOR|VT_LPWSTR == Ben Karas
System.Keywords: VT_VECTOR|VT_LPWSTR == Sol Duc Valley; Wildlife
System.ItemNameDisplay: VT_LPWSTR == scan0010.jpg

Numbers are stored in a variety of formats and are sometimes formatted or not. It turns out 5 stars corresponds to a raw value of 99:

System.Image.BitDepth: VT_UI4 == 24
System.Size: VT_UI8: 653729 --> 638 KB
System.Rating: VT_UI4: 99 --> 5 Stars

Raw dates look different than formatted dates. Actually, the raw value is stored in 8 bytes, but PropVariantToString gave us a locale-invariant format:

System.DateImported: VT_FILETIME: 2006/09/30:05:12:06.000 --> 9/29/2006 10:12 PM

Some properties are not meant for display:

System.ParsingBindContext: VT_UNKNOWN: <unprintable raw value> --> <formatfordisplay failed>
System.FindData: VT_VECTOR|VT_UI1: 32; 0; 0; 0; 0; 71; 228; 38; 161; 228; 198; ...

And there is even a property the system doesn't know about!

{9E5E05AC-1936-4A75-94F7-4704B8B01923} 0: VT_BSTR == scan0010.jpg

What I want to impress on you is that the property system supports a rich set of storage formats for values. Property handlers, such as the one for JPGs, are capable of exposing a large amount of information about a file. Finally, the rules about when to display and how to format values are data driven by property schemas.

-Ben Karas

Properties coding expedition #6 - Developer friendly output

benkaras — Thu, 12 Oct 2006 03:00:00 GMT

Using the tool I developed in this series, I know that my test photo has "Rating: 5 Stars". But how is this value actually represented in the JPG itself? Let's answer that by adding some developer friendly output. Here's what I did:

First, I need a developer-friendly label. I can get the canonical name using PSGetNameFromPropertyKey. If a property doesn't have a canonical name, I just grab the "{GUID} PID" representation.

HRESULT _PrintPropertyValue(__in REFPROPERTYKEY key, __in REFPROPVARIANT propvar)
{
    // 1. Get a canonical name for this property
    PWSTR pszName = NULL;
    HRESULT hr = PSGetNameFromPropertyKey(key, &pszName);
    if (FAILED(hr))
    {
        // 1b. There's no canonical name: get the "{GUID} PID" string.
        WCHAR szKey[100];
        hr = PSStringFromPropertyKey(key, szKey, ARRAYSIZE(szKey));
        if (SUCCEEDED(hr))
        {
            hr = SHStrDupW(szKey, &pszName);
        }
    }

Here, I get the type of the value. I'll show the helper later.

    PCWSTR pszType = NULL;
    if (SUCCEEDED(hr))
    {
        // 2. Get the type
        pszType = _GetVarTypeString(propvar.vt);
    }

Next, I get the raw value as a string. PropVariantToStringAlloc can convert most types to strings, but failing that I just print a message.

    PWSTR pszRawValue = NULL;
    if (SUCCEEDED(hr))
    {
        // 3. Get the raw value
        hr = PropVariantToStringAlloc(propvar, &pszRawValue);
        if (FAILED(hr))
        {
            hr = SHStrDupW(L"", &pszRawValue);
        }
    }

I also need the formatted value.

    PWSTR pszFormattedValue = NULL;
    if (SUCCEEDED(hr))
    {
        // 4. Get the formatted value
        hr = PSFormatForDisplayAlloc(key, propvar, PDFF_DEFAULT, &pszFormattedValue);
        if (FAILED(hr))
        {
            hr = SHStrDupW(L"", &pszFormattedValue);
        }
    }

Finally, I check to see if the formatted value differs from the raw value. Sometimes it does and sometimes it doesn't depending on the formatting that is performed. This results in slightly cleaner output:

    if (SUCCEEDED(hr))
    {
        // LRM RLM LRE RLE PDF LRO RLO
        _StripCharacters(pszFormattedValue, L"\x200e\x200f\x202a\x202b\x202c\x202d\x202e");
        _StripCharacters(pszRawValue, L"\x200e\x200f\x202a\x202b\x202c\x202d\x202e");
        if (StrCmpCW(pszFormattedValue, pszRawValue))
        {
            // The values are different: print them both
            wprintf(L"%s: %s: %s --> %s\n", pszName, pszType, pszRawValue, pszFormattedValue);
        }
        else
        {
            // The values are the same: print just one
            wprintf(L"%s: %s == %s\n", pszName, pszType, pszFormattedValue);
        }
    }

    CoTaskMemFree(pszName);
    CoTaskMemFree(pszRawValue);
    CoTaskMemFree(pszFormattedValue);

    return hr;
}

As promised, here's the helper function to obtain a string form of a VARTYPE:

PCWSTR _GetVarTypeString(__in VARTYPE vt)
{
#define VARTYPEENTRY(v) case v: return L ## #v
    switch (vt)
    {
        VARTYPEENTRY(VT_EMPTY);
        VARTYPEENTRY(VT_UI1);
        ...[snip]...
    }
    return L"<Unknown type>";
}

I'll go over the output tomorrow.

-Ben Karas

Properties coding expedition #5 - Stripping characters

benkaras — Wed, 11 Oct 2006 03:00:00 GMT

In Part 4, I discovered that WideCharToMultiByte converts certain invisible non-spacing Unicode characters to ?. This makes the output look really silly in a command line application. I want to keep this as a command line application, so I need to strip these characters away. A simple helper solves this rather neatly:

void _StripCharacters(__inout PWSTR pszText, __in PCWSTR pszRemove)
{
    PWSTR pszSource = pszText;
    PWSTR pszDest = pszSource;
    while (*pszSource)
    {
        // Skip copying characters found in pszRemove
        if (!StrChr(pszRemove, *pszSource))
        {
            *pszDest = *pszSource;
            pszDest++;
        }
        pszSource++;
    }
    *pszDest = 0;   // NULL terminate
}

This modifies the input string, omitting any characters found in pszRemove. Nothing fancy. Now I call it when I want to send a string to the console:

... from part 3 ...
PWSTR pszValue;
hr = ppropdesc->FormatForDisplay(propvar, PDFF_DEFAULT, &pszValue);
if (SUCCEEDED(hr))
{
    // LRM RLM LRE RLE PDF LRO RLO
    _StripCharacters(pszValue, L"\x200e\x200f\x202a\x202b\x202c\x202d\x202e");  
    wprintf(L"%s: %s\n", pszLabel, pszValue);
    CoTaskMemFree(pszValue);
}
...

Now the output is free of those annoying question marks:

Date last saved: 9/29/2006 10:12 PM
Width: 1139 pixels
Height: 769 pixels
Horizontal resolution: 200 dpi
Vertical resolution: 200 dpi
Bit depth: 24
Dimensions: 1139 x 769

Properties coding expedition #4 - The output

benkaras — Sat, 07 Oct 2006 03:00:00 GMT

The program itself is provided in parts 1, 2, and 3. So I compiled my program and ran it from the command line. Here's a snippet of what I got back:

Properties for 'scan0010.jpg'
Folder name: propshow
Type: JPEG Image
Name: scan0010.jpg
Size: 638 KB
Attributes: A
Date modified: ?9/?29/?2006 ??10:12 PM
Date created: ?9/?30/?2006 ??8:00 AM
Date accessed: ?9/?30/?2006 ??8:00 AM
Title: Mountain goat
Authors: Ben Karas
Tags: Sol Duc Valley; Wildlife
Content created: ?9/?29/?2006 ??10:12 PM
Date last saved: ?9/?29/?2006 ??10:12 PM
Width: ?1139 pixels
Height: ?769 pixels
Horizontal resolution: ?200 dpi
Vertical resolution: ?200 dpi
Bit depth: 24
Dimensions: ?1139 x 769?
Rating: 5 Stars
...[snip 20 more lines]...

Ok, now you get a sense about what properties are on a file! JPGs happen to be one of the better supported filetypes on the system. We can see titles, authors, ratings, dimensions, etc on JPG files. Also notice the variety of information. Some items are dates, others are numbers. There's even a list of tags in there!

Now the question you really want to ask is "What are those "?" doing in there?" This is a very common question. The ? result from a bad UNICODE->OEM conversion. IPropertyDescription::FormatForDisplay inserts UNICODE LTR and RTL characters (0x200e and 0x200f). These characters let English strings display correctly on Arabic builds. Arabic strings get similar characters so that they display correctly on left to right builds. UNICODE applications display these LTR and RTL characters correctly.

But the command line (and WideCharToMultiByte) for some reason converts these to "?". Oops.

This is a time when I wish FormatForDisplay had a flag to strip these characters out; alas.