Customizing the PIM User Experience by Using Source Providers

4/8/2010

A Source Provider is a custom function (DLL) that you can create and implement on a Windows Mobile device, that customizes the PIM user experience. Source Providers and their associated Source Identification Tag values (Source IDs) are part of a mechanism that supports a "Per-Provider Customization" of the PIM user experience on Windows Mobile devices.

There are several ways that you can customize the PIM user experience:**

• Provide a customized Summary tab for associated Contact items when the users open them from the Contact list view. For more information, see IPimSrcContactSummaryCard::Display.
• Provide a customized user interface (UI) that gives users the option of creating a specific kind of Contact (for example, a Contact that is linked to an external source) whenever they create a new one. For more information, see IPimSrcContactNew::Create.
• Provide a custom icon for associated Contact items when those Contact items appear in the Contact list view. For more information, see IPimSrcContactListIcon::Paint.
• Display Appointment items with alternate background colors in the Agenda and Day views. For more information, see Customizing an Appointment Item's Background Color.**

Typically, a Source Provider has a corresponding associate function that is responsible for synchronizing PIM data with the Windows Mobile device. Data that is synchronized with the mobile device by this associate function is tagged with the related Source ID. When Outlook Mobile displays a PIM item, it checks to see if the item has been tagged with a Source ID. If it finds one, it invokes the Source Provider, which customizes the UI for the PIM item.

Related Information

The Windows Mobile Classic and Windows Mobile Standard SDKs both contain a working sample called Register a Source Provider that demonstrates how to implement a Source Provider.

Remarks

**The Source Provider Customization Type Flags describe the types of customization that a particular Source Provider supports. Source Provider customization type flags are used to create the value for the Registry Key value.

The Source Provider PIM Type Ownership Flags describe the types of PIM items that are associated with a particular Source Provider. Source Provider PIM type ownership flags are used to create the value for the Type Registry Key value.**

When users enter new Contacts and Appointments, they can select a Source Provider to associate them with.

A valid Source ID is a DWORD that has only 1 bit set (that is there are 32 possible Source IDs).

Although Contact and Appointment items, regardless of Source ID, are synchronized with Microsoft Exchange—Source IDs are not.

Source IDs are not supported for Task items.

Since Contact and Appointment items can be associated with only one Source Provider, your Source Provider installation implementation must select a Source ID that is unique in the domain of all Source Providers installed on the Windows Mobile device (it is considered an error to determine Source IDs prior to install). Your implementation must choose a unique Source ID by first iterating over the installed Source Providers registered in the key \HKLM\PIMSources\, and then choosing the next available Source ID (for example 1, 2, 4, 8, 16...).

The default value for a Source ID is zero (0). Contact and Appointment items that have a Source ID value of zero are not associated with a Source Provider, and just use the default UI.

Your Source Provider uninstall implementation must reset the Source ID field of all associated Contact and Appointment items back to zero.

The Contact item OID is passed as a parameter to IPimSrcContactListIcon::Paint so that the Source Provider can look up any additional properties that it might require in order to determine how to draw the Contact item.

Source Providers must draw using a transparent background.

See Also

Reference

Source Provider Customization Type Flags
Source Provider PIM Type Ownership Flags
PIMSRC_COLOR
IPimSrcContactListIcon
IPimSrcContactNew
IPimSrcContactSummaryCard

Concepts

Customizing an Appointment Item's Background Color

Other Resources

Customizing the PIM User Experience
Register a Source Provider