ChooseContact

Article
08/28/2006

The ChooseContact function launches the Contact Chooser control, which provides access to the Contact application interface for selecting Contacts in your application.

Syntax

HRESULT ChooseContact(
  LPCHOOSECONTACT lpcc
);

Parameters

lpcc
[in/out] Reference to a CHOOSECONTACT structure. It contains information used to initialize the Contact Chooser control, and return information about the user's Contact and property selection. See CHOOSECONTACT for more details.

Return Values

This method returns the standard values HRESULT_FROM_WIN32(GetLastError()), E_INVALIDARG, and S_FAIL, as well as the following:

S_OK
The method completed successfully, and the Contact Chooser control was successfully launched.

The buffer pointed to by the oidContactID member of the CHOOSECONTACT structure contains the OID of the Contact, the ContactName member contains the name of the selected Contact, the pridPropertyID member contains the name of the property selected, and the lpstrPropertyValue member contains the string value of the data in the selected property.
S_FALSE
The Contact Chooser control successfully displayed, and propidSelected was set, but there was insufficient memory to allocate bstrPropertyValueSelected and bstrContactName. This suggests that the user chose a Contact, but no information was written to the bstrPropertyValueSelected and bstrContactName properties.
E_ABORT
The user canceled out of the Contact Chooser control.
E_INVALIDARG
An invalid argument was passed to the ChooseContact function.

Remarks

The Contact Chooser control is a system-defined modal dialog box. It provides the user interface that allows the user to select a single Contact and a single property of that Contact. It is used by Inbox for selecting email recipients, by Calendar for selecting Meeting attendees, and by the Pictures application to associate a picture with a Contact.

The client is blocked while this dialog is showing.

You must have RequiredProperties set to choose a property.

SelectContact must contain a valid Contact item when ChoosePropertyOnly is TRUE.

Setting ChooseContactOnly to TRUE automatically sets ChoosePropertyOnly to FALSE.

By default, ChooseContactOnly is set to TRUE. This allows you to call ShowDialog without setting any properties, and still get a reasonable default behavior.

ChooseContact fails when CCF_CHOOSECONTACTONLY is FALSE and rgpropidRequiredProperties is NULL.

Code Example

The following code example demonstrates how to use ChooseContact.

Note 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.

HRESULT ContactChooserExample()
{

    HRESULT hr                      = E_FAIL;    
    const CEPROPID c_propidAllEmail = PIMPR_ALL_EMAIL; 
    CHOOSECONTACT cc                = {0};

    // Setup the CHOOSECONTACT structure.
    cc.cbSize                     = sizeof (cc);
    cc.dwFlags                    = CCF_RETURNCONTACTNAME | CCF_RETURNPROPERTYVALUE | CCF_HIDENEW;
    cc.rgpropidRequiredProperties = &c_propidAllEmail;

    // The number of properties specified in the c_propidAllEmail array.
    cc.cRequiredProperties = 1;
    cc.hwndOwner           = NULL;

    // Display the Contact Chooser control, and prompt the user to choose a contact.
    hr = ChooseContact(&cc);

    // The name, and a string representation of the property, is returned according to 
    // the flags set in the CHOOSECONTACT structure above.
    DEBUGMSG(TRUE, (L"%s's email address is %s", cc.bstrContactName, cc.bstrPropertyValueSelected));

    // Free memory.
    SysFreeString(cc.bstrContactName);
    SysFreeString(cc.bstrPropertyValueSelected);

    return hr;

}

Requirements

Pocket PC: Windows Mobile Version 5.0 and later
Smartphone: Windows Mobile Version 5.0 and later
OS Versions: Windows CE 5.01 and later
Header: pimstore.h
Library: pimstore.lib