TouchProp

A command line program to get and set* any file property exposed by the Windows property system.

* For those properties that are read-write and supported for a file type.

Background

The Windows property system provides a generic interface to access file system and file metadata properties. Almost everything about a file that you can see, and where possible change, via Windows Explorer is exposed through the property system. TouchProp uses this programmatic interface to provide a means of reading and writing these properties from a command line program.

You can find more information on the Windows property system here.

Example Usage

The following command:

TouchProp MyPhoto.jpg System.Comment

will output the Comments property of the file MyPhoto.jpg.

While the following command:

TouchProp MyPhoto.jpg System.Comment "A great photo"

will change the Comments property of the file MyPhoto.jpg to: "A great photo".

Similarly, the following command will change the jpg file's "Date Taken" property to 11:22:33 25 December 2001

TouchProp MyPhoto.jpg System.Photo.DateTaken "2001/12/25:11:22:33.456"

The names "System.Comment" and "System.Photo.DateTaken" in the examples are known as the canonical property name. You can find information on canonical names here.

How to Find the Canonical Name of a Property

The following command will output a list of all the possible properties available on your system.

TouchProp -listprops

This is useful because the property system is extensible by third party products, and different versions of Windows may support different properties, though the most common are likely to be available on any supported version of Windows.

It's probably easiest to deal with this list by redirecting the output to a file:

TouchProp -listprops > properties.txt

and then loading the output file into your favourite spreadsheet program such as Microsoft Excel. It's a tab delimited file, so should import easily into the spreadsheet.

Once loaded into a spreadsheet, each row contains the following columns:

  1. The Canonical Name that you use on the TouchProp command line to identify the property you're using.
  2. The Descriptive Name. If the property has one, this is the name usually shown by Explorer in the column in details mode view and the file's Details property page, so it may be the name that you'll search for in order to find its canonical name.
  3. A read-only or read-write indication. A read-only property can't be modified, a read-write one can be if the particular file type supports it.
  4. The type of the property
    Properties can be numeric, string, date/times, and multiple values of these. See below for more information on property types.
  5. For property values that have enumerated values, the enumerated value options. See Enumerated Values below for more information.

Note that the canonical name must be spelled correctly with the correct case. "system.author" will not work, it has to be "System.Author".

NOTE: The following lists are types that I've encountered in testing, others may be listed on your system.

Supported Property Types

Listed as Description Output example Input format/example
IntN 1-8 byte signed integer number 1234 [-1234] 1234
UIntN 1-8 byte unsigned integer number 5678 5678
RealN Floating point (real) number 12.34 12.34
Boolean Boolean value Depends on the specific property Depends on the specific property
Unicode String
Filetime Date+time timestamp Your locale date/time format yyyy/MM/dd:HH:mm:ss.fff

yyyy: 4 digit year
MM: 2 digit month
dd: 2 digit date
HH: 24h hours
mm: minutes
ss: seconds
fff: thousandths of a second
Vector of ... The property is multi-valued Value1;Value2;Value3 Value[;ValueN]

Notes:

All properties are not applicable to all file types.

 If a file doesn't have a value for a property, TouchProp outputs: "The property value is empty".

If a property isn't applicable to the file type, TouchProp outputs: "Failed to set the property value. The property may not be applicable for the type of file."

Unsupported Types

The list from the -listprops option will show lots of properties that have types that are not currently supported by TouchProp. For example:

VT_BLOB Length-prefixed bytes
VT_STREAM The name of the stream follows
VT_CF Clipboard format
VT_CLSID A class ID
VT_UNKNOWN IUnknown

There's currently nothing TouchProp can do with these properties. If you encounter one of these (or some other) that you think would be useful, please let us know.

PowerShell DateTime Handling

If you're not familiar with handling timestamps in PowerShell, here's some information and examples that I've found useful to know.

The following examples have TouchProp.exe in the current working directory and the TestPhoto.jpg file in the parent directory.

Gets the DateTaken value stored in a DateTime variable named dtVar

$dtVar=Get-Date(.\touchprop ..\TestPhoto.jpg System.Photo.DateTaken)

Add/Subtract an hour to a DateTime

$dt2=$dtVar.AddHours(1)
$dt2=$dtVar.AddHours(-1)

Convert a PowerShell DateTime variable into the TouchProp format for setting a Filetime property with TouchProp

$dt2.ToString("yyyy/MM/dd:HH:mm:ss.fff")

Enumerated values

Many properties can only be discrete enumerated values; they are are often (unsigned) integer value types, but are output as one of the enumeration names shown for the property via the -listprops option.

 For example, the System.Photo.Contrast property may be output as "Normal", "Soft", or "Hard". You can modify the value by using the value (0, 1, 2) or by the corresponding enumeration output name. Note that if you use the name, it must match exactly, so for this property, "Soft" would be correct, but "soft" would result in an error.

Some property values have "ranged" enumerations - such as date/times, allowing you to use values such as "Yesterday", or "Earlier this month", but they are not precise times, so I think you'll find they're of limited practical use.

Multi-valued Properties

Many properties can have multiple values, for example, the System.Author (Authors) property is a multi-valued string property. If you display it using:

TouchProp MyPhoto.jpg System.Author

If the file has that property, TouchProp might output something like this:

David Lowndes; Julie Lowndes

To change the values, you can enter the following command:

TouchProp MyPhoto.jpg System.Author "Author1 Name[;AuthorN Name]"

i.e. repeat the section inside [] for each value and each value is separated with a semi-colon ';'

Known Quirks

Some properties may apparently be written OK ,with no problem is reported, but the underlying value doesn't change. For example, changing System.GPS.LongitudeDenominator on a JPG never seems to change the values.

Your feedback please

This is an early public release to get your feedback on this program. I've developed and tested it against a variety of files, but it now needs more people to try it. There's likely to be things that I've forgotten to write about here and things that may not work correctly, so please let me know via email of anything you encounter that's not covered in this document. Equally valuable to me is knowing what you're doing with it so that I can make it better suit your needs, so again, please let me know.

Thanks for your feedback.

David Lowndes