Verwenden von Bibliotheken in Ihrem Programm

  • Artikel

In diesem Thema werden einige der Punkte beschrieben, die bei der Verwendung von Bibliotheken in Ihrem Programm zu beachten sind.

In diesem Thema:

Übersicht über die Bibliotheksprogrammierung

Bibliotheken ermöglichen es Benutzern, ihre dateibasierten Inhalte auf eine Weise zu organisieren, die für sie sinnvoll ist und nicht durch die organization des Dateisystems beschränkt ist. Wenn Ihr Programm Bibliotheken unterstützt, ermöglicht es dem Benutzer, seine Inhalte auf eine Weise zu finden, die für ihn sinnvoll ist, während eine Benutzeroberfläche dargestellt wird, die mit der Windows 7-Benutzeroberfläche konsistent ist. Bibliotheken erleichtern es Ihrem Programm auch, dateibasierte Inhalte zu finden, die in verschiedenen Ordnern oder auf verschiedenen Computern gespeichert sind.

In den Themen in diesem Abschnitt wird beschrieben, wie Sie Ihrem Programm Bibliotheksunterstützung hinzufügen und die neuen Funktionen nutzen können, die Bibliotheken bieten. Windows 7 bietet standardmäßig einen Teil dieser Unterstützung. Wenn Ihr Programm die gängigen Dateidialogfelder, die es derzeit verwendet, nicht ändert, ist möglicherweise sehr wenig zusätzliche Programmierung erforderlich, um Bibliotheken zu unterstützen.

In diesem Abschnitt werden einige der wichtigsten Features von Bibliotheken und deren Unterstützung in Ihrem Programm beschrieben. Mit diesen Informationen können Sie entscheiden, welche Features das beste Benutzererlebnis in Ihrem Programm bieten. Wenn Ihr Programm die allgemeinen Dateidialogfelder anpasst, können Sie anhand der Informationen in diesem Abschnitt ermitteln, wie Sie die neuen allgemeinen Dateidialogfelder verwenden, um Bibliotheken zu verwenden und gleichwertige Funktionen in Windows 7 bereitzustellen.

Programmieren mit Bibliotheken

Das Windows Shell-Programmiermodell beschreibt, wie ein Programm mit Windows Shell-Programmierobjekten interagiert. Dateisystemobjekte, z. B. Dateien und Verzeichnisse, werden zwar durch Windows Shell-Objekte dargestellt, aber nicht alle Windows Shell-Objekte werden vom Dateisystem dargestellt. Bibliotheken sind beispielsweise Windows Shell-Objekte, die kein Dateisystemäquivalent aufweisen. Die Verwendung von Windows Shell-Objekten in Ihrem Programm ermöglicht es Ihrem Programm, auf alle Shellobjekte und nicht nur auf Dateisystemobjekte zuzugreifen.

Um optimale Ergebnisse zu erzielen, verwendet Ihr Programm die Shellbibliotheks-API , um mit Bibliotheken zu interagieren und auf deren Inhalte zuzugreifen. Während Bibliotheken Dateisystemelemente wie Ordner und Dateien enthalten, sind Bibliotheken keine Dateisystemelemente. Daher können Dateisystem-APIs nicht für den Zugriff auf Bibliotheksfeatures oder Bibliotheksinhalte verwendet werden.

Wenn Sie über ein vorhandenes Programm verfügen, das derzeit viele Dateisystem-APIs verwendet, kann Ihr Programm weiterhin die Bibliotheksfeatures nutzen. Die Shellbibliotheks-API kann Dateisystemverweise auf die Elemente in einer Bibliothek bereitstellen, und diese Dateisystemverweise, z. B. den Dateinamen und den Pfad, können an die vorhandenen Dateisystem-APIs übergeben werden, die sich in Ihrem vorhandenen Programm befinden.

Verschieben von bekannten Ordnern zu Bibliotheken

Vor Windows 7 war es üblich, einen bekannten Ordner, z. B. den Ordner "Eigene Dateien", als Standardordner bei Dateispeicher- oder Dateiöffnungsvorgängen zu verwenden. In Windows 7 sollte die entsprechende Bibliothek verwendet werden, damit der Benutzer die gleiche Erfahrung in Ihrem Programm hat wie bei anderen Windows 7-Programmen, z. B. dem Windows-Explorer.

Wenn Sie derzeit die Windows Shell-API in Ihrem Programm verwenden, ist das Hinzufügen von Bibliotheksunterstützung einfach. Wenn Sie beispielsweise derzeit die SHGetKnownFolderItem-Funktion aufrufen, um den Speicherort des Ordners "Eigene Dokumente" abzurufen, können Sie den KNOWNFOLDERID-Wert des Ordners "Meine Dokumente" durch den KNOWNFOLDERID-Wert der entsprechenden Bibliothek ersetzen.

Die folgende Tabelle zeigt die Beziehung zwischen den KNOWNFOLDERID-Werten bekannter Ordner und dem KNOWNFOLDERID-Wert der entsprechenden Bibliothek in Windows 7.

Known Folder KNOWNFOLDERID-Werte KNOWNFOLDERID-Werte der Bibliothek
FOLDERID_Documents FOLDERID_DocumentsLibrary
FOLDERID_Pictures FOLDERID_PicturesLibrary
FOLDERID_Music FOLDERID_MusicLibrary
FOLDERID_RecordedTV FOLDERID_RecordedTVLibrary

 

Heimnetzgruppe und freigegebene Bibliotheken

Wenn Sie Ihrem Programm Bibliotheksunterstützung hinzufügen, wird die Unterstützung für freigegebene Bibliotheken in einer Heimnetzgruppe ermöglicht. Die Heimnetzgruppe wird durch den KNOWNFOLDERID-WertFOLDERID_HomeGroup identifiziert. Ihr Programm kann den privaten oder freigegebenen Standardspeicherort des Benutzers ermitteln, indem es den DEFAULTSAVEFOLDERTYPE-Wert im Aufruf der IShellLibrary::GetDefaultSaveFolder-Methode festlegt.

Verwenden eines allgemeinen Dateidialogfelds mit Bibliotheken

Verwenden eines allgemeinen Dateidialogfelds mit Bibliotheken Das Dialogfeld "Gemeinsame Datei" wurde aktualisiert, um Bibliotheken in Windows 7 zu unterstützen. Die folgende Abbildung zeigt, wie das Dialogfeld "Allgemeine Datei" für einen Benutzer in Windows 7 angezeigt wird.

Screenshot des Dialogfelds

Wenn Ihr Programm in Windows 7 derzeit ein allgemeines Dateidialogfeld anzeigt und die Dialogfeldvorlage nicht ändert oder keines der zugehörigen Ereignisse einhakt, wird die neue Windows 7-Version des Dialogfelds automatisch angezeigt. Insbesondere im Aufruf der Allgemeinen Dateidialogfeldfunktion müssen die Elemente lpfnHook, hInstance, lpTemplatename der OPENFILENAME-StrukturNULL und die Flags OFN_ENABLEHOOK und OFN_ENABLETEMPLATE klar sein.

In Windows 7 ersetzen die IFileDialog-bezogenen Schnittstellen die funktionen des allgemeinen Dateidialogfelds, die in früheren Versionen von Windows verwendet wurden. Die früheren allgemeinen Dateidialogfeldfunktionen werden in Windows 7 weiterhin unterstützt, bieten jedoch nicht die vollständige Benutzeroberfläche von Windows 7 und unterstützen keine Bibliotheken. Zu den neuen Features, die von den IFileDialog-bezogenen Schnittstellen unterstützt werden, gehören:

  • Der Benutzer kann auf die Dateieigenschaften zugreifen, die vom Windows 7-Explorer unterstützt werden, um die Dateien zu durchsuchen und auszuwählen.
  • Das Programm kann Schnittstellen und Methoden aus der Shell-Namespace-API verwenden, um mit den Elementen zu arbeiten.
  • Das Programm kann ein datengesteuertes Anpassungsmodell anstelle eines ressourcendateigesteuerten Anpassungsmodells verwenden, um den allgemeinen Dateidialogfeldern neue Steuerelemente hinzuzufügen.

Sie sollten die IFileDialog-bezogenen Schnittstellen in folgenden Fällen verwenden:

  • Sie müssen das Dialogfeld "Allgemeine Datei" für Ihr Programm in Windows 7 anpassen. Dadurch kann Ihr Programm mit Bibliotheken arbeiten und das Anpassen Ihres Dialogfelds unterstützen.
  • Sie möchten, dass der Benutzer mehrere Dateien aus einem Dialogfeld für eine gemeinsame Datei auswählen kann. Dadurch wird sichergestellt, dass Sie die richtigen Pfade zum ausgewählten Objekt erhalten, da eine Bibliothek Inhalte enthalten kann, die in verschiedenen Ordnern gespeichert sind.

Weitere Informationen zu IFileDialog-bezogenen Schnittstellen finden Sie unter:

Aktivieren der Bibliotheksauswahl über die Benutzeroberfläche

Wenn Ihr Programm es dem Benutzer ermöglicht, einen Ordner auszuwählen, z. B. für Import- oder Exportfunktionen, in Windows 7, sollte es dem Benutzer auch ermöglichen, eine Bibliothek auszuwählen. Die IFileOpenDialog-Schnittstelle und die SHBrowseForFolder-Funktion ermöglichen es dem Benutzer, eine Bibliothek auszuwählen, wenn er aufgefordert wird, einen Ordner auszuwählen. Die IFileOpenDialog-Schnittstelle wird der SHBrowseForFolder-Funktion vorgezogen, da IFileOpenDialog die Windows 7-Benutzeroberfläche unterstützt.

Um Benutzern das Auswählen von Ordnern bei Verwendung der IFileOpenDialog-Schnittstelle zu ermöglichen, rufen Sie SetOptions auf, wobei das flag FOS_PICKFOLDERS festgelegt ist, und stellen Sie sicher, dass das flag FOS_FORCEFILESYSTEM eindeutig ist.

FILEOPENDIALOGOPTIONS fileOptions;

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

Damit Benutzer beim Aufrufen der SHBrowseForFolder-Funktion Ordner auswählen können, legen Sie im ulFlags-Element der BROWSEINFO-Struktur das flag BIF_USENEWUI fest, und deaktivieren Sie das flag BIF_RETURNONLYFSDIRS.

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

Zugreifen auf Bibliotheksinhalte in einem Programm

Um auf den Inhalt einer Bibliothek zuzugreifen, müssen Sie die Windows-Shell-API verwenden. Funktionen der Dateisystem-API können nicht für den Zugriff auf Bibliotheksinhalte verwendet werden, da Bibliotheken keine Dateisystemobjekte sind. Wenn Ihr Programm einen benutzerdefinierten Dateibrowser verwendet, der auf der Dateisystem-API basiert, kann es keine Bibliotheken durchsuchen oder auf Bibliotheksinhalte zugreifen.

In diesem Abschnitt wird beschrieben, wie Sie auf Bibliotheksinhalte zugreifen können, sodass Sie die beste Methode zum Aktualisieren Ihres Programms für die Verwendung von Bibliotheken auswählen können.

Zugreifen auf Bibliotheksinhalte über die IShellLibrary-Schnittstelle

Die einfachste Möglichkeit für ein Programm, auf Bibliotheksinhalte zuzugreifen, ist die Verwendung der Shellbibliotheks-API. Wenn Sie an einem Programm arbeiten, das die Dateisystem-API verwendet, kann die Shellbibliotheks-API die Dateisystemordner einer Bibliothek zurückgeben, wodurch die Änderung ihres vorhandenen Programmcodes minimiert wird.

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

Zugreifen auf Bibliotheksinhalte mit den Shell-APIs

Da die Bibliotheksobjekte Teil des Shell-Programmiermodells sind, können sie mit anderen Windows Shell-APIs verwendet werden. Beispielsweise können Sie die IShellItem- und IShellFolder-Schnittstellen in Ihrem Programm zusammen mit zugehörigen Hilfsfunktionen verwenden, um auf die Inhalte einer Bibliothek auf die gleiche Weise zuzugreifen wie Ordner und Ordnerinhalte, um auf Inhalte mit den Dateisystem-APIs zuzugreifen.

Die Windows Shell-APIs unterstützen zwei Enumerationsmodi für den Zugriff auf den Inhalt einer Bibliothek:

  • Enumeration durchsuchen

    Die Browse-Enumeration ist der Standardaufzählungsmodus und listet den Inhalt eines Bibliotheksordners auf. Deaktivieren Sie das Flag SHCONTF_NAVIGATION_ENUM, um diesen Modus zu verwenden.

  • Navigationsaufzählung

    Die Navigationsaufzählung listet die Bibliotheksordner auf. Legen Sie das SHCONTF_NAVIGATION_ENUM-Flag fest, um diesen Modus zu verwenden.

Wenn Ihr Programm ein benutzerdefiniertes Struktursteuerelement verwendet, um in den Ordnern des Benutzers zu navigieren, erhalten Sie durch das Auflisten der Ordner im Navigationsaufzählungsmodus eine Liste der Ordner einer Bibliothek, die mit der Aufzählung von Ordnern in Windows 7 von Windows Explorer konsistent ist.

Beispiele für die Verwendung dieser Features in einem Programm finden Sie im ShellStorage-Beispiel im Windows SDK.

Speichern von Benutzerinhalten in einer Bibliothek

Ihr Programm kann Benutzerinhalte sowohl in einer Bibliothek als auch in einem Ordner in der Bibliothek speichern. Ebenso kann der Benutzer in einem bestimmten Ordner in einer Bibliothek oder einfach in der Bibliothek speichern.

Jede Bibliothek verfügt über einen Ordner, der als Standardspeicherort festgelegt ist. Der Standardspeicherort wird beim Erstellen der Bibliothek definiert. Der Benutzer kann jedoch den Standardspeicherort einem beliebigen Ordner in der Bibliothek zuweisen. Der Benutzer muss zwar keinen Standardspeicherort konfigurieren, hat aber die Möglichkeit, ihn zu ändern. Wenn der Benutzer den Ordner löscht, der derzeit als Standardspeicherort festgelegt ist, konfiguriert die Bibliothek automatisch den nächsten Ordner in der Bibliothek als Standardspeicherort.

Es gibt mehrere Möglichkeiten, Benutzerinhalte in einer Bibliothek zu speichern.

  • Shell-API

    Wenn Sie das Shell-Programmiermodell verwenden und ein Shell-Element, wie durch ein IShellItem, IStorage oder IStream dargestellt, in einem Bibliotheksobjekt speichern, wird das Shell-Element automatisch am Standardspeicherort der Bibliothek gespeichert.

  • Dateisystem-API

    Wenn Sie über ein vorhandenes Programm verfügen, das viele Dateisystem-API-Aufrufe verwendet, können Sie einen Pfad zu dem Ordner abrufen, der als Standardspeicherort der Bibliothek definiert ist. Der Ordnerpfad kann dann an eine Dateisystem-API übergeben werden.

Beispiele für die Verwendung dieser Features in einem Programm finden Sie im ShellStorage-Beispiel im Windows SDK.

Unterstützung von Drag-and-Drop-Vorgängen in einer Bibliothek

Wenn Ihr Programm Drag-and-Drop-Aktionen unterstützt, sollten diese aktualisiert werden, um die richtige Bibliotheksinteraktion zu unterstützen. Wenn eine Datei in einer Bibliothek abgelegt wird, sollte die gelöschte Datei am Standardspeicherort gespeichert werden. Wenn ein Ordner in einer Bibliothek abgelegt wird, sollte der gelöschte Ordner als neuer Ordner zur Bibliothek hinzugefügt werden. Wenn eine Datei in einen vorhandenen Ordner abgelegt wird, der nicht der Standardspeicherort ist, sollte die Datei dem ausgewählten Ordner hinzugefügt werden.

Beispiele für das Hinzufügen von Bibliotheksunterstützung für Die Drag-and-Drop-Funktionalität ihrer Programme finden Sie im ShellLibraryCommandLine-Beispiel im Windows SDK.

Synchronisieren mit einer Bibliothek

In diesem Thema wird beschrieben, wie ein Programm die Ansicht des Inhalts einer Bibliothek auf dem neuesten Stand halten kann.

Massenaktualisierung

Da der Benutzer die Ordner einer Bibliothek interaktiv ändern kann, wenn Ihr Programm nicht ausgeführt wird, sollte Ihr Programm SHResolveLibrary aufrufen, wenn es beginnt, Änderungen an der Bibliothek zu ermitteln und zu speichern. Die Shell-API stellt die SHResolveLibrary-Funktion bereit, mit der ein Programm den aktuellen Inhalt einer Bibliothek und die aktuellen Speicherorte aller Ordner abrufen kann, die die Bibliothek möglicherweise enthält.

Beachten Sie, dass SHResolveLibrary eine blockierende Funktion ist, die je nachdem, was sich in der Bibliothek geändert hat, lange dauern kann, bis sie zurückgegeben wird. Daher sollte er nicht über einen UI-Thread aufgerufen werden.

Nachdem das Programm auf den neuesten Stand gebracht wurde, kann es sich für Änderungsbenachrichtigungen registrieren, um eine aktuelle Ansicht beizubehalten.

Shell-API-Benachrichtigung

Die Windows Shell-API stellt die Funktion SHChangeNotifyRegister bereit. Dies ist die bevorzugte Möglichkeit für Nicht-Dienstprozesse, über eine Änderung in der Bibliothek benachrichtigt zu werden.

Um Änderungen an Elementen innerhalb einer Bibliothek mithilfe der Windows Shell-API zu erkennen, rufen Sie SHChangeNotifyRegister auf, um Ihr Programm für Benachrichtigungen über Änderungen an Elementen in einem Bibliotheksordner zu registrieren. Diese Funktion kann Ihr Programm benachrichtigen, wenn eine Änderung in einer bibliothek oder nur in einer bestimmten Bibliothek erfolgt. Benachrichtigungen werden sofort gesendet, wenn eine Bibliothek geändert wird.

Dateisystem-API-Benachrichtigung

Dateisystembenachrichtigungen müssen in Dienstprozessen verwendet werden.

Um Änderungen an Elementen in einer Bibliothek mithilfe der Dateisystem-API zu erkennen, listen Sie die Ordner in der Bibliothek auf, und rufen Sie FindFirstChangeNotification für jeden zu überwachenden Ordner auf. Ihr Programm erhält eine Benachrichtigung, wenn sich ein überwachter Ordner ändert. Rufen Sie ReadDirectoryChangesW auf, um die bestimmte Datei mit dateien zu finden, die sich im Ordner geändert haben. Um Änderungen in der Bibliotheksbeschreibungsdatei zu erkennen, überwachen Sie den Ordner, in dem sie enthalten ist. Die Bibliotheksbeschreibungsdatei befindet sich im Ordner FOLDERID_Libraries . Die Bibliotheksbeschreibungsdatei sollte jedoch nicht geöffnet oder geändert werden.

Informationen zu Bibliotheken

IShellLibrary

Shelllinks

Bekannte Ordner

Bibliotheksbeschreibungsschema

IID_PPV_ARGS