Line Initialization and Shutdown

The TAPI function lineInitialize (Table 11.1) must be called before any other TAPI function is called. All TAPI functions start with "line," but this function doesn't initialize any one particular line device. The function returns a HLINEAPP handle that is the application's usage handle for TAPI. The header file "tapi.h" must be included when using any of the TAPI functions.

In Listing 11.1a lineInitialize is called, and the usage handle is stored in the global variable g_hLineApp. The function InitializeTAPI returns the number of available line devices to the caller. The callback function, lineCallbackFunc, is described later in the chapter in the section "Line Callback Function."

Listing 11.1a. Initializing TAPI

// initializes TAPI and returns available number
// of line devices
HLINEAPP &g_hLineApp;
DWORD InitializeTAPI()
{
  DWORD dwReturn, dwNumLines;
  dwReturn = lineInitialize (&g_hLineApp,
      hInst,
      (LINECALLBACK) lineCallbackFunc,
      _T("Examples Application"),
      &dwNumLines);
  if(dwReturn == LINEERR_REINIT)
    cout ≪ _T("Cannot initialize TAPI at present.")
      ≪ _T("Try again later") ≪ endl;
  else if (dwReturn != 0)
    cout ≪ _T("Error initializing TAPI: ")
         ≪ dwReturn≪ endl;
  return dwNumLines;
}

When an application has finished using TAPI, a call should be made to lineShutdown. This TAPI function is passed a single parameter, the application's usage handle stored in the variable g_hLineApp. Listing 11.1b shows a call to lineShutdown.

Listing 11.1b. Shutting down TAPI

void ShutdownTAPI()
{
  if(g_hLineApp != NULL)
  {
    lineShutdown(g_hLineApp);
    g_hLineApp = NULL;
  }
}
void Listing11_1()
{
  DWORD dwNumLines;
  dwNumLines = InitializeTAPI();
  if(dwNumLines > 0)
    cout ≪ _T("Number of available line devices: ")
      ≪ dwNumLines endl;
  else
    cout ≪
      _T("TAPI Error or no line devices present.")
       ≪ endl;
  ShutdownTAPI();
}