在程式中使用程式庫

本主題描述在程式中使用程式庫時要考慮的一些事項。

本主題內容：

• 程式庫程式設計概觀
• 使用程式庫進行程式設計
  • 從已知資料夾移至程式庫
  • HomeGroup 和共用程式庫
• 搭配程式庫使用通用檔案對話方塊
• 從使用者介面啟用程式庫選取
• 存取程式中的程式庫內容
  • 使用 IShellLibrary 介面存取程式庫內容
  • 使用殼層 API 存取程式庫內容
• 在文件庫中儲存使用者內容
• 支援程式庫中的拖放作業
• 與程式庫保持同步
  • 大量更新
  • 殼層 API 通知
  • 檔案系統 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 之前，通常會使用已知資料夾，例如 [我的檔] 資料夾，作為檔案儲存或檔案開啟作業中的預設資料夾。 在 Windows 7 中，應該使用對應的程式庫，讓使用者在程式中的體驗與其他 Windows 7 程式相同，例如 Windows 檔案總管。

如果您目前正在程式中使用 Windows Shell API，新增程式庫支援很簡單。 例如，如果您目前呼叫 SHGetKnownFolderItem 函式以取得 My Documents 資料夾的位置，您可以將 My Documents 已知資料夾的 KNOWNFOLDERID 值取代為對應文件庫的 KNOWNFOLDERID 值。

下表顯示已知資料夾的 KNOWNFOLDERID 值與 Windows 7 中對應程式庫的 KNOWNFOLDERID 值之間的關聯性。

已知資料夾 KNOWNFOLDERID 值	程式庫 KNOWNFOLDERID 值
FOLDERID_Documents	FOLDERID_DocumentsLibrary
FOLDERID_Pictures	FOLDERID_PicturesLibrary
FOLDERID_Music	FOLDERID_MusicLibrary
FOLDERID_RecordedTV	FOLDERID_RecordedTVLibrary

 

HomeGroup 和共用程式庫

將程式庫支援新增至您的程式，將可支援 HomeGroup 中的共用程式庫。 HomeGroup 是由其 KNOWNFOLDERID 值識別 FOLDERID_HomeGroup。 您的程式可以在呼叫 IShellLibrary：：GetDefaultSaveFolderFolder方法中設定DEFAULTSAVEFOLDERTYPE值，以識別使用者的私人或共用預設儲存位置。

搭配程式庫使用通用檔案對話方塊

使用通用檔案對話方塊與程式庫 [通用檔案] 對話方塊已更新，以支援 Windows 7 中的程式庫。 下圖顯示一般檔案對話方塊如何顯示給 Windows 7 中的使用者。

在 Windows 7 中，如果您的程式目前顯示一般檔案對話方塊，而且不會變更對話方塊範本或攔截其任何事件，它會自動顯示新的 Windows 7 版本對話方塊。 具體而言，在呼叫通用檔案對話方塊函式中，OPENFILENAME結構的lpfnHook、hInstance、lpTemplatename成員必須是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 介面時選取資料夾，請呼叫 SetOptions 並設定FOS_PICKFOLDERS旗標，並確定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 的程式， Shell 程式庫 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

使用殼層 API 存取程式庫內容

因為程式庫物件是 Shell 程式設計模型的一部分，所以可以與其他 Windows Shell API 搭配使用。 例如，您可以使用程式中的 IShellItem 和 IShellFolder 介面，以及相關的協助程式函式，以與列舉資料夾和資料夾內容的方式存取程式庫內容的方式相同，以使用檔案系統 API 存取內容。

Windows Shell API 支援兩種列舉模式來存取程式庫的內容：

• 流覽列舉

  流覽列舉是預設列舉模式，並列舉程式庫資料夾的內容。 清除SHCONTF_NAVIGATION_ENUM旗標以使用此模式。

• 流覽列舉

  流覽列舉會列舉程式庫資料夾。 將SHCONTF_NAVIGATION_ENUM旗標設定為使用此模式。

如果您的程式使用自訂樹狀結構控制項來巡覽使用者的資料夾，則列舉導覽列舉模式中的資料夾會提供程式庫資料夾的清單，與 Windows 檔案總管如何列舉 Windows 7 中的資料夾一致。

如需如何在程式中使用這些功能的範例，請參閱 Windows SDK 中的 ShellStorage 範例。

在文件庫中儲存使用者內容

您的程式可以將使用者內容儲存至文件庫，以及儲存至文件庫中的資料夾。 同樣地，使用者可以儲存至文件庫中的特定資料夾，也可以只儲存至文件庫。

每個文件庫都有一個資料夾，指定為預設儲存位置。 建立程式庫時會定義預設儲存位置;不過，使用者可以將預設儲存位置重新指派為文件庫中的任何資料夾。 雖然使用者不需要設定預設儲存位置，但可以選擇變更它。 如果使用者刪除目前設定為預設儲存位置的資料夾，程式庫會自動將文件庫中的下一個資料夾設定為預設儲存位置。

有數種方式可將使用者內容儲存至文件庫。

• 殼層 API

  如果您使用 Shell 程式設計模型，並將 Shell 專案儲存為 IShellItem、IStorage 或 IStream 所代表，則 Shell 專案會自動儲存在程式庫的預設儲存位置。

• 檔案系統 API

  如果您有使用許多檔案系統 API 呼叫的現有程式，您可以取得定義為程式庫預設儲存位置的資料夾路徑。 然後，資料夾路徑可以傳遞至檔案系統 API。

如需如何在程式中使用這些功能的範例，請參閱 Windows SDK 中的 ShellStorage 範例。

支援程式庫中的拖放作業

如果您的程式支援拖放動作，則應更新這些動作以支援正確的程式庫互動。 如果檔案卸載至程式庫，則卸載的檔案應該儲存在預設儲存位置。 如果資料夾已卸載至文件庫，則卸載的資料夾應該新增為文件庫的新資料夾。 如果檔案卸載至不是預設儲存位置的現有資料夾，則應該將檔案新增至選取的資料夾。

如需如何新增程式拖放功能的程式庫支援範例，請參閱 Windows SDK 中的 ShellLibraryCommandLine 範例。

與程式庫保持同步

本主題描述程式如何保持文件庫內容的最新檢視。

大量更新

因為當使用者的程式未執行時，可以互動方式修改程式庫的資料夾，所以當程式開始探索並儲存程式庫的任何變更時，您的程式應該呼叫 SHResolveLibrary 。 Shell API 提供 SHResolveLibrary 函式 ，讓程式能夠取得程式庫的目前內容，以及程式庫可能包含之任何資料夾的目前位置。

請注意， SHResolveLibrary 是封鎖函式，可能需要很長的時間才能傳回，視程式庫中變更的內容而定。 因此，不應該從 UI 執行緒呼叫它。

程式啟動到最新狀態之後，就可以註冊變更通知以維護目前的檢視。

殼層 API 通知

Windows Shell API 提供 SHChangeNotifyRegister 函式，這是非服務進程在程式庫中收到變更通知的慣用方式。

若要使用 Windows Shell API 偵測程式庫內專案的變更，請呼叫 SHChangeNotifyRegister 以註冊程式，以取得程式庫資料夾中專案的變更通知。 如果任何程式庫或只是在特定程式庫中發生變更，此函式可以通知您的程式。 變更程式庫時會立即傳送通知。

檔案系統 API 通知

檔案系統通知必須用於服務進程。

若要使用檔案系統 API 偵測程式庫中專案的變更，請列舉程式庫中的資料夾，並針對要監視的每個資料夾呼叫 FindFirstChangeNotification 。 當受監視的資料夾變更時，您的程式會收到通知。 若要尋找資料夾中變更之檔案的特定檔案，請呼叫 ReadDirectoryChangesW。 若要偵測程式庫描述檔案中的變更，請監視包含該檔案的資料夾。 您可以在 FOLDERID_Libraries 資料夾中找到程式庫描述檔案。 不過，不應該開啟或修改程式庫描述檔案。

相關主題

關於程式庫

IShellLibrary

殼層連結

已知資料夾

程式庫描述架構

IID_PPV_ARGS