tapi 函数

TAPI协议:
    TAPI是电话应用编程接口(Telephone Application Programming Interface)的缩写.开发人员使用TAPI编写的应用程序能有效的利用电话业务供应商的服务，既可以通过一个模拟Modem对其进行访问，也可以访问专业的用户交换机(PBX)所提供的高级功能
TAPI机制:
  TAPI提供4个层次的服务。
  (1)辅助电话:
    辅助电话提供的函数允许非电话的应用程序方便的在程序中集中添加拨打电话的功能.它可以在应用程序中添加电话的拨号功能。辅助电话只支持交互式的呼叫拨号。
   辅助电话只支持两个函数:
    tapiRequestMakeCall()
    tapiGetLoeationInfo()
    tapiRequestMakeCall()与Windows 95/98提供的Dialer.exe程序一起,处理寻找正确设备的所有具体事项，对该设备发出呼叫，拨打号码，提供可以挂断呼叫的用户接口.

tapiGetLoeationInfo()提供获取国家和城市代码信息的方法，这些信息可用于构建电话号码，供tapiRequestMakeCall使用.
LONG WINAPI tapiRequestMakeCall(
                                LPCSTR lpszDestAddress,
                                LPCSTR lpszAppName,
                                LPCSTR lpszCalledParty,
                                LPCSTR lpszComment  
                                );
lpszDestAddress//用于呼叫电话号码，可以给出一个规范的地址或一个可拨打的地址 .
规范的地址形式是"+<国家代码>(<地区代码>)<电话号码>"。 一个可拨打的号码是一个局部化的字符串，他可能包过用来访问外线的字符串，一个电话卡号，长途区号和地区号，一个脉冲或音调拨号模式指示器等.
余下的3个参数用于拨号程序的日志文件对这次呼叫的描述。第二个参数包过一个指针，指向NULL结尾的字符串，他是一个程序名，第3个参数是被叫方名字的字符串描述，最后一个参数是注解字符串。如果成功，它返回一个0，否则返回负数.
 tapiGetLoeationInfo函数原型:
LONG WINAPI tapiGetLoeationInfo(
                                LPSTR lpszCountryCode,
                                LPSTR lpszCityCode
                                 );
两个参数都是返回参数，一个是返回国家或地区的代号，另一个是返回所在城市的代号。tapiGetLoeationInfo 是从控制面板中的"电话和调制解调器"选项中获得该信息的.应用程序可以使用该函数帮助用户确定所要拨打的号码。函数成功返回0，否则返回负值。
(2)基本电话服务(对电话提供更多的控制):
  1地址翻译:
  2发出呼叫:
  3回答呼叫:
  4挂断电话:
  5监控通话状态和监控事件发生：
  6呼叫句柄控制(call handl control).
    地址翻译生成一个地址版本，这个地址标识了一个端点的所有的必要信息，包过国家代码，地区号和电话号。这种地址以“+”字符开始。
    地址翻译把一个规范地址作为输入内容，生成一个现场使用的拨号字符串。有了现场使用的拨号字符串，就可以呼叫了。呼叫的建立，处理和最后终止需要经过一些状态转移。打出去的电话会经过空闲，拨号音，拨号，连接，回铃，连接和断开这些状态。而对于拨入的电话，他会经过空闲，提供连接，同意连接，连接和断开这些状态。
   基本电话服务还提供了检索和控制呼叫句柄的机制。这是因为TAPI自身并没有提供在已建立的电话线路中传输数据的方法，必须通过其他类和API在TAPI线上通信。TAPI用于呼叫的建立和监控，不负责发送数据.
 相关API:
 LONG WINAPI lineInitialize(
                            LPHLINEAPP   lphLineApp,//线路程序句柄的指针，此句柄传递TAPI后作                                                   //为以后大多数函数调用的参数
                            HINSTANCE    hInstance,//应用程序实例句柄，可以用                                                   //AfxGetInstanceHandle检索该参数.TAPI需                                                      //要一个实例句柄来识别应用程序的过程事件.
                            LINECALLBACK lpfnCallback,//指向回调函数指针，该函数有应用程序创                                                      //建，声明成 FAR PASCAL或者CALLBACK
                            LPCSTR       lpszAppName,//用于识别应用程序，可以赋予任何值
                            LPDWORD      lpdwNumDevs//一个返回参数，lineInitialize将会在这个                                                    //参数中存储应用程序可用的设备数量。这些                                                    //可用的设备必须经查询，找出一个能满足应                                                    //用特定需要的设备
                            );//函数成功返回0，否则返回负值。
不过，lineInitialize用在TAPI2的应用程序上已经过时了。新的lineInitializeEx版本还要多出两个参数,一个是DWORD 型指针，指定应用程序TAPI的最高版本。另一个是指向LINEINITIALIZEEXPARAMS结构的指针.
lineInitializeEx函数原型如下:
LONG WINAPI lineInitializeEx(
                             LPHLINEAPP lphLineApp,
                             HINSTANCE hInstance,
                             LINECALLBACK lpfnCallback,
                             LPCSTR       lpszFriendlyAppName,
                             LPDWORD      lpdwNumDevs
                             LPDWORD      lpdwAPIVersion,
                             LPLINEINITIALIZEEXPARAMS lpLineInitializeExParams
                             );
使用lineInitializeEx函数有两个好处。第一个是它具有对TAPI版本的协商能力,第二个是应用程序如何通知事件的控制能力.
lineInitializeEx函数的一大优点是能控制通过什么方法去告知应用程序有关的线路事件。应用程序接收事件通知有3种方式。第一种是使用TAPI在TAPI应用程序中建立一个隐含的窗口，从而使发送给窗口的消息由TAPI自身去处理.当TAPI想发送一个消息给应用程序的时候，他就发送给隐含的窗口。应用程序调用GetMessage检索其消息。第二种方法是TAPI提供其他方法实现事件的通知。他将dwOptions字段设置成LINEINITIALIZEEXOPTION_USEEVENT.TAPI将创建一个Win32事件对象，用于指示TAPI设备的变化。第三种方法是通过Win32 CreateIoCompletionPort函数创建一个完成端口。
 在TAPI初始化实例建成后，下一步应协商一个TAPI版本，这可以通过lineNegotiateAPIVersion函数完成
  lineNegotiateAPIVersion函数原型如下:
 LONG WINAPI lineNegotiateAPIVersion(
                                    HLINEAPP hLineApp,//返回的是TAPI的实例句柄
                                    DWORD    dwDeviceID,//检查设备的标识符
                                    DWORD    dwAPILowVersion,//应用程序兼容的TAPI最低版本
                                    DWORD    dwAPIHightVersion,//TAPI兼容的最高版本
                                    LPDWORD  lpdwAPIVersion,//返回参数,协商后的TAPI版本号
                                    LPLINEEXTENSIONID lpExtensionID//指向一个结构指针每个服                                     //务程序都可以通过这个指针实现扩充的目的，返回参数，表                                     //示扩展的ID
                                    );
特定设备识别符的TAPI版本号确定后就可以通过调用lineGetDevCaps函数获取此设备的更多信息，包过该设备的可以处理的信息类型.
lineGetDevCaps(
               HLINEAPP hLineApp,//返回的是TAPI的实例句柄
               DWORD    dwDeviceID,//可用设备的标识符
               DWORD    dwAPIVersion,//协商后的TAPI版本号
               DWORD    dwExtVersion,//协商后的扩展版本号
               LPLINEDEVCAPS lpLineDevCaps//返回一个参数，表示当前可用线路设备的属性和能力
              );
如果此线路设备满足所有要求，则存储相应的识别符和TAPI版本信息以备使用。假设已合适的找到合适的线路设备，下一步调用lineOpen函数打开线路.
LONG WINAPI lineOpen(
                     HLINEAPP hLineApp,//TAPI的实例句柄
                     DWORD    dwDeviceID,//所选线路的索引
                     LPHLINE  lphLine,//一个指向HLINE参数的指针,用于把句柄返回给TAPI线路的实                                      //例
                     DWORD    dwAPIVersion,//第四个参数通过lineNegotiateAPIVersion协商后的                                         //TAPI版本号
                     DWORD    dwExtVersion,//协商后的扩展版本号，如果不打算使用服务器提供的                                         //程序扩展则需将值设为0
                     DWORD_PTR dwCallbackInstance,//一个DWORD,用于TAPI保留并返回给应用程序的                                               //不透明的数据.他是通过lineInitialize注册的回                                               //调函数被调用时产生的
                     DWORD    dwPrivileges,//于此线路相关设备联系的dwPrivileges参数，
                     DWORD    dwMediaModes,//只适用于dwPrivileges参数为                                           //LINECALLPRIVILEGE_OWNER模式的情况
                     LPLINECALLPARAMS const lpCallParams//
                     );成功返回0，否则负数
紧接着要对线路设备进行呼叫。在呼叫之前，必须生成一个拨号地址，可以通过lineTranslateAddress函数实现，它把规范的地址转换一个局部化的拨号地址.

LONG WINAPI lineTranslateAddress(
                                 HLINEAPP hLineApp,
                                 DWORD    dwDeviceID,
                                 DWORD    dwAPIVersion,
                                 LPCSTR   lpszAddressIn,//指向转换的规范地址的指针
                                 DWORD    dwCard,//一个索引，用于电话卡的重载
                                 DWORD    dwTranslateOptions,//用于转换时指定给随的任何特殊                                           //指令
                                 LPLINETRANSLATEOUTPUT lpTranslateOutput//存储生成的地址
                                 //LPLINETRANSLATEOUTPUT结构的值包含尺寸和偏移量，用于可拨号                                 //的和可显示的地址版本
                                 );
当地址转换成功后就可以调用lineMakeCall进行拨号了
LONG WINAPI lineMakeCall(
                        HLINE hLine,//TAPI的实例句柄
                        LPHCALL lphCall,//存放呼叫句柄
                        LPCSTR  lpszDestAddress,//NULL结尾的呼叫字符串
                        DWORD   dwCountryCode,//呼叫方的国家代码，如给0则使用默认值
                        LPLINECALLPARAMS const lpCallParams//
                        );
假设收到了回叫，表示请求的呼叫已经建立，则可以在线路中传输数据。正如前面所说的，传输数据这部分的工作不属于TAPI模块
数据在线路上传输后，下一步就挂起电话lineDrop.
LONG WINAPI lineDrop(
                     HCALL hCall,//处理现存的呼叫
                     LPCSTR lpsUserUserInfo,//用户传送的字符串信息
                     DWORD  dwSize//用户之间信息的大小
                     );
TAPI 的结束才是最后一步
LONG WINAPI lineShutdown(
                         HLINEAPP hLineApp//应用程序实例句柄
                         );
(3)增补电话服务:
          指被API定义的但不是某一特定TAPI服务提供程序所要求的服务。增补电话服务一般需要附加的硬件支持。因此该服务是可选的。
(4)扩充电话服务:
          TAPI的设计目标是提供一个可扩展的框架，通过用户程序可以访问供应商提供的硬件解决方案的特性和功能。扩充电话服务允许供应商通过添加设备和服务提供程序专门的特性和功能扩展电话API.应用这一服务级的程序一般是对准特定供应商的产品而开发的，因而缺乏良好的可移植性。

 

使用TAPI构造电话语音应用程序的方法

　　在Windows NT网络中，第一次建立电话环境时，应在进程中执行1个初始化调用来设置TAPI环境，包括：加载Tapi32．dll、执行TAPI服务Tapisrv．exe以及加载注册库中有关的电话设备驱动程序。
　　 编制电话语音应用程序大致需要经过如下的过程：
　　（1）初始化TAPI。通过lineInitialize函数在应用程序中完成TAPI的初始化。lineInitialize函数给出了应用程序的回调函数，用来通知应用程序的各种事件；lineInitialize函数返回1个TAPI使用句柄，并指明TAPI使用的通信机制。
　　（2）协调TAPI的版本。应用程序使用lineNegotiateAPIVersion函数把API使用版本通知给TAPI，返回与TAPI通信所能使用的版本，同时获得线路设备支持的扩展功能。
　　（3）检查设备。调用lineGetDevCaps函数询问设备的能力，返回1个LINEDEVCAPS类型的数据结构。设备的能力包括如下信息：TAPI服务提供者、交换机信息、字符串格式、载波方式、数据传输率等。
　　（4）应用程序注册。利用函数lineRegisterRequestRecipient将应用程序进行注册。
　　（5）拨号。启动拨号按钮，应用程序提取用户的输入数据，然后调用ResolveNumber函数修改用户的输入数据，修改后的号码用于拨号。
　　（6）启用线路设备。调用函数lineOpen打开1条线路设备，lineOpen返回线路设备的句柄，用以完成以后对此设备的各种操作。当然在1个应用程序中可以打开多个线路。
　　（7）号码转换。调用函数lineTranslateAddress将要拨的号码转变成可以直接在电话上拨的号码。转换好的号码返回给LINETRANSLATEOUTPUT结构，在转换后，返回2个号码：1个在线路设备上用于拨号，另1个显示给用户。
　　（8）呼叫。随后使用函数lineMakeCall进行呼叫，lineMakeCall使用lineOpen返回的线路句柄，返回1个带有拥有者特权的当前呼叫的句柄，用于对本次呼叫进行以后的操作。若函数lineMakeCall返回呼叫有问题，由LINE＿REPLY消息提供呼叫的状态。
　　（9）结束呼叫。通信完成后，调用lineDrop函数结束呼叫，但其并不释放呼叫的句柄，可以通过调用lineDeallocateCall来释放句柄。
　　（10）关闭线路。通过lineClose函数关闭线路，使其可以被其它应用程序使用，同时释放了呼叫的句柄。
　　（11）终止TAPI调用。调用lineShutdown函数关闭TAPI的使用。