Informatie ophalen over de inhoud van een map

In de sectie Map-id ophalen worden twee benaderingen besproken voor het verkrijgen van een verwijzer van een naamruimteobject naar een item-identificatielijst (PIDL). Een voor de hand liggende vraag is: Wanneer u een PIDL hebt, wat kunt u ermee doen? Een gerelateerde vraag is: Wat als geen van beide benaderingen werkt of geschikt is voor uw toepassing? Voor het antwoord op beide vragen moet u nader bekijken hoe de naamruimte wordt geïmplementeerd. De sleutel is de IShellFolder interface.

• de IShellFolder-interface gebruiken
• de inhoud van een map opsommen
• weergavenamen en andere eigenschappen bepalen
• Een aanwijzer naar de IShellFolder-interface van een submap
• Het bepalen van de bovenliggende map van een object

De IShellFolder-interface gebruiken

Eerder in deze documentatie werden naamruimtemappen aangeduid als objecten. Hoewel de term op dat moment in een losse zin werd gebruikt, is het eigenlijk ook in strikte zin waar. Elke naamruimtemap wordt vertegenwoordigd door een COM-object (Component Object Model). Elk mapobject bevat een aantal interfaces die kunnen worden gebruikt voor een groot aantal taken. Sommige interfaces die optioneel zijn, worden mogelijk niet weergegeven door alle mappen. Alle mappen moeten echter de fundamentele interface beschikbaar maken, IShellFolder.

De eerste stap bij het gebruik van een mapobject is het ophalen van een aanwijzer naar de IShellFolder interface. Naast toegang tot de andere interfaces van het object maakt IShellFolder een groep methoden beschikbaar die een aantal algemene taken verwerken, die in deze sectie worden besproken.

Als u een aanwijzer wilt ophalen naar de IShellFolder interface van een naamruimteobject, moet u eerst SHGetDesktopFolder-aanroepen. Deze functie retourneert een aanwijzer naar de IShellFolder interface van de naamruimte-hoofdmap, het bureaublad. Zodra u de IShellFolder interface van het bureaublad hebt, zijn er verschillende manieren om door te gaan.

Als u al beschikt over de PIDL van de map waarin u geïnteresseerd bent, bijvoorbeeld door SHGetFolderLocation-aan te roepen, kunt u de IShellFolder--interface ophalen door de methode IShellFolder::BindToObject van het bureaublad aan te roepen. Als u het pad van een bestandssysteemobject hebt, moet u eerst de PIDL ophalen door de IShellFolder::P arseDisplayName- methode van het bureaublad aan te roepen en vervolgens IShellFolder::BindToObjectaan te roepen. Als geen van deze methoden van toepassing is, kunt u andere IShellFolder methoden gebruiken om door de naamruimte te navigeren. Zie Navigeren in de naamruimtevoor meer informatie.

De inhoud van een map opsommen

Het eerste wat u meestal met een map wilt doen, is om erachter te komen wat deze bevat. U moet eerst de methode IShellFolder::EnumObjects van de map aanroepen. De map maakt een standaard OLE-opsommingsobject en retourneert de IEnumIDList interface. Deze interface bevat vier standaardmethoden,Clone, Next, Reseten Skip, waarmee de inhoud van de map kan worden opgesomd.

De basisprocedure voor het inventariseren van de inhoud van een map is:

1. Roep de mappen IShellFolder::EnumObjects methode aan om een aanwijzer op te halen naar de IEnumIDList-interface van een opsommingsobject.
2. Geef een niet-toegewezen PIDL door aan IEnumIDList::Next. Volgende zorgt ervoor dat de PIDL wordt toegewezen, maar de toepassing moet de toewijzing ongedaan maken wanneer deze niet meer nodig is. Wanneer Volgende retourneert, bevat de PIDL alleen de item-id van het object en de afsluitende NULL- tekens. Met andere woorden, het is een PIDL met één niveau, ten opzichte van de map, niet een volledig gekwalificeerde PIDL.
3. Herhaal stap 2 tot Volgende retourneert S_FALSE om aan te geven dat alle items zijn geïnventariseerd.
4. Roep IEnumIDList::Release aan om het opsommingsobject vrij te geven.

De resterende drie IEnumIDList methoden (Reset, Skipen Clone) zijn handig als u herhaalde opsommingen van de map moet uitvoeren. Hiermee kunt u de opsomming opnieuw instellen, een of meer objecten overslaan en een kopie van het opsommingsobject maken om de status ervan te behouden.

Weergavenamen en andere eigenschappen bepalen

Zodra u alle PIDLs hebt geïnventariseerd die zijn opgenomen in een map, kunt u erachter komen wat voor soort objecten ze vertegenwoordigen. De IShellFolder interface biedt een aantal nuttige methoden, die hier worden besproken. Andere IShellFolder methoden en andere Shellmap-interfaces worden later besproken.

Een van de handigste eigenschappen is de weergavenaam van het object. Als u de weergavenaam van een object wilt ophalen, geeft u de PIDL door aan IShellFolder::GetDisplayNameOf. Hoewel het object zich ergens onder de bovenliggende map in de naamruimte kan bevinden, moet de PIDL zich ten opzichte van de map bevinden.

IShellFolder::GetDisplayNameOf retourneert de weergavenaam als onderdeel van een STRRET structuur. Omdat het extraheren van de weergavenaam uit een STRRET structuur een beetje lastig kan zijn, biedt de Shell twee functies die de taak voor u uitvoeren, StrRetToStr en StrRetToBuf-. Beide functies hebben een STRRET structuur en retourneren de weergavenaam als een normale tekenreeks. Ze verschillen alleen in de wijze waarop de tekenreeks wordt toegewezen.

Naast de weergavenaam kan een object een aantal kenmerken hebben, zoals of het een map is of of het kan worden verplaatst. U kunt de kenmerken van een object ophalen door de PIDL door te geven aan IShellFolder::GetAttributesOf. De volledige lijst met kenmerken is vrij groot, dus u moet de verwijzing voor details zien. Houd er rekening mee dat de PIDL die u doorgeeft aan GetAttributesOf één niveau diep moet zijn. In het bijzonder accepteert IShellFolder::GetAttributesOf de PIDLs die worden geretourneerd door IEnumIDList::Next. U kunt een matrix met PIDLs doorgeven en GetAttributesOf retourneert deze kenmerken die alle objecten in de matrix gemeen hebben.

Als u een volledig gekwalificeerde padnaam of PIDL van een object hebt, biedt SHGetFileInfo een eenvoudige manier om informatie op te halen over een object die voor veel doeleinden voldoende informatie geeft. SHGetFileInfo een volledig gekwalificeerd pad of PIDL gebruikt en een verscheidenheid aan informatie over het object retourneert, waaronder:

• De weergavenaam van het object
• De kenmerken van het object
• Handgrepen voor de pictogrammen van het object
• Een verwijzing naar de systeemaftbeeldingenlijst
• Het pad van het bestand met het pictogram van het object

Een aanwijzer naar de IShellFolder-interface van een submap krijgen

U kunt bepalen of uw map submappen bevat door IShellFolder::GetAttributesOf aan te roepen en te controleren of de vlag SFGAO_FOLDER is ingesteld. Als een object een map is, kunt u er verbinding mee maken, zodat u een aanwijzer krijgt naar de IShellFolder-interface.

Als u verbinding wilt maken met een submap, roept u de methode IShellFolder::BindToObject van de bovenliggende map aan. Deze methode gebruikt de PIDL van de submap en retourneert een aanwijzer naar de IShellFolder interface. Zodra u deze aanwijzer hebt, kunt u de IShellFolder methoden gebruiken om de inhoud van de submappen te inventariseren, hun eigenschappen te bepalen, enzovoort.

De bovenliggende map van een object bepalen

Als u de PIDL van een object hebt, hebt u mogelijk een ingang nodig voor een van de interfaces die worden weergegeven door de bovenliggende map. Als u bijvoorbeeld de weergavenaam wilt bepalen die is gekoppeld aan een PIDL met behulp van IShellFolder::GetDisplayNameOf, moet u eerst de IShellFolder interface van het bovenliggende object ophalen. Het is mogelijk om dit te doen met de technieken die in de vorige secties zijn besproken. Een veel eenvoudigere benadering is echter het gebruik van de Shell-functie, SHBindToParent. Deze functie gebruikt de volledig gekwalificeerde PIDL van een object en geeft een specifieke interfacepointer op de oudermap. Optioneel retourneert het ook de PIDL van één niveau van het item voor gebruik in methoden zoals IShellFolder::GetAttributesOf.

De volgende voorbeeld van een consoletoepassing haalt de PIDL van de speciale systeemmap op en retourneert de weergavenaam.

#include <shlobj.h>
#include <shlwapi.h>
#include <iostream.h>
#include <objbase.h>

int main()
{
    IShellFolder *psfParent = NULL;
    LPITEMIDLIST pidlSystem = NULL;
    LPCITEMIDLIST pidlRelative = NULL;
    STRRET strDispName;
    TCHAR szDisplayName[MAX_PATH];
    HRESULT hr;

    hr = SHGetFolderLocation(NULL, CSIDL_SYSTEM, NULL, NULL, &pidlSystem);

    hr = SHBindToParent(pidlSystem, IID_IShellFolder, (void **) &psfParent, &pidlRelative);

    if(SUCCEEDED(hr))
    {
        hr = psfParent->GetDisplayNameOf(pidlRelative, SHGDN_NORMAL, &strDispName);
        hr = StrRetToBuf(&strDispName, pidlSystem, szDisplayName, sizeof(szDisplayName));
        cout << "SHGDN_NORMAL - " <<szDisplayName << '\n';
    }

    psfParent->Release();
    CoTaskMemFree(pidlSystem);

    return 0;
}

De toepassing maakt eerst gebruik van SHGetFolderLocation om de PIDL van de systeemmap op te halen. Vervolgens wordt SHBindToParentaangeroepen, waarmee een aanwijzer wordt geretourneerd naar de IShellFolder-interface van de bovenliggende map en de PIDL van de systeemmap ten opzichte van de bovenliggende map. Vervolgens wordt de IShellFolder::GetDisplayNameOf methode van de bovenliggende map gebruikt om de weergavenaam van de systeemmap op te halen. Omdat GetDisplayNameOf een STRRET- structuur retourneert, wordt StrRetToBuf- gebruikt om de weergavenaam te converteren naar een normale tekenreeks. Nadat de weergavenaam is weergegeven, worden de interfaceaanwijzers vrijgegeven en wordt de systeem-PIDL vrijgemaakt. Houd er rekening mee dat u de door SHBindToParentgeretourneerde relatieve PIDL niet vrij mag maken.