Address Translation

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 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.

See Also

Establishing a Modem Connection | TAPI Functions

 Last updated on Saturday, April 10, 2004

© 1992-2003 Microsoft Corporation. All rights reserved.