ChooseContact

Article
11/18/2015

4/8/2010

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 Structure for more details.

Return Value

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 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 users to select a single Contact and a single property of that Contact. It is used by the Messaging Application 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.

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

Header	pimstore.h
Library	Pimstore.lib
Windows Embedded CE	Windows CE 3.0 and later
Windows Mobile	Pocket PC for Windows Mobile Version 5.0 and later, Smartphone for Windows Mobile Version 5.0 and later