Export (0) Print
Expand All
Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

IPimSrcContactSummaryCard::Display

Windows Mobile 6.5
4/8/2010

The Display method allows a Source Provider to over-ride the default Contact Summary display tab, and display an alternate summary tab dialog box to be used when a Contact item is opened from Contact list view.

Bb446053.note(en-us,MSDN.10).gifNote:
To use this mechanism, you must provide your own implementation for Display, within a new class that derives from IPimSrcContactSummaryCard.


HRESULT Display(
   HWND hwndParent,
   IItem * pitem
)

hwndParent

[in] Handle (HWND) to the parent window. For information on the HWND type, see GetParent.

pitem

[in] Reference to the IAppointment IItem to display.

This method returns the standard values E_INVALIDARG, E_OUTOFMEMORY, E_UNEXPECTED, and E_FAIL, as well as the following:

S_OK

The method completed successfully.

Source Providers and their associated Source ID's are part of a mechanism that supports per-provider customization of the PIM experience on Windows Mobile devices.

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 Windows Mobile device. Data synchronized with the Windows Mobile device 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.

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

A valid Source ID is a DWORD with only 1 bit set (i.e., 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 Contacts and Appointments 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.

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

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

The following code example demonstrates how to use IPimSrcContactSummaryCard::Display. This method is implemented as a COM interface, which is called when you register a source provider, and set the Contact item's Source ID property to match that of this particular Source Provider.

Bb446053.note(en-us,MSDN.10).gifNote:
To make the following code example easier to read, security checking and error handling are not included. This code example should not be used in a release configuration unless it has been modified to include them.
STDMETHODIMP CTestProvider::Display(HWND hwndParent, IItem *pItem)
{
    HRESULT      hr               = E_FAIL;
    const WORD   cProps           = 2;
    const int    iBufLen          = 1024;
    CEPROPVAL  * rgVals           = NULL;
    ULONG        cbBuffer         = 0;

    HANDLE       hHeap            = GetProcessHeap();
    CEPROPID     rgPropID[cProps] = {PIMPR_OID, PIMPR_FIRSTNAME};

    TCHAR        tszBuffer[iBufLen];

    // Assume that pItem is a Contact item, and get its properties to display.
    hr = pItem->GetProps(rgPropID, CEDB_ALLOWREALLOC, cProps, &rgVals, &cbBuffer, hHeap);

    hr = StringCchPrintf(tszBuffer, iBufLen, _T("OID = 0x%x\n FirstName = %s\n"), rgVals[0].val.ulVal, rgVals[1].val.lpwstr);

    // Display a custom message box instead of the standard summary card.
    MessageBox(NULL, tszBuffer, _T("Custom Summary Tab"), MB_SETFOREGROUND | MB_OK);

    if(NULL != rgVals)
        HeapFree(hHeap, 0, rgVals);

    return hr;
}

Headerpimstore.h
LibraryPimstore.lib
Windows MobilePocket PC for Windows Mobile Version 5.0 and later, Smartphone for Windows Mobile Version 5.0 and later

Community Additions

Show:
© 2014 Microsoft