Udostępnij przez

Używanie bibliotek w programie

W tym temacie opisano niektóre zagadnienia, które należy wziąć pod uwagę podczas korzystania z bibliotek w programie.

W tym temacie:

Omówienie programowania bibliotek

Biblioteki umożliwiają użytkownikom organizowanie zawartości opartej na plikach w sposób zrozumiały dla nich, a nie ograniczony przez organizację systemu plików. Gdy program obsługuje biblioteki, pozwala użytkownikowi znaleźć swoją zawartość w sposób, który ma sens podczas prezentowania interfejsu użytkownika zgodnego z środowiskiem użytkownika systemu Windows 7. Biblioteki ułatwiają również programowi lokalizowanie zawartości opartej na plikach przechowywanych w różnych folderach lub na różnych komputerach.

W tematach w tej sekcji opisano sposób dodawania obsługi bibliotek do programu i korzystania z nowych funkcji oferowanych przez biblioteki. System Windows 7 domyślnie udostępnia niektóre z tych funkcji. Jeśli program nie modyfikuje typowych okien dialogowych plików używanych obecnie, może wymagać bardzo małego dodatkowego programowania do obsługi bibliotek.

W tej sekcji opisano niektóre kluczowe funkcje, które biblioteki udostępniają i jak je obsługiwać w programie. Dzięki tym informacjom możesz zdecydować, które funkcje zapewnią najlepsze doświadczenie użytkownika w ramach programu. Jeśli program dostosowuje typowe okna dialogowe plików, informacje w tej sekcji mogą pomóc w ustaleniu, jak używać nowych typowych okien dialogowych plików do korzystania z bibliotek i zapewnić równoważne funkcje w systemie Windows 7.

Programowanie za pomocą bibliotek

Model programowania powłoki Windows opisuje sposób interakcji programu z obiektami programowania powłoki Windows. Obiekty systemu plików, takie jak pliki i katalogi, są reprezentowane przez obiekty powłoki systemu Windows, ale nie wszystkie obiekty powłoki systemu Windows są reprezentowane przez system plików. Biblioteki, na przykład, to obiekty powłoki systemu Windows, które nie mają odpowiednika systemu plików. Wykorzystanie w programie obiektów powłoki Windows pozwala na dostęp do wszystkich obiektów powłoki, a nie tylko do obiektów systemu plików.

Aby uzyskać najlepsze wyniki, Twój program powinien używać API Biblioteki Powłoki do interakcji z bibliotekami oraz do uzyskiwania dostępu do ich zawartości. Biblioteki zawierają elementy systemu plików, takie jak foldery i pliki, ale biblioteki nie są elementami systemu plików. W związku z tym interfejsy API systemu plików nie mogą być używane do uzyskiwania dostępu do funkcji biblioteki ani zawartości biblioteki.

Jeśli masz istniejący program, który obecnie używa wielu interfejsów API systemu plików, program nadal może korzystać z funkcji biblioteki. Interfejs API biblioteki powłoki może udostępniać odwołania systemu plików do elementów znajdujących się w bibliotece, a te odwołania do systemu plików, takie jak nazwa pliku i ścieżka, można przekazać do istniejących interfejsów API systemu plików, które znajdują się w istniejącym programie.

Przechodzenie ze znanych folderów do bibliotek

Przed systemem Windows 7 często używać znanego folderu, takiego jak folder Moje dokumenty, jako domyślny folder w operacjach zapisywania plików lub otwierania pliku. W systemie Windows 7 należy użyć odpowiedniej biblioteki, aby użytkownik miał takie samo środowisko w programie, jak w przypadku innych programów systemu Windows 7, takich jak Eksplorator Windows.

Jeśli obecnie używasz Windows Shell API w swoim programie, dodanie wsparcia dla bibliotek jest proste. Jeśli na przykład obecnie wywołasz funkcję SHGetKnownFolderItem, aby uzyskać lokalizację folderu Moje dokumenty, możesz zastąpić wartość KNOWNFOLDERID wartością znanego folderu Moje dokumenty wartością KNOWNFOLDERID odpowiedniej biblioteki.

W poniższej tabeli przedstawiono relację między wartościami KNOWNFOLDERID znanych folderów a wartością KNOWNFOLDERID odpowiedniej biblioteki w systemie Windows 7.

Znane wartości FOLDERU KNOWNFOLDERID Wartości biblioteki KNOWNFOLDERID
FOLDERID_Documents FOLDERID_BibliotekaDokumentów
FOLDERID_Pictures FOLDERID_PicturesLibrary
FOLDERID_Music FOLDERID_MusicLibrary
FOLDERID_NagrywanaTelewizja FOLDERID_BibliotekaNagrańTV

 

HomeGroup i udostępnione biblioteki

Dodanie wsparcia dla bibliotek do programu umożliwi obsługę bibliotek współdzielonych w grupie domowej. Grupa domowa jest identyfikowana przez wartość KNOWNFOLDERIDFOLDERID_HomeGroup. Program może odnaleźć prywatną lub udostępnioną domyślną lokalizację zapisywania użytkownika, ustawiając wartość DEFAULTSAVEFOLDERTYPE w wywołaniu metody IShellLibrary::GetDefaultSaveFolder.

Używanie wspólnego okna dialogowego plików z bibliotekami

Korzystanie ze wspólnego okna dialogowego pliku z bibliotekami Wspólne okno dialogowe plików zostało zaktualizowane w celu obsługi bibliotek w systemie Windows 7. Na poniższej ilustracji pokazano, jak typowe okno dialogowe pliku jest wyświetlane użytkownikowi w systemie Windows 7.

zrzut ekranu okna dialogowego wspólnego pliku z wyświetlonymi bibliotekami

W systemie Windows 7, jeśli program aktualnie wyświetla typowe okno dialogowe pliku i nie zmienia szablonu okna dialogowego lub podłącza żadnego z jego zdarzeń, będzie automatycznie wyświetlać nową wersję okna dialogowego Windows 7. W szczególności w wywołaniu funkcji okna dialogowego wspólnego pliku członkowie lpfnHook, hInstance, lpTemplatename struktury OPENFILENAME muszą być ustawione jako NULL, a flagi OFN_ENABLEHOOK i OFN_ENABLETEMPLATE muszą być wyczyszczone.

W systemie Windows 7 interfejsy IFileDialog-related zastępują typowe funkcje okna dialogowego pliku, które były używane we wcześniejszych wersjach systemu Windows. Wcześniejsze typowe funkcje okna dialogowego plików są nadal obsługiwane w systemie Windows 7, ale nie zapewniają kompletnego środowiska użytkownika systemu Windows 7 i nie obsługują bibliotek. Niektóre nowe funkcje obsługiwane przez powiązane z IFileDialoginterfejsy obejmują:

  • Użytkownik może uzyskać dostęp do właściwości pliku obsługiwanych przez Eksploratora Windows 7, aby wyszukać i wybrać pliki.
  • Program może używać interfejsów i metod z interfejsu API przestrzeni nazw powłoki do obsługi elementów.
  • Program może używać modelu dostosowywania opartego na danych zamiast modelu dostosowywania opartego na plikach zasobów, aby dodać nowe kontrolki do typowych okien dialogowych pliku.

Należy użyć interfejsów związanych z IFileDialog, gdy:

  • Musisz dostosować typowe okno dialogowe pliku dla programu w systemie Windows 7. Umożliwi to programowi pracę z bibliotekami i obsługę dostosowywania okna dialogowego.
  • chcesz, aby użytkownik mógł wybrać wiele plików w oknie dialogowym wspólnego pliku. Dzięki temu uzyskasz poprawne ścieżki do wybranego obiektu, ponieważ biblioteka może zawierać zawartość przechowywaną w różnych folderach.

Aby uzyskać więcej informacji na temat interfejsów związanych z IFileDialog, zobacz:

Włączanie wyboru biblioteki z interfejsu użytkownika

Jeśli program umożliwia użytkownikowi wybranie folderu, takiego jak funkcje importu lub eksportu, w systemie Windows 7 powinno również umożliwić użytkownikowi wybranie biblioteki. Interfejs IFileOpenDialog oraz funkcja SHBrowseForFolder pozwalają użytkownikowi na wybranie biblioteki przy monicie o wybór folderu. Interfejs IFileOpenDialog jest preferowany przez funkcję SHBrowseForFolder, ponieważ IFileOpenDialog obsługuje interfejs użytkownika systemu Windows 7.

Aby umożliwić użytkownikom wybieranie folderów podczas korzystania z interfejsu IFileOpenDialog, wywołaj polecenie SetOptions z ustawioną flagą FOS_PICKFOLDERS i upewnij się, że flaga FOS_FORCEFILESYSTEM jest jasna.

FILEOPENDIALOGOPTIONS fileOptions;

hr = fileOpenDialogBox->GetOptions(&fileOptions);
fileOptions = fileOptions | FOS_PICKFOLDERS | ~FOS_FORCEFILESYSTEM;
hr = fileOpenDialogBox->SetOptions(fileOptions);

Aby umożliwić użytkownikom wybieranie folderów podczas wywoływania funkcji SHBrowseForFolder, w członku ulFlags struktury BROWSEINFO, ustaw flagę BIF_USENEWUI i wyczyść flagę BIF_RETURNONLYFSDIRS.

BROWSEINFO    browseInfo;
browseInfo.ulFlags = BIF_USENEWUI | ~BIF_RETURNONLYFSDIRS;
// Set other member values
pidl = SHBrowseForFolder(&browseInfo);

Uzyskiwanie dostępu do zawartości biblioteki w programie

Aby uzyskać dostęp do zawartości biblioteki, należy użyć interfejsu API powłoki systemu Windows. Funkcji interfejsu API systemu plików nie można używać do uzyskiwania dostępu do zawartości biblioteki, ponieważ biblioteki nie są obiektami systemu plików. Jeśli program używa niestandardowej przeglądarki plików opartej na interfejsie API systemu plików, nie będzie mógł przeglądać bibliotek ani uzyskiwać dostępu do zawartości biblioteki.

W tej sekcji opisano sposób uzyskiwania dostępu do zawartości biblioteki, dzięki czemu można wybrać najlepszy sposób aktualizowania programu do pracy z bibliotekami.

Uzyskiwanie dostępu do zawartości biblioteki za pomocą interfejsu IShellLibrary

Najprostszym sposobem dla programu na uzyskanie dostępu do zawartości biblioteki jest użycie interfejsu API biblioteki powłoki . Jeśli pracujesz nad programem korzystającym z interfejsu API systemu plików, interfejs API biblioteki powłoki może zwrócić foldery systemu plików biblioteki, co minimalizuje zmianę istniejącego kodu programu.

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

Uzyskiwanie dostępu do zawartości biblioteki za pomocą API powłoki

Ponieważ obiekty biblioteki są częścią modelu programowania powłoki Windows, mogą być używane z innymi interfejsami API powłoki Windows. Na przykład można użyć interfejsów IShellItem i IShellFolder w programie wraz z powiązanymi funkcjami pomocnika, aby uzyskać dostęp do zawartości biblioteki w taki sam sposób, jak wyliczanie folderów i zawartości folderów w celu uzyskania dostępu do zawartości za pomocą interfejsów API systemu plików.

API powłoki systemu Windows obsługują dwa tryby wyliczania, aby uzyskać dostęp do zawartości biblioteki:

  • Przeglądanie wyliczeń

    Tryb przeglądania jest domyślnym trybem enumeracji i służy do przeglądania zawartości folderu biblioteki. Wyczyść flagę SHCONTF_NAVIGATION_ENUM, aby użyć tego trybu.

  • wyliczenie nawigacji

    Wyliczenie nawigacji wylicza foldery biblioteki. Ustaw flagę SHCONTF_NAVIGATION_ENUM, aby używać tego trybu.

Jeśli program używa niestandardowej kontrolki drzewa do nawigowania po folderach użytkownika, wyliczanie folderów w trybie wyliczania nawigacji spowoduje wyświetlenie listy folderów biblioteki, które są zgodne z tym, jak Eksplorator Windows wylicza foldery w systemie Windows 7.

Przykłady użycia tych funkcji w programie można znaleźć w przykładzie ShellStorage w zestawie Windows SDK.

Zapisywanie zawartości użytkownika w bibliotece

Program może zapisywać zawartość użytkownika w bibliotece, a także do folderu w bibliotece. Podobnie użytkownik może zapisać w określonym folderze w bibliotece lub po prostu zapisać do biblioteki.

Każda biblioteka ma folder wyznaczony jako domyślną lokalizację zapisywania. Domyślna lokalizacja zapisywania jest definiowana podczas tworzenia biblioteki; użytkownik może jednak ponownie przypisać domyślną lokalizację zapisywania jako dowolny folder w bibliotece. Użytkownik nie musi konfigurować domyślnej lokalizacji zapisywania, ale ma możliwość jej zmiany. Jeśli użytkownik usunie folder, który jest obecnie ustawiony jako domyślna lokalizacja zapisywania, biblioteka automatycznie skonfiguruje następny folder w bibliotece jako domyślną lokalizację zapisywania.

Istnieje kilka sposobów zapisywania zawartości użytkownika w bibliotece.

  • interfejs API Shell

    Jeśli używasz modelu programowania Shell i zapiszesz element Shell, reprezentowany przez IShellItem, IStorage lub IStream, do obiektu bibliotecznego, element Shell zostanie automatycznie zapisany w domyślnej lokalizacji zapisu biblioteki.

  • interfejs API systemu plików

    Jeśli masz istniejący program, który używa wielu wywołań interfejsu API systemu plików, możesz uzyskać ścieżkę do folderu zdefiniowanego jako domyślna lokalizacja zapisywania biblioteki. Następnie można przekazać ścieżkę folderu do interfejsu API systemu plików.

Przykłady użycia tych funkcji w programie można znaleźć w przykładzie ShellStorage w zestawie Windows SDK.

Obsługa operacji przeciągania i upuszczania w bibliotece

Jeśli program obsługuje akcje przeciągania i upuszczania, należy je zaktualizować, aby obsługiwać prawidłową interakcję z biblioteką. Jeśli plik zostanie porzucony do biblioteki, porzucony plik powinien zostać zapisany w domyślnej lokalizacji zapisywania. Jeśli folder zostanie porzucony do biblioteki, należy dodać folder porzucony jako nowy folder do biblioteki. Jeśli plik zostanie porzucony do istniejącego folderu, który nie jest domyślną lokalizacją zapisywania, plik powinien zostać dodany do wybranego folderu.

Przykłady dodawania obsługi bibliotek dla funkcji przeciągania i upuszczania programów można znaleźć w przykładzie ShellLibraryCommandLine w zestawie Windows SDK.

Synchronizowanie z biblioteką

W tym temacie opisano, jak program może zachować wgląd w zawartość biblioteki up-to-date.

Aktualizacja zbiorcza

Ponieważ użytkownik może interaktywnie modyfikować foldery biblioteki, gdy program nie jest uruchomiony, program powinien wywołać SHResolveLibrary po rozpoczęciu odnajdywania i przechowywania wszelkich zmian w bibliotece. Interfejs API powłoki udostępnia funkcję SHResolveLibrary, aby umożliwić programowi pobranie aktualnej zawartości biblioteki oraz aktualnych lokalizacji wszystkich folderów, które biblioteka może zawierać.

Należy pamiętać, że SHResolveLibrary jest funkcją blokującą, która może zająć dłuższy czas, aby zwrócić wynik w zależności od zmian, jakie zaszły w bibliotece. W związku z tym nie powinien być wywoływany z wątku interfejsu użytkownika.

Gdy program zostanie doprowadzony do up-to-date, może następnie zarejestrować się do powiadomień o zmianach, aby zachować bieżący widok.

Powiadomienie API powłoki

Interfejs API powłoki systemu Windows udostępnia funkcję SHChangeNotifyRegister, która jest preferowanym sposobem powiadamiania procesów innych niż usługi o zmianie w bibliotece.

Aby wykryć zmiany elementów w bibliotece przy użyciu interfejsu API powłoki systemu Windows, wywołaj SHChangeNotifyRegister, aby zarejestrować program w celu otrzymywania powiadomień o zmianach elementów w folderze biblioteki. Ta funkcja może powiadomić program, jeśli nastąpiła zmiana w dowolnej bibliotece lub tylko w określonej bibliotece. Powiadomienia są wysyłane natychmiast po zmianie biblioteki.

Powiadomienie dotyczące interfejsu API systemu plików

Powiadomienia związane z systemem plików muszą być wykorzystywane w procesach usług.

Aby wykryć zmiany elementów w bibliotece przy użyciu interfejsu API systemu plików, należy wyliczyć foldery w bibliotece i wywołać FindFirstChangeNotification dla każdego folderu do monitorowania. Program otrzyma powiadomienie, gdy monitorowany folder ulegnie zmianie. Aby znaleźć konkretny plik plików, które uległy zmianie w folderze, wywołaj ReadDirectoryChangesW. Aby wykryć zmiany w pliku opisu biblioteki, monitoruj folder, który go zawiera. Plik opisu biblioteki można znaleźć w folderze FOLDERID_Libraries. Nie należy jednak otwierać ani modyfikować pliku opisu biblioteki.

Informacje o bibliotekach

IShellLibrary

łącza powłoki

znane foldery

Schemat opisu Biblioteki

IID_PPV_ARGS

 

 

  • Last updated on