ITPhone::get_PreferredAddresses method (tapi3if.h)

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

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

See also

EnumeratePreferredAddresses

ITAddress

ITPhone

get_Addresses

phoneGetID