IMessenger::InstantMessage method
[InstantMessage is no longer available for use as of 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]
-
Type: 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, retval]
-
Type: 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
Type: HRESULT
Returns one of the following values.
| Return code | Description |
|---|---|
|
Success. |
|
ppMWindow is a NULL pointer. |
|
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. |
|
Called this method against the local client user. |
|
Could not bring focus to the window. |
|
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
| End of client support |
Windows XP |
| End of server support |
Windows Server 2003 |
| Header |
|
| IDL |
|
| DLL |
|