• ISearchProtocol to manage UrlAccessor objects.
• IUrlAccessor to emit properties and identify appropriate filters for items in the data store.
• IFilter to filter proprietary files or to enumerate and filter hierarchically stored files.

This topic is organized as follows:

• About URLs
• Implementing Protocol Handler Interfaces
  • ISearchProtocol and ISearchProtocol2 Interfaces
  • IUrlAccessor, IUrlAccessor2, IUrlAccessor3, and IUrlAccessor4 Interfaces
  • IProtocolHandlerSite Interface
• Implementing Filter Handlers for Containers
• Ensuring that Your Items are Indexed
• Search Connectors for Protocol Handlers in Windows 7
  • Disabling Protocol Handler Search Connector Creation
  • Customizing the Name and Description for a Protocol Handler Search Connector
  • Using Registry String Redirection
  • Restoring a Deleted Protocol Handler Search Connector
• Additional Resources
• Related Topics

About URLs

Windows Search uses URLs to uniquely identify items in the hierarchy of your data store. The URL that is the first node in the hierarchy is called the search root; Windows Search begins at that search root, asking the protocol handler to enumerate child links for each URL.

The typical URL structure is:

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

The <protocol> portion identifies which protocol handler to invoke for the URL. If there is a {user SID} portion, the protocol handler is invoked in the security context of that user. Otherwise, it is invoked in the security context of the system service. The <path> portion defines the hierarchy of the store, where each forward slash ('/') is a separator between folder names. The <ItemID> is a unique string identifying the child item (for example, the file name).

The Windows Search Indexer trims the final slash from URLs, so you cannot rely on the existence of a final slash to identify a directory (as opposed to an item). Your protocol handler must be able to handle this URL syntax. Ensure that the protocol name that you select to identify your data store does not conflict with current ones. We recommend this naming convention: companyName.scheme.

For more information on creating a Shell data store, see Implementing the Basic Folder Object Interfaces.

Implementing Protocol Handler Interfaces

This section discusses the interfaces that implement protocol handlers. You can implement whichever interfaces best meets your needs.

ISearchProtocol and ISearchProtocol2 Interfaces

The SearchProtocol interfaces initialize and manage your protocol handler UrlAccessor objects. The ISearchProtocol2 interface is an extension of ISearchProtocol, and includes an extra method to specify more information about the user and the item.

IUrlAccessor, IUrlAccessor2, IUrlAccessor3, and IUrlAccessor4 Interfaces

The IUrlAccessor interfaces are described in the following table.

The UrlAccessor object is instantiated and initialized by a SearchProtocol object. The IUrlAccessor interfaces provide access to important pieces of information through the following methods:

• IUrlAccessor::GetLastModified returns the time that the URL was last modified. If this time is more recent than the last time the indexer processed this URL, IFilters are invoked to extract the (possibly) changed data for that item. Modified times for directories are ignored.
• IUrlAccessor::IsDirectory identifies whether the URL represents a folder containing child URLs.
• IUrlAccessor::BindToStream binds to an IStream interface [Structured Storage] that represents the data of a file in a custom store.
• IUrlAccessor::BindToFilter binds to a protocol handler-specific IFilter, which can emit properties for the item.
• IUrlAccessor4::ShouldIndexItemContent identifies whether the content of the item should be indexed.

IProtocolHandlerSite Interface

The IProtocolHandlerSite interface is used to instantiate a filter handler (an implementation of the IFilter interface), which are hosted in an isolated process. The appropriate filter handler is obtained for a specified persistent class identifier (CLSID), document storage class, or file name extension. The benefits of asking the host process to bind to IFilter is that the host process can manage the complexity of finding the appropriate filter handler, and can control the security of invoking the handler.

Implementing Filter Handlers for Containers

If you are implementing a hierarchical protocol handler, you must implement a container IFilter component that enumerates child URLs. The enumeration process is a loop through the IFilter::GetChunk and IFilter::GetValue methods of the IFilter interface; each child URL is emitted as the value of the property.

IFilter::GetChunk returns the properties of the container. To enumerate child URLs, IFilter::GetChunk returns either of the following:

• PKEY_Search_UrlToIndex: the URL to the item without the last modified time. IFilter::GetValue returns a PROPVARIANT containing the child URL.
• PKEY_Search_UrlToIndexWithModificationTime: the URL and the last modified time. IFilter::GetValue returns a PROPVARIANT containing a vector of the child URL and the last modified time.

Returning PKEY_Search_UrlToIndexWithModificationTime is more efficient because the indexer can immediately determine whether the item needs to be indexed without calling the ISearchProtocol::CreateAccessor and IUrlAccessor::GetLastModified methods.

The following example code demonstrates how to return PKEY_Search_UrlToIndexWithModificationTime .

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

Ensuring that Your Items are Indexed

Now that you have implemented your protocol handler, you need to specify which items your handler is registered for indexing. You can use the Catalog Manager to initiate re-indexing, and you can also use the Crawl Scope Manager (CSM) to set up default rules indicating the URLs that you want the indexer to crawl. Another option is to follow the procedure in the ReIndex sample in Windows Search SDK Samples.

The ISearchCrawlScopeManager interface provides methods that notify the search engine of containers to crawl and/or watch, and items under those containers to include or exclude when crawling or watching. In Windows 7 and later, ISearchCrawlScopeManager2 extends ISearchCrawlScopeManager with the ISearchCrawlScopeManager2::GetVersion method that gets the version, which informs clients whether the state of the CSM has changed.

You may need to stop and restart the Windows Search service to initiate re-indexing.

Search Connectors for Protocol Handlers in Windows 7

In Windows 7, searches from the Start menu or Windows Explorer include only files in indexed locations, and non-file system items such as remote data stores or protocol handler items that have a search connector. In addition to including the protocol handler items in the scope of Start menu and Shell searches, the search connector enables the Start menu to group protocol handler items together in Start menu results, so the user can click the group header and view results from only the protocol handler. Alternatively, the user can navigate to the Searches folder and search, and then open the search connector file and perform a search that includes only protocol handler items.

When a user first starts an application that registers a protocol handler, Windows Explorer generates a search connector file (.searchConnector-ms) for the protocol handler in the user's Searches folder (%userprofile%/Searches). Applications with protocol handlers can choose to disable this behavior or customize the name and description of the protocol handler search connector.

Windows Explorer controls the creation of a search connector for a protocol handler through registry key entries described in the following sections:

• Disabling Protocol Handler Search Connector Creation
• Customizing the Name and Description for a Protocol Handler Search Connector
• Restoring a Deleted Protocol Handler Search Connector

Disabling Protocol Handler Search Connector Creation

If your application is exposing items through a protocol handler for use in the application itself, and you do not want to expose the items through the Shell, you should set the following registry key values:

1. Set DoNotCreateSearchConnectors=1 to disable search connector creation.
2. Set the value to TRUE to emit the System.Shell.OmitFromView property on each item exposed by the protocol handler.

Set these values in the following registry key example. CLSID is of REG_DWORD type.

Customizing the Name and Description for a Protocol Handler Search Connector

The search connector name is used not only to identify the search connector in the Searches folder, but as the group headers for the results in Start menu searches. Hence, it is important to provide a clear name for the search connector. If a name is not provided in the registry key, by default Windows Explorer uses the name and blank description provided by IShellFolder for the protocol handler's search root. You can override the default name without having to rename the IShellFolder, through a registry key entry. Name is of the REG_SZ type.

Although it is not as visible as the search connector name, you can also set the override the description for the search connector by providing a description, as illustrated in the following registry key example. Location is of REG_SZ type.

For reference documentation related to these registry key entries, see IShellItem::GetDisplayName and SIGDN_NORMALDISPLAY.

Using Registry String Redirection

To ensure that the name you provide for the search connector can be localized, use a redirected string. You can include localizable strings for the name and description registry keys instead of entering the actual string into the registry. Name is of the REG_SZ type.

Restoring a Deleted Protocol Handler Search Connector

Because search connectors are files on the user's computer, they can be mistakenly deleted. To restore all deleted protocol handler search connectors, the user can restore the default libraries. To so do, open Windows Explorer, right-click the Libraries folder, and then select Restore Default Libraries.

Additional Resources

• For an overview of the indexing process, see The Indexing Process.
• For overviews of the Catalog Manager and CSM, see Using the Catalog Manager and Using the Crawl Scope Manager.
• To extend Windows Search to index the contents and properties of new file formats and data stores, see Extending the Index.
• To query file association attributes for a file type, see PerceivedTypes, SystemFileAssociations, and Application Registration.
• For conceptual information on filter handlers, see Developing Filter Handlers.
• For code samples, see Windows Search SDK Samples.

Related Topics

• About Protocol Handlers
• Developing Protocol Handlers
• Notifying the Index of Changes
• Adding Icons and Context Menus
• Sample: Shell Extensions for Protocol Handlers
• Debugging Protocol Handlers