CHOOSECONTACT Structure

4/8/2010

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.

• lpstrTitle
  [in] For Windows Mobile Classic and Windows Mobile Professional, 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 "...".

  For Windows Mobile Standard, 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.

  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.

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

  Non-communication related contact properties (for example, PIMPR_BUSINESS_ADDRESS) are not supported. For a list of supported properties that you can use, see ChooseContact Property ID's.

• oidContactID
  [in/out] If the CCF_CHOOSEPROPERTYONLY was not set, oidContactID will be set to the object identifier (OID) of the chosen contact. If the CCF_CHOOSEPROPERTYONLY flag was set, oidContactID is an input value that specifies the contact from which a property should be selected.

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

See Also

Reference

Pocket Outlook Object Model Structures
Contact Chooser Flags
ChooseContact