IMessenger::AddContact Method

  • Article

Deprecated. Launches the Add a Contact wizard.

Syntax

HRESULT AddContact(      
    long hwndParent,
    BSTR bstrEMail
);

Parameters

  • hwndParent
    [in] 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 Microsoft 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.

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 DMessengerEvents::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 DMessengerEvents::OnContactListAdd event.

Note  This method is not available for scripting languages.

Important  IMessenger::AddContact is no longer available in Windows Vista. See Windows Messenger for more information.