Export (0) Print
Expand All

IMessenger::InstantMessage

This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.

Starts a conversation window with the initial recipient specified as a parameter. Scriptable.


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

vContact

[in] A VARIANT that can take as its value either a VT_BSTR string or a VT_DISPATCH pointer to an existing IMessengerContact 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.

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 an IMessengerWindow object used to call other automation-accessible properties, such as the IMessengerWindow::Height property, the IMessengerWindow::Width property, the IMessengerWindow::Top property, the IMessengerWindow::Left property, and the IMessengerWindow::Show method.

Returns one of the following values. For managed code applications, these return values are received in the form of a COMException.

S_OK

Success.

S_FALSE

The messenger window is already closed.

E_FAIL

Could not get window handle.

Windows that are being closed while some actions are still in progress can return confirmation dialog boxes to the user, which hangs up the application until the user responds.

Closing the main application window effectively places it into the tray. The object is still active and maintains a process, but it does not appear on the taskbar. Closing a conversation window essentially dereferences it. Further IMessengerWindow interface calls against that window are invalid because the window and its internal object have been completely removed, not just hidden, from the client. After a conversation window is closed, any pointers to it should be cleaned up.

The following example starts an IM window to initiate a conversation with the IMessengerContact interface object, IMContact.

The event handler handles the DMessengerEvents::OnIMWindowDestroyed event. Using the System.Runtime.InteropServices.Marshal.ReleaseComObject() method, the application code cleans up the IMWindow pointer.

IMessengerWindow IM_Window;
IMessengerContact IMContact = (IMessengerContact)communicator.GetContact(
                                "jaya@contoso.com", 
                                communicator.MyServiceId
                                );

if (IMContact != null && communicator != null)
{
   try
  {
     IM_Window = communicator.InstantMessage(IMContact);
  }
  catch (COMException IMCE)
  {
     Console.WriteLine(IMCE.ErrorCode.ToString());
  }
}
else
{
   Console.WriteLine("Null Contact object");
}
...
// IM Window destroyed event handler clears pointer to IM window
void communicator_OnIMWindowDestroyed(object pIMWindow)
{
  try
  {
    System.Runtime.InteropServices.Marshal.ReleaseComObject(pIMWindow);
  }
  catch (MarshalDirectiveException)
  {}

}

Client

Requires Microsoft DirectX 9.0, C Runtime libraries (msvcm80.dll) on Microsoft Windows© Vista, Microsoft Windows XP Service Pack 1 (SP1) or later, or Microsoft Windows 2000 with Service Pack 4 (SP4). Any Communicator-imposed restrictions apply. .

Server

Requires Microsoft Office Communications Server 2007, AV MCU (for Media Support), Media Relay (for NAT/Firewall traversal) on Microsoft Office Communications Server 2007.

Product

Microsoft Office Communicator 2007 Automation API

IDL file

Msgrua.idl

Community Additions

ADD
Show:
© 2014 Microsoft