IMessenger::AddContact Method

[AddContact is no longer available in 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]
long

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

bstrEMail [in]
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

HRESULT

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

Return codeDescription
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

Header

Msgrua.h

IDL

Msgrua.idl

DLL

Msgsc.dll

See Also

IMessenger

 

 

Send comments about this topic to Microsoft

Build date: 6/30/2010

Community Additions

ADD
Show: