IMessenger::FindContact method
[FindContact is no longer available for use as of Windows Vista. See Windows Messenger for more information.]
Launches the Add a Contact wizard to the screen used for finding a contact based on information supplied as input parameters.
Syntax
HRESULT FindContact(
[in] long hwndParent,
[in] BSTR bstrFirstName,
[in] BSTR bstrLastName,
[in, optional] VARIANT vbstrCity,
[in, optional] VARIANT vbstrState,
[in, optional] VARIANT vbstrCountry
);
Parameters
-
hwndParent [in]
-
Type: long
A LONG. Reserved. All current implementations and calls should set this parameter to 0 or NULL.
-
bstrFirstName [in]
-
Type: BSTR
A BSTR that specifies the first name of the potential contact. Required.
-
bstrLastName [in]
-
Type: BSTR
A BSTR that specifies the last name of the potential contact. Required.
-
vbstrCity [in, optional]
-
Type: VARIANT
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, optional]
-
Type: VARIANT
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, optional]
-
Type: VARIANT
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 Visual C++ and Visual Basic, it is difficult to determine with certainty when using scripting languages.
Return value
Type: HRESULT
For a table of MSGR_E_* constants, see MSGRConstants. Returns one of the following values.
| Return code | Description | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
|
Success. |
||||||||||
|
bstrFirstName and/or bstrLastName values are NULL or one of the required or optional string parameters exceeds the maximum allowed string length.
|
||||||||||
|
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. |
||||||||||
|
An unspecified error has occurred. |
||||||||||
|
The Audio and Video Tuning Wizard was enabled and visible when this method was called. |
||||||||||
|
The Sign In dialog box was enabled and visible when this method was called. |
||||||||||
|
Client was not signed in to the primary service at the time this method was called. |
||||||||||
|
The Options dialog box was enabled and visible when this method was called. |
||||||||||
|
The Customer Experience Improvement Program (CEIP) dialog box was enabled and visible when this method was called. |
Remarks
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 AddContact method.
Search results cannot be obtained through an event in the Windows Messenger APIs. Only the user can see results through the 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.
Requirements
| End of client support |
Windows XP |
| End of server support |
Windows Server 2003 |
| Header |
|
| IDL |
|
| DLL |
|