ChooseContact (Compact 7)

3/12/2014

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()), 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.

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.

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

See Also

Reference

Pocket Outlook Object Model Functions
CHOOSECONTACT Structure
Contact Chooser Flags