Share via

CHOOSECONTACT

  • Article

Send Feedback

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

Syntax

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

  • lpstrTitle
    [in] For Pocket PC, specifies the settings header text. If NULL, then the default text is "Select a Contact". The title bar should be the name of the calling application. However, the settings header text displays the text specified with the ChooseContactDialog:Title property (by default: "Select a Contact"). The max length for the title is 32 Characters. If more than the maximum characters are defined, then the UI will append the text with a '...'.

    FoSmartphone, 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 address 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.

    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.

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

  • 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 Contact property identifers. They allow you to filter the list of Contacts that appear in the Contact Chooser and Property Chooser dialog boxes. The list appears in the "Apply To" drop-down list. 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.

    For convenience, instead of typing each and every Contact property identifier, you can use Contact property identifers that encompass multiple properties. For more information, see FindMatchingContact Property ID's.

    If PIMPR_HOME_ADDRESS, PIMPR_WORK_ADDRESS, or PIMPR_OTHER_ADDRESS, is specified, it is mapped internally to PIMPR_HOME_ADDRESS_STREET, PIMPR_WORK_ADDRESS_STREET, and PIMPR_OTHER_ADDRESS_STREET. When ChooseContact returns, bstrPropertyValueSelected is set to the appropriate street address, but propidSelected remains one of PIMPR_HOME_ADDRESS, PIMPR_WORK_ADDRESS, or PIMPR_OTHER_ADDRESS.

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

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

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

See Also

Pocket Outlook Object Model API Structures | Contact Chooser Flags | ChooseContact

Send Feedback on this topic to the authors

Feedback FAQs

© 2006 Microsoft Corporation. All rights reserved.