Share via

Installieren und Registrieren von Protokollhandlern (Windows Search)

  • Artikel

Zur Installation eines Protokollhandlers müssen die DLL(s) an einen geeigneten Ort im Verzeichnis Programme kopiert und dann der Protokollhandler über die Registrierung registriert werden. Die Installationsanwendung kann auch einen Suchstamm und Bereichsregeln hinzufügen, um einen Standard-Durchforstungsbereich für die Shelldatenquelle zu definieren.

Dieses Thema ist wie folgt organisiert:

Informationen zu URLs

Windows Search verwendet URLs zur eindeutigen Identifizierung von Elementen in der Hierarchie Ihrer Shelldatenquelle. Die URL, die der erste Knoten in der Hierarchie ist, wird als Suchstamm bezeichnet; Windows Search beginnt die Indizierung am Suchstamm und stellt die Anforderung, dass der Protokollhandler die untergeordneten Links für jede URL aufzählt.

Die typische URL-Struktur lautet:

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

Die URL-Syntax wird in der folgenden Tabelle beschrieben.

Syntax BESCHREIBUNG
<protocol> Gibt an, welcher Protokollhandler für die URL aufgerufen werden soll.
{user SID} Identifiziert den Benutzersicherheitskontext, unter dem der Protokollhandler aufgerufen wird. Wenn keine Benutzer-Sicherheits-ID (SID) identifiziert wird, wird der Protokollhandler im Sicherheitskontext des Systemdienstes aufgerufen.
<path> Definiert die Hierarchie des Speichers, wobei jeder Schrägstrich („/“) ein Trennzeichen zwischen Ordnernamen ist.
<ItemID> Stellt eine eindeutige Zeichenfolge dar, die das untergeordnete Element identifiziert (z. B. den Dateinamen).

 

Der Windows Search Indexer schneidet den letzten Schrägstrich von URLs ab. Daher können Sie sich nicht auf das Vorhandensein eines abschließenden Schrägstrichs verlassen, um ein Verzeichnis von einem Artikel zu unterscheiden. Ihr Protokollhandler muss in der Lage sein, diese URL-Syntax zu verarbeiten. Vergewissern Sie sich, dass der Protokollname, den Sie zur Identifizierung Ihrer Shelldatenquelle wählen, nicht in Konflikt mit den bereits vorhandenen Namen steht. Wir empfehlen diese Namenskonvention: companyName.scheme.

Weitere Informationen zum Erstellen einer Shelldatenquelle finden Sie unter Implementieren der grundlegenden Ordnerobjektschnittstellen.

Implementieren von Protokollhandlerschnittstellen

Zum Erstellen eines Protokollhandlers ist die Implementierung der folgenden drei Schnittstellen erforderlich:

  • ISearchProtocol zum Verwalten von UrlAccessor-Objekten.
  • IUrlAccessor, um Eigenschaften verfügbar zu machen und geeignete Filter für Elemente in der Shelldatenquelle zu identifizieren.
  • IFilter zum Filtern von geschützten Dateien oder zum Aufzählen und Filtern von hierarchisch gespeicherten Dateien.

Abgesehen von den drei aufgeführten obligatorischen Schnittstellen sind die anderen Schnittstellen optional. Es steht Ihnen frei, die optionalen Schnittstellen zu implementieren, die für die anstehende Aufgabe am besten geeignet sind.

ISearchProtocol und ISearchProtocol2

Die SearchProtocol-Schnittstellen initialisieren und verwalten Ihre Protokollhandler UrlAccessor-Objekte. Die ISearchProtocol2-Schnittstelle ist eine optionale Erweiterung vonISearchProtocol und enthält eine zusätzliche Methode, um weitere Informationen über eine*n Benutzer*in und das Element anzugeben.

IUrlAccessor, IUrlAccessor2, IUrlAccessor3, und IUrlAccessor4

Die IUrlAccessor-Schnittstellen werden in der folgenden Tabelle beschrieben.

Schnittstelle Beschreibung
IUrlAccessor Für eine angegebene URL bietet die Schnittstelle IUrlAccessor Zugriff auf die Eigenschaften des Elements, das in der URL enthalten ist. Sie kann diese Eigenschaften auch an einen Protokollhandler-spezifischen Filter binden (d.h. einen anderen Filter als den, der mit dem Dateinamen verbunden ist).
IUrlAccessor2 (optional) Die Schnittstelle IUrlAccessor2 erweitert IUrlAccessor um Methoden, die eine Codepage für die Eigenschaften des Objekts und seine Anzeige-URL abrufen und die den Typ des Objekts in der URL (Dokument oder Verzeichnis) ermitteln.
IUrlAccessor3 (optional) Die Schnittstelle IUrlAccessor3 erweitert IUrlAccessor2 um eine Methode, die ein Array von Benutzer-SIDs abruft und es dem Suchprotokoll-Host ermöglicht, sich für diese Benutzer*innen auszugeben, um das Objekt zu indizieren.
IUrlAccessor4 (optional) Die Schnittstelle IUrlAccessor4 erweitert die Funktionalität der Schnittstelle IUrlAccessor3 um eine Methode, die angibt, ob der Inhalt des Elements indiziert werden soll.

 

Das UrlAccessor-Objekt wird durch ein SearchProtocol-Objekt instanziiert und initialisiert. Die IUrlAccessor-Schnittstellen bieten Zugriff auf wichtige Informationen über die in der folgenden Tabelle beschriebenen Methoden.

Methode Beschreibung
IUrlAccessor::GetLastModified Gibt die Zeit zurück, zu der die URL zuletzt geändert wurde. Wenn dieser Zeitpunkt aktueller ist als das letzte Mal, als der Indexer diese URL verarbeitet hat, werden Filterhandler (Implementierungen der IFilter-Schnittstelle) aufgerufen, um die (möglicherweise) geänderten Daten für dieses Element zu extrahieren. Änderungszeiten für Verzeichnisse werden ignoriert.
IUrlAccessor::IsDirectory Gibt an, ob die URL einen Ordner darstellt, der untergeordnete URLs enthält.
IUrlAccessor::BindToStream Erstellt eine Bindung an eine IStream-Schnittstelle, die die Daten einer Datei in einem benutzerdefinierten Datenspeicher darstellt.
IUrlAccessor::BindToFilter Erstellt eine Bindung an einen Protokollhandler-spezifischen IFilter, der Eigenschaften für das Element bereitstellen kann.
IUrlAccessor4::ShouldIndexItemContent Gibt an, ob der Inhalt des Elements indiziert werden soll.

 

IProtocolHandlerSite

Die Schnittstelle IProtocolHandlerSite wird zur Instanziierung eines Filterhandlers verwendet, der in einem isolierten Prozess gehostet wird. Der entsprechende Filterhandler wird für einen bestimmten persistenten Klassenbezeichner (CLSID), eine Dokumentenspeicherklasse oder eine Dateinamenerweiterung abgerufen. Der Vorteil, den Hostprozess zu veranlassen, eine Bindung zu IFilter herzustellen, besteht darin, dass der Hostprozess die Suche nach einem geeigneten Filterhandler verwalten und die Sicherheit beim Aufruf des Handlers kontrollieren kann.

Implementieren von Filterhandlern für Container

Wenn Sie einen hierarchischen Protokollhandler implementieren, dann müssen Sie einen Filterhandler für einen Container implementieren, der untergeordnete URLs aufzählt. Ein Filterhandler ist eine Implementierung der IFilter-Schnittstelle. Der Aufzählungsprozess ist eine Schleife durch die Methoden IFilter::GetChunk und IFilter::GetValue der IFilter-Schnittstelle; jede untergeordnete URL wird als Wert der Eigenschaft angezeigt.

IFilter::GetChunk gibt die Eigenschaften des Containers zurück. Zum Aufzählen untergeordneter URLs gibt IFilter::GetChunk einen der folgenden Werte zurück:

Die Rückgabe von PKEY_Search_UrlToIndexWithModificationTime ist effizienter, da der Indexer sofort feststellen kann, ob das Element indiziert werden muss, ohne die Methoden ISearchProtocol::CreateAccessor und IUrlAccessor::GetLastModified aufrufen zu müssen.

Der folgende Beispielcode zeigt, wie Sie die Eigenschaft PKEY_Search_UrlToIndexWithModificationTime zurückgeben.

Wichtig

Copyright (c) Microsoft Corporation. Alle Rechte vorbehalten.

 

// 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;
}

Hinweis

Eine Container-IFilter-Komponente sollte immer alle untergeordneten URLs aufzählen, auch wenn sich die untergeordneten URLs nicht geändert haben, da der Indexer Löschvorgänge durch den Aufzählungsprozess erkennt. Wenn die Datumsausgabe in einem PKEY_Search_UrlToIndexWithModificationTime darauf hinweist, dass sich die Daten nicht geändert haben, aktualisiert der Indexer die Daten für diese URL nicht.

 

Installieren und Registrieren von Protokollhandlern

Bei der Installation von Protokollhandlern müssen die DLL(s) an einen geeigneten Ort im Verzeichnis Programme kopiert und dann registriert werden. Protokollhandler sollten eine Selbstregistrierung für die Installation implementieren. Die Installationsanwendung kann auch einen Suchstamm und Bereichsregeln hinzufügen, um einen Standard-Durchforstungsbereich für die Shelldatenquelle zu definieren, was unter Sicherstellen, dass Ihre Elemente indiziert werden am Ende dieses Themas besprochen wird.

Richtlinien für die Registrierung eines Protokollhandlers

Bei der Registrierung eines Protokollhandlers sollten Sie diese Richtlinien beachten:

  • Das Installationsprogramm muss entweder ein EXE- oder ein MSI-Installationsprogramm verwenden.
  • Es müssen Versionshinweise bereitgestellt werden.
  • Für jedes installierte Add-In muss ein Eintrag "Programme hinzufügen/entfernen" erstellt werden.
  • Das Installationsprogramm muss alle Registrierungseinstellungen für den jeweiligen Dateityp oder Speicher übernehmen, den das aktuelle Add-In versteht.
  • Wenn ein älteres Add-In überschrieben wird, sollte das Installationsprogramm die Benutzer*innen darüber informieren.
  • Wenn ein neueres Add-In das ältere Add-In überschrieben hat, sollte es die Möglichkeit geben, die Funktionalität des älteren Add-Ins wiederherzustellen und es wieder zum Standard-Add-In für diesen Dateityp zu machen.
  • Das Installationsprogramm sollte einen Standard-Durchforstungsbereich für den Indexer definieren, indem es einen Suchstamm und Bereichsregeln mithilfe des Durchforstungsbereichs-Managers (CSM) hinzufügt.

Registrieren eines Protokollhandlers

Sie müssen vierzehn Einträge in der Registrierung vornehmen, um die Komponente Protokollhandler zu registrieren, und zwar an folgenden Stellen:

  • Ver_Ind_ProgID ist die versionsunabhängige ProgID der Implementierung des Protokollhandlers.
  • Ver_Dep_ProgID ist die versionsabhängige ProgID der Implementierung des Protokollhandlers.
  • CLSID_1 ist die CLSID der Implementierung des Protokollhandlers.

So registrieren Sie einen Protokollhandler:

  1. Registrieren Sie die versionsunabhängige ProgID mit den folgenden Schlüsseln und Werten:

    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>

  2. Registrieren Sie die versionsabhängige ProgID mit den folgenden Schlüsseln und Werten:

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

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

  3. Registrieren Sie die CLSID des Protokollhandlers mit den folgenden Schlüsseln und Werten:

    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>

  4. Registrieren Sie den Protokollhandler bei Windows Search. Im folgenden Beispiel ist <Protokollname> der Name des Protokolls selbst, z. B. file, mapi usw:

    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>

    Vor Windows Vista:

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

Registrierung des Dateityphandlers des Protokollhandlers

Sie müssen zwei Einträge in der Registrierung vornehmen, um den Dateityphandler des Protokollhandlers zu registrieren (der auch als Shellerweiterung bekannt ist).

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

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

Sicherstellen, dass Ihre Elemente indiziert werden

Nachdem Sie Ihren Protokollhandler implementiert haben, müssen Sie angeben, welche Shellenelemente Ihr Protokollhandler indizieren soll. Sie können den Katalog-Manager verwenden, um die Neuindizierung zu starten (weitere Informationen finden Sie unter Verwenden des Katalog-Managers). Sie können auch den Durchforstungsbereich-Manager (CSM) verwenden, um Standardregeln einzurichten, die die URLs angeben, die der Indexer durchforsten soll (weitere Informationen finden Sie unter Verwenden des Durchforstungsbereich-Managers und Verwalten von Bereichsregeln). Sie können auch einen Suchstamm hinzufügen (weitere Informationen finden Sie unter Verwalten von Suchstämmen). Eine andere verfügbare Option ist, das Verfahren im ReIndex-Beispiel in Windows Search Codebeispiele zu befolgen.

Die Schnittstelle ISearchCrawlScopeManager bietet Methoden, die der Suchmaschine mitteilen, welche Container durchforstet und/oder überwacht werden sollen und welche Objekte unter diesen Containern beim Durchforsten oder Überwachen ein- oder ausgeschlossen werden sollen. In Windows 7 und höher erweitert ISearchCrawlScopeManager2ISearchCrawlScopeManager mit der Methode ISearchCrawlScopeManager2::GetVersion, die die Version abruft, die die Clients darüber informiert, ob sich der Status des CSM geändert hat.

Konzept

Grundlegendes zu Protokollhandlern

Entwickeln von Protokollhandlern

Benachrichtigen des Indexes über Änderungen

Hinzufügen von Symbolen und Kontextmenüs

Codebeispiel: Shell-Erweiterungen für Protokollhandler

Erstellen eines Suchconnectors für einen Protokollhandler

Debuggen von Protokollhandlern