ITPhone::get_PreferredAddresses method (tapi3if.h)

Article
02/22/2024

The get_PreferredAddresses method returns a collection of addresses that the phone is preferred for use on. The application does not have to call ITPhone::Open before executing this method.

This method is intended for Visual Basic and scripting applications. C/C++ applications will find it more convenient to use the EnumerateAddresses method.

Syntax

HRESULT get_PreferredAddresses(
  [out] VARIANT *pAddresses
);

Parameters

[out] pAddresses

Pointer to a VARIANT containing an ITCollection of ITAddress interface pointers.

Return value

This method can return one of these values.

Value	Meaning
S_OK	Method succeeded.
E_POINTER	The pAddresses parameter is not a valid pointer.
E_OUTOFMEMORY	There is not enough memory to allocate the collection object.

Remarks

If no usable addresses are present on the system, this method returns an empty collection.

A phone device declares itself as being preferred to an address or set of addresses by returning address/line IDs using the TAPI 2.x phoneGetID function with device class tapi/line.

Although the phoneGetID function requires the handle to an open phone device, the application does not have to call the ITPhone::Open method before calling EnumeratePreferredAddresses. This is because the implementation of the phone object can open the phone and call phoneGetID during TAPI initialization or when a new phone object appears.

TAPI calls the AddRef method on the ITAddress interface returned by ITPhone::get_PreferredAddresses. The application must call Release on the ITAddress interface to free resources associated with it.

Requirements

Requirement	Value
Target Platform	Windows
Header	tapi3if.h (include Tapi3.h)
Library	Uuid.lib
DLL	Tapi3.dll