ChooseContact

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.

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.

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;
}

Reference