Notification-based indexing support for store providers in Outlook 2007 (919198)


The information in this article applies to:

  • Microsoft Office Outlook 2007

Beta Information

This article discusses a Beta release of a Microsoft product. The information in this article is provided as-is and is subject to change without notice.

No formal product support is available from Microsoft for this Beta product. For information about how to obtain support for a Beta release, see the documentation that is included with the Beta product files, or check the Web location where you downloaded the release.

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 "pusher" stores because they "push" 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.

"Pusher" store provider mask flag

Definition
#define STORE_PUSHER_OK			((ULONG) 0x00800000)
UsageSet this flag for a store provider that is a "pusher" 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.

MAPI Protocol Handler properties

Definition
#define PR_PROVIDER_ITEMID          		PROP_TAG(PT_BINARY, 	0x0EA3)
#define PR_PROVIDER_PARENT_ITEMID   		PROP_TAG(PT_BINARY, 	0x0EA4)
UsageUse 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://SID/StoreDisplayName ($HashNumber)/StoreType/FolderNameA/./FolderNameN/[EntryIDEncoded[?at=AttachIDEncoded:FileName]]

The following list defines the placeholders in this MAPI URL:
  • SID represents the security identifier (SID) for the current user.
  • StoreDisplayName represents the display name for the store.
  • HashNumber 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.
  • StoreType 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 StoreType.
    ValueStore type
    0Normal store. This includes stores that are not public or delegate stores, such as default stores, personal folder files (PSTs), and so on.
    1Delegate store. These stores are used for delegate items that are cached locally.
    2Public folder. These folders are used to store public folder favorites.
    Note The value for stores that have been crawled by the indexer is always X.
  • FolderNameA/./FolderNameN 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.
  • EntryIDEncoded represents the MAPI Entry ID for the item. EntryIDEncoded is encoded as a Unicode string.
  • AttachIDEncoded represents the MAPI Attachment ID for the item. AttachIDEncoded is encoded as a Unicode string.
  • FileName represents the attachment file name as it appears in the message.
MAPI URL examplesThis 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 examplesThe 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 "pusher" stores

A MAPI notification type has been added to facilitate shutdown scenarios for "pusher" 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 "pusher" 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
#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.
#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.
MemberPurpose
dwVersionThe version of the data being sent. Currently, this value is 1.
dwFlagsReserved for future use. Currently, this value is 0.
cbProfileNameSize of the profile name in bytes. The MAPI Protocol Handler uses this value to know which profile to use when it indexes the item.
wszProfileNameNull-terminated Unicode string that contains the profile name.
cbProviderItemIDSize of the provider item ID in bytes.
wszProviderItemIDNull-terminated Unicode string that contains the provider item ID. The provider item ID uniquely identifies the item in the store.

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. DefinitionsThe 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
#define dispidWorkAddressStreet 0x8045
#define dispidWorkAddressCity 0x8046
#define dispidWorkAddressState 0x8047
#define dispidWorkAddressPostalCode 0x8048
#define dispidWorkAddressCountry 0x8049
#define dispidInstMsg 0x8062
#define dispidEmailDisplayName 0x8080
#define dispidEmailOriginalDisplayName 0x8084

// In PSETID_Task
#define dispidTaskStartDate 0x8104
#define dispidTaskDueDate 0x8105
#define dispidTaskActualEffort 0x8110
#define dispidTaskEstimatedEffort 0x8111
#define dispidTaskFRecur 0x8126

// In PSETID_Appointment
#define dispidLocation 0x8208
#define dispidApptStartWhole 0x820D
#define dispidApptEndWhole 0x820E
#define dispidApptDuration 0x8213
#define dispidRecurring 0x8223
#define dispidAllAttendeesString 0x8238
#define dispidToAttendeesString 0x823B
#define dispidCCAttendeesString 0x823C

// In PSETID_Common
#define dispidReminderSet 0x8503
#define dispidSmartNoAttach 0x8514
#define dispidCommonStart 0x8516
#define dispidCommonEnd 0x8517
#define dispidRequest 0x8530
#define dispidCompanies 0x8539
#define dispidReminderNextTime 0x8560

// In PSETID_Log (also known as Journal)
#define dispidLogType 0x8700
#define dispidLogStart 0x8706
#define dispidLogDuration 0x8707
#define dispidLogEnd 0x8708
These are the MNID_STRING named properties.
// In PS_PUBLIC_STRINGS 
"Keywords" 

// In PS_INTERNET_HEADERS
"return-path"
Modification Type:MajorLast Reviewed:6/26/2006
Keywords:kbExpertiseInter kbhowto kbinfo KB919198 kbAudDeveloper
©2004 Microsoft Corporation. All rights reserved.