Enumerating TAPI Devices

< BACK  NEXT >

[oR]

The function lineInitialize returns the number of available line devices. Next, an application typically needs to enumerate this list of devices to decide which one will be used to make a call. Often, a list of devices will be presented to the user from which one will be selected. This process of enumeration involves the following tasks for each line device:

• Negotiating with the line device which TAPI version to use by calling the function lineNegotiateAPIVersion.

• Obtaining the line device's capabilities by calling the function lineGetDevCaps function. The information returned from this structure includes a human-friendly description.

Negotiating TAPI Version

Version negotiation is used to ensure that all the parties the application, TAPI, and the service provider DLL agree on the version to use. The TAPI function lineNegotiateAPIVersion is used for this purpose.

Table 11.2. lineNegotiateAPIVersion Negotiates TAPI version for using a line device

lineNegotiateAPIVersion
HLINEAPP hLineApp	HLINEAPP handle returned from calling lineInitialize.
DWORD dwDeviceID	Line device identifier to negotiate version for. Between 0 and dwNumLines 1 returned from lineInitialize.
DWORD dwAPILowVersion	Minimum version number acceptable to the application.
DWORD dwAPIHighVersion	Maximum version number supported by the application.
LPDWORD lpdwAPIVersion	DWORD pointer that contains the version number returned from TAPI.
LPLINEEXTENSIONID lpExtensionID	Must be NULL for Windows CE.
LONG Return Value	Zero for success, or a LINERR_ value indicating an error. These errors are defined in tapi.h.

The line device is designated by an integer number between 0 and the value dwNumLines 1 returned from lineInitialize. In Listing 11.2a three defines are used to specify the high and low versions that the application can support. The agreed TAPI version number is returned in the variable dwRAPIVersion.

Listing 11.2a Negotiating TAPI version

 #define TAPI_VERSION_1_0      0x00010003 #define TAPI_VERSION_3_0      0x00030000 #define TAPI_CURRENT_VERSION  TAPI_VERSION_3_0 DWORD NegotiateTAPIVersion(DWORD dwLineId) {   DWORD dwReturn, dwRAPIVersion;   if (dwReturn = lineNegotiateAPIVersion (     g_hLineApp,   // TAPI registration handle     dwLineId,     // Line device to be queried     TAPI_VERSION_1_0,  // Least recent API version     TAPI_CURRENT_VERSION, // Most recent API version     &dwRAPIVersion,  // Negotiated API version     NULL))           // Must be NULL   {     cout   _T("Could not negotiate TAPI version")           dwLineId  endl;     return 0;   }   return dwRAPIVersion; } 

Getting Line Device Capabilities

The TAPI function lineGetDevCaps (Table 11.3) is used to return information about a line device in a LINEDEVCAPS structure. This function needs to be passed a negotiated TAPI version number and the device identifier representing the line device whose capabilities are to be returned. The complexity in calling this function results from the LINEDEVCAPS structure the size of the structure differs from line device to line device. Additional information is appended on to the end of the LINEDEVCAPS structure, the size of which depends on the line device. The LINEDEVCAPS structure member dwNeededSize contains, after a call to lineGetDevCaps, the required size of the LINEDEVCAPS structure.

In Listing 11.2b, the negotiated TAPI version is obtained by calling the NegotiateTAPIVersion function from Listing 11.2a. A "do" loop is then executed that first calls lineGetDevCaps with a pointer to a LINEDEVCAPS structure initially created with the size of LINEDEVCAPS defined in TAPI.H. The LINEDEVCAPS structure is then reallocated using the size contained in the dwNeededSize member, and another call to lineGetDevCaps is made. This new structure should then be sufficiently large to return all the line device's capabilities.

Table 11.3. lineGetDevCaps Returns capabilities of a line device

lineGetDevCaps
HLINEAPP hLineApp	HLINEAPP handle returned from calling lineInitialize.
DWORD dwDeviceID	Line device identifier to negotiate version for. Between 0 and dwNumLines 1 returned from lineInitialize.
DWORD dwAPIVersion	Negotiated TAPI version number returned from lineNegotiate-APIVersion.
DWORD dwExtVersion	Not supported, pass as zero.
LPLINEDEVCAPS lpLineDevCaps	LINEDEVCAPS structure filled in with the line device's capabilities.
LONG Return Value	Zero for success, or a LINERR_ value indicating an error. These errors are defined in tapi.h.

Listing 11.2b Getting line device capabilities

 void DisplayLineInfo(DWORD dwLineId) {   DWORD dwRAPIVersion, dwSize, dwReturn;   LPLINEDEVCAPS lpLineDevCaps = NULL;   LPTSTR lpszString;   // first negotiate TAPI version   dwRAPIVersion = NegotiateTAPIVersion(dwLineId);   if(dwRAPIVersion == 0)   {     cout   _T("Could not negotiate TAPI version")           dwLineId  endl;     return;   }   dwSize = sizeof (LINEDEVCAPS);   // Allocate enough memory for lpLineDevCaps.   do   {     if (!(lpLineDevCaps = (LPLINEDEVCAPS)           LocalAlloc (LPTR, dwSize)))     {       cout   _T("Out of memory")   endl;       return;     }     lpLineDevCaps->dwTotalSize = dwSize;     if (dwReturn = lineGetDevCaps (g_hLineApp,           dwLineId,           dwRAPIVersion,           0,           lpLineDevCaps))     {       cout   _T("Could not get Dev Caps")            endl;       return;     }     // Stop if the allocated memory is equal to     // or greater than the needed memory.     if (lpLineDevCaps->dwNeededSize <=           lpLineDevCaps->dwTotalSize)       break;     dwSize = lpLineDevCaps->dwNeededSize;     LocalFree (lpLineDevCaps);     lpLineDevCaps = NULL;   } while (TRUE);   lpszString = (LPTSTR)((LPBYTE)lpLineDevCaps +         lpLineDevCaps->dwLineNameOffset);   // now display information   cout   _T("Device: ")   dwLineId   _T(" ")         lpszString   endl;   LocalFree (lpLineDevCaps); } void Listing11_2() {   DWORD dwNumLines, dw;   if(!(dwNumLines = InitializeTAPI()))     return;   for(dw = 0; dw < dwNumLines; dw++)     DisplayLineInfo(dw);   ShutdownTAPI(); } 

After the "do" loop, Listing 11.2b shows how to extract data at the end of the LINEDEVCAPS structure defined in Tapi.h. The device name is returned as a Unicode string, the offset of which is contained in the dwLineNameOffset member. The following code returns a pointer that uses this offset (as a number of bytes) from the start of the LINEDEVCAPS structure:

 lpszString = (LPTSTR)((LPBYTE)lpLineDevCaps +       lpLineDevCaps->dwLineNameOffset); 

The LINEDEVCAPS structure contains a large number of members describing the line device's capability. Table 11.4 describes some of the more important members used in Windows CE.

Table 11.4. Important LINEDEVCAPS structure members

Member	Purpose
DWORD dwTotalSize	Actual size of the LINEDEVCAPS structure. Set before calling line-DevCaps.
DWORD dwNeededSize	Size of the LINEDEVCAPS structure required for the line device. Set after calling lineDevCaps.
DWORD dwUsedSize	Size of the LINEDEVCAPS returned for the line device.
DWORD dwLineNameSize	Size in bytes of the line device's name.
DWORD dwLineNameOffset	Offset, in bytes, from the start of the LINEDEVCAPS structure, for the location of the line device's name.
DWORD dwBearerModes	Flag array describing the type of calls that a line device can make. Examples include LINEBEARERMODE_VOICE for voice call, LINEBEARERMODE_DATA for data call.
DWORD dwMaxRate	The maximum possible transmission rate in bits per second.
DWORD dwMediaMode	A flag array indicating the media modes the line device can transmit data in. Examples include LINEMEDIAMODE_DATAMODEM for data transfer, LINEMEDIAMODE_G3FAX for group 3 fax, and LINEMEDIA-MODE_G4FAX for group 4 fax.

The dwMediaMode parameter is important, as this indicates how data can be transmitted once the call is established. For example, if dwMediaMode includes the flag LINEMEDIAMODE_DATAMODEM, the serial communications functions like ReadFile and WriteFile can be used by an application to receive and send data.

< BACK  NEXT >