Making a Phone Call

Article
06/30/2006

To place a call, the application must call the lineMakeCall function. TAPI sends LINE_CALLSTATE messages to indicate the progress of the call. For example, LINE_CALLSTATE indicates states of connection, dialing, proceeding, and so on. The messages vary depending on the type of call and the service that is provided. The application should not be designed to one type or one special sequence of call states.

The lineMakeCall function has the following parameters.

A handle to the open line device on which a call is originated.
A pointer to the handle to the call. Use this call handle to identify the call when you invoke other telephony operations on the call.
A pointer to the destination address. The destination address follows the standard area code and telephone number format.
The country/region code of the called party.
A pointer to a LINECALLPARAMS structure. This structure enables the application to specify how to set up the call. Also, it enables the application to select elements, such as the call bearer mode, data rate, expected media, and dialing parameters.

After the lineMakeCall function successfully sets up the call, the application receives a LINE_REPLY message. This message also informs the application that the call handle that is returned by lineMakeCall is valid.

The following code example shows how to open a line and make an outbound call.

VOID MakePhoneCall (LPCTSTR lpszPhoneNum)
{
  DWORD dwReturn,
        dwSizeOfTransOut = sizeof (LINETRANSLATEOUTPUT),
        dwSizeOfCallParams = sizeof (LINECALLPARAMS);

  LPLINECALLPARAMS lpCallParams = NULL;
  LPLINETRANSLATEOUTPUT lpTransOutput = NULL;
  
  TCHAR szDialablePhoneNum[TAPIMAXDESTADDRESSSIZE + 1] = {'\0'};

  // Initialize g_MakeCallRequestID.
  g_MakeCallRequestID = 0;
  
  // Open the current line.
  if (dwReturn = lineOpen (
          g_hLineApp,                 // Usage handle for TAPI
          g_dwCurrentLineID,          // Cannot use the LINEMAPPER value
          &g_CurrentLineInfo.hLine,   // Line handle
          g_CurrentLineInfo.dwAPIVersion, 
                                      // API version number
          0,                          // Must set to zero for Windows CE
          0,                          // No data passed back 
          LINECALLPRIVILEGE_NONE,     // Can only make an outgoing call
          0,                          // Media mode 
          NULL))                      // Must set to NULL for Windows CE
  {
    goto exit;
  }
  
  // Call translate address before dialing.
  do
  {
    // Allocate memory for lpTransOutput.
    if (!(lpTransOutput = (LPLINETRANSLATEOUTPUT) LocalAlloc (
                                                    LPTR,  
                                                    dwSizeOfTransOut)))
    {
      goto exit;
    }

    lpTransOutput->dwTotalSize = dwSizeOfTransOut;

    if (dwReturn = lineTranslateAddress (
          g_hLineApp,               // Usage handle for TAPI
          g_dwCurrentLineID,        // Line device identifier
          g_CurrentLineInfo.dwAPIVersion, 
                                    // Highest TAPI version supported
          lpszPhoneNum,             // Address to be translated
          0,                        // Must be 0 for Windows CE
          0,                        // No associated operations
          lpTransOutput))           // Result of the address translation
    {
      goto exit;
    }
    
    if (lpTransOutput->dwNeededSize <= lpTransOutput->dwTotalSize)
      break; 
    else
    {
      dwSizeOfTransOut = lpTransOutput->dwNeededSize;
      LocalFree (lpTransOutput);
      lpTransOutput = NULL;
    }

  } while (TRUE);
     
  dwSizeOfCallParams += lpTransOutput->dwDisplayableStringSize;
  
  if (!(lpCallParams = (LPLINECALLPARAMS) LocalAlloc (
                                                  LPTR, 
                                                  dwSizeOfCallParams)))
  {
    goto exit;
  }

  // Set the call parameters.
  lpCallParams->dwTotalSize = dwSizeOfCallParams;
  lpCallParams->dwBearerMode = LINEBEARERMODE_VOICE;
  lpCallParams->dwMediaMode = LINEMEDIAMODE_DATAMODEM; 
  lpCallParams->dwCallParamFlags = LINECALLPARAMFLAGS_IDLE;
  lpCallParams->dwAddressMode = LINEADDRESSMODE_ADDRESSID;
  lpCallParams->dwAddressID = g_dwCurrentLineAddr;
  lpCallParams->dwDisplayableAddressSize = 
                                lpTransOutput->dwDisplayableStringSize;
  lpCallParams->dwDisplayableAddressOffset = sizeof (LINECALLPARAMS);

  // Save the translated telephone number for dialing.
  lstrcpy (szDialablePhoneNum, 
    (LPTSTR) ((LPBYTE) lpTransOutput + lpTransOutput->dwDialableStringOffset));
  lstrcpy ((LPTSTR) ((LPBYTE) lpCallParams+ lpTransOutput->dwDisplayableStringOffset), 
    (LPTSTR) ((LPBYTE) lpTransOutput + lpTransOutput->dwDisplayableStringOffset));

  // Set the cursor as the wait cursor.
  SetCursor (LoadCursor (NULL, IDC_WAIT));

  // Make the telephone call. lpCallParams should be NULL if the default 
  // call setup parameters are requested.
  g_MakeCallRequestID = lineMakeCall (g_CurrentLineInfo.hLine,            
                                      &g_hCall,         
                                      szDialablePhoneNum, 
                                      0, 
                                      lpCallParams);    

  // Set the cursor back to an arrow.
  SetCursor (0);

  if (g_MakeCallRequestID > 0) 
  {
    g_bCurrentLineAvail = FALSE;

    DialogBoxParam (g_hInst, 
                    MAKEINTRESOURCE(IDD_DIALING), 

                    g_hwndMain, 
                    (DLGPROC) DialingProc, 0);
  }
  else 
  {
    ErrorBox (TEXT("Failed in making the phone call, function")
              TEXT("\nlineMakeCall failed."));
    CurrentLineClose ();
  }

exit :

  if (lpCallParams)
    LocalFree (lpCallParams);
  
  if (lpTransOutput)
    LocalFree (lpTransOutput);

  // If the lineMakeCall function call did not succeed, but the line was opened, 
  // close it.
  if ((g_MakeCallRequestID <= 0) && (g_CurrentLineInfo.hLine))
    CurrentLineClose ();

  return;
}

Share via

Making a Phone Call

See Also

Additional resources