IMessenger::AddContact Method

[AddContact is no longer available in Windows Vista. See Windows Messenger for more information.]

Launches the Add a Contact wizard.


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


hwndParent [in]

Sets Reserved. Current implementations should set this parameter to 0 or NULL.

bstrEMail [in]

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 will step 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 Windows Messenger sign-in name), the user will be prompted to take appropriate corrective action.

Return Value


For a table of MSGR_E_* constants, see MSGRConstants. Returns one of the following values.

Return codeDescription



The system could not allocate enough memory.


bstrEMail has invalid characters.

- or -

bstrEMail exceeded 129 characters.

- or -

bstrEMail contains a carriage return or linefeed.


The Add a Contact wizard is already displayed. The supplied parameters will be ignored and the wizard will be 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.


Unspecified internal error.


Called this method while the Audio and Video Tuning Wizard was enabled and visible.


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


The Sign In 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.



The contact is added to the primary service of the primary client.

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 launches the Add a Contact wizard and allows the user to specify the e-mail address of the new contact.

From the Add a Contact wizard, the user can search for a contact by name or e-mail name if the contact's sign-in name is unknown. When the user selects a name from the search results and clicks Next in the wizard, a OnContactListAdd event that contains the results of the add request is received.

The format of the string entered to identify a Windows Messenger 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 by the API; however, the service that is being connected to may apply validation.

Calling this API while the client is offline does not throw an error. To determine if a contact was added successfully, check the result in the OnContactListAdd event.

Note  This method is not available for scripting languages.








See Also




Send comments about this topic to Microsoft

Build date: 6/30/2010

Community Additions