April 21, 2014
Hot Topics:
RSS RSS feed Download our iPhone app

Exploring Extended TAPI Functions

  • May 10, 2005
  • By Alex Gusev
  • Send Email »
  • More Articles »

There are a lot of TAPI functions that were not touched in previous articles. I obviously don't pretend to cover them all here. Such huge task requires separate book to be described. However, I will try to overview different function groups to give you high level picture of available options.

Retrieving General Information

We will start this part of tutorial from regular things. This section describes how to obtain various general information for specified TAPI device. This function groups belong to Extended TAPI. ExTAPI, proving its name, extends wireless API with different options:

  • various device specific info
  • info about signal strength
  • info about system type
  • info about line operators
  • choosing the cellular network
  • registering lines for specific operator
  • get/set GPRS class
  • get/set equipment state
  • and more...

ExTAPI uses Telephony API (TAPI) functions and available TAPI line devices. There is only one restriction with ExTAPI. All its operations are available only if:

  • your application has successfully negotiated a device-specific extension version using lineNegotiateExtVersion
  • your application has successfully obtained a line device handle using lineOpen

What it means for you is that most of ExTAPI functions won't work if your application hasn't requested (and obtained) enough privileges (pay attention to the LINECALLPRIVILEGE_OWNER parameter of ::lineOpen in the very first sample).

Initialization

As you have seen in previous articles, first of all you have to initialize TAPI. Here, I'll put one more example of how to do it. The only difference from previous examples is that this code snipped uses the Event mechanism instead of a callback function to receive further notifications:

BOOL CExTapiDlg::OnInitDialog()
{
   CDialog::OnInitDialog();
   ...

   LINEINITIALIZEEXPARAMS LineExtParams;
   LineExtParams.dwTotalSize = sizeof(LineExtParams);
   LineExtParams.dwOptions   = LINEINITIALIZEEXOPTION_USEEVENT;

   if (::lineInitializeEx(&m_hLineApp, 0, 0, _T("Developer.com Test"),
                          &m_dwNumDevs, &m_dwAPIVersion,
                          &LineExtParams))
   {
      EndDialog(IDOK);
      return FALSE;
   }

   m_dwTSPILineDeviceID = GetTSPLineDeviceID(CELLTSP_LINENAME_STRING);
   if ( m_dwTSPILineDeviceID == (DWORD)-1 )
   {
      ::lineShutdown(m_hLineApp);
      EndDialog(IDOK);
      return FALSE;
   }

   // open the line
   if( ::lineOpen(m_hLineApp, m_dwTSPILineDeviceID,
                  &m_hLine, m_dwAPIVersion, 0, 0,
                  LINECALLPRIVILEGE_OWNER,
                  LINEMEDIAMODE_DATAMODEM, 0) )
   {
      ::lineShutdown(m_hLineApp);
      EndDialog(IDOK);
      return FALSE;
   }

   // set up ExTAPI
   if ( ::lineNegotiateExtVersion(m_hLineApp, m_dwTSPILineDeviceID,
                                  m_dwAPIVersion, EXT_API_LOW_VERSION,
                                  EXT_API_HIGH_VERSION,
                                  &m_dwExtVersion) )
   {
      ::lineClose(m_hLine);
      ::lineShutdown(m_hLineApp);
      EndDialog(IDOK);
      return FALSE;
   }
}

DWORD CExTapiDlg::GetTSPLineDeviceID(const TCHAR*
                                     const psTSPLineName)
{
   DWORD dwReturn = -1;
   for(DWORD dwCurrentDevID = 0 ; dwCurrentDevID < m_dwNumDevs ;
       dwCurrentDevID++)
   {
      LINEEXTENSIONID LineExtensionID;
      if( ::lineNegotiateAPIVersion(m_hLineApp, dwCurrentDevID,
                                    TAPI_API_LOW_VERSION,
                                    TAPI_CURRENT_VERSION,
                                    &m_dwAPIVersion,
                                    &LineExtensionID) == 0 )
      {
         LINEDEVCAPS LineDevCaps;
         LineDevCaps.dwTotalSize = sizeof(LineDevCaps);
         if( ::lineGetDevCaps(m_hLineApp, dwCurrentDevID,
                              m_dwAPIVersion, 0, &LineDevCaps) == 0 )
         {
            BYTE* pLineDevCapsBytes = new BYTE[LineDevCaps.dwNeededSize];
            if(0 != pLineDevCapsBytes)
            {
               LINEDEVCAPS* pLineDevCaps =
                  (LINEDEVCAPS*)pLineDevCapsBytes;
               pLineDevCaps->dwTotalSize = LineDevCaps.dwNeededSize;
               if( ::lineGetDevCaps(m_hLineApp, dwCurrentDevID,
                                    m_dwAPIVersion, 0,
                                    pLineDevCaps) == 0 )
               {
                  if( _tcscmp((TCHAR*)
                     ((BYTE*)pLineDevCaps+pLineDevCaps->
                       dwLineNameOffset), psTSPLineName) == 0 )
                  {
                     dwReturn = dwCurrentDevID;
                  }
               }
               delete[]  pLineDevCapsBytes;
            }
         }
      }
   }
   return dwReturn;
}

'Get/Set' functions

There are a couple dozen get/set-functions that give you a lot of useful information and allow managing line devices. It doesn't make sense to describe them all here; I'll only put a brief 'get' calls reference. You will find detailed explanations in SDK help:

  • lineGetCallBarringCaps
  • lineGetCallBarringState
  • lineGetCallWaitingCaps
  • lineGetCallWaitingState
  • lineGetCurrentAddressID
  • lineGetCurrentHSCSDStatus
  • lineGetCurrentOperator
  • lineGetCurrentSystemType
  • lineGetEquipmentState
  • lineGetGeneralInfo
  • lineGetGPRSClass
  • lineGetHSCSDCaps
  • lineGetHSCSDState
  • lineGetMuteState
  • lineGetNumberCalls
  • lineGetOperatorStatus
  • lineGetRadioPresence
  • lineGetRegisterStatus
  • lineGetSendCallerIDState
  • lineGetUSSD




Page 1 of 2



Comment and Contribute

 


(Maximum characters: 1200). You have characters left.

 

 


Sitemap | Contact Us

Rocket Fuel