Implementera grundläggande mappobjektgränssnitt

Proceduren för att implementera ett namnområdestillägg liknar det för alla andra com-objekt (Component Object Model) i processen. Alla tillägg måste ha stöd för tre primära gränssnitt som ger Utforskaren den grundläggande information som krävs för att visa tilläggets mappar i trädvyn. Men om du vill använda funktionerna i Utforskaren fullt ut måste tillägget också exponera ett eller flera valfria gränssnitt som stöder mer avancerade funktioner, till exempel snabbmenyer eller dra och släpp, och tillhandahålla en mappvy.

I det här dokumentet beskrivs hur du implementerar de primära och valfria gränssnitt som Utforskaren anropar för information om innehållet i tillägget. En diskussion om hur du implementerar en mappvy och hur du anpassar Utforskaren finns i Implementera en mappvy.

• Grundläggande implementering och registrering
  • Registrering av ett tillägg
• Hantering av PIDL:er
  • Skapa en SHITEMID-struktur
  • Konstruera en PIDL
  • Tolkning av PIDL:er
• Implementera de primära gränssnitten
  • IPersistFolder Interface
  • IShellFolder-gränssnitt
  • IEnumIDList Interface
• Implementera valfria gränssnitt
  • IExtractIcon
  • IContextMenu
  • IQueryInfo
  • IDataObject och IDropTarget
• arbeta med implementeringen av standardgränssnittsmappvyn

Grundläggande implementering och registrering

Som en processbaserad COM-server måste DLL-filen exponera flera standardfunktioner och gränssnitt:

• DllCanUnloadNow
• DllGetClassObject
• IClassFactory
• IUnknown

Dessa funktioner och gränssnitt implementeras på samma sätt som för de flesta andra COM-objekt. Mer information finns i COM-dokumentationen.

Registrera ett tillägg

Precis som med alla COM-objekt måste du skapa ett klassidentifierare (CLSID) GUID för din förlängning. Registrera objektet genom att skapa en undernyckel för HKEY_CLASSES_ROOT\CLSID- med namnet för CLSID för tillägget. DLL-filen ska registreras som en in-process-server och ska ange lägenhetstrådsmodellen. Du kan anpassa beteendet för ett tilläggs rotmapp genom att lägga till en mängd olika undernycklar och värden i tilläggets CLSID-nyckel.

Flera av dessa värden gäller endast för tillägg med virtuella knutpunkter. Dessa värden gäller inte för tillägg vars knutpunkter är filsystemmappar. Mer information finns i Ange ett namnområdestilläggs plats. Om du vill ändra beteendet för ett tillägg med en virtuell knutpunkt lägger du till ett eller flera av följande värden i tilläggets CLSID-nyckel:

• Vill FORPARSING. Parsningsnamnet för ett tillägg med en virtuell knutpunkt har normalt formuläret ::{GUID}. Tillägg av den här typen innehåller normalt virtuella objekt. Vissa tillägg, till exempel Mina dokument, motsvarar dock i själva verket filsystemmappar, även om de har virtuella knutpunkter. Om tillägget representerar filsystemobjekt på det här sättet kan du ange värdet WantsFORPARSING. Utforskaren begär sedan rotmappens parsningsnamn genom att anropa mappobjektets IShellFolder::GetDisplayNameOf metod med uFlags inställd på SHGDN_FORPARSING och pidl inställd på en enda tom pekare till en objektidentifierarlista (PIDL). En tom PIDL innehåller bara en terminator. Metoden bör sedan returnera rotmappens ::{GUID} parsningsnamn.
• HideFolderVerbs. Verben som registreras under HKEY_CLASSES_ROOT\Mapp associeras normalt med alla tillägg. De visas på tilläggets snabbmeny och kan anropas av ShellExecute. Om du vill förhindra att något av dessa verb associeras med tillägget anger du värdet HideFolderVerbs.
• HideAsDelete. Om en användare försöker ta bort tillägget döljer Utforskaren i stället tillägget.
• HideAsDeletePerUser. Det här värdet har samma effekt som HideAsDelete men per användare. Tillägget är endast dolt för de användare som har försökt ta bort det. Tillägget är synligt för alla andra användare.
• QueryForOverlay. Ange det här värdet för att ange att rotmappens ikon kan ha ett ikonöverlägg. Mappobjektet måste ha stöd för gränssnittet IShellIconOverlay. Innan Windows Explorer visar rotmappens ikon begär den en överläggsikon genom att anropa en av de två IShellIconOverlay- metoder med pidlItem inställd på en tom PIDL.

Återstående värden och undernycklar gäller för alla tillägg:

• Om du vill ange visningsnamnet för tilläggets kopplingspunktsmapp anger du standardvärdet för tilläggets CLSID-undernyckel till en lämplig sträng.
• När markören hovrar över en mapp visas vanligtvis en infotip som beskriver innehållet i mappen. Om du vill ange en infotip för tilläggets rotmapp skapar du ett InfoTip-REG_SZ värde för tilläggets CLSID-nyckel och anger den till en lämplig sträng.
• Om du vill ange en anpassad ikon för tilläggets rotmapp skapar du en undernyckel för tilläggets CLSID-undernyckel med namnet DefaultIcon. Ange standardvärdet för DefaultIcon till ett REG_SZ värde som innehåller namnet på filen som innehåller ikonen, följt av ett kommatecken följt av ett minustecken följt av indexet för ikonen i filen.
• Som standard innehåller snabbmenyn i tilläggets rotmapp de objekt som definierats under HKEY_CLASSES_ROOT\Folder. Objekten Delete, Renameoch Properties läggs till om du har angett lämpliga SFGAO_XXX flaggor. Du kan lägga till andra objekt i rotmappens snabbmeny eller åsidosätta befintliga objekt, ungefär som för en filtyp. Skapa en undernyckel Shell under tilläggets CLSID-nyckel och definiera kommandon som beskrivs i Utöka snabbmenyerna.
• Om du behöver ett mer flexibelt sätt att hantera rotmappens snabbmeny kan du implementera en snabbmenyhanterare. Om du vill registrera snabbmenyhanteraren skapar du en ShellEx- nyckel under tilläggets CLSID-nyckel. Registrera hanterarens CLSID som du skulle göra för en konventionell Skapa gränssnittstilläggshanterare.
• Om du vill lägga till en sida i rotmappens egenskapsblad Egenskaper ger du mappen attributet SFGAO_HASPROPSHEET och implementerar en egenskapsbladshanterare. Om du vill registrera egenskapsbladets hanterare skapar du en ShellEx- nyckel under tilläggets CLSID-nyckel. Registrera hanterarens CLSID som du skulle göra för en konventionell Skapa gränssnittstilläggshanterare.
• Om du vill ange attributen för rotmappen lägger du till en ShellFolder undernyckel i tilläggets CLSID-undernyckel. Skapa ett attributvärde och ange det till lämplig kombination av SFGAO_XXX flaggor.

I följande tabell visas några vanliga attribut för rotmappar.

Flagga	Värde	Beskrivning
SFGAO_FOLDER	0x20000000	Tilläggets rotmapp innehåller ett eller flera objekt.
SFGAO_HASSUBFOLDER	0x80000000	Tilläggets rotmapp innehåller en eller flera undermappar. Utforskaren placerar ett plustecken ( + ) bredvid mappikonen.
SFGAO_CANDELETE	0x00000020	Tilläggets rotmapp kan tas bort av användaren. Mappens snabbmeny har ett Ta bort objekt. Den här flaggan ska anges för knutpunkter som placeras under någon av de virtuella mapparna.
SFGAO_CANRENAME	0x00000010	Rotmappen för tillägget kan döpas om av användaren. Mappens snabbmeny har ett Byt namn alternativ.
SFGAO_HASPROPSHEET	0x00000040	Tilläggets rotmapp har ett egenskapsblad för Egenskaper. Mappens snabbmeny har ett Egenskaper objekt. Om du vill ange egenskapsbladet måste du implementera en egenskapsbladshanterare. Registrera hanteraren under tilläggets CLSID-nyckel, enligt beskrivningen tidigare.

 

I följande exempel visas CLSID-registerposten för ett tillägg med visningsnamnet MyExtension. Tillägget har en anpassad ikon som finns i tilläggets DLL med indexet 1. Attributen SFGAO_FOLDER, SFGAO_HASSUBFOLDERoch SFGAO_CANDELETE anges.

HKEY_CLASSES_ROOT
   CLSID
      {Extension CLSID}
         (Default) = MyExtension
         InfoTip = Some appropriate text
      DefaultIcon
         (Default) = c:\MyDir\MyExtension.dll,-1
      InProcServer32
         (Default) = c:\MyDir\MyExtension.dll
         ThreadingModel = Apartment
      ShellFolder
         Attributes = 0xA00000020

Hantera PIDL:er

Varje objekt i Shell-namnområdet måste ha en unik PIDL. Utforskaren tilldelar en PIDL till rotmappen och skickar värdet till tillägget under initieringen. Tillägget ansvarar sedan för att tilldela en korrekt konstruerad PIDL till vart och ett av dess objekt och tillhandahålla dessa PIDL:er till Windows Utforskaren på begäran. När gränssnittet använder en PIDL för att identifiera ett av tilläggets objekt måste tillägget kunna tolka PIDL och identifiera det specifika objektet. Tillägget måste också tilldela ett visningsnamn och ett parsningsnamn till varje objekt. Eftersom PIDL:er används av praktiskt taget alla mappgränssnitt implementerar tillägg ofta en enda PIDL-hanterare för att hantera alla dessa uppgifter.

Termen PIDL är kort för en ITEMIDLIST struktur eller en pekare till en sådan struktur, beroende på kontext. Som deklarerat har en ITEMIDLIST--struktur endast en medlem, en SHITEMID--struktur. Ett objekts ITEMIDLIST- struktur är faktiskt en packad matris med två eller flera SHITEMID- strukturer. Ordningen på dessa strukturer definierar en sökväg genom namnområdet, på ungefär samma sätt som c:\MyDirectory\MyFile definierar en sökväg genom filsystemet. Vanligtvis består ett objekts PIDL av en serie SHITEMID- strukturer som motsvarar mapparna som definierar namnområdessökvägen, följt av objektets SHITEMID- struktur följt av en terminator.

Terminatorn är en SHITEMID--struktur, med medlemmen cb inställd på NULL-. Terminatorn är nödvändig eftersom antalet SHITEMID- strukturer i ett objekts PIDL beror på objektets plats i Shell-namnområdet och sökvägens startpunkt. Dessutom kan storleken på de olika SHITEMID- strukturerna variera. När du får en PIDL har du inget enkelt sätt att fastställa dess storlek eller ens det totala antalet SHITEMID- strukturer. I stället måste du "gå" den packade matrisen, struktur för struktur, tills du når terminatorn.

För att skapa en PIDL måste programmet:

1. Skapa en SHITEMID- struktur för vart och ett av dess objekt.
2. Sätt samman de relevanta SHITEMID- strukturerna till en PIDL.

Skapa en SHITEMID-struktur

Ett objekts SHITEMID- struktur identifierar unikt objektet i mappen. Faktum är att en typ av PIDL som används av många av IShellFolder metoder består av bara objektets SHITEMID- struktur, följt av en terminator. Definitionen av en SHITEMID- struktur är:

typedef struct _SHITEMID { 
    USHORT cb; 
    BYTE   abID[1]; 
} SHITEMID, * LPSHITEMID;

abID- medlem är objektets identifierare. Eftersom längden på abID inte har definierats och kan variera, anges cb medlem till storleken på SHITEMID struktur i byte.

Eftersom varken längden eller innehållet i abID är standardiserat kan du använda valfritt schema som du vill tilldela abID värden till dina objekt. Det enda kravet är att du inte kan ha två objekt i samma mapp med identiska värden. Men av prestandaskäl bör din SHITEMID--struktur vara DWORD--justerad. Med andra ord bör du skapa dina abID- värden så att cb är en integrerad multipel av 4.

Vanligtvis pekar abID på en tilläggsdefinierad struktur. Förutom objektets ID används den här strukturen ofta för att lagra en mängd relaterad information, till exempel objektets typ eller attribut. Tilläggets mapparnas objekt kan sedan snabbt extrahera informationen från PIDL istället för att behöva hämta den.

Not

En av de viktigaste aspekterna av att utforma en datastruktur för en PIDL är att göra strukturen bestående och transportabel. I kontexten av PIDL:er är innebörden av dessa termer:

• Kan sparas. Systemet placerar ofta PIDL:er i olika typer av långtidslagring, till exempel genvägsfiler. Den kan sedan återställa dessa PIDL:er från lagring senare, eventuellt efter att systemet har startats om. En PIDL som har återställts från lagringen måste fortfarande vara giltig och meningsfull för tilläggsprogrammet. Det här kravet innebär till exempel att du inte ska använda pekare eller handtag i din PIDL-struktur. PIDL:er som innehåller den här typen av data är normalt meningslösa när systemet senare återställer dem från lagringen.
• Transporterbar. En PIDL måste förbli meningsfull när den transporteras från en dator till en annan. En PIDL kan till exempel skrivas till en genvägsfil, kopieras till en diskett och transporteras till en annan dator. Denna PIDL bör fortfarande vara meningsfull för ditt tillägg som körs på den andra datorn. Om du till exempel vill se till att dina PIDL:er kan transporteras använder du antingen ANSI- eller Unicode-tecken explicit. Undvik datatyper som TCHAR- eller LPTSTR-. Om du använder dessa datatyper kan en PIDL som skapats på en dator som kör en Unicode-version av tillägget inte läsas av en ANSI-version av tillägget som körs på en annan dator.

 

Följande deklaration visar ett enkelt exempel på en datastruktur.

typedef struct tagMYPIDLDATA {
  USHORT cb;
  DWORD dwType;
  WCHAR wszDisplayName[40];
} MYPIDLDATA, *LPMYPIDLDATA;

Den medlemmen cb är inställd till storleken på strukturen MYPIDLDATA. Den här medlemmen gör MYPIDLDATA till en giltig SHITEMID-struktur i sig självt. Resten av medlemmarna motsvarar abID medlemmar av en SHITEMID--struktur och lagrar privat data. dwType- medlem är ett tilläggsdefinierat värde som anger typen av objekt. I det här exemplet är dwType inställt på TRUE- för mappar och FALSE- annars. Med den här medlemmen kan du till exempel snabbt avgöra om objektet är en mapp eller inte. wszDisplayName medlem innehåller objektets visningsnamn. Eftersom du inte skulle tilldela samma visningsnamn till två olika objekt i samma mapp fungerar visningsnamnet även som objekt-ID. I det här exemplet är wszDisplayName inställt på 40 tecken för att garantera att strukturen SHITEMID kommer att justeras till DWORD. Om du vill begränsa storleken på dina PIDL:er kan du i stället använda en teckenmatris med variabel längd och justera värdet för cb i enlighet med detta. Fyll ut visningssträngen med tillräckligt med '\0' tecken för att behålla strukturens DWORD alineation. Andra medlemmar som kan vara användbara för att placera i strukturen är objektets storlek, attribut eller parsningsnamn.

Konstruera en PIDL

När du har definierat SHITEMID- strukturer för dina objekt kan du sedan använda dem för att skapa en PIDL. PIDL:er kan konstrueras för olika syften, men de flesta uppgifter använder en av två typer av PIDL. Det enklaste, en PIDL på en nivå, identifierar objektet i förhållande till den överordnade mappen. Den här typen av PIDL används av många av de IShellFolder- metoderna. En PIDL på en nivå innehåller objektets SHITEMID- struktur, följt av en terminator. En fullständigt kvalificerad PIDL definierar en sökväg genom namnområdeshierarkin från skrivbordet till objektet. Den här typen av PIDL börjar på skrivbordet och innehåller en SHITEMID-struktur för varje mapp i sökvägen, vilket följs av objektet och avslutaren. En fullständigt kvalificerad PIDL identifierar unikt objektet i hela Shell-namnområdet.

Det enklaste sättet att konstruera en PIDL är att arbeta direkt med strukturen ITEMIDLIST. Skapa en ITEMIDLIST- struktur, men allokera tillräckligt med minne för att lagra alla SHITEMID- strukturer. Adressen till den här strukturen pekar på den initiala SHITEMID-strukturen. Definiera värden för medlemmarna i den här ursprungliga strukturen och lägg sedan till så många ytterligare SHITEMID- strukturer som du behöver, i rätt ordning. Följande procedur beskriver hur du skapar en PIDL på en nivå. Den innehåller två SHITEMID- strukturer – en MYPIDLDATA- struktur följt av en terminator:

1. Använd funktionen CoTaskMemAlloc för att allokera minne för PIDL. Allokera tillräckligt med minne för dina privata data plus en USHORT- (två byte) för terminatorn. Omvandla resultatet till LPMYPIDLDATA.
2. Ange cb-medlemmen av den första MYPIDLDATA--strukturen till storleken av den strukturen. I det här exemplet anger du cb till sizeof(MYPIDLDATA). Om du vill använda en struktur med variabel längd måste du beräkna värdet för cb.
3. Tilldela lämpliga värden till de privata datamedlemmarna.
4. Beräkna adressen för nästa SHITEMID- struktur. Omvandla adressen för den aktuella MYPIDLDATA-strukturen till LPBYTE och lägg till värdet för cb som fastställs i steg 3.
5. I det här fallet är nästa struktur SHITEMID terminatorn. Ställ in strukturens cb medlem till noll.

För längre PIDL:er allokerar du tillräckligt med minne och upprepar steg 3–5 för varje ytterligare SHITEMID- struktur.

Följande exempelfunktion tar ett objekts typ och visningsnamn och returnerar objektets PIDL på en nivå. Funktionen förutsätter att visningsnamnet, inklusive dess avslutande null- tecken, inte överskrider det antal tecken som deklarerats för MYPIDLDATA- struktur. Om det antagandet visar sig vara felaktigt trunkerar funktionen StringCbCopyW visningsnamnet. Variabeln g_pMalloc är en IMalloc- pekare som skapats någon annanstans och lagras i en global variabel.

LPITEMIDLIST CreatePIDL(DWORD dwType, LPCWSTR pwszDisplayName)
{
    LPMYPIDLDATA   pidlOut;
    USHORT         uSize;

    pidlOut = NULL;

    //Calculate the size of the MYPIDLDATA structure.
    uSize = sizeof(MYPIDLDATA);

    // Allocate enough memory for the PIDL to hold a MYPIDLDATA structure 
    // plus the terminator
    pidlOut = (LPMYPIDLDATA)m_pMalloc->Alloc(uSize + sizeof(USHORT));

    if(pidlOut)
    {
       //Assign values to the members of the MYPIDLDATA structure
       //that is the PIDL's first SHITEMID structure
       pidlOut->cb = uSize;
       pidlOut->dwType = dwType;
       hr = StringCbCopyW(pidlOut->wszDisplayName, 
                          sizeof(pidlOut->wszDisplayName), pwszDisplayName);
       
       // TODO: Add error handling here to verify the HRESULT returned 
       // by StringCbCopyW.

       //Advance the pointer to the start of the next SHITEMID structure.
       pidlOut = (LPMYPIDLDATA)((LPBYTE)pidlOut + pidlOut->cb);

       //Create the terminating null character by setting cb to 0.
       pidlOut->cb = 0;
    }

    return pidlOut;

En fullständigt kvalificerad PIDL måste ha SHITEMID strukturer för varje objekt från skrivbordet till ditt objekt. Tillägget får en fullständigt kvalificerad PIDL för rotmappen när Shell kallar IPersistFolder::Initialize. Om du vill skapa en fullständigt kvalificerad PIDL för ett objekt tar du den PIDL som Shell har tilldelat till rotmappen och lägger till SHITEMID--strukturer, som behövs för att ta dig från rotmappen till objektet.

Interpretera PIDL:er

När Shell eller ett program anropar ett av tilläggets gränssnitt för att begära information om ett objekt identifieras vanligtvis objektet av en PIDL. Vissa metoder, till exempel IShellFolder::GetUIObjectOf, använder PIDL:er som är relativa till den överordnade mappen och är enkla att tolka. Tillägget kommer dock förmodligen också att få fullständigt kvalificerade PIDLs. Din PIDL-chef måste sedan avgöra vilka av dina objekt som PIDL refererar till.

Det som komplicerar uppgiften att associera ett objekt med en fullständigt kvalificerad PIDL är att en eller flera av de inledande SHITEMID- strukturer i PIDL kan tillhöra objekt som ligger utanför tillägget i Shell-namnområdet. Du kan inte tolka innebörden av abID medlem i dessa strukturer. Vad tillägget måste göra är att "gå" listan över SHITEMID strukturer tills du når den struktur som motsvarar rotmappen. Från och med då vet du hur du tolkar informationen i SHITEMID- strukturer.

För att iterera PIDL:en tar du det första värdet cb och lägger till det i PIDL-adressen för att flytta pekaren till början av nästa SHITEMID--struktur. Det kommer sedan att peka på medlemmen cb i den strukturen, som du kan använda för att flytta pekaren vidare till början av nästa SHITEMID struktur och så vidare. Varje gång du går vidare med pekaren undersöker du SHITEMID- struktur för att avgöra om du har nått roten för tilläggets namnområde.

Implementera de primära gränssnitten

Precis som med alla COM-objekt handlar implementeringen av ett tillägg till stor del om att implementera en samling gränssnitt. I det här avsnittet beskrivs de tre primära gränssnitt som måste implementeras av alla tillägg. De används för initiering och för att ge Utforskaren grundläggande information om innehållet i tillägget. Dessa gränssnitt, plus en mappvy, är allt som krävs för ett funktionellt tillägg. Men för att fullt ut utnyttja funktionerna i Utforskaren implementerar de flesta tillägg också ett eller flera av de valfria gränssnitten.

IPersistFolder-gränssnitt

Gränssnittet IPersistFolder anropas för att initiera ett nytt mappobjekt. Metoden IPersistFolder::Initiera tilldelar ett fullständigt kvalificerat PIDL till det nya objektet. Lagra denna PIDL för senare användning. Ett mappobjekt måste till exempel använda den här PIDL:en för att skapa fullständigt kvalificerade PIDL:er för objektets underordnade objekt. Mappobjektets skapare kan också anropa IPersist::GetClassID för att begära objektets CLSID.

Vanligtvis skapas och initieras ett mappobjekt av den överordnade mappens IShellFolder::BindToObject-metod. Men när en användare bläddrar till tillägget skapar och initierar Utforskaren tilläggets rotmappsobjekt. Den PIDL som rotmappsobjektet tar emot via IPersistFolder::Initialize innehåller sökvägen från skrivbordet till rotmappen som du behöver för att konstruera fullständigt kvalificerade PIDLs för tillägget.

IShellFolder-gränssnitt

Shell behandlar ett tillägg som en hierarkiskt ordnad samling mappobjekt. Gränssnittet IShellFolder är kärnan i alla tilläggsimplementering. Det representerar ett mappobjekt och ger Utforskaren mycket av den information som behövs för att visa innehållet i mappen.

IShellFolder är vanligtvis det enda mappgränssnittet förutom IPersistFolder som exponeras direkt av ett mappobjekt. Utforskaren använder en mängd olika obligatoriska och valfria gränssnitt för att hämta information om innehållet i mappen, men den hämtar pekare till dessa gränssnitt via IShellFolder.

Windows Explorer hämtar CLSID för tilläggets rotmapp på flera olika sätt. Mer information finns i Ange ett namnområdestilläggs plats eller Visa en Self-Contained vy över ett namnområdestillägg. Windows Utforskaren använder sedan den CLSID för att skapa och initiera en instans av rotmappen och fråga efter ett IShellFolder--gränssnitt. Tillägget skapar ett mappobjekt som representerar rotmappen och returnerar objektets IShellFolder- gränssnitt. Mycket av resten av interaktionen mellan tillägget och Utforskaren sker sedan via IShellFolder-. Utforskaren anropar IShellFolder till:

• Begär ett objekt som kan räkna upp innehållet i rotmappen.
• Hämta olika typer av information om innehållet i rotmappen.
• Begär ett objekt som exponerar ett av de valfria gränssnitten. Dessa gränssnitt kan sedan efterfrågas för ytterligare information, till exempel ikoner eller snabbmenyer.
• Begär ett mappobjekt som representerar en undermapp i rotmappen.

När en användare öppnar en undermapp i rotmappen anropar Utforskaren IShellFolder::BindToObject. Tillägget skapar och initierar ett nytt mappobjekt som representerar undermappen och returnerar dess IShellFolder- gränssnitt. Utforskaren anropar sedan det här gränssnittet för olika typer av information och så vidare tills användaren bestämmer sig för att navigera någon annanstans i Shell-namnområdet eller stänga Utforskaren.

I resten av det här avsnittet beskrivs kortfattat de viktigaste IShellFolder metoder och hur du implementerar dem.

EnumObjects

Innan innehållet i en mapp visas i trädvyn måste Utforskaren först fastställa vad mappen innehåller genom att anropa metoden IShellFolder::EnumObjects. Den här metoden skapar ett OLE-standarduppräkningsobjekt som exponerar ett IEnumIDList--gränssnitt och returnerar den gränssnittspekaren. Gränssnittet IEnumIDList gör att Utforskaren kan hämta PIDL:er för alla objekt som finns i mappen. Dessa PIDL:er används sedan för att hämta information om objekten som finns i mappen. Mer information finns i IEnumIDList Interface.

Obs

Metoden IEnumIDList::Next ska endast returnera PIDL:er som är relativt till den överordnade mappen. PIDL ska endast innehålla objektets SHITEMID- struktur, följt av en terminator.

 

CreateViewObject

Innan innehållet i en mapp visas anropar Utforskaren den här metoden för att begära en pekare till ett IShellView--gränssnitt. Det här gränssnittet används av Utforskaren för att hantera mappvyn. Skapa ett mappvyobjekt och returnera dess IShellView--gränssnitt.

Metoden IShellFolder::CreateViewObject anropas också för att begära ett av de valfria gränssnitten, till exempel IContextMenu, för själva mappen. Implementeringen av den här metoden bör skapa ett objekt som exponerar det begärda gränssnittet och returnerar gränssnittspekaren. Om Utforskaren behöver ett valfritt gränssnitt för ett av objekten som finns i mappen anropas IShellFolder::GetUIObjectOf.

GetUIObjectOf

Även om grundläggande information om innehållet i en mapp är tillgänglig via IShellFolder- metoder, kan tillägget även ge Utforskaren olika typer av ytterligare information. Du kan till exempel ange ikoner för innehållet i en mapp eller ett objekts snabbmeny. Utforskaren anropar metoden IShellFolder::GetUIObjectOf för att försöka hämta ytterligare information om ett objekt som finns i en mapp. Utforskaren i Windows anger vilket objekt som den vill ha information för och IID för det relevanta gränssnittet. Mappobjektet skapar sedan ett objekt som exponerar det begärda gränssnittet och returnerar gränssnittspekaren.

Om tillägget tillåter användare att överföra objekt med dra och släppa eller urklipp, kommer Utforskaren att anropa IShellFolder::GetUIObjectOf för att begära ett IDataObject-- eller IDropTarget--gränssnitt. Mer information finns i Överföring av skalobjekt med "drag och släpp" och Urklippet.

Utforskaren anropar IShellFolder::CreateViewObject när den vill ha samma typ av information om själva mappen.

BindToObject

Utforskaren anropar metoden IShellFolder::BindToObject när en användare försöker öppna en av tilläggets undermappar. Om riid är inställt på IID_IShellFolder bör du skapa och initiera ett mappobjekt som representerar undermappen och returnera objektets IShellFolder--gränssnitt.

Notera

För närvarande anropar Utforskaren endast den här metoden för att begära ett IShellFolder--gränssnitt. Anta dock inte att detta alltid kommer att vara fallet. Du bör alltid kontrollera värdet för riid innan du fortsätter.

 

GetDisplayNameOf

Utforskaren anropar metoden IShellFolder::GetDisplayNameOf för att konvertera PIDL för ett av mappens objekt till ett namn. PIDL måste vara relativ till objektets överordnade mapp. Med andra ord måste den innehålla en enda icke-NULL-SHITEMID- struktur. Eftersom det finns fler än ett möjligt sätt att namnge objekt anger Utforskaren typen av namn genom att ange en eller flera SHGDNF- flaggor i uFlags parameter. Ett av två värden, SHGDN_NORMAL eller SHGDN_INFOLDER, anges för att ange om namnet ska vara relativt till mappen eller i förhållande till skrivbordet. Ett av de andra tre värdena, SHGDN_FOREDITING, SHGDN_FORADDRESSBAReller SHGDN_FORPARSING, kan anges för att ange vilket namn som ska användas.

Du måste returnera namnet i form av en STRRET- struktur. Om SHGDN_FOREDITING, SHGDN_FORADDRESSBARoch SHGDN_FORPARSING inte har angetts returnerar du objektets visningsnamn. Om flaggan SHGDN_FORPARSING har angetts begär Utforskaren ett parsningsnamn. Parsningsnamn skickas till IShellFolder::ParseDisplayName för att hämta ett objekts PIDL, även om det kan finnas en eller flera nivåer under den aktuella mappen i namnområdeshierarkin. Till exempel är parsningsnamnet för ett filsystemobjekt dess sökväg. Du kan skicka den fullständigt kvalificerade sökvägen för alla objekt i filsystemet till skrivbordet IShellFolder::ParseDisplayName-metoden, och det returnerar objektets fullständigt kvalificerade PIDL.

Även om parsningsnamn är textsträngar behöver de inte nödvändigtvis inkludera visningsnamnet. Du bör tilldela parsningsnamn baserat på vad som fungerar mest effektivt när IShellFolder::P arseDisplayName anropas. Till exempel är många av Shells virtuella mappar inte en del av filsystemet och har ingen fullständigt kvalificerad sökväg. I stället tilldelas varje mapp ett GUID och parsningsnamnet får formatet ::{GUID}. Oavsett vilket schema du använder bör det kunna "tur och retur på ett tillförlitligt sätt". Om en anropare till exempel skickar ett parsningsnamn till IShellFolder::P arseDisplayName för att hämta ett objekts PIDL och sedan skickar pidl-filen till IShellFolder::GetDisplayNameOf med SHGDN_FORPARSING flagguppsättning, bör anroparen återställa det ursprungliga parsningsnamnet.

GetAttributesOf

Utforskaren anropar metoden IShellFolder::GetAttributesOf för att fastställa attributen för ett eller flera objekt som finns i ett mappobjekt. Värdet för cidl ger antalet objekt i frågan och aPidl- pekar på en lista över deras PIDL:er.

Eftersom det kan ta lång tid att testa vissa attribut begränsar Utforskaren vanligtvis frågan till en delmängd av de tillgängliga flaggorna genom att ange deras värden i rfgInOut-. Metoden bör bara testa för de attribut vars flaggor anges i rfgInOut-. Lämna de giltiga flaggorna oförändrade och rensa resten. Om fler än ett objekt ingår i frågan anger du endast de flaggor som gäller för alla objekt.

Not

Attributen måste vara korrekt inställda för att ett objekt ska visas korrekt. Om ett objekt till exempel är en mapp som innehåller undermappar måste du ange flaggan SFGAO_HASSUBFOLDER. Annars visar Utforskaren inte ett + bredvid objektets ikon i trädvyn.

 

ParseDisplayName

Metoden IShellFolder::ParseDisplayName är i någon mening en spegelbild av IShellFolder::GetDisplayNameOf. Den vanligaste användningen av den här metoden är att konvertera ett objekts parsningsnamn till den associerade PIDL:en. Parsningsnamnet kan referera till alla objekt som ligger under mappen i namnområdeshierarkin. Den returnerade PIDL:en är relativ till det mappobjekt som exponerar metoden och är vanligtvis inte fullständigt kvalificerad. Pidl kan med andra ord innehålla flera SHITEMID- strukturer, men den första är antingen själva objektets eller den första undermappen i sökvägen från mappen till objektet. Anroparen måste lägga till denna PIDL i mappens fullständigt kvalificerade PIDL för att få en fullständigt kvalificerad PIDL för objektet.

IShellFolder::ParseDisplayName kan också anropas för att begära ett objekts attribut. Eftersom det kan ta lång tid att fastställa alla tillämpliga attribut anger anroparen endast de SFGAO_XXX flaggor som representerar information som anroparen är intresserad av. Du bör ta reda på vilka av dessa attribut som är sanna för objektet och avmarkera de återstående flaggorna.

IEnumIDList-gränssnitt

När Utforskaren behöver räkna upp de objekt som finns i en mapp anropas IShellFolder::EnumObjects. Mappobjektet måste skapa ett uppräkningsobjekt som exponerar gränssnittet IEnumIDList och returnera den gränssnittspekaren. Utforskaren använder vanligtvis IEnumIDList- för att räkna upp PIDL:er för alla objekt som finns i mappen.

IEnumIDList är ett standardgränssnitt för OLE-uppräkning och implementeras på vanligt sätt. Kom ihåg dock, att de PIDL:er som du returnerar måste vara relativa till mappen och endast innehålla objektets SHITEMID- struktur och en terminator.

Implementera de valfria gränssnitten

Det finns ett antal valfria Shell-gränssnitt som filnamnstilläggets mappobjekt kan stödja. Många av dem, till exempel IExtractIcon, gör att du kan anpassa olika aspekter av hur användaren visar tillägget. Andra, till exempel IDataObject, tillåter att tillägget stöder funktioner som dra och släpp.

Inget av de valfria gränssnitten exponeras direkt av ett mappobjekt. I stället anropar Utforskaren någon av två IShellFolder- metoder för att begära ett gränssnitt:

• Utforskaren anropar ett mappobjekts IShellFolder::GetUIObjectOf för att begära ett gränssnitt för ett av objekten som finns i mappen.
• Utforskaren anropar ett mappobjekts IShellFolder::CreateViewObject för att begära ett gränssnitt för själva mappen.

För att tillhandahålla informationen skapar mappobjektet ett objekt som exponerar det begärda gränssnittet och returnerar gränssnittspekaren. Utforskaren anropar sedan gränssnittet för att hämta nödvändig information. I det här avsnittet beskrivs de vanligaste valfria gränssnitten.

IExtractIcon

Utforskaren begär ett IExtractIcon--gränssnitt innan innehållet i en mapp visas. Med gränssnittet kan tillägget ange anpassade ikoner för de objekt som finns i mappen. Annars används standardikonerna för filer och mappar. Om du vill ange en anpassad ikon skapar du ett ikonextraheringsobjekt som exponerar IExtractIcon- och returnerar en pekare till gränssnittet. För vidare diskussion, hänvisa till referensdokumentationen IExtractIcon eller Skapa ikonhanterare.

IContextMenu

När en användare högerklickar på ett objekt begär Utforskaren ett IContextMenu- gränssnitt. Om du vill tillhandahålla snabbmenyer för dina objekt skapar du ett menyhanterarobjekt och returnerar dess IContextMenu--gränssnitt.

Procedurerna för att skapa ett menyhanterarobjekt liknar dem som används för att skapa ett shell-tillägg för menyhanterare. Mer information finns i Skapa kontextmenyhanterare eller IContextMenu, IContextMenu2eller IContextMenu3 referens.

IQueryInfo

Utforskaren anropar IQueryInfo-gränssnittet för att hämta en textsträng för infotip.

IDataObject och IDropTarget

När dina objekt visas av Windows Utforskaren har en mappobjekt inget direkt sätt att veta när en användare försöker klippa ut, kopiera eller dra ett objekt. I stället begär Utforskaren ett IDataObject--gränssnitt. Om du vill tillåta att objektet överförs skapar du ett dataobjekt och returnerar en pekare till dess IDataObject--gränssnitt.

På samma sätt kan en användare försöka släppa ett dataobjekt i en Windows Explorer-representation av ett av dina objekt, till exempel en ikon eller en sökväg till adressfältet. Utforskaren begär sedan ett IDropTarget- gränssnitt. Om du vill tillåta att dataobjektet tas bort skapar du ett objekt som exponerar ett IDropTarget--gränssnitt och returnerar gränssnittspekaren.

Hantering av dataöverföring är en av de svårare aspekterna av att skriva namnområdestillägg. En detaljerad diskussion finns i Överföra gränssnittsobjekt med dra och släpp och Urklipp.

Arbeta med standardimplementeringen av shell-mappens förvalda vy

Datakällor som använder standardgränssnittets mappvyobjekt (DefView) måste implementera följande gränssnitt:

• IShellFolder
• IShellFolder2
• IPersistFolder
• IPersistFolder2

Alternativt kan de även implementera IPersistFolder3.