IMessenger::InstantMessage Method

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

Launches a conversation window with the initial recipient specified as a parameter.

Syntax

HRESULT InstantMessage(
  [in]           VARIANT vContact,
  [out, retval]  IDispatch **ppMWindow
);

Parameters

vContact [in]
VARIANT

A VARIANT that can take as its value either a VT_BSTR string or a VT_DISPATCH pointer to an existing MessengerContact object.

If the input value type is a string, this method creates a new MessengerContact object internally. The string should be the full sign-in name. For a Microsoft .NET Messenger Service contact, this should include an "at" sign (@) and domain name.

If the input value type is a pointer to an existing MessengerContact object (should be type VT_DISPATCH), the existing object is used for contact information.

ppMWindow [out]
IDispatch
A pointer to a pointer to the IDispatch interface on a MessengerWindow object, which can be accessed through the IMessengerWindow interface that is used to call other automation-accessible properties, such as Height, Width, Top, Left, and Show.

Return Value

HRESULT

Returns one of the following values. 

Return codeDescription
S_OK

Success.

RPC_X_NULL_REF_POINTER

ppMWindow is a NULL pointer.

E_INVALIDARG

vContact is NULL, points to a NULL string, or points to a string that has a space as the first character.

- or -

vContact is a VT_BSTR that exceeded 129 characters.

- or -

vContact is a VT_BSTR and contains a carriage return or linefeed.

E_FAIL

Called this method against the local client user.

S_FALSE

Could not bring focus to the window.

MSGR_E_NOT_LOGGED_ON

Client was not signed in the primary service at the time this method was called.

 

Remarks

If a conversation window is already open to a session with the user specified by vContact (and ppMWindow has not been released), no new window is displayed, no specific HResult is returned (returns S_OK), and the existing window instance will be referenced by the IDispatch pointer in the return value. If the specified vContact parameter represents different contacts in each case, more than one conversation window may be open in the client.

Because conversation windows are not modal, options or other client control UI can be open at the same time.

All windows will be closed if the client signs out. If the client goes offline, the MessengerWindow objects that correspond to those windows will become de-referenced and should be released. Calling APIs on these objects is no longer valid.

Because there is no way to specify a secondary service contact through this method, InstantMessage should not be used to send an instant message to a contact who is not in the Messenger service and does not already exist as a MessengerContact object. To open a conversation window to a secondary service user, the vContact parameter should be an existing MessengerContact object that has already been properly established, using the desired secondary service when creating or accessing that object.

A client cannot open a message to the local client user. This will result in E_FAIL. In this case, check IsSelf or do a string comparison of vContact and MySigninName.

ppMWindow should be released when it is no longer needed.

The Windows Messenger� APIs cannot determine whether a message can be successfully delivered. The success or failure of delivery is known only to the client user in real time. The process of clicking the Send button (thereby submitting the message to the Messenger servers for distribution) is controlled by the client user and cannot be automated. Users of the InstantMessage� API should still make their best effort to assure that the vContact string they pass specifies a legitimately addressable user. Validation and error checking for the supplied contact's name should be performed before it reaches this method. When this method is invoked, the conversation UI will always be displayed, even if the value entered for vContact is not a valid user or in a valid format.

Note  This method is available for scripting languages.

Requirements

Header

Msgrua.h

IDL

Msgrua.idl

DLL

Msgsc.dll

See Also

IMessenger
IMessengerContact

 

 

Send comments about this topic to Microsoft

Build date: 6/30/2010

Show: