Share via

CHOOSECONTACT Structure (Compact 7)

  • Article

3/12/2014

The CHOOSECONTACT structure is used as an input parameter to the ChooseContact function. It contains information about the Contact item to choose, and about the behavior of the Contact Chooser control.

Syntax

struct {
  UINT cbSize;
  HWND hwndOwner;
  DWORD dwFlags;
  LPCWSTR lpstrTitle;
  LPCWSTR lpstrChoosePropertyText;
  LPCWSTR lpstrRestrictContacts;
  LPCWSTR lpstrIncrementalFilter;
  UINT cRequiredProperties;
  const CEPROPID * rgpropidRequiredProperties;
  CEOID oidContactID;
  BSTR bstrContactName;
  CEPROPID propidSelected;
  BSTR bstrPropertyValueSelected
} CHOOSECONTACT, *LPCHOOSECONTACT;

Members

  • cbSize
    [in] Size (count of bytes) of the CHOOSECONTACT structure.
  • hwndOwner
    [in] Handle to the window that owns the Contact Chooser dialog box. This can be any valid window handle, or NULL if the dialog box has no owner.

  • dwFlags
    [in] Bitmask of flags used to initialize the Contact Chooser dialog box. These can be combined with the bitwise OR. See Contact Chooser Flags for the set of possible values.

    Note

    When you set both the CCF_RETURNCONTACTNAME and CCF_CHOOSEPROPERTYONLY flags, the contact name is not returned.

  • lpstrTitle
    Specifies the text for the title bar. If NULL, then the default text is "Select a Contact". The first time the user enters the Contact Chooser View, the title bar displays the text specified with the ChooseContactDialog:Title property (by default: "Select a Contact"). The max length for the title is 18 characters. If more than the maximum characters are defined, then the UI will cut off the text.
  • lpstrChoosePropertyText
    [in] Specifies the text string displayed in the Property Chooser control's description box. If NULL, then the default text is "Select the phone number/e-mail address that you want to use".

  • lpstrRestrictContacts
    [in] A string that allows you to restrict which Contacts appear in the Contact Chooser control when it opens. It contains a Boolean expression that evaluates to TRUE or FALSE for any item.

    Maximum length is 256 characters. ChooseContact returns E_INVALIDARG for longer strings.

    ChooseContact returns E_INVALIDARG when lpstrRestrictContacts is invalid or incorrectly formatted.

    Enclose property names between brackets. You can combine criteria with AND and OR. Comparison operators are the following: <, <=, >, >=, = or <>. For example, Restrict("[name] = \"Joe\" AND [company] = \"Microsoft\"") returns a collection of Contacts named Joe who work at Microsoft.

    lpstrRestrictContacts accepts any string that IPOutlookItemCollection::Restrict accepts. By default, the string should be blank. If NULL, the system leaves it NULL, and does not impose a restriction.

    Parenthesizing a restrict query has the effect of causing the query to be evaluated from right-to-left, as opposed to left-to-right. For example, the two queries below yield different results. The only difference is the usage of parenthesis.

    Query 1: [Categories] = "Health" AND [SourceId] = 16 OR [Subject] = "Water"

    Query 2: ( ( [Categories] = "Health" AND [SourceId] = 16) OR [Subject] = "Water" )

  • lpstrIncrementalFilter
    [in] A string containing the filter criteria for filtering Contacts in the Contact Chooser.

    Maximum length is 100 characters. ChooseContact returns E_INVALIDARG for longer strings.

  • cRequiredProperties
    [in] Size (count of bytes) of rgpropidRequiredProperties. This is the number of properties in the rgpropidRequiredProperties array. The default is zero.

    If zero, there is no restriction on which Contacts are displayed (all Contacts show), the FileAs property is returned, and rgpropidRequiredProperties is ignored.

  • rgpropidRequiredProperties
    [in] An array of communication-related Contact property identifiers. They allow you to filter the list of Contacts that appear in the Contact Chooser and Property Chooser dialog boxes. Only those contacts that have data in one or more of the properties listed, appear in the Contact Chooser dialog box; and only those properties are shown in the Property Chooser dialog box.

    Note

    New for Windows Embedded Compact 7. Non communication-related Contact properties are supported as well as communication-related. For a complete list of all the supported properties that you can use, see the Remarks section below.

  • oidContactID
    [in/out] The object identifier (OID) of the chosen Contact item. If you want the user to select a specific Contact property only, then set the CCF_CHOOSEPROPERTYONLY flag. In this case, the oidContactID property is read.

  • bstrContactName
    [out] The name of the Contact that the user selected. The name is returned as it appears in the Contact Chooser dialog box. This is determined by the flags that you set.

    To return a value, you must set the CCF_RETURNCONTACTNAME flag.

    Note

    When you set both the CCF_RETURNCONTACTNAME and CCF_CHOOSEPROPERTYONLY flags, the contact name is not returned.

  • propidSelected
    [out] The property identifier of the property that the user selected. See Contact Property ID's for a complete list of possible values.

    propidSelected is empty when the Contact Chooser is first called. When the user selects a property, propidSelected takes the property ID of the selected Contact property. If the user clicks Cancel, then propidSelected remains NULL. propidSelected should be read only. It is not necessary to set propidSelected before calling the Contact Chooser.

  • bstrPropertyValueSelected
    [out] Stores the selected Contact property that the user selects in the Contact Chooser. The value is an empty string when the Contact Chooser is first called. When the user selects a property in the property picker screen, bstrPropertyValueSelected should be read only. If ContactProperty.Categories was the selected property, its value is returned as a semicolon separated list. It is not necessary to set bstrPropertyValueSelected before calling the Contact Chooser.

    To return a value, you must set the CCF_RETURNPROPERTYVALUE flag.

Remarks

The ChooseContact function launches the Contact Chooser control, which provides access to the Contact application interface for selecting Contacts in your application. It provides the user interface that allows the user to select a recipient from the Contact collection. It is used by Inbox for selecting email recipients, and by Calendar for selecting Meeting attendees.

The rgpropidRequiredProperties member can take the following Contact properties.

  • PIMPR_ACCOUNT_NAME
  • PIMPR_ASSISTANT_NAME
  • PIMPR_ASSISTANT_TELEPHONE_NUMBER
  • PIMPR_BUSINESS_ADDRESS
  • PIMPR_BUSINESS_FAX_NUMBER
  • PIMPR_BUSINESS_TELEPHONE_NUMBER
  • PIMPR_BUSINESS2_TELEPHONE_NUMBER
  • PIMPR_CAR_TELEPHONE_NUMBER
  • PIMPR_CATEGORIES
  • PIMPR_CHILDREN
  • PIMPR_COMPANY_NAME
  • PIMPR_COMPANY_TELEPHONE_NUMBER
  • PIMPR_CUSTOMERID
  • PIMPR_DEPARTMENT
  • PIMPR_EMAIL1_ADDRESS
  • PIMPR_EMAIL2_ADDRESS
  • PIMPR_EMAIL3_ADDRESS
  • PIMPR_FILEAS
  • PIMPR_GOVERNMENTID
  • PIMPR_HOME_ADDRESS
  • PIMPR_HOME_FAX_NUMBER
  • PIMPR_HOME_TELEPHONE_NUMBER
  • PIMPR_HOME2_TELEPHONE_NUMBER
  • PIMPR_IM1_ADDRESS
  • PIMPR_IM2_ADDRESS
  • PIMPR_IM3_ADDRESS
  • PIMPR_JOB_TITLE
  • PIMPR_MANAGER
  • PIMPR_MMS
  • PIMPR_MOBILE_TELEPHONE_NUMBER
  • PIMPR_OFFICE_LOCATION
  • PIMPR_OTHER_ADDRESS
  • PIMPR_PAGER_NUMBER
  • PIMPR_RINGTONE
  • PIMPR_SIM_PHONE
  • PIMPR_SMS
  • PIMPR_SPOUSE
  • PIMPR_YOMI_COMPANY
  • PIMPR_YOMI_FILEAS

Requirements

Header

pimstore.h

Library

Pimstore.lib

See Also

Reference

Pocket Outlook Object Model Structures
Contact Chooser Flags
ChooseContact