Starts the Add a Contact Wizard to add a contact to the contact list of the signed-in user. If the bstrEMail parameter is not supplied, the wizard opens to its first page. Not scriptable.

Syntax

HRESULT AddContact(
   [in] long hwndParent,
   [in] BSTR bstrEMail
);

Parameters

hwndParent

[in] Reserved. A caller should set this parameter to 0 or null.

bstrEMail

[in] The sign-in name to be added as a contact. If this string value is null, the first page of the Add a Contact Wizard is displayed and the user is prompted to specify the contact to add. If bstrEMail specifies a contact to add, the Add a Contact Wizard steps through the first page automatically, without the user clicking Next. If there is a problem adding the contact (for example, if the contact does not map to a known Microsoft® Office Communicator sign-in name), the user is prompted to take appropriate corrective action.

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

The contact was added successfully.

E_OUTOFMEMORY

The system could not allocate enough memory.

E_INVALIDARG

One of the following:

  • bstrEMail has invalid characters.

  • bstrEMail exceeded 129 characters.

  • bstrEMail contains a carriage return or linefeed.

S_FALSE

The Add a Contact Wizard is already displayed. The supplied parameters are ignored and the wizard is brought to the foreground with already existing values. 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 internal error occurred.

MSGR_E_AUDIO_UI_ACTIVE

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

MSGR_E_OPTION_UI_ACTIVE

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

MSGR_E_NOT_LOGGED_ON

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

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

Remarks

Calling this method from an application is equivalent to the user clicking Contacts, and then clicking Add a Contact in Communicator.

If the supplied input parameter is other than a blank string, this method populates the input in the Add a Contact Wizard with the specified string.

Entering a blank (null string) value for the bstrEMail parameter is common usage because it starts the Add a Contact Wizard and allows you to specify the e-mail address of the new contact.

In the Add a Contact Wizard, you can search for a contact by name or e-mail name if the contact's sign-in name is unknown. When you select a name from the search results and click Next in the wizard, a DMessengerEvents::OnContactListAdd event that contains the results of the Add request is received.

The format of the string entered to identify a Communicator client user by sign-in name depends on the service. For some services, the parameter name bstrEMail is a misnomer. No validation is performed on the supplied bstrEMail parameter by the API; however, the service that is being connected to might apply validation.

The best time to call this method with the SigninName filled is when that name is known to be a valid Office Communicator user. For example, if you are accessing the "Recent Contacts" store in the local machine registry. The registry holds the SignInNames of Office Communicator users the local client has interacted with in the recent past.

If the method is called with a well-formed sign-in name that does not belong to any communicator user, you still get an IMessengerContact object as the return value. The status of that contact continues to be shown as unknown until the Office Communicator server finds the contact. To avoid undue server processing, it is better not to pass a sign-in name that is known to be invalid.

Calling this API while the client is offline returns the MSGR_E_NOT_LOGGED_ON error. To determine if a contact is added successfully, check the result in the DMessengerEvents::OnContactListAdd event.

Example

In this example, AddContact is called in two different ways. Both calls require a null or zero value in the first parameter position while the second parameter position is optional. The example code is looking at a check box (supplySignin) form control to determine how to call the method. In the first instance, the IMessengerContact::SigninName of the contact to be added is supplied. The second instance of the call passes a null string. This second instance displays the Office Communicator Add Contact Wizard and begins the process on the first page of the wizard.

There is a processing cost associated with catching exceptions. It is always better to prevent an exception from being raised than to provide and expensive exception handler. In this case, the example code could have examined each parameter value before making the call to ensure validity.

Copy Code 
try
{
  int parentHandle = 0;
  string nullSignin = null;
  if (supplySignin.Checked == true)
	 communicator.AddContact(parentHandle, "jaya@contoso.com");
  else
	 communicator.AddContact(parentHandle, nullSignin);
}
catch (ArgumentException)
{
}
catch (COMException ACE)
{
   Console.WriteLine(ACE.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