After two weeks break, we are back to our normal technical posts, covering Windows 7 Libraries. This is the sixth post about Windows 7 Libraries. By now, you should be familiar with Windows 7 Libraries (Understanding Windows 7 Libraries) and understand the internal structure of Libraries 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 this post, we focus on the Windows 7 Libraries helper functions.
The IShellLibrary COM object presents a Windows 7 Library. This interface defines methods for creating and managing Libraries. You can work directly with the COM interface, but it's easier to use a higher abstraction layer of functions. Shobjidl.h provides the following library helper functions:
- SHAddFolderPathToLibrary - Adds a folder to a library
- SHCreateLibrary - Creates an IShellLibrary object
- SHLoadLibraryFromItem - Creates and loads an IShellLibrary object from a specified library definition file
- SHLoadLibraryFromKnownFolder - Creates and loads an IShellLibrary object for a specified KNOWNFOLDERID
- SHLoadLibraryFromParsingName - Creates and loads an IShellLibrary object for a specified path
- SHRemoveFolderPathFromLibrary - Removes a folder from a library
- SHResolveFolderPathInLibrary - Attempts to resolve the target location of a library folder that has been moved or renamed
- SHSaveLibraryInFolderPath - Saves an IShellLibrary object to disk
Note: if you are really interested in how these helper functions are implemented, simply go to the Shobjidl.h h file and search for these functions.
Using these help functions, you can perform most of the management operations on a Library without using the lower level APIs. For example, you can add a folder to a Library using SHAddFolderPathToLibrary without calling ISHellLibrary::Commit(). Since the IShellLibrary is a COM-based API, you will need to CoInitialize the COM objects. After doing so, all you need to do is use the helper functions. The following code snippet creates a new Library, adds a folder to it, and saves the Library definition file in the Libraries folder.
IShellLibrary *pLib;
IShellItem *pSi;
SHCreateLibrary(IID_PPV_ARGS(&pLib));
SHAddFolderPathToLibrary( pLib, L"C:\\temp ");
pLib ->SaveInKnownFolder(
FOLDERID_Libraries,
L"Test 1 Lib",
LSF_MAKEUNIQUENAME,
& pSi);
The helper functions don’t provide all the functionality in the IShellLibrary interface. By working directly with the IShellLibrary interface, you can get or set the Library icon using the GetIcon, and SetIcon. But more importantly, you can get the contents of a library by using the IShellLibrary:: GetFolders() as shown in the next code snippet
IShellLibrary *pslLibrary;
SHLoadLibraryFromKnownFolder(
FOLDERID_PicturesLibrary,
STGM_READ,
IID_PPV_ARGS(&pslLibrary));
IShellItemArray *psiaFolders;
pslLibrary->GetFolders(
LFF_FORCEFILESYSTEM,
IID_PPV_ARGS(&psiaFolders));
In the next post we will walk through some techniques of staying in sync with the library contents.