Property Store Extender

 Keywords: Property Store Utility Extender COM interfaces Vista Read Write Access File System Shell Folder Properties DSOFile GetDetailsOf Windows Media Player iTunes MP3 Tag PDF ID3 Details Tab

General Usage Information:

The Property Store Utility Extender was written to provide the Windows Interface Language with script-level access to the full featured Property Store COM interfaces that exist on Windows Vista and newer. These COM interfaces provide built-in access to a generalized property storage mechanism that is agnostic w/respect to file formats, with various property store providers being responsible for performing the low-level file I/O operations that are required to actually read & write the various properties associated with different types of files. Depending on the type of file, such as a MS Office document, a MP3 file, a WMV file, a JPG/GIF/PNG file, or a regular program file, the Property Store COM interfaces provide read [and possibly write] access to the document properties, ID3 tag, image metadata and file system information for the file.

Prior to Windows Vista, the Property Store COM interfaces either did not exist, or existed in a very limited form. Lacking this access to the Property Store functionality, WinBatch scripts were relegated to using various methods to access & manipulate the metadata that is made available through the Property Store.

To access generalized file system information and some limited document properties and ID3 tag information, the automation-enabled Shell Folder COM interface could be used to call the GetDetailsOf() method. This method retrieved a subset of the data that can be obtained via the Property Store, behaved differently across different versions of Windows and was read-only.
A special COM object projects from Microsoft, called DSOFile, could read document properties for MS Office 2007 & earlier documents, and has not been maintained or upgraded in the past several years.
The Windows Media Player could be accessed as a COM server object to gain access to the ID3 tag and other media file metadata, but to do so requires that the media files be cataloged in the Media Player's library. The Media Player is also incapable of handling various types of media, such as music files purchased & downloaded from iTunes.
iTunes cannot modify the actual ID3 tag or media file metadata; it can only modify the entry in the iTunes database that is associated with the media file. And, of course, media file has to be cataloged in the iTunes database before you can even use iTunes to read the ID3 tag / media file metadata.
External 3rd party applications, tools & utilities such as mp3tag, Irfanview, ImageMagick, exiftool, FFmpeg, PDF Creator, and other such programs could be either run by WinBatch or accessed via COM to provide various types of access to media file metadata.

With the availability of the Property Store Utility Extender, all of the property names & values that are available within the Windows Explorer's "Details" tab on the folder & file "Properties" sheet are now readily accessible from within a WinBatch Script. Not all properties can be modified via the Property Store; it is up to the property providers themselves to determine which properties are read-only and which ones are read-write. If a file's property store is opened in read-only mode, then all of the available properties can be read via the property store. If a file's property store is opened in read-write mode, then only the writable properties will be accessible via the property store. This document doesn't provide a list of which properties are read-only & read-write.

Normal usage of this extender in a WinBatch script typically involves the following sequence of steps and/or function calls:

Obtain a property store from a file by calling psuOpenPS(). This can be done to get a read-only or read-write property store. A Property Store Index value is returned by this function, which is effectively a handle to an open property store. Mutliple property stores may be opened simultaneously. Most extender functions require a Property Store Index value as their first parameter.
Call psuGetPropertyNames() to obtain a list of property names that are valid for the property store's file type and open mode [read-only vs. read-write].
Call psuGetPropertyValue() to obtain any given property's value. If the property doesn't have a value, an empty string is returned.
Call psuSetPropertyValue() to modify the value of a writeable property in the property store. This function always fails if the open-mode is read-only, and also fails if the property itself is read-only even when the open mode is read-write.
If changes have been made to the property store, they won't get written back to the file until the psuCommitChanges() function is called. The psuIsDirty() function can be called to determine if a property store has uncommitted changes.
Finally, call the psuClosePS() function to close an open property store. After this function is successfully called, the Property Store Index value that was passed in to it is no longer valid and may be returned again by a subsequent call to psuOpenPS() even if a different file's property store is opened.

Author: Chuck Chopp

[WWPSU45001.zip]

To access the functions in this extender, add the following to your script:

32-bit Extender

  
AddExtender('WWPSU45Ix86.DLL')

System Requirements: WinBatch version 2006D or newer. Windows Vista or newer.

64-bit Extender

  
AddExtender('WWPSU45Ix64.DLL')

System Requirements: WinBatch version 2011B or newer. Windows Vista or newer.

Property Store Utility Extender Installation:

Run the SETUP.WBT file to install the extender for you.

PROPERTY STORE UTILITY EXTENDER

FIXES AND IMPROVEMENTS

Version 45000 [build 3] Aug 31, 2011
Initial release of the extender with both 32-bit & 64-bit builds of the DLL.

The possible set of errors that can be returned by the extender has not yet been
documented well enough to include here. A future version should have an "Error Codes"
section added to the documentation. Questions about particular error codes will be
answered as-needed until comprehensive documentation is available.

The gps-flags parameter for the psuOpenPS() function currently has only 2 valid
values: 0 [zero] and 2 [two]. In a future version, additional flag bit values
will be documented that controls how the property store is obtained and what
properties are accessible via the property store.

The format-flags parameter for the psuGetPropertyValue() function is currently reserved
and must have a value of 0 [zero]. In a future version, actual flag bit values will be
documented that can be used to control the formatting of the property values that are
returned.

There's not a lot of example code, yet. For now, the "Examples" section of the help
topic for psuOpenPS() gives a basic demonstration. For a more comprehensive practical
application of the extender & its functions, take a look at the Property Store Explorer
script, PSExplorer.wbt, which is included with the extender & this help file.

Version 45001 [build 1] 3/25/2012
Fixed a problem where calling psuSetPropertyValue() with a value for a property name
that is not currently present in the property store would result in the error "224: The
specified property name is not valid in the specified property store." being generated.
This effectively made it impossible to add a value for a property that had never previously
existed for any particular file.

Article ID:   W17637

Filename:   Property Store Extender.txt

File Created: 2019:08:14:08:57:58

Last Updated: 2019:08:14:08:57:58

Database Search

TechHome

Property Store Extender

General Usage Information: