Pocket Outlook Object Model Registry Settings

Windows Mobile 6.5
4/8/2010

This topic covers Source Provider registry settings, and settings for other types of customization.

Source Providers and their associated Source ID's are part of a mechanism that supports per-provider customization of the Personal Information Management (PIM) experience on Windows® phones. A Source Provider is a custom function that customizes the PIM user experience. Typically, a Source Provider has a corresponding associate function that is responsible for synchronizing PIM data with the phone. Data synchronized with the phone by this associate function is marked with a Source identification tag (Source ID). When Outlook Mobile displays a PIM item, it checks to see if the item has a Source ID. If it finds one, it invokes the Source Provider, which customizes the user interface for the PIM item.

You register a Source Provider on a Windows phone under the HKEY_LOCAL_MACHINE\System\PIMSources registry key, using the registry paths and values defined in the following tables.

\\HKLM

 

 

 

 

 

Key

 

\System

 

 

 

 

Key

 

 

\PIMSources

 

 

 

Key

 

 

 

\<SourceID>

 

 

Key

 

 

 

 

\Colors

 

Key

 

 

 

 

 

\1

Entry

 

 

 

 

\Customizations

 

Entry

 

 

 

 

\Type

 

Entry

 

 

 

 

\CLSID

 

Entry

Start by creating a <SourceID> subkey under PIMSources. The subkey name will be your Source ID. Choose a SourceID that follows the sequence 1, 2, 4, etc. (exactly one bit set).

Bb446155.note(en-us,MSDN.10).gifNote:
When you register your Source Provider, be sure that you create a Source ID that is not already in use on the Windows phone. It is your responsibility to ensure that your registration does not collide with other sources.

The following table lists the constants that denote the registry paths, keys, and values you can use to programmatically register your Source Provider.

Name Value Type Format Description

PIMSRC_REGPATH_ROOT

L"System\\PIMSources"

REG_SZ

 

The route for all Source Providers. A key called PIMSources is located under the write-protected key HKEY_LOCAL_MACHINE\System.

PIMSRC_REGPATH_COLORS

L"Colors"

L"1"

REG_SZ

REG_DWORD

 

A subkey under the SourceID key. Include this subkey if you want your Source Provider to support alternate background colors for Appointments in the Agenda and Day views.

To specify the color you want, create an entry under this subkey, and give it the name "1" (from the PIMSRC_COLOR enumeration). The decimal value you assign to "1" represents the color. For example, a value of 65280 represents the color green, because the hexadecimal equivalent of 65280 is 00FF00 (Red:0, Green:255, Blue:0).

PIMSRC_REGVALUE_CLSID

L"CLSID"

REG_SZ

{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}

An entry under the SourceID key. Its value represents the GUID of the COM class that implements your Source Provider.

PIMSRC_REGVALUE_CUSTOMIZATIONS

L"Customizations"

REG_DWORD

A combination of PIMSRC_CUSTOM_* values.

An entry under the SourceID key. Its value describes the UI customizations that the Source Provider provides. This is the decimal equivalent of a bitmask that represents a combination of Source Provider Customization Type Flags.

For example, the decimal value 5 specifies that you support both customized Summary tabs and alternate icons.

PIMSRC_REGVALUE_ICON

L"Icon"

REG_SZ

"<dll name>, #<resource id>"

Pointer to an icon resource that represents the source provider.

Text size is limited to 255.

PIMSRC_REGVALUE_TYPE

L"Type"

REG_DWORD

A combination of PIMSRC_TYPE_* values.

An entry under the SourceID key. Its value describes the PIM items types that the Source Provider handles. This is the decimal equivalent of a bitmask that represents a combination of Source Provider PIM Type Ownership Flags.

For example, the decimal value 3 specifies that you support both Contact and Appointment items.

PIMSRC_REGVALUE_DISPLAYNAME

L"DisplayName"

REG_MUI_SZ or REG_SZ

For REG_MUI_SZ:"<dll name>, #<resource id>"

For REG_SZ:A text string.

The display name for the Source Provider. A localized text string.

Note   If you do not provide a value for this key, then the IPimSrcContactNew source will not appear in the Choose Contact Type list, even if the customization flag PIMSRC_CUSTOM_CONTACTS_NEW is set. For more information, see Source Provider Customization Type Flags.

When users enter new PIM data on the Windows phone, they will be able to select the Source Provider to use.

PIM items with a Source ID value of zero just use the default user interface.

As part of your Source Provider uninstall procedure, make sure that all PIM items associated with your Source Provider have their Source ID's changed to zero.

Description

The following code example shows a portion of source provider registration code that changes the contact type icon that is used in the dialog box that appears to ask users to choose a contact type.

Code

const LPWSTR g_szIconID   = L",101";
WCHAR szIconFullPath[256] = {0};

// Set the icon for this provider.
hr = GetModuleFileName(GetModuleHandle(g_szDllName), szIconFullPath, 250);
CHR(hr);

wcscat(szIconFullPath, g_szIconID);

hr = RegistrySetString(hkeySource, NULL, PIMSRC_REGVALUE_ICON, szIconFullPath);
CHR(hr);

To specify whether email contact groups, messaging contact groups, or both group types appear in the contact type chooser user interface, you must set the following HKCU\Security\Software\Microsoft\ActiveSync registry key value.

Name Type Description

ContactGroups

DWORD

If this value is set to 0 or does not exist then neither contact group will appear in the contact chooser user Interface.

1 = enable email groups

2 = enable messaging groups

3 = enable both group

The email contact groups and the messaging contact groups can be included in the suggestion list that appears when the user begins typing in the “To” or “CC” fields of an email message. Two registry keys control this. One key enables the inclusion of contact groups in the list. The other registry key specifies which contact groups will be included in the list.

You set the following HKEY_LOCAL_MACHINE\SYSTEM\Inbox\RecipientAutocomplete\SuggestionGenerators registry key value to enable the inclusion of contacts groups in the suggestion list.

Name Type Description

phone

REG_SZ

To enable contacts groups in the suggestion list use GUID "{BEBD4D6C-33D1-473f-8F78-FB1A42712610}".

Bb446155.note(en-us,MSDN.10).gifNote:
Use this as the default setting

To disable contacts groups use GUID "{45EEED9B-898C-4caf-BC3E-A5422F56085B}"

To specify which contact groups will appear in the suggestion list, you must set the following HKEY_LOCAL_MACHINE\SYSTEM\Inbox\RecipientAutocomplete IncludeContactsGroups registry key value.

Name Type Description

IncludeContactsGroups

DWORD

0 = include no group

1 = include email group

2 = include messaging group

Applies to Windows Mobile 6.5.3

A user composing an e-mail can invoke contact chooser control, which provides access to the Contact application interface for selecting Contacts in your application. An OEM can provide a custom contact chooser to be invoked instead of the default Windows Mobile contact chooser. The technique to do this is to write a function named CustomChooseMultipleContacts and to set a registry key that specifies the module that implements this function. When this registry key and function exists, e-mail compose view will invoke the custom function rather than ChooseContact.

CustomChooseMultipleContacts takes one parameter - LPCHOOSEMULTIPLECONTACTS which can hold multiple contacts selection information. This function returns a standard HRESULT.

HRESULT CustomChooseMultipleContacts(
  LPCHOOSEMULTIPLECONTACTS
);
Bb446155.note(en-us,MSDN.10).gifNote:
LPCHOOSEMULTIPLECONTACTS is defined in a public header file (\public\apps\sdk\inc\pimstore.h).

The registry key is:

HKEY_LOCAL_MACHINE\Security\Contacts

The registry value is:

Name Type Description

CustomChooseContactModule

REG_SZ

This is the name of the module containing CustomChooseMultipleContacts. The module should be placed in the \Windows directory.

The following Contact Chooser settings are stored in the registry key HKEY_LOCAL_MACHINE\Security\Contacts\Chooser.

These settings do not apply to the property picker list view that appears when CCF_CHOOSEPROPERTYONLY flag is TRUE (see Contact Chooser Flags).

Name Type Description

LVItemHeight

REG_DWORD

Sets the list view item height in pixels when the ChooseContact API is used to choose a contact.

If this value is not set, the list view item height will be determined from font metric and standard spacing constants.

LVBackgroundColor

REG_DWORD

Sets the background color of the Contact Chooser list view as a COLORREF value.

If this value is not set, the default system color will be used.

OEMs can customize the title box of the Contacts Chooser on Windows Mobile Professional. The following elements of the title box can be customized.

  • Control height
  • Background color
  • Background bitmap
  • Transparency
  • Text Color
  • Text positioning
  • Text background color
  • Text font

To customize the title box of Contact Chooser, create the following registry key and values.

HKEY_LOCAL_MACHINE\Security\Contacts\Chooser\Title.

Name Type Description

ctrlHeight

DWORD

Specifies the height in pixels of the title box control.

bmpPortrait

REG_SZ

Specifies the file path of the background image to use in portrait mode. A background image will only be displayed if the bmpPortrait and bmpLandscape values are correctly specified. Otherwise, the background color will be displayed.

bmpLandscape

REG_SZ

Specifies the file path of the background image to use in landscape mode. A background image will only be displayed if the bmpPortrait and bmpLandscape values are correctly specified. Otherwise the background color will be displayed.

backgroundColor

DWORD

COLOREF value which specifies the background color title box. The background color is only used if the bmpPortrait and bmpLandscape values are not correctly specified.

Title Box Text

To customize the text for the title box of the Contacts Chooser, create the following registry key and values.

HKEY_LOCAL_MACHINE\Security\Contacts\Chooser\Title\Text.

The following font settings are used to populate a LOGFONT structure. The member that each value populates is specified in the descriptions below. For a complete description of each member, see LOGFONT.

Name Type Description

Name

REG_SZ

Specifies the font name. This value populates the lfFaceName member.

Height

REG_DWORD

Specifies the font height. This value populates the lfHeight member.

Italic

REG_DWORD

Specifies and italic font if the value is set to 1. This value populates the lfItalic member.

Weight

REG_DWORD

Specifies the font weight. This value populates the lfWeight member.

CharSet

REG_DWORD

Specifies the font character set. This value populates the lfCharSet member.

Quality

REG_DWORD

Specifies the output quality. This value populates the lfQuality member.

textColor

REG_DWORD

COLORREF value which specifies the color of the text.

textFlags

REG_DWORD

Specifies the alignment of the text. For the list of possible values, refer the uformat parameter of the DrawText function in the topic with the same type of flags specified in DrawText. For an example of how to use DrawText flags as registry settings, see public\common\sdk\inc\wingdi.h.

backgroundColor

REG_DWORD

COLORREF value which specifies the background color of the text. The default value specifies a transparent background. If this value is not specified, the default value is used.

bkTransparent

REG_DWORD

1 specifies a transparent background. 0 specifies a non transparent background.

OEMs can customize the search bar for the Contacts Chooser. The search bar consists of a tool bar that contains a combo box and an edit control.

To customize the search bar for the Contacts chooser, create the following registry key and values.

HKEY_LOCAL_MACHINE\Security\Contacts\Chooser\Search.

Name Type Description

ctrlHeight

REG_SZ

Specifies the height in pixels of the tool bar. This value is automatically scaled on hi dpi resolutions.

bmpPortrait

REG_DWORD

Specifies the file path of the background image to use in portrait mode. A background image will only be displayed if the bmpPortrait and bmpLandscape values are correctly specified. Otherwise the background color will be displayed.

bmpLandscape

REG_DWORD

Specifies the file path of the background image to use in landscape mode. A background image will only be displayed if the bmpPortrait and bmpLandscape values are correctly specified. Otherwise the background color will be displayed.

backgroundColor

REG_DWORD

COLOREF value which specifies the background color title box. The background color is only used if the bmpPortrait and bmpLandscape values are not correctly specified.

ctrlStyle

REG_DWORD

Additional styling to be OR'ed with the existing style of the control, (WS_CHILD). Currently, only WS_BORDER is supported. If this is not defined, WS_BORDER will be used.

disableCombobox

REG_DWORD

Indicates whether the combo box should be disabled. 1 disables the combo box, 0 enables it.

cxPadding

REG_DWORD

Specifies the x-distance between the tool bar and the edit control. This value is automatically scaled on hi dpi resolutions.

cyPadding

REG_DWORD

Specifies the y-distance between the tool bar and the edit control. This value is automatically scaled on hi dpi resolutions.

Search Bar Text

To customize the text of the search bar for the Contacts Chooser, create the following registry key and values.

HKEY_LOCAL_MACHINE\Security\Contacts\Chooser\Search\Text.

The following font settings are used to populate a LOGFONT structure. The member that each value populates is specified in the descriptions below. For a complete description of each member, see LOGFONT.

Name Type Description

Name

REG_SZ

Specifies the font name. This value populates the lfFaceName member.

Height

REG_DWORD

Specifies the font height. This value populates the lfHeight member.

Italic

REG_DWORD

Specifies and italic font if the value is set to 1. This value populates the lfItalic member.

Weight

REG_DWORD

Specifies the font weight. This value populates the lfWeight member.

CharSet

REG_DWORD

Specifies the font character set. This value populates the lfCharSet member.

Quality

REG_DWORD

Specifies the output quality. This value populates the lfQuality member.

textColor

REG_DWORD

COLORREF value which specifies the background color of the text. The default value specifies a transparent background. If this value is not specified, the default value is used.

backgroundColor

REG_DWORD

1 specifies a transparent background. 0 specifies a non transparent background.

OEMs can customize the font and color of the text in the body of the Contact Chooser list view when the list view is empty.

Use the following registry key and values to make this customization. HKEY_LOCAL_MACHINE\Security\Contacts\Chooser\ListView\Text.

The following font settings are used to populate a LOGFONT structure. The member that each value populates is specified in the descriptions below. For a complete description of each member, see LOGFONT.

Name Type Description

Name

REG_SZ

Specifies the font name. This value populates the lfFaceName member.

Height

REG_DWORD

Specifies the font height. This value populates the lfHeight member.

Italic

REG_DWORD

Specifies and italic font if the value is set to 1. This value populates the lfItalic member.

Weight

REG_DWORD

Specifies the font weight. This value populates the lfWeight member.

CharSet

REG_DWORD

Specifies the font character set. This value populates the lfCharSet member.

Quality

REG_DWORD

Specifies the output quality. This value populates the lfQuality member.

textColor

REG_DWORD

COLORREF value which specifies the color of the text.

backgroundColor

REG_DWORD

COLORREF value which specifies the background color of the text. The default value specifies a transparent background. If this value is not specified, the default value is used.

A developer can customize what happens in response to a user selecting a hyperlink in the calendar application. The developer must provide event handlers to implement the desired behavior. The event handlers are the OnEmail and OnPhoneNumber methods of the ICalContactLinkHandler interface.

The interface must be placed into a COM object, and the CLSID of the COM object must be specified in registry key:

HKEY_LOCAL_MACHINE]\Software\Microsoft\Calendar\OEM

The value is:

Name Type Description

CustomContactHandler

REG_DWORD

The CLSID of the COM object that implements the ICalContactLinkHandler interface.

For an overview of Action key customization, see Customizing Action Key Behavior for Calendar Hyperlinks.

Headerpimstore.h
LibraryPimstore.lib
Windows Embedded CEWindows CE 3.0 and later
Windows MobilePocket PC 2000 and later, Smartphone 2002 and later

Community Additions

Show: