IMessenger::FindContact Method
Deprecated. Launches the Add a Contact wizard to the screen used for finding a contact based on information supplied as input parameters.
Syntax
HRESULT FindContact( long hwndParent, BSTR bstrFirstName, BSTR bstrLastName, VARIANT vbstrCity, VARIANT vbstrState, VARIANT vbstrCountry );
Parameters
hwndParent
[in] A LONG. Reserved. All current implementations and calls should set this parameter to 0 or NULL.bstrFirstName
[in] A BSTR that specifies the first name of the potential contact. Required.bstrLastName
[in] A BSTR that specifies the last name of the potential contact. Required.vbstrCity
[in] A VARIANT that specifies the city name that is used to narrow search criteria and match the given first and last names with the city provided in the contact's personal information. Applicable only when vbstrCountry is "United States."vbstrState
[in] A VARIANT that specifies the state name that is used to narrow search criteria and match the given first and last names with the state provided in the contact's personal information. Applicable only when vbstrCountry is "United States." If no state name is provided, this value defaults to "(any)".vbstrCountry
[in] A VARIANT that specifies the country/region name that is used to narrow search criteria and match the given first and last names with the country/region provided in the contact's personal information. If no country/region name is provided, this value defaults to "(any)".This is not an ISO 3166 value or other standard means of specifying a country/region or locale. The value passed will be compared as the closest literal match to the available countries/regions in the client's Country drop-down list. For the United States only, pass the string "United States".
The string passed to this API must be aware of the locale of the client against which it is being implemented. Although it is possible to obtain the client locale in Microsoft Visual C++ and Microsoft Visual Basic, it is difficult to determine with certainty when using scripting languages.
Return Value
For a table of MSGR_E_* constants, see MSGRConstants. Returns one of the following values:
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > >> >
S_OK Success. E_INVALIDARG bstrFirstName and/or bstrLastName values are NULL or one of the required or optional string parameters exceeds the maximum allowed string length.
bstrFirstName 63 characters maximum, 1 character minimum. bstrLastName 63 characters maximum, 1 character minimum. bstrCity If given, 63 characters maximum. bstrState If given, 63 characters maximum. bstrCountry If given, 63 characters maximum. No carriage return (0x0D), linefeed (0x0A), or ANSI characters with values greater than 126 (0x7E). S_FALSE The Add a Contact wizard is already displayed. The supplied parameters will be ignored and the wizard will be brought to the foreground with preexisting values. It may be necessary to go back in the wizard sequence in order to see the parameters that were populated. S_FALSE cannot typically be captured in scripting error trapping because the initial 'error' bit is not 1 in this HResult. E_FAIL An unspecified error has occurred. MSGR_E_AUDIO_UI_ACTIVE The Audio and Video Tuning Wizard was enabled and visible when this method was called. MSGR_E_LOGON_UI_ACTIVE The Sign In dialog box was enabled and visible when this method was called. MSGR_E_NOT_LOGGED_ON Client was not signed in to the primary service at the time this method was called. MSGR_E_OPTIONS_UI_ACTIVE The Options dialog box was enabled and visible when this method was called. MSGR_E_OTHER_UI_ACTIVE The Customer Experience Improvement Program (CEIP) dialog box was enabled and visible when this method was called. Remarks
IMessenger::FindContact searches for the contact in the primary service of the primary client.
Entering a blank (empty string) value for the bstrFirstName and bstrLastName parameters is common usage and presents a true dialog box to the user.
Find a Contact is actually the Search By Name screen of the Add a Contact wizard. Users can also add a contact with a known e-mail address by clicking the Back button, which switches to the Add a Contact screen. The Add a Contact screen can be displayed initially by calling the IMessenger::AddContact method.
Search results cannot be obtained through an event in the Microsoft Windows Messenger APIs. Only the user can see results through the user interface (UI).
The actual UI has field size restrictions that do not necessarily match the input limits of this API. For example, the English version of the client restricts the field size to 40 characters. Users can scroll through fields that were populated through the API to be longer than 40 characters in the English client, but cannot enter them using the UI. The API limit is set to a higher value than the UI to allow the use of double-byte character strings (DBCS).
Note This method is not available for scripting languages.
Important IMessenger::FindContact is no longer available in Windows Vista. See Windows Messenger for more information.