Address Translation
A version of this page is also available for
4/8/2010
A telephone number might have to be converted or translated into a dialable address format. For example, an application can help a user avoid dialing the wrong number by calling a function and displaying a dialog box for a user to change or confirm the number. Another example might be when a call that is placed to a different area code is not a long-distance telephone call. Some calls that are placed to another exchange prefix within the same area code are long-distance and require that a 1 be added before dialing. The lineTranslateDialog (TAPI) function displays a dialog box in which a user can change the current telephone number, adjust the location, and see the effect on a telephone number to be dialed.
Following the call to the lineTranslateDialog function, the application first must call the lineGetTranslateCaps function to save any changes that a user made to the telephony address translation parameters, and then call the lineTranslateAddress function to obtain a dialable string that is based on the new user selections.
The following code example shows how to use the lineTranslateDialog and lineGetTranslateCaps functions.
DWORD dwCounter,
dwSizeTranslateCaps;
LPLINELOCATIONENTRY lpLocationEntry;
LPLINETRANSLATECAPS lpLineTranslateCaps;
// Bring up the modal dialog box to adjust the location.
if (lineTranslateDialog (g_hLineApp,
g_dwCurrentLineID,
g_CurrentLineInfo.dwAPIVersion,
hwnd,
NULL))
return FALSE;
dwSizeTranslateCaps = sizeof (LINETRANSLATECAPS);
// Allocate sufficient memory for lpLineTranslateCaps.
do
{
if (!(lpLineTranslateCaps = (LINETRANSLATECAPS*) LocalAlloc(
LPTR, dwSizeTranslateCaps)))
return FALSE;
lpLineTranslateCaps->dwTotalSize = dwSizeTranslateCaps;
if (lineGetTranslateCaps (g_hLineApp,
g_CurrentLineInfo.dwAPIVersion,
lpLineTranslateCaps))
{
LocalFree (lpLineTranslateCaps);
return FALSE;
}
if (lpLineTranslateCaps->dwNeededSize <=
lpLineTranslateCaps->dwTotalSize)
break;
else
{
dwSizeTranslateCaps = lpLineTranslateCaps->dwNeededSize;
LocalFree (lpLineTranslateCaps);
lpLineTranslateCaps = NULL;
}
} while (TRUE);
lpLocationEntry = (LPLINELOCATIONENTRY)
((LPBYTE)lpLineTranslateCaps +
lpLineTranslateCaps->dwLocationListOffset);
// Find the selected location.
for (dwCounter = 0;
dwCounter < lpLineTranslateCaps->dwNumLocations;
dwCounter++)
{
if (lpLocationEntry[dwCounter].dwPermanentLocationID ==
lpLineTranslateCaps->dwCurrentLocationID)
break;
}
// Error occured in finding the selected location.
if (dwCounter == lpLineTranslateCaps->dwNumLocations)
{
LocalFree (lpLineTranslateCaps);
return FALSE;
}
// Save the location name, country/region, and area code data.
wsprintf (g_szLocationName,
(LPTSTR)((LPSTR)lpLineTranslateCaps +
lpLocationEntry[dwCounter].dwLocationNameOffset));
wsprintf (g_szCountryCode, TEXT("%ld"),
lpLocationEntry[dwCounter].dwCountryCode);
wsprintf (g_szAreaCode,
(LPTSTR)((LPSTR)lpLineTranslateCaps +
lpLocationEntry[dwCounter].dwCityCodeOffset));
LocalFree (lpLineTranslateCaps);
return TRUE;
The lineTranslateAddress function examines the registry settings to find the user location, which includes the country/region and area code. This function then produces a valid dialing sequence by removing unnecessary portions of the number — such as the country/region code or area code — and adding other digits, such as a long-distance prefix or a digit that is used to dial out of a local, private branch exchange.