Delen via

Bibliotheken gebruiken in uw programma

  • Artikel

In dit onderwerp worden enkele van de aandachtspunten beschreven bij het gebruik van bibliotheken in uw programma.

In dit onderwerp:

Overzicht van bibliotheekprogrammering

Met bibliotheken kunnen gebruikers hun inhoud op basis van bestanden ordenen op een manier die voor hen zinvol is en niet wordt beperkt door de organisatie van het bestandssysteem. Wanneer uw programma bibliotheken ondersteunt, kan de gebruiker de inhoud ervan vinden op een manier die zinvol is bij het presenteren van een gebruikersinterface die consistent is met de Gebruikerservaring van Windows 7. Bibliotheken maken het voor uw programma ook gemakkelijker om bestandsinhoud te vinden die is opgeslagen in verschillende mappen of op verschillende computers.

In de onderwerpen in deze sectie wordt beschreven hoe u bibliotheekondersteuning aan uw programma kunt toevoegen en kunt profiteren van de nieuwe mogelijkheden die bibliotheken bieden. Windows 7 biedt standaard een aantal van deze ondersteuning. Als uw programma de algemene dialoogvensters voor bestanden die momenteel worden gebruikt niet wijzigt, is er mogelijk weinig extra programmering nodig om bibliotheken te ondersteunen.

In deze sectie worden enkele van de belangrijkste functies beschreven die bibliotheken bieden en hoe u deze in uw programma kunt ondersteunen. Met deze informatie kunt u bepalen welke functies de beste gebruikerservaring van uw programma bieden. Als uw programma de algemene dialoogvensters voor bestanden aanpast, kunt u met de informatie in deze sectie bepalen hoe u de nieuwe algemene bestandsdialoogvensters kunt gebruiken om bibliotheken te gebruiken en gelijkwaardige functionaliteit te bieden in Windows 7.

Programmeren met bibliotheken

In het Programmeermodel van Windows Shell wordt beschreven hoe een programma communiceert met Windows Shell-programmeerobjecten. Hoewel bestandssysteemobjecten, zoals bestanden en mappen, worden vertegenwoordigd door Windows Shell-objecten, worden niet alle Windows Shell-objecten vertegenwoordigd door het bestandssysteem. Bibliotheken zijn bijvoorbeeld Windows Shell-objecten die geen equivalent van het bestandssysteem hebben. Als u Windows Shell-objecten in uw programma gebruikt, heeft uw programma toegang tot alle Shell-objecten en niet alleen bestandssysteemobjecten.

Voor de beste resultaten gebruikt uw programma de Shell Library-API om te communiceren met bibliotheken en toegang te krijgen tot hun inhoud. Hoewel bibliotheken bestandssysteemitems zoals mappen en bestanden bevatten, zijn bibliotheken geen bestandssysteemitems. Als zodanig kunnen API's van het bestandssysteem niet worden gebruikt voor toegang tot bibliotheekfuncties of bibliotheekinhoud.

Als u een bestaand programma hebt dat momenteel veel API's voor het bestandssysteem gebruikt, kan uw programma nog steeds profiteren van bibliotheekfuncties. De Shell Library-API kan bestandssysteemverwijzingen bieden naar de items die zich in een bibliotheek bevinden en deze bestandssysteemverwijzingen, zoals de bestandsnaam en het pad, kunnen worden doorgegeven aan de bestaande bestandssysteem-API's die zich in uw bestaande programma bevinden.

Verplaatsen van bekende mappen naar bibliotheken

Voor Windows 7 was het gebruikelijk om een bekende map te gebruiken, zoals de map Mijn documenten, als de standaardmap in het opslaan van bestanden of bewerkingen voor het openen van bestanden. In Windows 7 moet de bijbehorende bibliotheek worden gebruikt, zodat de gebruiker dezelfde ervaring heeft in uw programma als bij andere Windows 7-programma's, zoals Windows Verkenner.

Als u momenteel de Windows Shell-API in uw programma gebruikt, is het toevoegen van bibliotheekondersteuning eenvoudig. Als u bijvoorbeeld momenteel de functie SHGetKnownFolderItem aanroept om de locatie van de map Mijn documenten op te halen, kunt u de KNOWNFOLDERID waarde van de bekende map Mijn documenten vervangen door de KNOWNFOLDERID waarde van de bijbehorende bibliotheek.

In de volgende tabel ziet u de relatie tussen de KNOWNFOLDERID waarden van bekende mappen en de KNOWNFOLDERID waarde van de bijbehorende bibliotheek in Windows 7.

Bekende map van KNOWNFOLDERID-waarden Library KNOWNFOLDERID-waarden
FOLDERID_Documents FOLDERID_DocumentsLibrary
FOLDERID_Afbeeldingen FOLDERID_PicturesLibrary
FOLDERID_Music FOLDERID_MusicLibrary
FOLDERID_RecordedTV FOLDERID_OpgenomenTVBibliotheek

 

Thuisgroep en gedeelde bibliotheken

Als u bibliotheekondersteuning aan uw programma toevoegt, wordt ondersteuning voor gedeelde bibliotheken in een Thuisgroep ingeschakeld. De thuisgroep wordt geïdentificeerd door de KNOWNFOLDERID waarde van FOLDERID_HomeGroup. Uw programma kan de privé- of gedeelde standaardlocatie voor opslaan van de gebruiker vinden door de DEFAULTSAVEFOLDERTYPE- waarde in te stellen in de aanroep naar IShellLibrary::GetDefaultSaveFolder methode.

Gebruik een gebruikelijk dialoogvenster met bibliotheken

Het gebruik van een algemeen dialoogvenster voor bestanden met bibliotheken Het algemene dialoogvenster voor bestanden is bijgewerkt ter ondersteuning van bibliotheken in Windows 7. In de volgende afbeelding ziet u hoe het gebruikelijke bestandsdialoogvenster eruitziet voor een gebruiker in Windows 7.

schermafbeelding van het algemene dialoogvenster met bibliotheken

Als een programma in Windows 7 momenteel een algemeen bestandsdialoogvenster weergeeft en de sjabloon van het dialoogvenster niet wordt gewijzigd of er geen van de gebeurtenissen ervan wordt geschaakt, wordt de nieuwe versie van het Windows 7-dialoogvenster automatisch weergegeven. In de aanroep van de algemene bestandsdialoogvensterfunctie moet de lpfnHook, hInstance, lpTemplatename leden van de OPENFILENAME structuur NULL- zijn en moeten de OFN_ENABLEHOOK en OFN_ENABLETEMPLATE vlaggen duidelijk zijn.

In Windows 7 vervangen de IFileDialog--gerelateerde interfaces de algemene bestandsdialoogvensterfuncties die zijn gebruikt in eerdere versies van Windows. De eerdere algemene bestandsdialoogvensterfuncties worden nog steeds ondersteund in Windows 7, maar bieden geen volledige gebruikerservaring voor Windows 7 en bieden geen ondersteuning voor bibliotheken. Enkele van de nieuwe functies die worden ondersteund door de IFileDialog--gerelateerde interfaces zijn:

  • De gebruiker heeft toegang tot de bestandseigenschappen die worden ondersteund door Windows 7 Windows Verkenner om de bestanden te zoeken en te selecteren.
  • Het programma kan interfaces en methoden van de Shell-naamruimte-API gebruiken om met de items te werken.
  • Het programma kan een gegevensgestuurd aanpassingsmodel gebruiken in plaats van een resourcebestandsgestuurd aanpassingsmodel om nieuwe besturingselementen toe te voegen aan de algemene bestandsdialoogvensters.

U moet de IFileDialog-gerelateerde interfaces gebruiken wanneer:

  • u moet het algemene dialoogvenster voor bestanden voor uw programma in Windows 7 aanpassen. Hierdoor kan uw programma werken met bibliotheken en ondersteuning bieden voor het aanpassen van uw dialoogvenster.
  • u wilt dat de gebruiker meerdere bestanden in een algemeen dialoogvenster kan selecteren. Dit zorgt ervoor dat u de juiste paden naar het geselecteerde object krijgt, omdat een bibliotheek inhoud kan bevatten die in verschillende mappen is opgeslagen.

Zie voor meer informatie over de interfaces die verband houden met IFileDialog:

Bibliotheekselectie inschakelen vanuit de gebruikersinterface

Als de gebruiker met uw programma een map kan selecteren, zoals voor import- of exportfuncties, moet de gebruiker in Windows 7 ook een bibliotheek kunnen selecteren. Met de IFileOpenDialog interface en de functie SHBrowseForFolder kan de gebruiker een bibliotheek selecteren wanneer hij wordt gevraagd een map te selecteren. De IFileOpenDialog interface heeft de voorkeur boven de functie SHBrowseForFolder omdat IFileOpenDialog- ondersteuning biedt voor de gebruikersinterface van Windows 7.

Als u wilt toestaan dat gebruikers mappen selecteren wanneer ze de IFileOpenDialog-interface gebruiken, roept u SetOptions aan met de FOS_PICKFOLDERS vlag ingesteld en controleert u of de FOS_FORCEFILESYSTEM vlag is gewist.

FILEOPENDIALOGOPTIONS fileOptions;

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

Als u wilt toestaan dat gebruikers mappen selecteren wanneer de functie SHBrowseForFolder wordt aangeroepen, stel dan in het ulFlags-lid van de BROWSEINFO-structuur de vlag BIF_USENEWUI in en deactiveer de vlag BIF_RETURNONLYFSDIRS.

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

Toegang tot bibliotheekinhoud in een programma

Voor toegang tot de inhoud van een bibliotheek moet u de Windows Shell-API gebruiken. Functies van de BESTANDSSYSTEEM-API kunnen niet worden gebruikt voor toegang tot bibliotheekinhoud omdat bibliotheken geen bestandssysteemobjecten zijn. Als uw programma gebruikmaakt van een aangepaste bestandsbrowser die is gebaseerd op de BESTANDSSYSTEEM-API, kan het niet bladeren door bibliotheken of toegang krijgen tot bibliotheekinhoud.

In deze sectie wordt beschreven hoe u toegang hebt tot bibliotheekinhoud, zodat u de beste manier kunt selecteren om uw programma bij te werken met bibliotheken.

Toegang tot bibliotheekinhoud met de IShellLibrary-interface

De eenvoudigste manier voor een programma voor toegang tot bibliotheekinhoud is het gebruik van de Shell Library-API-. Als u werkt aan een programma dat gebruikmaakt van de BESTANDSSYSTEEM-API, kan de Shell Library-API de bestandssysteemmappen van een bibliotheek retourneren, waardoor de wijziging in uw bestaande programmacode wordt geminimaliseerd.

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

Toegang tot bibliotheekinhoud met de Shell-API's

Omdat de bibliotheekobjecten deel uitmaken van het Shell-programmeermodel, kunnen ze worden gebruikt met andere Windows Shell-API's. U kunt bijvoorbeeld de IShellItem- en IShellFolder interfaces in uw programma gebruiken, samen met gerelateerde helperfuncties, om toegang te krijgen tot de inhoud van een bibliotheek op dezelfde manier als u mappen en mapinhoud opsommen om toegang te krijgen tot inhoud met de API's van het bestandssysteem.

De Windows Shell-API's ondersteunen twee opsommingsmodi voor toegang tot de inhoud van een bibliotheek:

  • opsomming doorbladeren

    Browse-inventarisatie is de standaard opsommingsmodus en inventariseert de inhoud van een bibliotheekmap. Wis de vlag SHCONTF_NAVIGATION_ENUM om deze modus te gebruiken.

  • navigatie-opsomming

    Met navigatie-inventarisatie worden de bibliotheekmappen opgesomd. Stel de SHCONTF_NAVIGATION_ENUM vlag in om deze modus te gebruiken.

Als in uw programma een aangepast structuurbesturingselement wordt gebruikt om door de mappen van de gebruiker te navigeren, krijgt u een lijst met mappen van een bibliotheek die consistent is met de manier waarop mappen in Windows Verkenner worden opgesomd in Windows 7.

Zie het ShellStorage-voorbeeld in de Windows SDK voor voorbeelden van het gebruik van deze functies in een programma.

Gebruikersinhoud opslaan in een bibliotheek

Uw programma kan gebruikersinhoud opslaan in een bibliotheek en in een map in de bibliotheek. Op dezelfde manier kan de gebruiker opslaan in een specifieke map in een bibliotheek of alleen opslaan in de bibliotheek.

Elke bibliotheek heeft een map die is aangewezen als de standaardlocatie voor opslaan. De standaardlocatie voor opslaan wordt gedefinieerd wanneer de bibliotheek wordt gemaakt; de gebruiker kan de standaardlocatie voor opslaan echter opnieuw toewijzen aan elke map in de bibliotheek. Hoewel de gebruiker geen standaardlocatie voor opslaan hoeft te configureren, heeft de gebruiker de mogelijkheid om deze te wijzigen. Als de gebruiker de map verwijdert die momenteel is ingesteld als de standaardlocatie voor opslaan, configureert de bibliotheek automatisch de volgende map in de bibliotheek als de standaardlocatie voor opslaan.

Er zijn verschillende manieren waarop u gebruikersinhoud kunt opslaan in een bibliotheek.

  • Shell-API-

    Als u het Shell-programmeermodel gebruikt en een Shell-item opslaat, zoals vertegenwoordigd door een IShellItem, IStorage of IStream, naar een bibliotheekobject, wordt het Shell-item automatisch opgeslagen op de standaardopslaglocatie van de bibliotheek.

  • Bestandssysteem-API

    Als u een bestaand programma hebt dat gebruikmaakt van veel API-aanroepen van het bestandssysteem, kunt u een pad naar de map ophalen die is gedefinieerd als de standaardlocatie voor opslaan van de bibliotheek. Het mappad kan vervolgens worden doorgegeven aan een bestandssysteem-API.

Zie het ShellStorage-voorbeeld in de Windows SDK voor voorbeelden van het gebruik van deze functies in een programma.

Ondersteuning voor slepen en neerzetten in een bibliotheek

Als uw programma slepen-en-neerzetten-acties ondersteunt, moeten deze worden bijgewerkt om de juiste interactie met de bibliotheek te ondersteunen. Als een bestand in een bibliotheek wordt geplaatst, moet het verwijderde bestand worden opgeslagen op de standaardlocatie voor opslaan. Als een map in een bibliotheek wordt geplaatst, moet de map als een nieuwe map aan de bibliotheek worden toegevoegd. Als een bestand wordt neergezet in een bestaande map die niet de standaardlocatie voor opslaan is, moet het bestand worden toegevoegd aan de geselecteerde map.

Zie het voorbeeld ShellLibraryCommandLine in de Windows SDK voor voorbeelden van hoe u bibliotheekondersteuning kunt toevoegen aan de slepen-en-neerzettenfunctionaliteit van uw programma's.

Synchroon houden met een bibliotheek

In dit onderwerp wordt beschreven hoe een programma de weergave van de inhoud van een bibliotheek kan bijhouden up-to-date.

Bulksgewijs bijwerken

Omdat de gebruiker de mappen van een bibliotheek interactief kan wijzigen wanneer uw programma niet wordt uitgevoerd, moet het programma SHResolveLibrary aanroepen wanneer deze wijzigingen in de bibliotheek begint te detecteren en op te slaan. De Shell-API biedt de functie SHResolveLibrary- om een programma in staat te stellen de huidige inhoud van een bibliotheek op te halen en de huidige locaties van mappen die de bibliotheek kan bevatten.

Houd er rekening mee dat SHResolveLibrary- een blokkerende functie is die lang kan duren om terug te keren, afhankelijk van wat er in de bibliotheek is gewijzigd. Daarom mag deze niet worden aangeroepen vanuit een UI-thread.

Nadat het programma up-to-date is gebracht, kan het zich vervolgens registreren voor wijzigingsmeldingen om een huidige weergave te behouden.

Shell-API-melding

De Windows Shell-API biedt de functie SHChangeNotifyRegister, de voorkeursmethode voor niet-serviceprocessen die op de hoogte worden gesteld van een wijziging in de bibliotheek.

Als u wijzigingen in items in een bibliotheek wilt detecteren met behulp van de Windows Shell-API, roept u SHChangeNotifyRegister aan om uw programma te registreren voor meldingen van wijzigingen in items in een bibliotheekmap. Met deze functie kunt u uw programma waarschuwen als er een wijziging is in een bibliotheek of alleen in een specifieke bibliotheek. Meldingen worden onmiddellijk verzonden wanneer een bibliotheek wordt gewijzigd.

Api-melding voor bestandssysteem

Meldingen van het bestandssysteem moeten worden gebruikt in serviceprocessen.

Als u wijzigingen in items in een bibliotheek wilt detecteren met behulp van de Bestandssysteem-API, inventariseert u de mappen in de bibliotheek en roept u FindFirstChangeNotification aan om elke map te monitoren. Uw programma ontvangt een melding wanneer een bewaakte map wordt gewijzigd. Om het specifieke bestand of de bestanden die in de map zijn gewijzigd te vinden, roept u ReadDirectoryChangesWaan. Als u wijzigingen in het beschrijvingsbestand van de bibliotheek wilt detecteren, controleert u de map die het bevat. Het beschrijvingsbestand van de bibliotheek vindt u in de map FOLDERID_Libraries. Het beschrijvingsbestand van de bibliotheek mag echter niet worden geopend of gewijzigd.

Over bibliotheken

IShellLibrary

Shell-koppelingen

bekende mappen

beschrijvingsschema voor bibliotheek

IID_PPV_ARGS