ITAddressTranslation::TranslateAddress method (tapi3if.h)

Article
10/13/2021

The TranslateAddress method creates the address translation information interface. The primary goal of the TranslateAddress method is to obtain the pDestAddress string (dialable address) needed as a parameter for ITAddress::CreateCall. The TranslateAddress method returns the dialable address indirectly, as one of the properties of an ITAddressTranslationInfo object.

Syntax

HRESULT TranslateAddress(
  [in]  BSTR                     pAddressToTranslate,
  [in]  long                     lCard,
  [in]  long                     lTranslateOptions,
  [out] ITAddressTranslationInfo **ppTranslated
);

Parameters

[in] pAddressToTranslate

Pointer to BSTR containing address that requires translation.

[in] lCard

Calling card used for translation.

[in] lTranslateOptions

Indicator of translation options, see LINETRANSLATEOPTION__Constants.

[out] ppTranslated

Pointer to newly created ITAddressTranslationInfo interface.

Return value

This method can return one of these values.

Value	Meaning
S_OK	Method succeeded.
E_POINTER	The ppTranslated parameter is not a valid pointer.
E_OUTOFMEMORY	Insufficient memory exists to perform the operation.
E_UNEXPECTED	The method failed for unknown reasons.
E_INVALIDARG	The lTranslateOptions value is not valid.
TAPI_E_NODRIVER	This address has no TSP associated with it.
TAPI_E_REGISTRY_SETTING_CORRUPT	The registry is corrupt.
TAPI_E_OPERATIONFAILED	The method failed with TAPI.
TAPI_E_RESOURCEUNAVAIL	The TSP is not available.
TAPI_E_INVALCARD	The card number is not valid.

Remarks

The application must use SysAllocString to allocate memory for pAddressToTranslate and use SysFreeString to free the memory when the variable is no longer needed.

The TranslateAddress method is a COM wrapper for the TAPI 2.1 LineTranslateAddress function.

TAPI calls the AddRef method on the ITAddressTranslationInfo interface returned by TranslateAddress. The application must call Release on the ITAddressTranslationInfo 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