I’ve been hoping that someday I’d actually have a short post to make on my blog about something Windows Desktop Search (WDS) related… But today isn’t that day…

We’ve been hearing some requests that users would like to add new locations to the “All Locations” list in WDS.  Maybe something like this:

So that when you type in a query and select this added location you get navigated to a set of web search results like this:

And to be honest the real request we heard was for info about adding new desktop search locations but since we support the adding of both desktop and web search locations to the list I thought I’d unofficially tell you how to add both.  As usual this isn’t an officially supported feature and is likely to change in the future.  But when it does change we’ll most likely have a UI for adding these things but for now you’ll have to add them manually via the registry.  So as a further disclaimer, be comfortable with modifying your registry before making any of these changes.  I’d also recommend you make a backup of your registry settings before making any modifications to them.

Adding “MSN Music” to your locations list…

You’ll want to open RegEdit and navigate “HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\MSN Apps\DS\Views\Locations”.  Under that key you’ll notice a list of sub-keys for each location in the list:

As you can from the screenshot I’ve already added a new sub-key called Music for the MSN Music location displayed in my “All Locations” list above.  To add this same location to your list just add a Music sub-key under Locations and add the values you see in the screenshot.  Reboot your machine (or restart Explorer.exe) for the changes to take effect and the next time you launch a WDS results window your “All Locations” list should look just like mine.  Well almost like mine.  Yours won’t have a separator between “MSN Music” and “Outlook Express”.  To get a separator you’ll need to modify the OE sub-key as well:

Change your OE keys Separator value from a 0 to 1.  This should add the separator to your list after another reboot.

Understanding the “Locations” registry values…

So now I’ll drill into the details of what these seemingly random registry values mean and how you can use them to build a wide range of ready to use filters.  As you’ve noticed we currently support two types of locations, Desktop Search and Web Search.  The registry values you need to fill out are largely dependant upon the type of location you want.  But there are a few common values used to control the display of the location in the list so let me talk about those first:

• Title:  Display name of the location in the UI.
• Icon:  Resource info for the Icon to show next to the location.  “msnlExtRes.dll,-164” will show the globe with a magnifying glass icon but you should be able to assign any icon you want.  The format of this string is expected to be “<module>,<index>”.
• Position:  The locations order within the list.  It’s super important that the value of Position be unique and sequential for each location starting from 0.  So for the 6 entries in the screenshot their Position values are from 0 – 5.
• Indent:  The amount of indention if any to apply to the location.  This is used to represent a tree like structure within the list and can contain a value of 0 – 3.  A value of 0 means it’s a root location, 1 means it’s a child location, 2 means it’s a child of a child location, etc.
• Separator:  Inserts a separator line into the list immediately after the location.  A value of 1 means the location is followed by a separator and a value 0 means it isn’t.  Note that you can temporarily hide locations (see Visible) so we’ll try to be smart about automatically rolling up the separators for hidden locations to the next visible one in the list.
• Visible:  Temporarily removes the location from the list if set to a value of 0.  In hind site I wish we would have called this value Hide because its default value is 1 if it’s missing.  So its only purpose is to remove a location from the list.
• Type:  Determines the type of search performed when the location is selected within the UI.  A value of 0 means Desktop Search and a value of 1 means Web Search.

As you’ve probably figured out the locations list is built by simply walking the sub-keys of “HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\MSN Apps\DS\Views\Locations” on first use.  So to begin with you’ll need to add a uniquely named sub-key to this hive and fill out the common values listed above.  If you’re adding a Web Search location you’ll need to fill out the following value as well:

• Value:  The URL of the HTTP server to contact when the location is selected.  You can indicate where to insert the URL Encoded terms of the query by inserting a “$w” into the URL.  Note that this is the same URL format as the one used for adding new deskbar shortcuts.

Now anytime you select your new Web Search location we’ll navigate to the locations URL using the terms entered into our query box.  For a Desktop Search location things are a little more interesting but follow the same principle as a Web Search location in that you need to tell us how we should filter your query.  But for Desktop Search locations we give you 3 different dimensions to filter the query by:

• ItemStore:  This is Unique ID (UID) we’ve assigned to the “store” you’d like us to filter results too.  Yes you’ve just discovered the part of all this voted “Most likely to change” in a future release.  Internally we use these things called UID’s to identify the various objects within our schema.  An “ItemStore” is one of the objects in our schema and we currently have 4 (see UID Values section for a list).  Just set this value to the UID of the store you want to search over. J
• TypeFilter:  This is an optional value you can set to filter results to a specific type within a store.  Again this is UID based and the UID’s are for the various “Type” objects within our schema (see UID Values section for a list).  If you omit this value or set it to 0x00000000 we’ll apply the filter to the query without altering the type selection.  That’s why you can select “Outlook” from the locations list and we filter to a new store without change the Type you have selected.
• Value:  Filters the query by appending a hidden Advanced Query Syntax (AQS) fragment to the query.  Also an optional value but probably the most interesting.  Using this value you can scope the query to anything you want using AQS.  For instance, the “Inbox” location scopes queries the “inbox” folder of the Outlook store by appending the AQS fragment “in:Inbox” to the users query.

Another thing worth talking about is the fact these locations get stored in HKEY_LOCAL_MACHINE.  That means the changes you make to this list of locations will be applied to every user on the machine.  But you can avoid that by copying the entire Locations hive to HKEY_CURRENT_USER and making your changes there.  That way each user can have their own list of locations if they’d like.

How’s this useful?

So hopefully all that made sense and you have a hundred ideas for new locations you want to create.  If so great!  Maybe we’ll even turn it into a supported feature in the future. J  But if not here are a couple of ideas worth considering:

• Personal Favorites:  I originally called this feature “favorites” and you can certainly setup your own list of favorite AQS fragments you end up applying all the time.
• Intranet Locations:  I think the Web Search locations are most interesting when thinking about deployments of WDS within organizations.  If you have a large organization with various SPS servers and such you might think about creating a standard list of locations that point to the searchable resources within your org.  You can then save that list off to a .reg file and install it on users machines as part of your deployment.
• 3^rd Party Add-in Locations:  If you’re a 3^rd party who’s developed a new protocol handler you can create a location for your protocol handler by scoping to the results view via AQS fragments.  To do this you'd want to append an AQS fragment of the form “store:myph” where "myph" is the name you've assigned to your protocol handler.  The tricky part of this is installing this location automatically on users’ machines.  You could blindly install it at Position 5 within the users location list but then you risk overwriting entries on machines containing modified location lists.  The safest thing to do would be to programmatically walk the users existing location list and install it as the last position on the list but that will require you writing custom code to do that.

Anyway… There are a couple of ideas and please let me know if you find this useful or have any comments… Enjoy!

-Steve

UID Values

ItemStore UIDs:

      uidStoreAny       = 0x30000001

      uidStoreFile      = 0x30000002

      uidStoreMAPI      = 0x30000003

      uidStoreOE        = 0x30000004

TypeFilter UIDs:

      uidTypeAny                  = 0x10000

      uidTypeAttachments          = 0x80000

      uidTypeContact              = 0xA0000

      uidTypeCommunications       = 0x60000

      uidTypeEmail                = 0x70000

      uidTypeCalendar             = 0x90000

      uidTypeIM                   = 0x160000

      uidTypeTask                 = 0xB0000

      uidTypeDocuments            = 0x20000

      uidTypeTextDoc              = 0x30000

      uidTypeNote                 = 0xC0000

      uidTypeSpreadsheet          = 0x40000

      uidTypePresentation         = 0x50000

      uidTypeMusic                = 0x100000

      uidTypePictureVideo         = 0xD0000

      uidTypePicture              = 0xE0000

      uidTypeVideo                = 0xF0000

      uidTypeFolder               = 0x110000

      uidTypeFavorite             = 0x120000

      uidTypeProgram              = 0x130000

      uidTypeMultimedia           = 0x140000

I had actually wanted to blog a few weeks ago the fact we’ve released some new API’s for WDS as part of our 2.5 release.  I chose to hold off on posting any comments here because I knew we had fairly significant update in the works.  So now that we’ve posted an updated set of files let me tell you about them.

The 2.5 release was largely about internationalization for us but we were able to squeeze in some new API’s which we’ve been hearing requests for.  The new API’s provide access to a SearchManager component to simplify setup & management of protocol handlers and a SearchDesktop component to provide programmatic access to our index.  Both of these components are implemented as COM objects and require WDS 2.5 or later.  The initial SDK we posted contained a single IDL file which required compilation via Visual Studios MIDL utility into a .tlb file before you could do anything useful with it.  And if you wanted to use the SDK from within a .NET application you then needed to run the .tlb generated by MIDL through another utility called TLBIMP which generates an interop assembly that can then be added as a reference to your .NET project.  Easy right?  Well to simplify both your lives and ours (we have to explain this stuff to you) we decided to do this work for you and give it to you in the form of an updated SDK.  We also talked Brandon Paddock into putting together a sample C# app to get you started in using the new API’s.  I’m sure Brandon will blog about the sample so I’ll just talk a bit about the files in the SDK and the basic principles behind the API.  Be sure and check out the sample as there’s some cool code in there that enables data binding of a queries results to standard WinForms controls.  I’m also going to save discussions about the SearchManager component for another post as there’s enough to talk about with the SearchDesktop component.

What’s in the SDK?

Good question.  Here’s a list of the files:

            End user agreement

SDK EULA.rtf

COM Interface definitions

wdsQuery.idl

wdsSetup.idl

Output of MIDL

wdsQuery.tlb

wdsQuery.h

wdsQuery_i.c

wdsQuery_p.c

wdsSetup.tlb

wdsSetup.h

wdsSetup_i.c

wdsSetup_p.c

Output of TLBIMP

WDSQuery.dll

WDSSetup.dll

The EULA is mandatory, the .idl files define the COM objects we’re exposing, the files built by MIDL are the files you’ll need if you plan to call the API from C++, and the two .dll’s are the .NET interop assemblies generated after we ran the .tlb’s through TLBIMP.  For .NET developers the two .dll’s are the only files you’ll need to make your applications work.  And in most cases you’ll only need one or the other. 

If you create a new C# project and add references to WDSQuery.dll & WDSSetup.dll, you’ll notice from within the Object Browser that two new namespaces are available to your project:

            Microsoft.Windows.DesktopSearch.Query

            Microsoft.Windows.DesktopSearch.Setup

If you browse into those namespaces you’ll notice a SearchDesktopClass class along with a bunch of ADO stuff in the Microsoft.Windows.DesktopSearch.Query namespace and a SearchManagerClass class in the Microsoft.Windows.DesktopSearch.Setup namespace.  The two classes are interop wrappers around the two COM components we’ve exposed via the SDK.  Like I said above the SearchManager component is only relevant to building new protocol handlers so we’ll save that discussion for another time.

Tell me about the classy SearchDesktopClass class…

Ok so now I’m just getting corny…  The SearchDesktopClass is the class you’ll use to create a connection and issue a query to the indexer.  If you look at the methods exposed by this class you’ll see it’s pretty simple:

public virtual new Microsoft.Windows.DesktopSearch.Query._Recordset ExecuteQuery ( System.String lpcwstrQuery , System.String lpcwstrColumn , System.String lpcwstrSort , System.String lpcwstrRestriction )

 

public virtual new Microsoft.Windows.DesktopSearch.Query._Recordset ExecuteSQLQuery ( System.String lpcwstrSQL )

 

Just two methods of which you’re probably only ever going to call one, ExecuteQuery().  Why so simple?  It’s a really low level wrapper around the core component used by the UI when it calls the indexer.  The UI and the SearchDesktopClass both communicate with the indexer via an OLE-DB Provider exposed off the indexer.  More accurately they both communicate with the indexers OLE-DB provider via ADO so you can think of the SearchDesktopClass as a thin wrapper around ADO calls to the indexer which is why results come back as an ADO recordset.

Such low level access to the indexer has PRO’s and CON’s.  The PRO’s are that it’s fast and you can pretty much ask for anything you want.  The CON is that since you can ask for pretty much anything you want you have to first know what it is that you want. :)  Which leads into my explanation of the differences between ExecuteQuery() and  ExecuteSQLQuery().  Let’s start with ExecuteSQLQuery().

Calling SearchDesktopClass.ExecuteSQLQuery()

The ExecuteSQLQuery() method is pretty much a direct call to the indexers OLE-DB provider via ADO.  The only thing we’ve done is hidden some connection setup details from you.  It wants as an argument the complete SQL statement that should be evaluated by the indexer.  Here’s the SQL generated when you query for “test query” and don’t filter to a specific type:

SELECT DocFormat, Url, HasAttach, Characterization, PerceivedType, IsDeleted, WorkID, IsAttachment, ConversationID, FileExt, Rank, DocTitlePrefix, DocTitle, FlagText, IsFlagged, Create, DueDate, Importance, ToName, CcName, AttachmentNames, DocCompany, Location, DocCategory, DocKeywords, MusicAlbum, FileName, MusicGenre, DocAuthor, PrimaryDate, Size, FileExtDesc, DisplayFolder, PrimaryTelephone, EmailAddress, EndDate, Location, DueDate, TaskStatus, MusicAlbum, MusicGenre, DocComments, DocKeywords, AudioAvgDataRate, DocComments FROM "MyIndex"..scope() WHERE CONTAINS(*,'"test*"',1033) AND CONTAINS(*,'"query*"',1033) ORDER BY PrimaryDate DESC

 

Here’s another example of the same query, “test query” but filtered to only show e-mails:

SELECT DocFormat, Url, HasAttach, Characterization, PerceivedType, IsDeleted, WorkID, IsAttachment, ConversationID, FileExt, Rank, DocAuthor, FromName, DocTitlePrefix, DocTitle, Importance, IsFlagged, IsFlaggedCompleted, FlagText, DueDate, AttachmentNames, BccName, CcName, ToName, People, DocCategory, ReceivedDate, PrimaryDate, FromAddress, ToAddress, CcAddress, BccAddress, Size, DisplayFolder FROM "MyIndex"..scope() WHERE CONTAINS(*,'"test*"',1033) AND CONTAINS(*,'"query*"',1033) AND (Contains(PerceivedType,'email') RANK BY COERCION(Absolute, 1000)) ORDER BY ReceivedDate DESC

These guys look a little overwhelming but they’re not too bad once you understand them.  If you look closely at these two expressions you’ll notice two differences; 1) some of the columns are different because we’ve figured out you’re querying for e-mails and we might want to show those specialized columns to you. And 2) The WHERE clause has changed to accommodate the added constraint need to only return e-mail’s.

So how do you know what to put in your SQL expression?  Well for the columns you just have to know which ones you want.  We don’t have them documented yet because they’re not stable enough to say “We’re going to support these forever!”  But check out the sample app and the examples above for a good starter list and I’ll also try to post some additional sample SQL queries in the near future that call out additional columns.  Just be aware that some of them most likely WILL CHANGE in the future. At any rate the columns is a fairly manageable portion of the expression but the WHERE clause is another story. 

The sample WHERE clauses above are relatively tame because the original query text didn’t contain any Advanced Query Syntax (AQS).  Once you start adding AQS to the mix your WHERE clauses can get messy in a hurry.  To help you out of this jam we added the ExecuteQuery() method.  Remember how I said that’s the only method you’ll ever want to call. :)

Calling SearchDesktopClass.ExecuteQuery()

The ExecuteQuery() method implements the proper logic for building a well formed SQL expression before calling the indexers OLE-DB provider via ADO.  ExecuteQuery() takes the following arguments:

• pcwstrQuery:  This is the text of the users query which MAY contain AQS expressions.  The query will be parsed and converted into a WHERE clause to be passed as part of the SQL expression passed to the indexer.
• lpcwstrColumn:  This is a list of 1 or more columns you want retrieved from the indexer.  This is the SELECT portion of the SQL expression.
• lpcwstrSort:  This is the column you want the results ordered by.  This directly becomes the ORDER BY clause so you’ll need to pass it in as “RecievedDate DESC” or “ReceivedDate ASC”.  This value must be explicitly set to null if you don’t want the results sorted.  Due to a bug in 2.5 passing an empty string (“”) will cause the method to fail.
• lpcwstrRestriction:  This is any optional constraint you want appended to the SQL expressions WHERE clause.  Why do you need this?  It let’s you filter the results to a particular type without have to append the AQS expression of “type:email” to the users query.  To constrain the results to email you’d pass in “Contains(PerceivedType,'email')”. This value must also be explicitly set to null if you don’t want any additional constraint applied.  Due to a bug in 2.5 passing an empty string (“”) will cause the method to fail.

As you can see, calling ExecuteQuery() is a lot simpler then calling ExecuteSQLQuery() even though it takes more arguments.  The only thing special you still need to know is the list of columns you want returned.  But watch this and other blogs for updates to the unofficial list of columns currently supported in 2.5.

Final tips…

In summary we can’t wait to see what cool tools you guys build using the new API’s.  Check out the sample and use that as a starting point.  And here are a couple of final tips for now:

• Create a new SearchDesktopClass instance for every query.  There shouldn’t be any leaks when reusing an existing SearchDesktopClass but in the UI we create a new instance for every query so I’d recommend you do to as this will be the most tested usage pattern.
• Don’t pass empty strings (“”) in any of the arguments to ExecuteQuery() at least for 2.5.  Pass null instead as there is a known bug related to passing empty strings.
• The data binding stuff in the sample is super cool!  But when dealing with really large results sets it may not be super efficient as the entire result set has to be copied to a .NET DataTable object before use.  For ultimate speed you’ll have to stick with using the raw ADO recordset we return but you should at least give the data binding stuff a shot and see if you’re happy with the perf.
• Give us feedback!  Lots and lots of feedback.  We are listening…

-Steve 

To create the Debug.htm file copy everything below the “—copy—“ line into an empty Notepad.exe document.  Then save the document AS UTF-8 to “c:\Debug.htm”.  The saved file MUST be UTF-8 encoded.   Use Notepads Save As feature to do this because the default for Notepad is to save as Unicode which won’t work.

—copy—

<html>

   <head>

      <!-- Template: debug.htm -->

      <meta http-equiv="content-type" content="text/html; charset=UTF-8">

      <style>

            .debug-group       { font-family: tahoma; font-size: 12pt; border: 1px solid #7EB6F0; background-color: #2765AB; color: #FFFFFF; }

            .debug-row-header  { font-family: tahoma; font-size: 10pt;background-color: #FFFFFF; color: green; }

        .debug-row-hidden  { font-family: tahoma; font-size: 8pt; background-color: #EEF4FB; color: black; }

        .debug-row         { font-family: tahoma; font-size: 8pt; background-color: #FFFFFF; color: black; }

            .debug-cell-header { border-bottom: 1px solid #7EB6F0; }

        .debug-cell        { border-bottom: 1px solid #7EB6F0; }

      </style>

      <script>

        function AddHiddenRow( prop, title, value )

        {

           document.write('<tr class="debug-row-hidden">');

           document.write('<td class="debug-cell">' + prop + '</td>');

           document.write('<td class="debug-cell">' + title + '&nbsp;</td>');

           document.write('<td class="debug-cell">' + value + '&nbsp;</td>');

           document.write('</tr>');

        }

        function AddRow( prop, title, value )

        {

           document.write('<tr class="debug-row">');

           document.write('<td class="debug-cell">' + prop + '</td>');

           document.write('<td class="debug-cell">' + title + '&nbsp;</td>');

           document.write('<td class="debug-cell">' + value + '&nbsp;</td>');

           document.write('</tr>');

        }

      </script>

   </head>

   <body leftmargin="0" topmargin="0" marginwidth="0" marginheight="0">

      <!-- First we'll dump out the available properties -->

      <br>

      <div align="center" style="width: 100%; padding: 0px 15px 0px 15px;">

         <div class="debug-group" align="left" style="width: 100%; height=100%;">

            <div style="padding: 5px 5px 5px 5px;">Item properties</div>

            <div style="overflow: auto; width: 100%;">

               <table border="0" width="100%" cellspacing="0" cellpadding="5">

                  <tr class="debug-row-header">

                     <td class="debug-cell-header" width="100">Property</td>

                     <td class="debug-cell-header" width="100">Title</td>

                     <td class="debug-cell-header">Value</td>

                  </tr>

                  <script>

                     <%if:DocFormat%>

                        AddHiddenRow('DocFormat', '<%title:DocFormat%>', '<%value:DocFormat%>');

                     <%endif%>

                     <%if:Url%>

                        AddHiddenRow('Url', '<%title:Url%>', '<%value:Url%>');

                     <%endif%>

                     <%if:HasAttach%>

                        AddHiddenRow('HasAttach', '<%title:HasAttach%>', '<%value:HasAttach%>');

                     <%endif%>

                     <%if:PerceivedType%>

                        AddHiddenRow('PerceivedType', '<%title:PerceivedType%>', '<%value:PerceivedType%>');

                     <%endif%>

                     <%if:IsDeleted%>

                        AddHiddenRow('IsDeleted', '<%title:IsDeleted%>', '<%value:IsDeleted%>');

                     <%endif%>

                     <%if:WorkID%>

                        AddHiddenRow('WorkID', '<%title:WorkID%>', '<%value:WorkID%>');

                     <%endif%>

                     <%if:IsAttachment%>

                        AddHiddenRow('IsAttachment', '<%title:IsAttachment%>', '<%value:IsAttachment%>');

                     <%endif%>

                     <%if:ConversationID%>

                        AddHiddenRow('ConversationID', '<%title:ConversationID%>', '<%value:ConversationID%>');

                     <%endif%>

                     <%if:FileExt%>

                        AddHiddenRow('FileExt', '<%title:FileExt%>', '<%value:FileExt%>');

                     <%endif%>

                     <%if:Rank%>

                        AddRow('Rank', '<%title:Rank%>', '<%value:Rank%>');

                     <%endif%>

                     <%if:DocTitlePrefix%>

                        AddRow('DocTitlePrefix', '<%title:DocTitlePrefix%>', '<%value:DocTitlePrefix%>');

                     <%endif%>

                     <%if:DocTitle%>

                        AddRow('DocTitle', '<%title:DocTitle%>', '<%value:DocTitle%>');

                     <%endif%>

                     <%if:DocAuthor%>

                        AddRow('DocAuthor', '<%title:DocAuthor%>', '<%value:DocAuthor%>');

                     <%endif%>

                     <%if:PrimaryDate%>

                        AddRow('PrimaryDate', '<%title:PrimaryDate%>', '<%value:PrimaryDate%>');

                     <%endif%>

                     <%if:Size%>

                        AddRow('Size', '<%title:Size%>', '<%value:Size%>');

                     <%endif%>

                     <%if:FileExtDesc%>

                        AddRow('FileExtDesc', '<%title:FileExtDesc%>', '<%value:FileExtDesc%>');

                     <%endif%>

                     <%if:DisplayFolder%>

                        AddRow('DisplayFolder', '<%title:DisplayFolder%>', '<%value:DisplayFolder%>');

                     <%endif%>

                     <%if:FlagText%>

                        AddRow('FlagText', '<%title:FlagText%>', '<%value:FlagText%>');

                     <%endif%>

                     <%if:IsFlagged%>

                        AddRow('IsFlagged', '<%title:IsFlagged%>', '<%value:IsFlagged%>');

                     <%endif%>

                     <%if:Create%>

                        AddRow('Create', '<%title:Create%>', '<%value:Create%>');

                     <%endif%>

                     <%if:DueDate%>

                        AddRow('DueDate', '<%title:DueDate%>', '<%value:DueDate%>');

                     <%endif%>

                     <%if:Importance%>

                        AddRow('Importance', '<%title:Importance%>', '<%value:Importance%>');

                     <%endif%>

                     <%if:ToName%>

                        AddRow('ToName', '<%title:ToName%>', '<%value:ToName%>');

                     <%endif%>

                     <%if:CcName%>

                        AddRow('CcName', '<%title:CcName%>', '<%value:CcName%>');

                     <%endif%>

                     <%if:AttachmentNames%>

                        AddRow('AttachmentNames', '<%title:AttachmentNames%>', '<%value:AttachmentNames%>');

                     <%endif%>

                     <%if:DocCompany%>

                        AddRow('DocCompany', '<%title:DocCompany%>', '<%value:DocCompany%>');

                     <%endif%>

                     <%if:Location%>

                        AddRow('Location', '<%title:Location%>', '<%value:Location%>');

                     <%endif%>

                     <%if:DocCategory%>

                        AddRow('DocCategory', '<%title:DocCategory%>', '<%value:DocCategory%>');

                     <%endif%>

                     <%if:DocKeywords%>

                        AddRow('DocKeywords', '<%title:DocKeywords%>', '<%value:DocKeywords%>');