IMessenger::Phone method

Article
05/31/2018

[Phone is no longer available for use as of Windows Vista. See Windows Messenger for more information.]

Launches the Phone Call dialog box.

Syntax

HRESULT Phone(
  [in]          VARIANT     vContact,
  [in]          MPHONE_TYPE ePhoneNumber,
  [in]          BSTR        bstrNumber,
  [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 the "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.

ePhoneNumber [in]

Type: MPHONE_TYPE

A value of the MPHONE_TYPE enumeration that specifies the type of telephone number being called.

bstrNumber [in]

Type: BSTR

A BSTR that contains the telephone number that will be entered on the text field of the Phone Call dialog box. No validation is performed on this string. The string is expected to follow Telephony Application Programming Interface (TAPI) standards for phone numbers, which are as follows:

+[countrycode]SPACE[phonenumber]

where:

+ is the plus character.
[countrycode] is any valid country/region code per international phone dialing conventions. An access code should not be supplied in this phone number string. The access code is added by the exchange that initiates the standard telephony portion of the call.
SPACE is the space character, CHR(20).
[phonenumber] is the phone number within the respective country's exchange, including area or regional codes, as appropriate.
Punctuation (except the + sign) should not be provided. Punctuation in [countrycode] or [phonenumber] will be ignored.

If the bstrNumber parameter is given as a NULL string, the text field of the new dialog box will be initially blank.

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. This parameter cannot be null.

Return value

Type: HRESULT

For a table of all MSGR_E_* constants MSGRConstants, see.

Returns one of the following values.

Return code	Description
S_OK	Success.
E_FAIL	Could not create a Phone Call window. - or - Called this method against the local client user.
MSGR_E_NOT_LOGGED_ON	Client was not signed in the primary service at the time this method was called.
S_FALSE	The Phone Call dialog box is already open.
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. - or - The phone type is out of range. - or - bstrNumber exceeds 256 characters.
MSGR_E_PHONESERVICE_UNAVAILABLE	The service for the contact you are attempting to call does not support phone calls.
MSGR_E_PHONE_INVALID_NUMBER	The contact you are attempting to call does not have the given phone-type number set.
MSGR_E_POLICY_RESTRICTED	Windows Messenger 5.0 and later. The local computer or local user policy does not allow users to make phone calls.

Remarks

The Microsoft Exchange Instant Messaging Service (IM) cannot support this method. Calling this method on an Exchange service contact will fail.

ppMWindow should be released when it is no longer needed.

Only one Phone Call dialog box can be active at one time. Calling Phone multiple times returns S_OK, not S_FALSE. The phone number displayed in the dialog box will be 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.

Note

This method is available for scripting languages.

Requirements


End of client support	Windows XP
End of server support	Windows Server 2003
Header	Msgrua.h
IDL	Msgrua.idl
DLL	Msgsc.dll

Share via