IMessenger::Phone

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.

Opens the Phone Call dialog box. Not scriptable.

Syntax

HRESULT Phone(
   [in] VARIANT vContact,
   [in] MPHONE_TYPE ePhoneNumber,
   [in] BSTR bstrNumber,
   [out,
   retval] 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 IMessengerContact object. If the input value type is a string, this method creates a new MessengerContact object internally. If the input value type is a pointer to an existing MessengerContact object (should be type VT_DISPATCH), the existing object is used.

• ePhoneNumber
  [in] A value of the enumeration MPHONE_TYPE that specifies the type of telephone number that you are calling.

• bstrNumber
  [in] A BSTR that contains the telephone number that is entered in the text box in the Phone Call dialog box. No validation is performed on this string. For information about the format of the phone number, see the "Remarks" section below. If the bstrNumber parameter is given as a null string, the text box of the new dialog box is initially blank.

• 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 the IMessengerWindow::Height property, the IMessengerWindow::Width property, the IMessengerWindow::Top property, the IMessengerWindow::Left property, and the IMessengerWindow::Show method. This parameter cannot be null.

Return Value

For a table of all MSGR_E_* constants, see Error Codes.

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

• S_OK
  Success.

• E_FAIL
  The method could not create a Phone Call dialog box or you called this method against the local client user.

• MSGR_E_NOT_LOGGED_ON
  The client is not signed in the primary service at the time this method is called.

• S_FALSE
  The Phone Call dialog box is already open.

• E_INVALIDARG
  One of the following:

  • vContact is null, points to a null string, or points to a string that has a space as the first character.
  • vContact is a VT_BSTR that exceeded 129 characters.
  • vContact is a VT_BSTR and contains a carriage return or linefeed.
  • The phone type is out of range.
  • bstrNumber exceeds 256 characters.

• MSGR_E_PHONESERVICE_UNAVAILABLE
  The service for the contact whom you are attempting to call does not support phone calls.

• MSGR_E_PHONE_INVALID_NUMBER
  The contact whom you are attempting to call does not have the given phone-type number set.

• MSGR_E_POLICY_RESTRICTED
  The local computer or local user policy does not allow users to make phone calls.

Remarks

ppMWindow should be released when it is no longer needed.

Only one Phone Call dialog box can be active at one time. Calling the IMessenger::Phone method multiple times returns S_OK, not S_FALSE. The phone number displayed in the dialog box is the phone number entered as a parameter in the most recent method call.

In anticipation of numbers that exceed normal limits because of extensions, key sequences for private uses, and so on, there is no enforcement of string length for the bstrNumber parameter. There is a physical limit to the display of strings in the dialog box.

Example

The following example demonstrates starting a phone call dialog box from the Office Communicator UI using the supplied parameters. In this case, an IMessengerContact object (foundContact) is passed to the method along with the contact's telephone type and telephone number. The telephone number is optional and if omitted, the telephone dialog opens but the call is not placed. The IMessengerWindow object can be used to manipulate the opened telephone dialog. For illustration purposes, the phone dialog window is closed immediately after it is opened. Closing the phone dialog in this way causes the UI to display a dialog confirming that the user wants to end the telephone call.

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

if (communicator != null && IMContact != null)
{
   IMessengerWindow phoneWindow;
   try
   {
     phoneWindow = (IMessengerWindow)communicator.Phone(IMContact, MPHONE_TYPE.MPHONE_TYPE_WORK, foundContact.get_PhoneNumber(MPHONE_TYPE.MPHONE_TYPE_WORK));
     if (phoneWindow != null)
     {
        phoneWindow.Close();
     }
   }
   catch (COMException MPCE)
   {
       Console.WriteLine(MPCE.ErrorCode.ToString());
   }
}

Requirements

• 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

See Also

Reference

Interfaces