Line Initialization and Shutdown

< BACK  NEXT >

[oR]

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.

Table 11.1. lineInitialize Initializes an applications use of TAPI.DLL

lineInitialize
LPHLINEAPP lphLineApp	Pointer to a HLINEAPP handle in which the application's usage handle for TAPI is returned.
HINSTANCE hInstance	Instance handle of the application or DLL calling the function.
LINECALLBACK lpfnCallback	Callback function, through which notifications are returned for asynchronous events.
LPCTSTR lpszAppName	Name of application using TAPI. This string is used in notifications to indicate the name of the application making calls to TAPI.
LPDWORD lpdwNumDevs	Pointer to a DWORD returning the number of line devices available to the application.
LONG Return Value	Zero for success, or a LINERR_ value indicating an error. These errors are defined in tapi.h.

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(); } 

< BACK  NEXT >