ITPhone::EnumerateAddresses method (tapi3if.h)

The EnumerateAddresses method enumerates the addresses that the phone can be used on. The application does not have to call ITPhone::Open before executing this method.

This method is intended for C/C++ applications. Visual Basic and scripting applications must use the get_Addresses method.

Syntax

HRESULT EnumerateAddresses(
  [out] IEnumAddress **ppEnumAddress
);

Parameters

[out] ppEnumAddress

Pointer to the IEnumAddress interface.

Return value

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

If no phones are available for use with the address, this method produces an empty enumeration and returns S_OK.

A phone device declares itself as being available on all addresses that support audio terminals by the TSP setting the PHONEFEATURE_GENERICPHONE bit in the dwPhoneFeatures member of the PHONECAPS structure. A phone device can also declare itself as being preferred to an address or set of addresses by returning address/line IDs using phoneGetID with device class tapi/line. The EnumerateAddresses method returns addresses that have been identified both ways.

To get only addresses that the phone is preferred on, you can call the EnumeratePreferredAddresses method.

A phone device declares itself as being specific to an address or set of addresses by returning address/line IDs using phoneGetID 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 EnumerateAddresses. 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 IEnumAddress interface returned by ITPhone::EnumerateAddresses. The application must call Release on the IEnumAddress interface to free resources associated with it.

Requirements

See also

EnumeratePreferredAddresses

ITPhone