Dela via

Använda bibliotek i ditt program

I det här avsnittet beskrivs några av de saker du bör tänka på när du använder bibliotek i ditt program.

I det här avsnittet:

Översikt över biblioteksprogrammering

Bibliotek gör det möjligt för användare att organisera sitt filbaserade innehåll på ett sätt som är meningsfullt för dem och inte begränsas av filsystemets organisation. När programmet har stöd för bibliotek kan användaren hitta sitt innehåll på ett sätt som passar dem när de presenterar ett användargränssnitt som överensstämmer med Användarupplevelsen i Windows 7. Bibliotek gör det också enklare för programmet att hitta filbaserat innehåll som lagras i olika mappar eller på olika datorer.

Avsnitten i det här avsnittet beskriver hur du kan lägga till biblioteksstöd i ditt program och dra nytta av de nya funktioner som bibliotek erbjuder. Windows 7 tillhandahåller en del av det här stödet som standard. Om programmet inte ändrar de gemensamma fildialogrutor som används för närvarande kan det kräva mycket lite ytterligare programmering för att stödja bibliotek.

I det här avsnittet beskrivs några av de viktigaste funktionerna som bibliotek tillhandahåller och hur du stöder dem i ditt program. Med den här informationen kan du bestämma vilka funktioner som ska ge den bästa användarupplevelsen från ditt program. Om programmet anpassar de vanliga fildialogrutorna kan informationen i det här avsnittet hjälpa dig att avgöra hur du använder de nya gemensamma fildialogrutorna för att använda bibliotek och tillhandahålla motsvarande funktioner i Windows 7.

Programmering med bibliotek

Programmeringsmodellen Windows Shell beskriver hur ett program interagerar med programmeringsobjekt i Windows Shell. Även om filsystemobjekt, till exempel filer och kataloger, representeras av Windows Shell-objekt, representeras inte alla Windows Shell-objekt av filsystemet. Bibliotek är till exempel Windows Shell-objekt som inte har en filsystemsekvivalent. Genom att använda Windows Shell-objekt i programmet kan programmet komma åt alla Shell-objekt och inte bara filsystemobjekt.

För bästa resultat använder programmet API:et för Shell-bibliotek för att interagera med bibliotek och få åtkomst till deras innehåll. Bibliotek innehåller filsystemobjekt som mappar och filer, men bibliotek är inte filsystemobjekt. Därför kan filsystem-API:er inte användas för att komma åt biblioteksfunktioner eller biblioteksinnehåll.

Om du har ett befintligt program som för närvarande använder många filsystem-API:er kan programmet fortfarande dra nytta av biblioteksfunktioner. API:et för Shell-bibliotek kan ge filsystemreferenser till de objekt som finns i ett bibliotek och dessa filsystemreferenser, till exempel filnamn och sökväg, kan skickas till befintliga filsystem-API:er som finns i ditt befintliga program.

Flytta från kända mappar till bibliotek

Före Windows 7 var det vanligt att använda en känd mapp, till exempel mappen Mina dokument, som standardmapp i filspar- eller filöppningsåtgärder. I Windows 7 ska motsvarande bibliotek användas så att användaren får samma upplevelse i ditt program som med andra Windows 7-program, till exempel Utforskaren i Windows.

Om du för närvarande använder Windows Shell-API:et i ditt program är det enkelt att lägga till biblioteksstöd. Om du till exempel anropar funktionen SHGetKnownFolderItem för att hämta platsen för mappen Mina dokument kan du ersätta värdet KNOWNFOLDERID för mappen Mina dokument med värdet KNOWNFOLDERID för motsvarande bibliotek.

I följande tabell visas relationen mellan KNOWNFOLDERID värden för kända mappar och värdet KNOWNFOLDERID för motsvarande bibliotek i Windows 7.

Kända mappvärden för KNOWNFOLDERID Bibliotekets KNOWNFOLDERID-värden
FOLDERID_Documents FOLDERID_DokumentBibliotek
FOLDERID_Pictures FOLDERID_PicturesLibrary
FOLDERID_Music FOLDERID_Musikbibliotek
FOLDERID_RecordedTV MAPPID_TVInspelningarBibliotek

 

Hemgrupp och delade bibliotek

Om du lägger till biblioteksstöd i programmet aktiveras stöd för delade bibliotek i en hemgrupp. HomeGroup identifieras av dess KNOWNFOLDERID värde för FOLDERID_HomeGroup. Programmet kan identifiera användarens privata eller delade standardlagringsplats genom att ange värdet DEFAULTSAVEFOLDERTYPE i anropet till IShellLibrary::GetDefaultSaveFolder-metoden.

Använda en gemensam fildialogruta med bibliotek

Använda en gemensam fildialogruta med bibliotek Den gemensamma fildialogrutan har uppdaterats för att stödja bibliotek i Windows 7. Följande bild visar hur den gemensamma fildialogrutan visas för en användare i Windows 7.

skärmbild av den gemensamma fildialogrutan som visar bibliotek

Om programmet för närvarande visar en gemensam fildialogruta i Windows 7 och inte ändrar dialogrutemallen eller kopplar någon av dess händelser, visas den nya Windows 7-versionen av dialogrutan automatiskt. Mer specifikt måste lpfnHook, hInstance, lpTemplatename medlemmar i OPENFILENAME- struktur vara NULL- och OFN_ENABLEHOOK och OFN_ENABLETEMPLATE flaggor måste vara tydliga.

I Windows 7 ersätter IFileDialog-relaterade gränssnitt de vanliga fildialogfunktionerna som användes i tidigare versioner av Windows. De tidigare vanliga fildialogrutorna stöds fortfarande i Windows 7, men de ger inte den fullständiga Användarupplevelsen för Windows 7 och de stöder inte bibliotek. Några av de nya funktionerna som stöds av IFileDialog-relaterade gränssnitt är:

  • Användaren kan komma åt de filegenskaper som stöds av Windows 7 Windows Explorer för att söka efter och välja filerna.
  • Programmet kan använda gränssnitt och metoder från Shell-namnområdes-API:et för att arbeta med objekten.
  • Programmet kan använda en datadriven anpassningsmodell i stället för en resursfildriven anpassningsmodell för att lägga till nya kontroller i de gemensamma fildialogrutorna.

Du bör använda IFileDialog-relaterade gränssnitt när:

  • du måste anpassa den gemensamma fildialogrutan för ditt program i Windows 7. På så sätt kan programmet arbeta med bibliotek och stöd för att anpassa dialogrutan.
  • du vill att användaren ska kunna välja flera filer från en gemensam fildialogruta. På så sätt får du rätt sökvägar till det markerade objektet eftersom ett bibliotek kan ha innehåll som lagras i olika mappar.

Mer information om IFileDialog-relaterade gränssnitt finns i:

Aktivera biblioteksval från användargränssnittet

Om programmet tillåter att användaren väljer en mapp, till exempel för import- eller exportfunktioner, i Windows 7 bör användaren också kunna välja ett bibliotek. Med IFileOpenDialog-gränssnittet och funktionen SHBrowseForFolder kan användaren välja ett bibliotek när användaren uppmanas att välja en mapp. Gränssnittet IFileOpenDialog föredras framför funktionen SHBrowseForFolder eftersom IFileOpenDialog stöder Användargränssnittet för Windows 7.

Om du vill tillåta användare att välja mappar när de använder IFileOpenDialog--gränssnittet anropar du SetOptions med flaggan FOS_PICKFOLDERS inställd och kontrollerar att flaggan FOS_FORCEFILESYSTEM är tydlig.

FILEOPENDIALOGOPTIONS fileOptions;

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

Om du vill tillåta användare att välja mappar när de anropar funktionen SHBrowseForFolder i ulFlags-medlemmen i strukturen BROWSEINFO anger du flaggan BIF_USENEWUI och avmarkerar flaggan BIF_RETURNONLYFSDIRS.

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

Åtkomst till biblioteksinnehåll i ett program

Om du vill komma åt innehållet i ett bibliotek måste du använda Windows Shell-API:et. Funktioner i filsystem-API:et kan inte användas för att komma åt biblioteksinnehåll eftersom bibliotek inte är filsystemobjekt. Om programmet använder en anpassad filwebbläsare som baseras på filsystem-API:et kan det inte bläddra bland bibliotek eller komma åt biblioteksinnehåll.

I det här avsnittet beskrivs hur du kan komma åt biblioteksinnehåll så att du kan välja det bästa sättet att uppdatera programmet så att det fungerar med bibliotek.

Åtkomst till biblioteksinnehåll med IShellLibrary-gränssnittet

Det enklaste sättet för ett program att komma åt biblioteksinnehåll är att använda API:et för Shell-bibliotek. Om du arbetar med ett program som använder filsystem-API:et kan Shell Library API returnera filsystemmapparna i ett bibliotek, vilket minimerar ändringen av din befintliga programkod.

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

Åtkomst till biblioteksinnehåll med Shell-API:er

Eftersom biblioteksobjekten ingår i Shell-programmeringsmodellen kan de användas med andra Windows Shell-API:er. Du kan till exempel använda IShellItem och IShellFolder-gränssnitt i programmet, tillsammans med relaterade hjälpfunktioner, för att få åtkomst till innehållet i ett bibliotek på samma sätt som du räknar upp mappar och mappinnehåll för att komma åt innehåll med filsystem-API:erna.

Windows Shell-API:erna stöder två uppräkningslägen för att få åtkomst till innehållet i ett bibliotek:

  • Bläddra

    Bläddra uppräkning är standarduppräkningsläget och räknar upp innehållet i en biblioteksmapp. Avmarkera flaggan SHCONTF_NAVIGATION_ENUM för att använda det här läget.

  • navigeringsuppställning

    Navigeringsuppräkning räknar upp biblioteksmapparna. Ange flaggan SHCONTF_NAVIGATION_ENUM för att använda det här läget.

Om ditt program använder en anpassad trädkontroll för att navigera i användarens mappar ger uppräkning av mapparna i navigeringsuppräkningsläget en lista över ett biblioteks mappar som överensstämmer med hur Utforskaren räknar upp mappar i Windows 7.

Exempel på hur du använder dessa funktioner i ett program finns i ShellStorage-exemplet i Windows SDK.

Spara användarinnehåll i ett bibliotek

Programmet kan spara användarinnehåll i ett bibliotek samt till en mapp i biblioteket. På samma sätt kan användaren spara till en specifik mapp i ett bibliotek eller så kan de bara spara i biblioteket.

Varje bibliotek har en mapp som är avsedd som standardplats för sparande. Standardplatsen för sparande definieras när biblioteket skapas. Användaren kan dock omtilldela standardplatsen för att spara till valfri mapp i biblioteket. Användaren behöver inte konfigurera en standardplats för sparande, men de har möjlighet att ändra den. Om användaren tar bort den mapp som för närvarande är inställd som standardplats för sparande konfigurerar biblioteket automatiskt nästa mapp i biblioteket till standardplatsen för sparande.

Det finns flera sätt att spara användarinnehåll i ett bibliotek.

  • Shell API

    Om du använder Shell-programmeringsmodellen och sparar ett Shell-objekt, som representeras av en IShellItem, IStorage eller IStream, till ett biblioteksobjekt, lagras Shell-objektet automatiskt på standardplatsen för sparande av biblioteket.

  • API för filsystem

    Om du har ett befintligt program som använder många API-anrop för filsystem kan du hämta en sökväg till mappen som definieras som bibliotekets standardplats för sparande. Sökvägen till mappen kan sedan skickas till ett API för filsystem.

Exempel på hur du använder dessa funktioner i ett program finns i ShellStorage-exemplet i Windows SDK.

Stöd för dra och släpp-åtgärder i ett bibliotek

Om programmet stöder drag-och-släpp-åtgärder bör de uppdateras för att stödja rätt biblioteksinteraktion. Om en fil släpps till ett bibliotek ska den borttagna filen sparas på standardplatsen för sparande. Om en mapp släpps till ett bibliotek ska den borttagna mappen läggas till som en ny mapp i biblioteket. Om en fil släpps till en befintlig mapp som inte är standardplatsen för sparande ska filen läggas till i den valda mappen.

Exempel på hur du lägger till biblioteksstöd för dina program dra och släpp-funktioner finns i exemplet ShellLibraryCommandLine i Windows SDK.

Hålla sig synkroniserad med ett bibliotek

Det här avsnittet beskriver hur ett program kan behålla sin vy över ett biblioteks innehåll up-to-date.

Massuppdatering

Eftersom användaren kan ändra mapparna i ett bibliotek interaktivt när programmet inte körs bör programmet anropa SHResolveLibrary när det börjar identifiera och lagra ändringar i biblioteket. Shell-API:et tillhandahåller funktionen SHResolveLibrary för att aktivera ett program för att hämta det aktuella innehållet i ett bibliotek och de aktuella platserna för alla mappar som biblioteket kan innehålla.

Observera att SHResolveLibrary är en blockerande funktion som kan ta lång tid att returnera beroende på vad som har ändrats i biblioteket. Därför bör den inte anropas från en användargränssnittstråd.

När programmet har tagits up-to-date kan det sedan registrera sig för ändringsmeddelanden för att upprätthålla en aktuell vy.

Shell API-meddelande

Windows Shell-API:et tillhandahåller funktionen SHChangeNotifyRegister, vilket är det bästa sättet för icke-tjänstprocesser att meddelas om en ändring i biblioteket.

Om du vill identifiera ändringar i objekt i ett bibliotek med hjälp av Windows Shell-API:et anropar du SHChangeNotifyRegister för att registrera programmet för meddelanden om ändringar i objekt i en biblioteksmapp. Den här funktionen kan meddela ditt program om det sker en ändring i något bibliotek eller bara i ett specifikt bibliotek. Meddelanden skickas omedelbart när ett bibliotek ändras.

Api-meddelande för filsystem

Filsystemmeddelanden måste användas i tjänstprocesser.

Om du vill identifiera ändringar av objekt i ett bibliotek med hjälp av filsystem-API:et räknar du upp mapparna i biblioteket och anropar FindFirstChangeNotification för varje mapp att övervaka. Programmet får ett meddelande när en övervakad mapp ändras. Om du vill hitta den specifika fil med filer som har ändrats i mappen anropar du ReadDirectoryChangesW. Om du vill identifiera ändringar i biblioteksbeskrivningsfilen övervakar du mappen som innehåller den. Du hittar biblioteksbeskrivningsfilen i mappen FOLDERID_Libraries. Biblioteksbeskrivningsfilen bör dock inte öppnas eller ändras.

Om bibliotek

IShellLibrary

Shell-länkar

kända mappar

Schema för beskrivning av bibliotek

IID_PPV_ARGS

 

 

  • Last updated on