IMessenger::AddContact method

Article
05/31/2018

[AddContact is no longer available for use as of Windows Vista. See Windows Messenger for more information.]

Launches the Add a Contact wizard.

Syntax

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

Parameters

hwndParent [in]

Type: long

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

bstrEMail [in]

Type: BSTR

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

Type: HRESULT

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

Return code	Description
S_OK	Success.
E_OUTOFMEMORY	The system could not allocate enough memory.
E_INVALIDARG	bstrEMail has invalid characters. - or - bstrEMail exceeded 129 characters. - or - bstrEMail contains a carriage return or linefeed.
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 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	Unspecified internal error.
MSGR_E_AUDIO_UI_ACTIVE	Called this method while the Audio and Video Tuning Wizard was enabled and visible.
MSGR_E_OPTION_UI_ACTIVE	The Options dialog box was enabled and visible when this method was called.
MSGR_E_NOT_LOGGED_ON	The Sign In dialog box was enabled and visible when this method was called.
MSGR_E_LOGON_UI_ACTIVE	The Customer Experience Improvement Program (CEIP) dialog box was enabled and visible when this method was called.

Remarks

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.

Requirements


End of client support	Windows XP
End of server support	Windows Server 2003
Header	Msgrua.h
IDL	Msgrua.idl
DLL	Msgsc.dll

Share via