Starts the Add a Contact Wizard to the screen used for finding a contact based on information supplied as input parameters. Not scriptable.

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] A LONG. Reserved. A caller 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 passed value is compared as the closest literal match to the available countries/regions in the client's Country 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

Returns one of the following values. For managed code applications, these return values are received in the form of a COMException.

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, one character minimum.

bstrLastName - 63 characters maximum, one 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 is enabled and visible when this method is called.

MSGR_E_LOGON_UI_ACTIVE

The Audio and Video Tuning Wizard is enabled and visible when this method is called.

MSGR_E_NOT_LOGGED_ON

The client is not signed in to the primary service at the time this method is called.

MSGR_E_OPTIONS_UI_ACTIVE

The Options dialog box is enabled and visible when this method is called.

MSGR_E_OTHER_UI_ACTIVE

The Customer Experience Improvement Program (CEIP) dialog box is enabled and visible when this method is called.

For a table of MSGR_E_* constants, see Error Codes.

Remarks

The IMessenger::FindContact method searches for the contact.

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 . You can also add a contact with a known e-mail address by clicking Back, 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 Office Communicator Automation API. The find results are only available to the user 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 are 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 (DBCSs).

Example

The first example illustrates a search for a user by first and last name, independent of any city, state, or country in which the user might reside.

The second example searches for the same Office Communicator user but limits the search to a specific city, state, and country. If you know the city or state and country, the resulting limited search is quicker and less likely to result in multiple search results.

Copy Code
IMessengerContact myContact;
int parentHandle = 0;
try
{
   if (connected == true)
	communicator.FindContact(parentHandle, "Jay", "Allen");
}
catch (ArgumentException)
{ }
catch (COMException FCCE)
{
  Console.WriteLine(FCCE.ErrorCode.ToString());
}

IMessengerContact myContact;
int parentHandle = 0;
try
{
   if (connected == true)
	communicator.FindContact(parentHandle, "Jay", "Allen","Redmond","Washington"," United States");
}
catch (ArgumentException)
{ }
catch (COMException FCCE)
{
  Console.WriteLine(FCCE.ErrorCode.ToString());
}

Requirements

Client

Requires Microsoft DirectX 9.0, C Runtime libraries (msvcm80.dll) on Microsoft Windows© Vista, Microsoft Windows XP Service Pack 1 (SP1) or later, or Microsoft Windows 2000 with Service Pack 4 (SP4). Any Communicator-imposed restrictions apply. .

Server

Requires Microsoft Office Communications Server 2007, AV MCU (for Media Support), Media Relay (for NAT/Firewall traversal) on Microsoft Office Communications Server 2007.

Product

Microsoft Office Communicator 2007 Automation API

IDL file

Msgrua.idl

See Also

Reference

Interfaces