Windows 7 新特性 Shell Library 编程接口介绍

下文所用到的示例代码来源于微软一站式开发技术框架解决方案。你可以通过http://cfx.codeplex.com/Release/ProjectReleases.aspx下载到Windows 7 Shell Library相关的sample。其中包含C++、C#、VB.NET对Shell Library操作的示例代码：CppWin7ShellLibrary, C#Win7ShellLibrary, VBWin7ShellLibrary。

为了帮助用户更加有效地对硬盘上的文件进行管理，Windows 7中引入了新的文件管理方式：库(Library)。库自然演化自以往操作系统中My Documents 文件夹这个概念。有了库，我们就可以将多个相关的文件夹组织到同一个库下，从而更快更便捷地管理和搜索数据。

创建Windows Shell Library

Windows 7提供了SHCreateLibrary API用来创建一个Shell Library：

/**//*!
* Create a new shell library under the user's Libraries folder. If a library 
* with the same name already exists, the new one overrides the existing one.
* 
* \param pwszLibraryName
* The name of the shell library to be created. 
*/
BOOL CreateShellLibrary(LPWSTR pwszLibraryName)
{
    /**//////////////////////////////////////////////////////////////////////////
    // Create the shell library COM object.
    // 

    IShellLibrary* pShellLib = NULL;
    HRESULT hr = SHCreateLibrary(IID_PPV_ARGS(&pShellLib));
    if (FAILED(hr))
    {
        _tprintf(_T("SHCreateLibrary failed to create the shell library ") \
            _T("COM object w/err 0x%08lx\n"), hr);
        return FALSE;
    }


    /**/////////////////////////////////////////////////////////////////////////
    // Save the new library under the user's Libraries folder.
    // 

    IShellItem* pSavedTo = NULL;
    hr = pShellLib->SaveInKnownFolder(FOLDERID_UsersLibraries, 
        pwszLibraryName, LSF_OVERRIDEEXISTING, &pSavedTo);
    if (FAILED(hr))
    {
        _tprintf(_T("IShellLibrary::SaveInKnownFolder failed to save the ") \
            _T("library w/err 0x%08lx\n"), hr);
        return FALSE;
    }


    /**//////////////////////////////////////////////////////////////////////////
    // Clean up.
    // 

    if (pShellLib != NULL)
        pShellLib->Release();

    if (pSavedTo != NULL)
        pSavedTo->Release();

    return TRUE;
}

/**//////////////////////////////////////////////////////////////////////
// Create a shell library.
// 

using (ShellLibrary library = new ShellLibrary(libraryName, true))
{
}

管理Windows Shell Library

你可以通过调用SHShowManageLibraryUI API显示出Windows 标准的Shell Library管理对话框。值得注意的是，在调用SHShowManageLibraryUI前请确保 shell library没有被以可写方式打开。否则在SHShowManageLibraryUI中对shell library的修改将无法被保存。

C++ ShowManageLibraryUI
/**//*!
* Shows the library management dialog box of the specified library, which 
* enables users to manage the library folders and default save location.
* 
* \param pwszLibraryName
* The name of the shell library
*/
BOOL ShowManageLibraryUI(LPWSTR pwszLibraryName)
{
    // Get the shell item that represents the library.
    IShellItem2* pShellItem = GetShellLibraryItem(pwszLibraryName);

    HRESULT hr = SHShowManageLibraryUI(pShellItem, NULL, 
        L"CppWin7ShellLibrary", L"Manage Library folders and settings", 
        LMD_ALLOWUNINDEXABLENETWORKLOCATIONS);

    // Clean up
    if (pShellItem != NULL)
        pShellItem->Release();

    return SUCCEEDED(hr);
}

// ShowManageLibraryUI requires that the library is not currently 
// opened with write permission. 
ShellLibrary.ShowManageLibraryUI(libraryName, IntPtr.Zero,
    "CSWin7ShellLibrary", "Manage Library folders and settings", true);

向Shell Library中添加文件夹
SHAddFolderPathToLibrary可用来向指定的Shell Library中添加文件夹。

/**//*!
* Add a folder to an existing shell library.
* 
* \param pShellLib
* The IShellLibrary interface of the shell library
* 
* \param pwszFolderPath
* The path of the folder to be added into the shell library
* 
* \param bSaveLocation
* If bSaveLocation is TRUE, set the folder as the save location of the shell 
* library
*/
BOOL AddFolderToShellLibrary(IShellLibrary* pShellLib, 
                             LPWSTR pwszFolderPath, BOOL bSaveLocation)
{
    HRESULT hr = SHAddFolderPathToLibrary(pShellLib, pwszFolderPath);
    if (FAILED(hr))
    {
        _tprintf(_T("SHAddFolderPathToLibrary failed to add a folder ") \
            _T("to the shell library w/err 0x%08lx\n"), hr);
        return FALSE;
    }

    // Save the folder as the save location of the shell library
    if (bSaveLocation)
    {
        // Create shell item from folder path
        IShellItem2* pShellItemSaveFolder = NULL;
        hr = SHCreateItemFromParsingName(pwszFolderPath, 0, 
            IID_PPV_ARGS(&pShellItemSaveFolder));
        if (FAILED(hr))
        {
            _tprintf(_T("SHCreateItemFromParsingName failed w/err ") \
                _T("0x%08lx\n"), hr);
            return FALSE;
        }

        // Set the folder as the save location
        pShellLib->SetDefaultSaveFolder(DSFT_DETECT, pShellItemSaveFolder);
        
        if (pShellItemSaveFolder != NULL)
            pShellItemSaveFolder->Release();

        if (FAILED(hr))
        {
            _tprintf(_T("IShellLibrary::SetDefaultSaveFolder failed ") \
                _T("w/err 0x%08lx\n"), hr);
            return FALSE;
        }
    }

    // Commit the change of the shell library
    pShellLib->Commit();

    return TRUE;
}

using (ShellLibrary library = ShellLibrary.Load(libraryName, false))
{
    /**//////////////////////////////////////////////////////////////////
    // Add a folder to the shell library.
    // 

    // Add the folder to the shell library
    library.Add(folderPath);
    library.DefaultSaveFolder = folderPath;
}

枚举Shell Library中的文件夹
IShellLibrary::GetFolders可用来得到Shell Library中的文件夹。

/**//*!
* List all folders in the shell library.
* 
* \param pShellLib
* The IShellLibrary interface of the shell library
*/
void ListFoldersInShellLibrary(IShellLibrary* pShellLib)
{
    HRESULT hr = S_OK;

    IShellItemArray* pShellItemArray = NULL;
    pShellLib->GetFolders(LFF_ALLITEMS, IID_PPV_ARGS(&pShellItemArray));
    if (FAILED(hr))
    {
        _tprintf(_T("IShellLibrary::GetFolders failed to get the folders ") \
            _T("of the shell library w/err 0x%08lx\n"), hr);
        return;
    }

    DWORD dwFolderCount;
    pShellItemArray->GetCount(&dwFolderCount);

    // Iterate through all folders of the shell library
    for (DWORD i = 0; i < dwFolderCount; i++)
    {
        IShellItem *pShellItem;
        hr = pShellItemArray->GetItemAt(i, &pShellItem);
        if (FAILED(hr))
            continue;

        // Convert IShellItem to IShellItem2
        IShellItem2 *pShellItem2;
        pShellItem->QueryInterface(IID_PPV_ARGS(&pShellItem2));
        pShellItem->Release();

        // Fix folder path changes
        IShellItem2 *pShellItemResolvedFolder = NULL;
        hr = pShellLib->ResolveFolder(pShellItem2, 5000, IID_PPV_ARGS(
            &pShellItemResolvedFolder));
        if (SUCCEEDED(hr))
        {
            // Point to the fixed folder
            pShellItem2->Release();
            pShellItem2 = pShellItemResolvedFolder;
        }
        // Else we will show the unfixed folder

        // Print the folder path
        LPWSTR wszFolderPath;
        hr = pShellItem2->GetString(PKEY_ParsingPath, &wszFolderPath);
        if (SUCCEEDED(hr))
        {
            _putws(wszFolderPath);
        }
        CoTaskMemFree(wszFolderPath);

        // Clean up
        pShellItem2->Release();
    }

    pShellItemArray->Release();
}

using (ShellLibrary library = ShellLibrary.Load(libraryName, false))
{
    /**//////////////////////////////////////////////////////////////////
    // List all folders in the library.
    // 

    foreach (ShellFolder folder in library)
    {
        Console.WriteLine(folder);
    }
}

 
删除一个Shell Library

/**//*!
* Delete the shell library under the user's Libraries folder according to the 
* specified library name. 
* 
* \param pwszLibraryName
* The name of the shell library to be deleted.
*/
BOOL DeleteShellLibrary(LPWSTR pwszLibraryName)
{
    /**//////////////////////////////////////////////////////////////////////////
    // Get the shell item that represents the library and its full path.
    // 

    IShellItem2* pShellItem = GetShellLibraryItem(pwszLibraryName);

    // Get the file-system full path of the shell item
    LPWSTR wszLibraryFullPath;
    pShellItem->GetString(PKEY_ParsingPath, &wszLibraryFullPath);


    /**//////////////////////////////////////////////////////////////////////////
    // Delete file with the library file-system based full path.
    // 

    BOOL bSuccess = DeleteFileW(wszLibraryFullPath);

    // Clean up
    CoTaskMemFree(wszLibraryFullPath);
    if (pShellItem != NULL)
        pShellItem->Release();

    return bSuccess;
}

/**//////////////////////////////////////////////////////////////////////
// Delete the shell library.
// 

string librariesPath = Path.Combine(Environment.GetFolderPath(
    Environment.SpecialFolder.ApplicationData), 
    ShellLibrary.LibrariesKnownFolder.RelativePath);

string libraryPath = Path.Combine(librariesPath, libraryName);
string libraryFullPath = Path.ChangeExtension(libraryPath, "library-ms");

File.Delete(libraryFullPath);

更多关于Windows 7 Shell Library的操作请参见CppWin7ShellLibrary, CSWin7ShellLibrary和VBWin7ShellLibrary示例。