IMessenger::InstantMessage Method

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

Syntax

HRESULT InstantMessage(      
    VARIANT vContact,
    IDispatch **ppMWindow
);

Parameters

• vContact
  [in] 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, retval] 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 IMessengerWindow::Height, IMessengerWindow::Width, IMessengerWindow::Top, IMessengerWindow::Left, and IMessengerWindow::Show.

Return Value

Returns one of the following values. 

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 user interface (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, IMessenger::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 IMessengerContact::IsSelf or do a string comparison of vContact and IMessenger::MySigninName.

ppMWindow should be released when it is no longer needed.

The Microsoft 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 IMessenger::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.

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

See Also

IMessengerContact