20110510 Brew工程师培训笔记——第十六章 ITAPI 简介

第十六章 ITAPI 简介

一、主要内容

（1）、获取状态信息以及进入或正在呼叫的主叫号码

（2）、安排语音呼叫

（3）、短消息的提取和发送

（4）、BREW短消息

二、获取手机的状态信息

（1）、呼叫状态

（a）、呼叫状态的信息可以通过ITAPI_GetStatus()获得，所得到的信息存储在数据结构TAPIStatus中

typedef structure

{

char szMobileID[MOBILE_ID_LEN +1];

PhoneState state;

flg bData:1;

flg bDigital:1;

flg bRoaming:1;

flg bCallEnded:1;

flg bE911CallbackMode:1;

flg bRestricted:1;

flg bRegistered:1;

flg bDormancy:1;

} TAPIStatus;

（2）、设备的状态

（a）、PhoneState 用于 ITAPI_GetStatus()，以获取设备的当前状态。 它是 TAPIStatus 数据结构中的一个成员，该结构将由 ITAPI_GetStatus() 函数填充。

typedef enum

{

PS_OFFLINE,

PS_IDLE,

PS_INCOMING,

PS_ORIG,

PS_CONVERSATION

} PhoneState;

（3）、呼叫相关的用户信息

（a）、获取进入或外发语音呼叫的用户号码

1、通过ITAPI_GetCallerID()得到

（4）、获得设备的 IMSI/MIN

（a）、ITAPI_GetStatus() 返回的 TAPIStatus 结构中的 szMobileID - 所有 BREW SDK 版本。

（b）、设备项目 AEE_DEVICEITEM_MOBILE_ID 的 ISHELL_GetDeviceInfoEx() - BREW SDK 2.1 以上 

（5）、呼叫状态发生变化时的通知

（a）、ITAPI_OnCallStatus()方法用于注册回调函数，当呼叫状态发生变化时， BREW 将调用该回调函数。

（b）、它支持用于指定应用程序所关注呼叫状态类型的标记

int ITAPI_OnCallStatus

(

ITAPI * pITAPI,

PFNNOTIFY pfn,

void * pUser,

uint32 dwDelay,

uint16 wFlags

)

三、语音呼叫

（1）、语音呼叫的特点

（a）、ITAPI_MakeVoiceCall()方法用于安排语音呼叫 

（b）、拨叫的号码通过数字字符串指定。 如果输入的是空串或NULL，则不安排呼叫 

（c）、只允许使用以下数字：0-9、#、*。其它数字均将忽略

（d）、如果正在进行语音呼叫，则返回 EALREADY 

（e）、如果正在进行数据呼叫但是没有网络活动 (TCP)，则结束数据呼叫而安排语音呼叫。 

（f）、该函数可以实现运营商确立的保密策略， 其中包括以对话框方式提供给用户的中间提示

（2）、语音呼叫的事件流程

（a）、向用户显示对话框。

（b）、清除对话框时，将事件 EVT_DIALOG_END 发送至应用程序。

（c）、此时，应用程序必须刷新屏幕。

（d）、如果用户同意安排呼叫，则将事件 EVT_APP_SUSPEND 发送至应用程序。

（e）、呼叫完成时，将事件 EVT_APP_RESUME 发送至应用程序。

（f）、应用程序必须刷新屏幕。

四、收发普通短消息

（1）、普通短消息的接收

（a）、使用 MIF Editor （或使用 ISHELL_RegisterNotify()）注册 AEECLSID_TAPI 类的NMASK_TAPI_SMS_TEXT 通知。

（b）、当入局 SMS 文本消息进入系统时，向应用程序发送 EVT_NOTIFY 事件，其中， dwParam 指向的 AEENotify 结构的 pData 将指向 AEESMSMsg 结构。

（c）、将此结构传至 ITAPI_ExtractSMSText()，以提取消息的格式化文本部分。

AEESMSTextMsg * ITAPI_ExtractSMSText

(

ITAPI * pITAPI,

const AEESMSMsg * pMsg

)

（2）、普通短消息的发送

（a）、用BREW的ITAPI_SendSMS()函数来发送中／英文短消息。ITAPI_SendSMS()函数的原形如下

int ITAPI_SendSMS

(

ITAPI *pITapi,

const char * pszDst,

const char * pszMsg,

AEECLSID clsDst,

PFNSMSSTATUS pfn,

void *pUser

)

（3）、普通短消息的发送示例

（a）、英文短消息

ITAPI_SendSMS(pITapi, 

"8581112222", 

"Hello World", 

0,

  MyMOSMSNotify, 

pMe);

（b）、中文短消息:

AECHAR w_string[]= { 0x4F60, 0x597D,0x4e2D,0x56FD, ‘/0’}; //你好中国

ITAPI_SendSMS(pITapi,

 "8581112222", 

(const char*)w_string,

 0,

 MyMOSMSNotify, 

pMe);

（c）、短消息发送成功与否的判断

1、ITAPI_SendSms()实际上是一个异步调用

2、消息发送是否成功则需要底层通过回调函数来通知

3、BREW API定义了回调函数的类型为PFNSMSSTATUS

typedef void (*PFNSMSSTATUS)(void * pUser, int16 status);

4、如果用户的回调函数名为MySmsNotify, 则其函数原形为

void MySmsNotify(CSmsApp * pApp, int16 status)

5、建议在回调函里只把发送状态值status保存下来 

五、BREW 短消息

（1）、Brew 短消息的格式

（a）、BREW把一种特定格式的短消息称为BREW特定应用消息(BREW directed message)，即这种特殊的短消息是发送给某一个特定的BREW应用程序的 。

（b）、BREW短信的格式如下：

 //BREW:<Class ID>:<Text Payload>

其中：

//BREW——消息头，表示本短信为BREW短信；

Class ID——表示接收短信的应用程序的Class ID 号；

Text Payload——附加的消息文本，ASCII格式；

例如：

//BREW:01009FF0:test

//BREW:0x01009FF0:Hello world

（2）、BREW短信的发送简例

（a）、和发送普通短信一样，调用ITAPI_SendSMS()函数发送 

ITAPI_SendSMS(pMe->m_pITAPI,

”13331016561”,

”//BREW:0x01009FF0:Hello world”, 

0, 

(PFNSMSSTATUS)MySmsNotify,

  pMe);

（b）、BREW短信的接收过程

1、BREW手机的底层软件首先截获短消息，判断消息头是否为 //BREW；

2、如果判断是BREW短信，则启动BREW应用管理器

3、BREW应用管理器根据收到的Class ID加载对应的BREW应用程序,并完成该应用程序的初始化工作；

4、BREW应用管理器发送EVT_APP_MESSAGE事件给应用程序；

5、应用程序的HandleEvent()函数处理EVT_APP_MESSAGE事件，如果需要启动应用，则调用ISHELL_StartApplet()函数来启动；或者也可以“悄悄地”进行处理而不用启动应用程序。

（c）、BREW短信的接收简例

case EVT_APP_MESSAGE:
//得到BREW短信的文本信息 

char* textPayload = (char *)dwParam; 

// 启动应用

ISHELL_StartApplet(pMe->a.m_pIShell, 
AEECLSID_HELLOWORLD);
return TRUE;

（d）、BREW短信中发送中文

1、定义变量wStrMessage, 类型为（AECHAR*），指向一段UNICODE字符串的缓冲区；

2、定义变量BrewHeader存储BREW短信的消息头字符串，这里假设为 //BREW:0x01009FF0:。将这段ASCII字符串拷贝到wStrMessage缓冲区的开始段。可以用STRNCPY函数来完成拷贝，例子如下：

STRNCPY( (char *)(wStrMessage), BrewHeader, STRLEN(BrewHeader) );

3、在wStringMessage缓冲区中，紧接着BREW短消息头的后面，将中文字符串ChineseTextMsg拷贝过来；例如：

WSTRCPY（&(wstrMessage[STRLEN(BrewHeader)/2]), ChineseTextMsg);

4、调用ITAPI_SendSMS()函数发送，注意UNICODE字符串wStrMessage要强制转换成（const char*），这是ITAPI_SendSMS()函数要求的 

（e）、BREW短信中接收中文

1、EVT_APP_MESSAGE事件的dwParam变成了指向UNICODE字符串的指针，只要把该段的数据拷贝过来即可。例子如下：

case EVT_APP_MESSAGE:

{
WSTRCPY( (AECHAR*)wTextPayload, (AECHAR*)dwParam);

      return TRUE;

 }

（f）、用BREW短信开发应用程序的几种解决方案 

1、在短信中直接传送消息。如果在用户的数据量不大的情况下，是最简单实用的方法。缺点是当数据量变大时，不适用 

2、在短信中传送应用程序的启动参数。和命令行参数类似，通过发送不同的参数来执行程序的不同分枝。可以用ISHELL_StartAppletArgs()函数来实现。

3、在短信中传送一个网站的URL地址，应用程序收到短信后可以自动连接网站

（g）、注意事项 

1、也可以发送普通短信的方式来发送BREW短信，只要数据格式正确，在任何一台能发短信的手机上都可以发送。

2、如果BREW短信的消息头格式错误，则该短信会被手机的短消息信箱接收到。

3、如果BREW短信的消息头格式正确，但是Class ID错误或者接收方手机中无此应用程序，该短消息会丢弃不用，而不会传到手机的普通短消息信箱中，也不产生任何形式的提示信息。 

4、接收方的应用程序无需在MIF文件中作notification, ITAPI等选项设置 

（h）、示例程序

在模拟器器中测试Brew短消息激活应用的方法如下：

1、启动ＢＲＥＷ模拟器

2、选择小程序的路径到Myitapi示例程序

3、选择Brew模拟器中的“Tools－Tapi Emulation”

4、在弹出对话框中单击“Send SMS”

5、输入Myitapi的ClassＩＤ, 再输入字符串“Hello Brew”，单击“Send”

6、ＢＲＥＷ模拟器 将出现“Hello Brew”页面

六、本章关键点

（1）、获得状态信息

（2）、语音呼叫

（3）、普通短消息

（4）、Brew 短消息

七、问题回顾

（1）、可以获得那些状态信息？

（2）、语音呼叫的流程是什么？

（3）、短消息的收发方法是什么？

（4）、如何使用BREW短消息激活一个应用？

（5）、如何发送带中文的BREW短消息？