Microsoft KB Archive/919198

= Notification-based indexing support for store providers in Outlook 2007 =

Article ID: 919198

Article Last Modified on 4/25/2007

-

APPLIES TO


 * Microsoft Office Outlook 2007

-





SUMMARY
''Microsoft Office Outlook 2007 includes changes to support notification-based indexing for store providers. This article contains the information that a developer must have to create a store provider that uses notification-based indexing in Outlook 2007.''



INTRODUCTION
This article describes changes in Microsoft Office Outlook 2007 to support notification-based indexing for store providers.

A store provider can support notification-based indexing when the following conditions are true:
 * The store provider does not require crawls by the MAPI Protocol Handler.
 * The store provider indexes all items by using notifications.

These types of store providers are sometimes referred to as &quot;pusher&quot; stores because they &quot;push&quot; URLs to the indexer by calling the appropriate indexer API function. Each URL corresponds to a message, a folder, or an attachment. The indexer passes the URLs to the MAPI Protocol Handler. The MAPI Protocol Handler then parses the URL to determine the corresponding message, folder, or attachment object. The MAPI Protocol Handler opens the object by using MAPI and obtains the properties to be indexed. The text is returned to the indexer. The indexer parses the text and saves the terms in the catalog.

Note Some properties, such as the body or an attachment, may require that you use a filter host. The filter host is a different process that uses an IFilter object to open the documents. The filter host can then extract the text so that the indexer can parse it.



MORE INFORMATION
The following sections describe the changes in Outlook 2007 to support notification-based indexing by store providers.

Definition

 * 1) define STORE_PUSHER_OK        ((ULONG) 0x00800000)

Usage
Set this flag for a store provider that is a &quot;pusher&quot; store. If a store provider sets this flag, the MAPI Protocol Handler does not crawl the store provider. The store provider is responsible for pushing any notification-based changes to the indexer.

You can determine whether this flag is set by obtaining the PR_STORE_SUPPORT_MASK property from the store provider.

Definition

 * 1) define PR_PROVIDER_ITEMID                 PROP_TAG(PT_BINARY,     0x0EA3)
 * 2) define PR_PROVIDER_PARENT_ITEMID          PROP_TAG(PT_BINARY,     0x0EA4)

Usage
Use these properties in a store provider to identify an item or a folder. These properties are retrieved when a store provider obtains the search results from the search engine. These properties identify which items match the query.

Store providers can set provider-specific values for these properties. However, you should not change the property values between sessions. Otherwise, the items may not be mapped correctly when you obtain the search results.

MAPI URLs
Store providers must create a unique Unicode-encoded MAPI URL and then send it to the indexer every time that a folder, a message, or an attachment is to be indexed. This URL is used later to identify which object will be indexed in the MAPI Protocol Handler.

MAPI URLs have the following format:

Mapi:// / ($ )/ / /[ [?at= : ]]

The following list defines the placeholders in this MAPI URL:   represents the security identifier (SID) for the current user.  represents the display name for the store.  represents a DWORD hexadecimal value. The DWORD value is based on the store entry ID or the file path. This value is stored in the registry and is used to identify the store in the MAPI Protocol Handler. The DWORD value must be calculated in a way that minimizes collisions between other stores.  represents a number that identifies the type of the store that contains the object to be indexed. The following table shows the possible values for.

Note The value for stores that have been crawled by the indexer is always X.  represents the path from the root of the IPM_SUBTREE folder to the folder or to the message. For example, Inbox/Family specifies a message in the Family folder under the Inbox folder.  represents the MAPI Entry ID for the item. is encoded as a Unicode string.</li>  represents the MAPI Attachment ID for the item. is encoded as a Unicode string.</li>  represents the attachment file name as it appears in the message.</li></ul>

MAPI URL examples
This is an example of a MAPI URL for a folder:

mapi://S-1-5-21-2127521184-1604012920-1887927527-71418/Mailbox – Some User ($be19928f)/2/Office

This is an example of a MAPI URL for a message. It contains Hangul (Korean) Unicode-encoded characters:

mapi://S-1-5-21-2127521184-1604012920-1887927527-71418/Mailbox – Some User ($484efb89)/0/Calendar/곯가가가걍걝걌곌겷걢곒갑겛개가검걟곔걙곾걤곂갠가

This is an example of a MAPI URL for an attachment. It contains Hangul (Korean) Unicode-encoded characters:

mapi://S-1-5-21-2127521184-1604012920-1887927527-71418/Mailbox – Some User ($484efb89)/0/Inbox/곯가가가걍걝걌곌겷걢곒갑겛개가검걟곔걙곾간곷갦가/at=겅걋각가:somefile.txt

MAPI URL code examples
The following code example demonstrates how Outlook calculates the hash number for a MAPI URL. DWORD ComputeStoreHash(ULONG cbStoreEID, LPENTRYID pbStoreEID, LPCWSTR pwzFileName) {   DWORD   dwHash = 0; ULONG  cdw = 0; DWORD* pdw = NULL; ULONG  cb  = 0; BYTE*  pb  = NULL; ULONG  i = 0;

// Get the Store Entry ID   // pbStoreEID is a pointer to the Entry ID    // cbStoreEID is the size in bytes of the Entry ID    pdw = (DWORD*)pbStoreEID; cdw = cbStoreEID / sizeof(DWORD);

for (i = 0; i < cdw; i++) {       dwHash = (dwHash << 5) + dwHash + *pdw++; }

pb = (BYTE *)pdw; cb = cbStoreEID % sizeof(DWORD);

for (i = 0; i < cb; i++) {       dwHash = (dwHash << 5) + dwHash + *pb++; }

// You may want to also include the store file name in the hash calculation // Get store FileName // pwzFileName is a NULL terminated string with the path and filename of the store if (pwzFileName) {       while (*pwzFileName) {           dwHash = (dwHash << 5) + dwHash + *pwzFileName++; }   }    // dwHash now contains the hash to be used. It should be written in hex when building the URL. return dwHash; }// ComputeStoreHash The following code example demonstrates how to encode the MAPI Entry ID and the MAPI Attachment ID in Unicode for a MAPI URL. const WORD kwBaseOffset = 0xAC00; // Hangul char range (AC00-D7AF) LPWSTR EncodeID(ULONG cbEID, LPENTRYID rgbID) {   ULONG   i = 0; LPWSTR pwzDst = NULL; LPBYTE pbSrc = NULL; LPWSTR pwzIDEncoded = NULL;

// rgbID is the item Entry ID or the attachment ID   // cbID is the size in bytes of rgbID

// Allocate memory for pwzIDEncoded pwzIDEncoded = new WCHAR[cbEID]; if (!pwzIDEncoded) return NULL;

for (  i = 0, pbSrc = (LPBYTE)rgbID, pwzDst = pwzIDEncoded;        i < cbEID;        i++, pbSrc++, pwzDst++) {       *pwzDst = (WCHAR) (*pbSrc + kwBaseOffset); }

// Ensure NULL terminated *pwzDst = L'\0';

// pwzIDEncoded now contains the entry ID encoded. return pwzIDEncoded; }// EncodeID

MAPI notification type for &quot;pusher&quot; stores
A MAPI notification type has been added to facilitate shutdown scenarios for &quot;pusher&quot; stores. These stores must keep track of what has to be pushed to the indexer. This is because the stores may not be able to index everything before a shutdown occurs. A &quot;pusher&quot; store provider should send the following notification to make sure that the MAPI Protocol Handler knows which process to monitor for a given store. If the process is shut down or unexpectedly exits (crashes), the MAPI Protocol Handler can immediately close the store.

Definition

 * 1) define fnevIndexing       ((ULONG) 0x00010000)

/* Indexing notifications (used for FTE related communications)    */ /* Shares EXTENDED_NOTIFICATION to pass structures below,      */ /* but NOTIFICATION type will be fnevIndexing              */

// Stores that are pusher enabled (PR_SUPPORT_MASK contains STORE_PUSHER_OK) // are required to send notifications regarding the process that is pushing.
 * 1) define INDEXING_SEARCH_OWNER      ((ULONG) 0x00000001)

typedef struct _INDEX_SEARCH_PUSHER_PROCESS {   DWORD       dwPID;          /* PID for process pushing */ } INDEX_SEARCH_PUSHER_PROCESS;

Binary large object (BLOB) for MAPI URLs
Stores that push MAPI URLs for indexing should also create a binary large object. The binary large object contains additional information that is used by the MAPI Protocol Handler. The binary large object is associated with each MAPI URL. Additionally, the binary large object is sent when the MAPI URL is pushed to the indexer.

Definition
DWORD  dwVersion DWORD  dwFlags ULONG  cbProfileName WCHAR  wszProfileName ULONG  cbProviderItemID WCHAR  wszProviderItemID Note You must write these values to the binary large object in the order that is shown. The provider item ID should only be sent for folders. This makes sure that extra folders are not opened.

The following table describes the members in the binary large object.

MAPI Protocol Handler named properties
The following named properties are indexed by the MAPI Protocol Handler. These properties are read-only. They should not be used to create items or to modify items.

Definitions
The following GUIDs represent the namespaces of the named properties. const GUID PSETID_Appointment  = {0x00062002, 0x0000, 0x0000, {0xC0, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x46}}; const GUID PSETID_Task         = {0x00062003, 0x0000, 0x0000, {0xC0, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x46}}; const GUID PSETID_Address      = {0x00062004, 0x0000, 0x0000, {0xC0, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x46}}; const GUID PSETID_Common       = {0x00062008, 0x0000, 0x0000, {0xC0, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x46}}; const GUID PSETID_Log          = {0x0006200A, 0x0000, 0x0000, {0xC0, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x46}}; const GUID PS_PUBLIC_STRINGS   = {0x00020329, 0x0000, 0x0000, {0xC0, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x46}}; const GUID PS_INTERNET_HEADERS = {0x00020386, 0x0000, 0x0000, {0xC0, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x46}}; These are the MNID_ID named properties. // In PSETID_Address
 * 1) define dispidWorkAddressStreet 0x8045
 * 2) define dispidWorkAddressCity 0x8046
 * 3) define dispidWorkAddressState 0x8047
 * 4) define dispidWorkAddressPostalCode 0x8048
 * 5) define dispidWorkAddressCountry 0x8049
 * 6) define dispidInstMsg 0x8062
 * 7) define dispidEmailDisplayName 0x8080
 * 8) define dispidEmailOriginalDisplayName 0x8084

// In PSETID_Task
 * 1) define dispidTaskStartDate 0x8104
 * 2) define dispidTaskDueDate 0x8105
 * 3) define dispidTaskActualEffort 0x8110
 * 4) define dispidTaskEstimatedEffort 0x8111
 * 5) define dispidTaskFRecur 0x8126

// In PSETID_Appointment
 * 1) define dispidLocation 0x8208
 * 2) define dispidApptStartWhole 0x820D
 * 3) define dispidApptEndWhole 0x820E
 * 4) define dispidApptDuration 0x8213
 * 5) define dispidRecurring 0x8223
 * 6) define dispidAllAttendeesString 0x8238
 * 7) define dispidToAttendeesString 0x823B
 * 8) define dispidCCAttendeesString 0x823C

// In PSETID_Common
 * 1) define dispidReminderSet 0x8503
 * 2) define dispidSmartNoAttach 0x8514
 * 3) define dispidCommonStart 0x8516
 * 4) define dispidCommonEnd 0x8517
 * 5) define dispidRequest 0x8530
 * 6) define dispidCompanies 0x8539
 * 7) define dispidReminderNextTime 0x8560

// In PSETID_Log (also known as Journal) These are the MNID_STRING named properties. // In PS_PUBLIC_STRINGS &quot;Keywords&quot;
 * 1) define dispidLogType 0x8700
 * 2) define dispidLogStart 0x8706
 * 3) define dispidLogDuration 0x8707
 * 4) define dispidLogEnd 0x8708

// In PS_INTERNET_HEADERS &quot;return-path&quot;

Additional query words: OL2007 Outlook2007

Keywords: kbexpertiseinter kbhowto kbinfo KB919198

-

[mailto:TECHNET@MICROSOFT.COM Send feedback to Microsoft]

© Microsoft Corporation. All rights reserved.