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 to avoid dialing the wrong number. The application can call a function and display a dialog box for a user to change or confirm the number. Another example might be when a call placed to a different area code is not a long-distance phone call. Some calls 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 where a user can change the current phone number and adjust the location and see the effect on a phone number to be dialed.

Following the call to lineTranslateDialog, the application must call the lineGetTranslateCaps function to save any changes a user made to the telephony address translation parameters, and then call lineTranslateAddress to obtain a dialable string 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.
          lineTranslateDialog (g_hLineApp,     
                               g_dwCurrentLineID,      
                               g_CurrentLineInfo.dwAPIVersion,  
                               hwnd,        
                               NULL);
         
          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, 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, including the country and area code. It then produces a valid dialing sequence by removing unnecessary portions of the number—such as the country code or area code—and adding other digits such as a long-distance prefix or a digit used to dial out of a local private branch exchange.