Het installeren en registreren van protocol-handlers (Windows Search)

Het installeren van een protocolhandler omvat het kopiëren van de DLL('s) naar een geschikte locatie in de map Program Files en het registreren van de protocolhandler via het register. De installatietoepassing kan ook een zoekhoofd- en bereikregels toevoegen om een standaard verkenningsbereik voor de Shell-gegevensbron te definiëren.

Dit onderwerp is als volgt ingedeeld:

Over URLs
ProtocolHandler interfaces implementeren
Filterhandlers implementeren voor containers
een protocolhandler installeren en registreren
ervoor zorgen dat uw items worden geïndexeerd
Verwante onderwerpen

Over URL's

Windows Search gebruikt URL's om items in de hiërarchie van uw Shell-gegevensbron uniek te identificeren. De URL die het eerste knooppunt in de hiërarchie is, wordt de zoekwortelgenoemd; Windows Search begint met indexeren bij de zoekwortel, waarbij wordt opgevraagd dat de protocolhandler onderliggende koppelingen voor elke URL opsomt.

De typische URL-structuur is:

<protocol>:// [{user SID}/] <localhost>/<path>/[<ItemID>]

De URL-syntaxis wordt beschreven in de volgende tabel.

Syntaxis	Beschrijving
<protocol>	Hiermee wordt aangegeven welke protocolhandler moet worden aangeroepen voor de URL.
{user SID}	Identificeert de beveiligingscontext van de gebruiker waaronder de protocolhandler wordt aangeroepen. Als er geen ID (User Security Identifier) wordt geïdentificeerd, wordt de protocolhandler aangeroepen in de beveiligingscontext van de systeemservice.
<pad>	Definieert de hiërarchie van het archief, waarbij elke slash ('/') een scheidingsteken is tussen mapnamen.
<ItemID->	Vertegenwoordigt een unieke tekenreeks die het onderliggende item identificeert (bijvoorbeeld de bestandsnaam).

De Windows Search-indexeerfunctie trimt de laatste slash van URL's. Als gevolg hiervan kunt u niet vertrouwen op het bestaan van een definitieve slash om een map versus een item te identificeren. Uw protocolhandler moet deze URL-syntaxis kunnen verwerken. Zorg ervoor dat de protocolnaam die u selecteert om uw Shell-gegevensbron te identificeren, niet conflicteren met de huidige. We raden deze naamconventie aan: companyName.scheme.

Voor meer informatie over het maken van een Shell-gegevensbron, zie De basismapobjectinterfaces implementeren.

Protocolhandlerinterfaces implementeren

Voor het maken van een protocolhandler is de implementatie van de volgende drie interfaces vereist:

ISearchProtocol- voor het beheren van UrlAccessor-objecten.
IUrlAccessor- om eigenschappen weer te geven en de juiste filters te identificeren voor items in de Shell-gegevensbron.
IFilter om eigen bestanden te filteren of hiërarchisch opgeslagen bestanden op te sommen en te filteren.

Behalve de drie verplichte interfaces die worden vermeld, zijn de andere interfaces optioneel en u bent vrij om te implementeren welke optionele interfaces het meest geschikt zijn voor de taak.

ISearchProtocol en ISearchProtocol2

De SearchProtocol-interfaces initialiseren en beheren uw UrlAccessor-objecten van de protocolhandler. De ISearchProtocol2 interface is een optionele uitbreiding van ISearchProtocolen bevat een extra methode om meer informatie over de gebruiker en het item op te geven.

Iurlaccessor, iurlaccessor2, iurlaccessor3 en IUrlAccessor4

De IUrlAccessor interfaces worden beschreven in de volgende tabel.

Interface	Beschrijving
IUrlAccessor	Voor een opgegeven URL biedt de IUrlAccessor--interface toegang tot de eigenschappen van het item dat in de URL wordt weergegeven. Deze eigenschappen kunnen ook worden gekoppeld aan een protocolhandlerspecifiek filter (een ander filter dan het filter dat is gekoppeld aan de bestandsnaam).
IUrlAccessor2 (optioneel)	De IUrlAccessor2-interface breidt IUrlAccessor uit met methoden waarmee een codepagina voor de eigenschappen van het item en de bijbehorende weergave-URL wordt verkregen, en waarmee het type item in de URL (document of map) wordt bepaald.
IUrlAccessor3 (optioneel)	De IUrlAccessor3-interface breidt IUrlAccessor2- uit met een methode waarmee een matrix met gebruikers-SID's wordt opgehaald, waardoor de host van het zoekprotocol deze gebruikers kan imiteren om het item te indexeren.
IUrlAccessor4 (optioneel)	De IUrlAccessor4 interface breidt de functionaliteit van de IUrlAccessor3 interface uit met een methode waarmee wordt aangegeven of de inhoud van het item moet worden geïndexeerd.

Het UrlAccessor-object wordt geïnstantieerd en geïnitialiseerd door een SearchProtocol-object. De IUrlAccessor interfaces bieden toegang tot belangrijke gegevens via de methoden die in de volgende tabel worden beschreven.

Methode	Beschrijving
IUrlAccessor::GetLastModified	Retourneert de tijd waarop de URL voor het laatst is gewijzigd. Als deze tijd recenter is dan de laatste keer dat de indexeerfunctie deze URL heeft verwerkt, worden filterhandlers (implementaties van de IFilter-interface interface) aangeroepen om de (mogelijk) gewijzigde gegevens voor dat item te extraheren. Gewijzigde tijden voor mappen worden genegeerd.
IUrlAccessor::IsDirectory	Hiermee wordt aangegeven of de URL een map met onderliggende URL's vertegenwoordigt.
IUrlAccessor::BindToStream-	Wordt gekoppeld aan een IStream-interface die de gegevens van een bestand in een aangepast gegevensarchief vertegenwoordigt.
IUrlAccessor::BindToFilter	Bindt aan een protocolhandlerspecifieke IFilter, waarmee eigenschappen voor het item kunnen worden weergegeven.
IUrlAccessor4::ShouldIndexItemContent	Hiermee wordt aangegeven of de inhoud van het item moet worden geïndexeerd.

IProtocolHandlerSite

De IProtocolHandlerSite interface wordt gebruikt om een filterhandler te instantiëren, die wordt gehost in een geïsoleerd proces. De juiste filterhandler wordt verkregen voor een opgegeven permanente klasse-id (CLSID), documentopslagklasse of bestandsnaamextensie. Het voordeel van het vragen van het hostproces om verbinding te maken met IFilter is dat het hostproces het proces van het zoeken naar een geschikte filterhandler kan beheren en de beveiliging kan beheren die betrokken is bij het aanroepen van de handler.

Filterhandlers implementeren voor containers

Als u een hiërarchische protocolhandler implementeert, moet u een filterhandler implementeren voor een container waarin onderliggende URL's worden opgesomd. Een filterhandler is een implementatie van de IFilter interface. Het opsommingsproces is een lus door de IFilter::GetChunk en IFilter::GetValue methoden van de IFilter interface; elke onderliggende URL wordt weergegeven als de waarde van de eigenschap.

IFilter::GetChunk retourneert de eigenschappen van de container. Als u onderliggende URL's wilt inventariseren, retourneert IFilter::GetChunk een van de volgende waarden:

PKEY_Search_UrlToIndex:

De URL naar het item zonder de laatste wijzigingstijd. IFilter::GetValue retourneert een PROPVARIANT die de kinder-URL bevat.
PKEY_Search_UrlToIndexWithModificationTime:

De URL en de laatste wijzigingstijd. IFilter::GetValue retourneert een PROPVARIANT met een vector van de kind-URL en het laatst gewijzigde tijdstip.

Het retourneren van PKEY_Search_UrlToIndexWithModificationTime is efficiënter omdat de indexeerfunctie onmiddellijk kan bepalen of het item moet worden geïndexeerd zonder de ISearchProtocol::CreateAccessor- en IUrlAccessor::GetLastModified methoden aan te roepen.

In de volgende voorbeeldcode ziet u hoe u de eigenschap PKEY_Search_UrlToIndexWithModificationTime kunt retourneren.

Belangrijk

// Parameters are assumed to be valid

HRESULT GetPropVariantForUrlAndTime
    (PCWSTR pszUrl, const FILETIME &ftLastModified, PROPVARIANT **ppPropValue)
{
    *ppPropValue = NULL;

    // Allocate the propvariant pointer.
    size_t const cbAlloc = sizeof(**ppPropValue);
    *ppPropValue = (PROPVARIANT *)CoTaskMemAlloc(cbAlloc));

    HRESULT hr = *ppPropValue ? S_OK : E_OUTOFMEMORY;

    if (SUCCEEDED(hr))
    {
        PropVariantInit(*ppPropValue);  // Zero init the value

        // Now allocate enough memory for 2 nested PropVariants.
        // PKEY_Search_UrlToIndexWithModificationTime is an array of two PROPVARIANTs.
        PROPVARIANT *pVector = (PROPVARIANT *)CoTaskMemAlloc(sizeof(*pVector) * 2);
        hr = pVector ? S_OK : E_OUTOFMEMORY;

        if (SUCCEEDED(hr))
        {
            // Set the container PROPVARIANT to be a vector of two PROPVARIANTS.
            (*ppPropValue)->vt = VT_VARIANT | VT_VECTOR;
            (*ppPropValue)->capropvar.cElems = 2;
            (*ppPropValue)->capropvar.pElems = pVector;
            PWSTR pszUrlAlloc;
            hr = SHStrDup(pszUrl, &pszUrlAlloc);

            if (SUCCEEDED(hr))
            {
                // Now fill the array of PROPVARIANTS.
                // Put the pointer to the URL into the vector.
                (*ppPropValue)->capropvar.pElems[0].vt = VT_LPWSTR; 
                (*ppPropValue)->capropvar.pElems[0].pwszVal = pszUrlAlloc;

                 // Put the FILETIME into vector.
                (*ppPropValue)->capropvar.pElems[1].vt = VT_FILETIME; 
                (*ppPropValue)->capropvar.pElems[1].filetime = ftLastModified;
            }

            else
            {
                CoTaskMemFree(pVector);
            }
        }
 
        if (FAILED(hr))
        {
            CoTaskMemFree(*ppPropValue);
            *ppPropValue = NULL;
        }
    }
    return S_OK;
}

Notitie

Een container IFilter onderdeel moet altijd alle onderliggende URL's inventariseren, zelfs als de onderliggende URL's niet zijn gewijzigd, omdat de indexeerfunctie verwijderingen detecteert via het opsommingsproces. Als de datumuitvoer in een PKEY_Search_UrlToIndexWithModificationTime aangeeft dat de gegevens niet zijn gewijzigd, werkt de indexeerfunctie de gegevens voor die URL niet bij.

Een protocolhandler installeren en registreren

Het installeren van protocolhandlers omvat het kopiëren van de DLL('s) naar een geschikte locatie in de map Program Files en het registreren van de DLL('s). Protocolhandlers moeten zelfregistratie implementeren voor installatie. De installatietoepassing kan ook een zoekhoofdmap en bereikregels toevoegen om een standaard verkenningsbereik voor de Shell-gegevensbron te definiëren. Dit wordt besproken in Ervoor zorgen dat uw items worden geïndexeerd aan het einde van dit onderwerp.

Richtlijnen voor het registreren van een protocolhandler

Volg deze richtlijnen bij het registreren van een protocolhandler:

Het installatieprogramma moet een EXE- of MSI-installatieprogramma gebruiken.
Releaseopmerkingen moeten worden opgegeven.
Er moet een vermelding voor het toevoegen/verwijderen van programma's worden gemaakt voor elke geïnstalleerde invoegtoepassing.
Het installatieprogramma moet alle registerinstellingen voor het specifieke bestandstype overnemen of opslaan dat de huidige invoegtoepassing begrijpt.
Als een eerdere invoegtoepassing wordt overschreven, moet het installatieprogramma de gebruiker op de hoogte stellen.
Als een nieuwere invoegtoepassing de vorige invoegtoepassing heeft overschreven, moet u de mogelijkheid hebben om de functionaliteit van de vorige invoegtoepassing te herstellen en deze opnieuw de standaardinvoegtoepassing voor dat bestandstype te maken.
Het installatieprogramma moet een standaard verkenningsbereik voor de indexeerfunctie definiëren door een zoekhoofdmap en bereikregels toe te voegen met behulp van verkenningsbereikbeheer (CSM).

Een protocolhandler registreren

U moet veertien vermeldingen in het register maken om het protocolhandleronderdeel te registreren, waarbij:

Ver_Ind_ProgID is de versie-onafhankelijke ProgID van de implementatie van de protocolhandler.
Ver_Dep_ProgID is de versieafhankelijke ProgID van de implementatie van de protocolhandler.
CLSID_1 is de CLSID van de implementatie van de protocolhandler.

Een protocolhandler registreren:

Registreer de versie onafhankelijke ProgID met de volgende sleutels en waarden:

HKEY_CLASSES_ROOT
   <Ver_Ind_ProgID>
      (Default) = <Protocol Handler Class Description>

HKEY_CLASSES_ROOT
   <Ver_Ind_ProgID>
      CLSID
         (Default) = {CLSID_1}

HKEY_CLASSES_ROOT
   <Ver_Ind_ProgID>
      CurVer
         (Default) = <Ver_Dep_ProgID>

Registreer de versieafhankelijke ProgID met de volgende sleutels en waarden:

HKEY_CLASSES_ROOT
   <Ver_Dep_ProgID>
      (Default) = <Protocol Handler Class Description>

HKEY_CLASSES_ROOT
   <Ver_Dep_ProgID>
      CLSID
         (Default) = {CLSID_1}

Registreer de CLSID van de protocolhandler met de volgende sleutels en waarden:

HKEY_CLASSES_ROOT
   {CLSID_1}
      (Default) = <Protocol Handler Class Description>

HKEY_CLASSES_ROOT
   {CLSID_1}
      {InprocServer32}
         (Default) = <DLL Install Path>
         Threading Model = Both

HKEY_CLASSES_ROOT
   {CLSID_1}
      <ProgID>
         (Default) = <Ver_Dep_ProgID>

HKEY_CLASSES_ROOT
   {CLSID_1}
      <ShellFolder>
         Attributes = dword:a0180000

HKEY_CLASSES_ROOT
   {CLSID_1}
      TypeLib
         (Default) = {LIBID of PH Component}

HKEY_CLASSES_ROOT
   {CLSID_1}
      VersionIndependentProgID
         (Default) = <Ver_Ind_ProgID>

Registreer de protocolhandler met Windows Search. In het volgende voorbeeld is <protocolnaam> de naam van het protocol zelf, zoals bestand, mapi, enzovoort:

HKEY_LOCAL_MACHINE
   SOFTWARE
      Microsoft
         Windows Search
            ProtocolHandlers
               <Protocol Name> = <Ver_Dep_ProgID>

HKEY_CURRENT_USER
   SOFTWARE
      Microsoft
         Windows Search
            ProtocolHandlers
               <Protocol Name> = <Ver_Dep_ProgID>

Vóór Windows Vista:

HKEY_CURRENT_USER
   SOFTWARE
      Microsoft
         Windows Desktop Search
            DS
               Index
                  ProtocolHandlers
                     <Protocol Name>
                        HasRequirements = dword:00000000
                        HasStartPage = dword:00000000

De protocolhandler als handler voor het bestandstype registreren

Je moet twee vermeldingen in het register maken om de bestandstype-handler van de protocolhandler te registreren (ook bekend als een shell-extensie).

HKEY_LOCAL_MACHINE
   SOFTWARE
      Microsoft
         Windows
            CurrentVersion
               Explorer
                  Desktop
                     NameSpace
                        {CLSID of PH Implementation}
                           (Default) = <Shell Implementation Description>

HKEY_LOCAL_MACHINE
   SOFTWARE
      Microsoft
         Windows
            CurrentVersion
               Explorer
                  Shell Extensions
                     Approved
                        {CLSID of PH Implementation} = <Shell Implementation Description>

Ervoor zorgen dat uw items worden geïndexeerd

Nadat u de protocolhandler hebt geïmplementeerd, moet u opgeven welke Shell-items uw protocolhandler moet indexeren. U kunt Catalog Manager gebruiken om het opnieuw indexeren te initiëren (zie Het gebruik van de Catalog Manager-). U kunt ook csm (Crawl Scope Manager) gebruiken om standaardregels in te stellen die aangeven welke URL's de indexeerfunctie moet verkennen (zie voor meer informatie Het verkenningsbereikbeheer gebruiken en Bereikregels beheren). U kunt ook een zoekhoofdmap toevoegen (zie Het beheren van zoekhoofdmappen). Een andere optie die voor u beschikbaar is, is het volgen van de procedure in het ReIndex-voorbeeld in Windows Search-codevoorbeelden.

De ISearchCrawlScopeManager interface biedt methoden waarmee de zoekmachine kan worden geïnformeerd over containers die moeten worden doorzocht en/of bewaakt, en items onder deze containers die moeten worden opgenomen of uitgesloten bij het doorzoeken of bewaken. In Windows 7 en hoger breidt ISearchCrawlScopeManager2ISearchCrawlScopeManager uit met de methode ISearchCrawlScopeManager2::GetVersion waarmee de versie wordt opgehaald, waarmee clients worden geïnformeerd of de status van de CSM is gewijzigd.

conceptuele
Begrijpen van protocolhandlers
Protocolhandlers ontwikkelen
de index van wijzigingen melden
pictogrammen en contextmenu's toevoegen
codevoorbeeld: Shell-extensies voor protocolhandlers
Een zoekconnector maken voor een protocolhandler
Foutopsporingsprotocolhandlers

Feedback

Is deze pagina nuttig?

Laatst bijgewerkt om 2025-03-26