Here is another post in the Windows 7 Libraries post series. So far, we have covered what Windows 7 Libraries are (
Understanding Windows 7 Libraries), their internal structure, and how they integrate into the Windows Shell (
Libraries Under The Hood). You know the different programming models that are available to choose from (
Light Up with Windows 7 Libraries), and you know how to use Windows Shell APIs to consume the contents of a library (
Consuming the Contents of Windows 7 Libraries). In previous post, we focused on the Windows 7 Libraries helper functions (
Windows 7 Libraries Helpers). In this post you will learn how to stay in sync with a library.
Before Windows 7 and Libraries, you stored your music files in the My Music folder. Before Windows 7, when you wanted to play music using the Windows Media Player, you had to manually point Windows Media Player to the correct music folder and choose a song. If you moved a song from the music folder, Windows Media Player didn’t know that the file was moved. The music file would still appear in the play list, but when it was time to play the song, you would see that annoying message that Windows Media Player can’t find that music file -- all because Windows Media Player was out of sync with My Music folder. In this model, Windows Media Player needs to maintain its own database of songs and locations, and the user has to update that database manually.
With Windows 7 Libraries, this error is far less probable. You may ask, "Why?" Well the answer is simple. The Windows Media Player that ships with Windows 7 does not maintain any internal database of songs, it completely relies on the Windows 7 Music, Video, and Pictures Libraries, and it is fully synced with these libraries. This means that when you remove a song from the Music Library, it is no longer present in the Windows Media Player playlist. The following image shows that by right clicking on the Music tab you can choose to manage the Music library.
Stay in sync
You may want your application to recognized when the user makes changes to the library description, adds or removes folders from the library, or updates any of the files included in the library. There are several ways to “stay in sync,” depending on your application’s requirements. Most applications should use the Shell programming model with
SHChangeNotifyRegister for all non-service processes.
Using the Shell programming model
To detect changes in items within a library using the Shell programming model, use the
SHChangeNotifyRegister to listen for changes to items in all library folders.
SHChangeNotifyRegister can take
a single library item, for example the Music library, as a parameter to receive notifications on all content included in the library. It will note ANY status change in any of the items in the Music library. Additionally, registering the library will allow the application to receive notifications
on the fly, so libraries are updated immediately upon changes to the library. The user may additionally modify the folders that have been included in the library without using the IShellLibrary API. For this reason, you should call
SHResolveLibrary each time the library is loaded to identify changes to the folders included in the library. This will preserve changes in the folder or folder name back in the library description file. If the user adds, removes, or reorders folders using the library management dialog or the
IShellLibrary interface, these changes will be persisted directly to the underlying .library-ms file. Using this information, a client application can then re-enumerate the library folders.
Show the familiar library management dialog
This is the last piece of the Windows 7 Libraries. To promote consistency among Windows components and among content management elements, Windows 7 includes a common library management dialog for use in your application. If your application needs to manage a library folder, like the Music folder, invoking the library management dialog (
SHShowManageLibraryUI) will provide a consistent user experience for managing Windows Explorer libraries. If you choose to use this interface, it will make the changes to the library directly – as if Windows Explorer modified the library contents directly. Note that this dialog will
not return any information to your application; if you show library contents within your application, you will need
to receive notifications directly from the Shell as describe above.
By default, the library management dialog blocks addition of unsupported folders to libraries. However, if your application relies on content from folders that cannot be indexed locally or remotely by Windows Search, you can invoke the dialog with the
LMD_ALLOWUNINDEXABLENETWORKLOCATIONS flag set to override the default setting and allow you to include such folders You can also use one of the new APIs like
SHAddFolderPathToLibrary, which we covered in the
Windows 7 Libraries Helpers post, to add folders, including folders that cannot be indexed.
This post completes our Windows 7 Libraries tour. Next, we will cover the Managed Code API and start posting about Windows 7 Taskbar.