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.

Copy Code 
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