Pocket Outlook Object Model Registry Settings
4/8/2010
This topic covers Source Provider registry settings, and settings for other types of customization.
Source Provider Registry Settings
Settings Overview
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).
Note
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. |
Remarks
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.
Example
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);
Contacts Groups Registry Settings
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}". > [!NOTE] > Use this as the default settingTo 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 |
Contact Chooser Customization Registry Settings
Providing a Custom Contact Chooser for use during E-mail Composition
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
);
Note
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. |
Setting List View Characteristics
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. |
Title Box Customization
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. |
Search Bar Customization
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. |
Empty List View Text
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. |
Other Customization Registry Settings
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.
Requirements
| Header | pimstore.h |
| Library | Pimstore.lib |
| Windows Embedded CE | Windows CE 3.0 and later |
| Windows Mobile | Pocket PC 2000 and later, Smartphone 2002 and later |
See Also
Reference
PIMSRC_COLOR
IPimSrcContactListIcon::Paint
IPimSrcContactSummaryCard::Display
ICalContactLinkHandler
Pocket Outlook Object Model Registry Settings
Concepts
Customizing Action Key Behavior for Calendar Hyperlinks