Использование библиотек в программе
В этом разделе описываются некоторые аспекты, которые следует учитывать при использовании библиотек в программе.
В этом разделе:
- Общие сведения о программировании библиотек
- Программирование с помощью библиотек
- Использование диалогового окна общего файла с библиотеками
- Включение выбора библиотеки из пользовательского интерфейса
- Доступ к содержимому библиотеки в программе
- Сохранение пользовательского содержимого в библиотеке
- Поддержка операций перетаскивания в библиотеке
- Синхронизация с библиотекой
- Связанные темы
Общие сведения о программировании библиотек
Библиотеки позволяют пользователям упорядочивать содержимое на основе файлов таким образом, который имеет смысл для них и не ограничивается организацией файловой системы. Если ваша программа поддерживает библиотеки, она позволяет пользователю находить свое содержимое таким образом, который имеет смысл для него при представлении пользовательского интерфейса, соответствующего пользовательскому интерфейсу Windows 7. Библиотеки также упрощают для программы поиск файлового содержимого, хранящегося в разных папках или на разных компьютерах.
В разделах этого раздела описывается, как добавить поддержку библиотек в программу и воспользоваться преимуществами новых возможностей библиотек. Windows 7 предоставляет некоторые из этих средств по умолчанию. Если программа не изменяет общие диалоговые окна файлов, которые она использует в настоящее время, ей может потребоваться очень мало дополнительного программирования для поддержки библиотек.
В этом разделе описываются некоторые ключевые функции, предоставляемые библиотеками, и способы их поддержки в вашей программе. С помощью этих сведений вы можете решить, какие функции обеспечат лучший пользовательский интерфейс в вашей программе. Если программа настраивает диалоговые окна с общими файлами, сведения в этом разделе помогут вам определить, как использовать новые диалоговые окна общих файлов для использования библиотек и предоставления эквивалентных функций в Windows 7.
Программирование с помощью библиотек
Модель программирования оболочки Windows описывает, как программа взаимодействует с программными объектами оболочки Windows. Хотя объекты файловой системы, такие как файлы и каталоги, представлены объектами оболочки Windows, не все объекты оболочки Windows представлены файловой системой. Например, библиотеки — это объекты оболочки Windows, которые не имеют эквивалента файловой системы. Использование объектов оболочки Windows в программе позволяет программе получать доступ ко всем объектам оболочки, а не только к объектам файловой системы.
Для достижения наилучших результатов программа будет использовать API библиотек оболочки для взаимодействия с библиотеками и доступа к их содержимому. Хотя библиотеки содержат элементы файловой системы, такие как папки и файлы, библиотеки не являются элементами файловой системы. Таким образом, API файловой системы нельзя использовать для доступа к функциям библиотеки или содержимому библиотеки.
Если у вас есть программа, которая в настоящее время использует множество API файловой системы, ваша программа по-прежнему может воспользоваться преимуществами функций библиотеки. API библиотеки оболочки может предоставлять ссылки файловой системы на элементы, которые находятся в библиотеке, и эти ссылки файловой системы, такие как имя файла и путь, могут быть переданы в существующие API файловой системы, которые находятся в существующей программе.
Переход из известных папок в библиотеки
До Windows 7 в качестве папки по умолчанию в операциях сохранения или открытия файлов обычно использовались известные папки, такие как папка "Мои документы". В Windows 7 следует использовать соответствующую библиотеку, чтобы пользователь работал в вашей программе так же, как и в других программах Windows 7, таких как Windows Обозреватель.
Если в настоящее время вы используете API оболочки Windows в программе, добавить поддержку библиотеки несложно. Например, если вы вызываете функцию SHGetKnownFolderItem для получения расположения папки "Мои документы", можно заменить значение KNOWNFOLDERID известной папки "Мои документы" значением KNOWNFOLDERID соответствующей библиотеки.
В следующей таблице показана связь между значениями KNOWNFOLDERID известных папок и значением KNOWNFOLDERID соответствующей библиотеки в Windows 7.
| Значения known folder KNOWNFOLDERID | Значения библиотеки KNOWNFOLDERID |
|---|---|
| FOLDERID_Documents | FOLDERID_DocumentsLibrary |
| FOLDERID_Pictures | FOLDERID_PicturesLibrary |
| FOLDERID_Music | FOLDERID_MusicLibrary |
| FOLDERID_RecordedTV | FOLDERID_RecordedTVLibrary |
Домашняя группа и общие библиотеки
Добавление поддержки библиотек в программу обеспечит поддержку общих библиотек в домашней группе. Домашняя группа идентифицируется по значению KNOWNFOLDERIDFOLDERID_HomeGroup. Программа может определить частное или общее расположение сохранения пользователя по умолчанию, задав значение DEFAULTSAVEFOLDERTYPE в вызове метода IShellLibrary::GetDefaultSaveFolder .
Использование диалогового окна общего файла с библиотеками
Использование диалогового окна общих файлов с библиотеками. Диалоговое окно общего файла обновлено для поддержки библиотек в 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 Обозреватель для поиска и выбора файлов.
- Программа может использовать интерфейсы и методы из 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, в элементе ulFlags структуры BROWSEINFO установите флаг BIF_USENEWUI и снимите флаг BIF_RETURNONLYFSDIRS.
BROWSEINFO browseInfo;
browseInfo.ulFlags = BIF_USENEWUI | ~BIF_RETURNONLYFSDIRS;
// Set other member values
pidl = SHBrowseForFolder(&browseInfo);
Доступ к содержимому библиотеки в программе
Чтобы получить доступ к содержимому библиотеки, необходимо использовать API оболочки Windows. Функции API файловой системы нельзя использовать для доступа к содержимому библиотеки, так как библиотеки не являются объектами файловой системы. Если программа использует пользовательский браузер файлов, основанный на API файловой системы, она не сможет просматривать библиотеки или получать доступ к содержимому библиотек.
В этом разделе описывается, как получить доступ к содержимому библиотеки, чтобы выбрать оптимальный способ обновления программы для работы с библиотеками.
Доступ к содержимому библиотеки с помощью интерфейса IShellLibrary
Самый простой способ доступа программы к содержимому библиотеки — использовать 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
Доступ к содержимому библиотеки с помощью API оболочки
Так как объекты библиотеки являются частью модели программирования оболочки, их можно использовать с другими API оболочки Windows. Например, вы можете использовать интерфейсы IShellItem и IShellFolder в программе вместе со связанными вспомогательными функциями для доступа к содержимому библиотеки так же, как при перечислении папок и содержимого папок для доступа к содержимому с помощью API файловой системы.
API оболочки Windows поддерживают два режима перечисления для доступа к содержимому библиотеки:
Просмотр перечисления
Перечисление Browse является режимом перечисления по умолчанию и перечисляет содержимое папки библиотеки. Снимите флаг SHCONTF_NAVIGATION_ENUM, чтобы использовать этот режим.
Перечисление навигации
Перечисление навигации перечисляет папки библиотеки. Установите флаг SHCONTF_NAVIGATION_ENUM для использования этого режима.
Если программа использует пользовательский элемент управления в виде дерева для перемещения по папкам пользователя, перечисление папок в режиме перечисления навигации даст вам список папок библиотеки, который согласуется с тем, как windows Обозреватель перечисляет папки в Windows 7.
Примеры использования этих функций в программе см. в примере ShellStorage в windows SDK.
Сохранение пользовательского содержимого в библиотеке
Программа может сохранять пользовательское содержимое в библиотеке, а также в папке в библиотеке. Аналогичным образом пользователь может сохранить в определенной папке в библиотеке или просто сохранить в библиотеке.
У каждой библиотеки есть папка, назначенная в качестве расположения сохранения по умолчанию. Расположение сохранения по умолчанию определяется при создании библиотеки; однако пользователь может переназначить расположение сохранения по умолчанию любой папке в библиотеке. Хотя пользователю не нужно настраивать расположение сохранения по умолчанию, у него есть возможность изменить его. Если пользователь удаляет папку, которая в настоящее время является расположением для сохранения по умолчанию, библиотека автоматически настроит следующую папку в библиотеке, чтобы она была расположением сохранения по умолчанию.
Существует несколько способов сохранения пользовательского содержимого в библиотеке.
API оболочки
Если вы используете модель программирования оболочки и сохраняете элемент оболочки, представленный IShellItem, IStorage или IStream, в объект библиотеки, элемент оболочки будет автоматически сохранен в расположении сохранения библиотеки по умолчанию.
API файловой системы
Если у вас есть программа, которая использует множество вызовов API файловой системы, можно получить путь к папке, которая определена как расположение сохранения библиотеки по умолчанию. Затем путь к папке можно передать в API файловой системы.
Примеры использования этих функций в программе см. в примере ShellStorage в windows SDK.
Поддержка операций перетаскивания в библиотеке
Если программа поддерживает действия перетаскивания, их следует обновить для поддержки правильного взаимодействия с библиотекой. Если файл удаляется в библиотеку, он должен быть сохранен в расположении сохранения по умолчанию. Если папка удаляется в библиотеку, она должна быть добавлена в библиотеку как новая папка. Если файл удаляется в существующую папку, которая не является местом сохранения по умолчанию, он должен быть добавлен в выбранную папку.
Примеры добавления поддержки библиотек для функций перетаскивания программ см. в примере ShellLibraryCommandLine в windows SDK.
Синхронизация с библиотекой
В этом разделе описывается, как программа может поддерживать актуальное представление содержимого библиотеки.
Массовое обновление
Так как пользователь может изменять папки библиотеки в интерактивном режиме, когда программа не запущена, программа должна вызывать SHResolveLibrary , когда начинает обнаруживать и сохранять изменения в библиотеке. API оболочки предоставляет функцию SHResolveLibrary , позволяющую программе получать текущее содержимое библиотеки и текущие расположения папок, которые могут содержаться в ней.
Обратите внимание, что SHResolveLibrary — это блокирующая функция, возвращаемая в зависимости от того, что изменилось в библиотеке. Таким образом, он не должен вызываться из потока пользовательского интерфейса.
После обновления программы можно зарегистрироваться для получения уведомлений об изменениях, чтобы сохранить текущее представление.
Уведомление API оболочки
API оболочки Windows предоставляет функцию SHChangeNotifyRegister , которая является предпочтительным способом уведомления процессов, не относящихся к службам, об изменениях в библиотеке.
Чтобы обнаружить изменения элементов в библиотеке с помощью API оболочки Windows, вызовите SHChangeNotifyRegister , чтобы зарегистрировать программу для уведомлений об изменениях элементов в папке библиотеки. Эта функция может уведомлять программу о наличии изменений в какой-либо библиотеке или только в определенной библиотеке. Уведомления отправляются сразу при изменении библиотеки.
Уведомление API файловой системы
Уведомления файловой системы должны использоваться в процессах службы.
Чтобы обнаружить изменения элементов в библиотеке с помощью API файловой системы, перечислите папки в библиотеке и вызовите Метод FindFirstChangeNotification для каждой отслеживаемой папки. Программа получит уведомление при изменении отслеживаемой папки. Чтобы найти конкретный файл файлов, которые изменились в папке, вызовите ReadDirectoryChangesW. Чтобы обнаружить изменения в файле описания библиотеки, отслеживайте папку, содержащую ее. Файл описания библиотеки можно найти в папке FOLDERID_Libraries . Однако файл описания библиотеки не следует открывать или изменять.
Связанные темы