在程式中使用程式庫
本主題描述在程式中使用函式庫時要考慮的一些事項。
在本主題中：
- 程式庫程式開發概觀
- 使用連結庫 程式設計
- 使用通用檔案對話框與資料夾
- 從使用者介面啟用庫選取
-
存取程式中函式庫的內容
- 使用 IShellLibrary 介面存取連結庫內容
- 使用 Shell API 存取程式庫內容
- 在文檔庫中儲存用戶內容
- 支援連結庫中的拖放作業
- 與程式庫保持同步
- 相關主題
程式庫程式設計概覽
資料庫可讓使用者以對他們有意義的方式組織其檔案內容，而不會受限於檔案系統的組織。 當您的程式支持連結庫時，它可讓使用者在呈現與 Windows 7 用戶體驗一致的使用者介面時，以對他們有意義的方式尋找其內容。 連結庫也可讓您的程式更輕鬆地找出儲存在不同資料夾或不同電腦上之檔案型內容。
本節中的主題說明如何將連結庫支援新增至您的程式，並利用連結庫所提供的新功能。 Windows 7 預設會提供部分支援。 如果您的程式未修改它目前使用的通用檔案對話方塊，可能需要很少額外的程式設計來支持連結庫。
本節說明連結庫提供的一些重要功能，以及如何在您的程式中支持它們。 透過這項資訊，您可以決定哪些功能會提供您程式的最佳用戶體驗。 如果您的程式自定義通用檔案對話框，本節中的資訊可協助您判斷如何使用新的通用檔案對話框來使用連結庫，並在 Windows 7 中提供對等功能。
使用程式庫進行程式設計
Windows Shell 程式設計模型描述程式如何與 Windows Shell 程式設計物件互動。 雖然文件系統物件，例如檔案和目錄，是由 Windows Shell 物件表示，並非所有的 Windows Shell 物件都是以文件系統來表示。 例如，資料庫是沒有對應檔案系統的 Windows Shell 物件。 在您的程式中使用 Windows Shell 物件可讓程式存取所有 Shell 物件，而不只是檔案系統物件。
為了獲得最佳結果，您的程式會使用 Shell 連結庫 API 來與連結庫互動並存取其內容。 雖然連結庫包含資料夾和檔案等檔案系統專案，但連結庫不是檔系統專案。 因此，檔案系統 API 無法用來存取連結庫功能或連結庫內容。
如果您有目前使用許多檔案系統 API 的現有程式，您的程式仍然可以利用連結庫功能。 Shell 程式庫 API 可以提供檔案系統參考，指向在程式庫中找到的項目，這些檔案系統參考，例如檔名和路徑，能夠傳遞到您現有程式中的現有檔案系統 API。
從已知資料夾移至資料庫
在 Windows 7 之前，通常會使用已知資料夾，例如 My Documents 資料夾，做為檔案儲存或檔案開啟作業中的預設資料夾。 在 Windows 7 中，應該使用對應的連結庫，讓使用者在程式中會有與 Windows 檔案總管等其他 Windows 7 程式相同的體驗。
如果您目前在程式中使用 Windows Shell API，新增函式庫支援是相當簡單的。 例如，如果您目前呼叫 SHGetKnownFolderItem 函式以取得 My Documents 資料夾的位置，您可以將 My Documents 已知資料夾的 KNOWNFOLDERID 值取代為對應文檔庫的 KNOWNFOLDERID 值。
下表顯示已知資料夾 KNOWNFOLDERID 值與 Windows 7 中對應連結庫 值 KNOWNFOLDERID 之間的關聯性。
| 已知資料夾 KNOWNFOLDERID 值 | 資料庫 KNOWNFOLDERID 值 |
|---|---|
| FOLDERID_Documents | FOLDERID_DocumentsLibrary |
| FOLDERID_Pictures（圖片資料夾） | 圖片庫文件夾ID |
| 音樂文件夾 (FOLDERID_Music) | FOLDERID_MusicLibrary |
| FOLDERID_RecordedTV | FOLDERID_RecordedTVLibrary |
HomeGroup 和共享連結庫
將程式庫支援新增至您的程式中，將會啟用 HomeGroup 中的共享程式庫支援。 家庭群組是透過其 KNOWNFOLDERID 值 FOLDERID_HomeGroup來識別的。 您的程式可以在呼叫 IShellLibrary：：GetDefaultSaveFolderFolder 方法中設定 defaultSAVEFOLDERTYPE 值，以識別使用者的私人或共用默認儲存位置。
搭配資料夾庫使用共用檔案對話框
搭配連結庫使用通用檔案對話框：通用檔案對話框已更新為支援 Windows 7 中的連結庫。 下圖顯示通用檔案對話框如何顯示給 Windows 7 中的使用者。
顯示檔案庫的通用檔案對話框螢幕快照 
在 Windows 7 中，如果您的程式目前顯示通用檔案對話框，而且不會變更對話框範本或攔截其任何事件，它會自動顯示新的 Windows 7 版本對話方塊。 具體來說，在呼叫通用檔案對話框函式時，lpfnHook、hInstance和 lpTemplatename 必須在 OPENFILENAME 結構中設為 NULL，並且必須清除 OFN_ENABLEHOOK 和 OFN_ENABLETEMPLATE 旗標。
在 Windows 7 中，IFileDialog相關介面會取代舊版 Windows 中使用的通用檔案對話框函式。 Windows 7 中仍然支援先前的一般檔案對話框函式，但是它們不提供完整的 Windows 7 用戶體驗，而且不支持連結庫。 IFileDialog相關介面所支援的一些新功能包括：
- 用戶可以存取 Windows 7 Windows 檔案總管支援的檔案屬性，以搜尋並選取檔案。
- 程式可以使用 Shell 命名空間 API 中的介面和方法來處理項目。
- 程式可以使用數據驅動自定義模型，而不是資源文件驅動自定義模型，將新的控件新增至通用檔案對話方塊。
您應該在下列情況下使用 IFileDialog相關的介面：
- 您必須在 Windows 7 中自訂程式的通用檔案對話框。 這可讓您的程式使用連結庫，並支援自定義您的對話方塊。
- 您希望使用者能夠從通用檔案對話框中選取多個檔案。 這可確保您取得所選物件的正確路徑，因為連結庫可以有儲存在不同資料夾中的內容。
如需 IFileDialog相關介面的詳細資訊，請參閱：
- IFileDialog
- IFileOpenDialog
- IFileSaveDialog
- IFileDialogCustomize
- IFileDialogEvents
- IFileDialogControlEvents
通過使用者介面來啟用程式庫選擇
如果您的程式允許使用者在 Windows 7 中選取資料夾，例如匯入或匯出函式，它也應該允許使用者選取連結庫。 IFileOpenDialog 介面和 SHBrowseForFolder 函式可讓使用者在系統提示選取資料夾時選取連結庫。 IFileOpenDialog 介面優先於 SHBrowseForFolder 函式，因為 IFileOpenDialog 支援 Windows 7 使用者介面。
若要允許使用者在使用 IFileOpenDialog 介面時選取資料夾，請使用FOS_PICKFOLDERS旗標集呼叫 SetOptions，並確定FOS_FORCEFILESYSTEM旗標已清除。
FILEOPENDIALOGOPTIONS fileOptions;
hr = fileOpenDialogBox->GetOptions(&fileOptions);
fileOptions = fileOptions | FOS_PICKFOLDERS | ~FOS_FORCEFILESYSTEM;
hr = fileOpenDialogBox->SetOptions(fileOptions);
若要允許使用者在呼叫SHBrowseForFolder函式時選取資料夾，請在 BROWSEINFO 結構的 ulFlags 成員中，設定BIF_USENEWUI旗標並清除BIF_RETURNONLYFSDIRS旗標。
BROWSEINFO browseInfo;
browseInfo.ulFlags = BIF_USENEWUI | ~BIF_RETURNONLYFSDIRS;
// Set other member values
pidl = SHBrowseForFolder(&browseInfo);
在程式中存取函式庫內容
若要存取連結庫的內容，您必須使用 Windows Shell API。 檔案系統 API 的函式無法用來存取連結庫內容，因為連結庫不是檔案系統物件。 如果您的程式使用以檔案系統 API 為基礎的自訂檔案瀏覽器，將無法瀏覽連結庫或存取連結庫內容。
本節說明如何存取連結庫內容，以便選取更新程式以使用連結庫的最佳方式。
使用 IShellLibrary 介面存取連結庫內容
程式存取連結庫內容最簡單的方式是使用 Shell 連結庫 API。 如果您正在處理使用文件系統 API 的程式，殼層連結庫 API 可以傳回連結庫的文件系統資料夾，這可將現有程式碼的變更降至最低。
IShellLibrary *picturesLibrary;
hr = SHLoadLibraryFromKnownFolder(FOLDERID_PicturesLibrary,
STGM_READ,
IID_PPV_ARGS(&picturesLibrary));
// picturesLibrary now points to the user's picture library
IShellItemArray *pictureFolders;
hr = pslLibrary->GetFolders(LFF_FORCEFILESYSTEM, IID_PPV_ARGS(&pictureFolders));
// pictureFolders now contains an array of Shell items that
// represent the folders found in the user's pictures library
使用 Shell API 存取連結庫內容
因為連結庫物件是Shell程式設計模型的一部分，所以可以與其他Windows Shell API搭配使用。 例如，您可以使用程式中 IShellItem 和 IShellFolder 介面，以及相關的協助程式函式，以與列舉資料夾和資料夾內容以存取檔案系統 API 的內容相同的方式來存取連結庫的內容。
Windows Shell API 支援兩種列舉模式來存取連結庫的內容：
瀏覽列舉
流覽列舉是預設列舉模式，並列舉連結庫資料夾的內容。 清除SHCONTF_NAVIGATION_ENUM旗標以使用此模式。
導航列舉
導覽列舉功能會列出資料庫資料夾。 將SHCONTF_NAVIGATION_ENUM旗標設定為使用此模式。
如果您的程式使用自訂樹狀目錄控制項來瀏覽使用者的資料夾，那麼在導覽列舉模式下列舉資料夾時，您將獲得一個與檔案總管在 Windows 7 中列舉資料夾方式一致的資料夾清單。
如需如何在程式中使用這些功能的範例，請參閱 Windows SDK 中的 ShellStorage 範例。
將用戶內容儲存在文檔庫中
您的程式可以將使用者內容儲存至文檔庫，以及儲存至文檔庫中的資料夾。 同樣地，用戶可以儲存至文檔庫中的特定資料夾，也可以只儲存至文檔庫。
每個連結庫都有指定為預設儲存位置的資料夾。 建立連結庫時會定義預設儲存位置;不過，使用者可以將預設儲存位置重新指派為文檔庫中的任何資料夾。 雖然使用者不需要設定預設儲存位置，但他們可以選擇變更它。 如果使用者刪除目前設定為預設儲存位置的資料夾，連結庫會自動將文檔庫中的下一個資料夾設定為預設儲存位置。
有數種方式可將用戶內容儲存至文檔庫。
Shell API
如果您使用 Shell 程式設計模型，並將 Shell 項目，如 IShellItem、IStorage 或 IStream，儲存到資料夾資料庫，該項目會自動儲存在資料夾資料庫的預設儲存位置。
檔案系統 API
如果您有使用許多檔案系統 API 呼叫的現有程式，您可以取得定義為連結庫預設儲存位置的資料夾路徑。 然後，資料夾路徑可以傳遞至檔案系統 API。
如需如何在程式中使用這些功能的範例，請參閱 Windows SDK 中的 ShellStorage 範例。
支援程式庫中的拖曳操作
如果您的程式支援拖放動作，則應該更新這些動作以支援正確的連結庫互動。 如果檔案被拖放至檔案庫，則該檔案應儲存在預設的儲存位置。 如果資料夾已卸除至文檔庫，則卸除的資料夾應該新增為文檔庫的新資料夾。 如果檔案已放入不是預設儲存位置的現有資料夾，則檔案應該新增至選取的資料夾。
如需範例說明如何為程式的拖放功能新增函式庫支援，請參閱 Windows SDK 中的 ShellLibraryCommandLine 範例。
與資料庫保持同步
本主題描述程式如何維持對函式庫內容的檢視 up-to-date。
大量更新
因為使用者可以在程式未執行時以互動方式修改連結庫的資料夾，所以當程序開始探索並儲存連結庫的任何變更時，應該呼叫 SHResolveLibrary。 Shell API 提供 SHResolveLibrary 函式，讓程式能夠取得連結庫的目前內容，以及連結庫可能包含之任何資料夾的目前位置。
請注意，SHResolveLibrary 是封鎖函式，視連結庫中變更的內容而定，可能需要很長的時間才能傳回。 因此，不應該從UI線程呼叫它。
程式 up-to日期之後，就可以註冊變更通知，以維護目前的檢視。
Shell API 通知
Windows Shell API 提供 SHChangeNotifyRegister 函式，這是非服務進程在連結庫中收到變更通知的慣用方式。
若要使用 Windows Shell API 偵測連結庫內項目的變更，請呼叫 SHChangeNotifyRegister，以註冊程式，以通知連結庫資料夾中項目的變更。 此函式可以通知您的程式是否有任何程式庫或特定程式庫中的變更。 當程式庫被更動時，會立即發送通知。
檔案系統 API 通知
檔系統通知必須用於服務進程。
若要使用文件系統 API 偵測連結庫中項目的變更，請列舉連結庫中的資料夾，並針對要監視的每個資料夾呼叫 FindFirstChangeNotification。 當受監視的資料夾變更時，您的程式會收到通知。 若要尋找資料夾中變更的特定檔案檔案，請呼叫 ReadDirectoryChangesW。 若要偵測連結庫描述檔中的變更，請監視包含它的資料夾。 您可以在 FOLDERID_Libraries 資料夾中找到連結庫描述檔。 不過，不應該開啟或修改連結庫描述檔。
相關主題