RTXClient 插件開發(fā)指南 Step by step

1、 第 1 頁 共 20 頁RTXCRTXC 插件開發(fā)指南插件開發(fā)指南 StepStep byby stepstep騰訊科技（深圳）有限公司騰訊科技（深圳）有限公司版權(quán)所有 侵權(quán)必究 第 2 頁 共 20 頁目目 錄錄1、開發(fā)前準(zhǔn)備、開發(fā)前準(zhǔn)備 .42、創(chuàng)建插件工程、創(chuàng)建插件工程 .43、界面上的體現(xiàn)、界面上的體現(xiàn) .84、交互控制、交互控制 .115、收發(fā)數(shù)據(jù)處理、收發(fā)數(shù)據(jù)處理 .176、插件打包發(fā)布、插件打包發(fā)布 .217、后語、后語 .21 第 3 頁 共 20 頁1、開發(fā)前準(zhǔn)備、開發(fā)前準(zhǔn)備需要安裝如下文件：RTXClient 安裝包 RTXClient SDK 安裝包開發(fā)插件的過程一般是

2、要經(jīng)歷一下幾個步驟：創(chuàng)建插件工程，RTX 客戶端里界面上體現(xiàn)，交互控制，數(shù)據(jù)傳輸，打包發(fā)布；以下的用例是開發(fā)一個程序共享的插件，通過介紹開發(fā)程序共享的插件，來講解插件的一般開發(fā)過程。2、創(chuàng)建插件工程、創(chuàng)建插件工程創(chuàng)建插件工程，首先把 RTXC SDK 目錄中 wizard 目錄下的 RTXCModuleAW.awx文件拷至 VC 安裝目錄 Microsoft Visual StudioCOMMONMSDev98Template ，然后在 VC 中創(chuàng)建一個插件工程。第一步：創(chuàng)建一個 AppSharePlugin 工程。 第 4 頁 共 20 頁第二步：設(shè)置插件的信息。第三步：設(shè)置插件內(nèi)部邦定的事

3、件。 第 5 頁 共 20 頁完成以上三個步驟之后，可以自動生成如下函數(shù)： 第 6 頁 共 20 頁這些自動生成的代碼，已經(jīng)定義了 RTXC 的接口函數(shù)，一個插件的基本框架已經(jīng)搭建成功，用戶只需要在這些接口函數(shù)里添加自己的功能。創(chuàng)建完成一個插件工程之后，就需要考慮在 RTX 的客戶端界面能體現(xiàn)出該插件，如菜單、面板、TAB 或者在 RTXC 其他的界面元素上；程序共享主要在 RTXC 的菜單上增加一個新的菜單項來體現(xiàn)，其他的體現(xiàn)方式，可以參看 RTXC SDK 文檔。 第 7 頁 共 20 頁3、界面上的體現(xiàn)、界面上的體現(xiàn)程序共享一般需要在 RTX 客戶端的菜單中添加“程序共享”的菜單項，操作

4、步驟如下：第一步：設(shè)置動態(tài)菜單相關(guān)的內(nèi)容。首先在 Stdafx.h 文件中添加如下代碼：#import ClientObjects.tlb raw_interfaces_only no_namespace, named_guids#include RTXCModuleIds.h在插件中實現(xiàn)動態(tài)的添加和刪除菜單，就必須包含 ClientOjbect.tlb 和RTXModuleIds.h 這兩個文件，這兩個文件分別位于 SDK 安裝目錄下的 TLB 和 INCLUDE目錄下，用戶可以根據(jù)實際情況，設(shè)置文件的相對路徑。然后在 AppSharePluginModule.h 文件中增加菜單對象的定義和

5、菜單響應(yīng)的函數(shù)，如下：IRTXCMenuPtrm_pMenu; / 定義 RTXC 菜單對象IRTXCUICommand*m_pUICmd;定義菜單響應(yīng)函數(shù)的接口：BEGIN_DUAL_INTERFACE_PART(MenuSink, IRTXCUICommand)STDMETHOD(OnInvoke)(enum RTXC_UI_TYPE UIType, long Id, VARIANT Parameter)METHOD_PROLOGUE(CAppSharePluginModule, MenuSink)return pThis-OnInvoke(UIType, Id, Parameter);S

6、TDMETHOD(OnQueryState)(enum RTXC_UI_TYPE UIType, long Id, VARIANT Parameter, BSTR* Text, enum RTXC_UI_ITEM_STATE* State)METHOD_PROLOGUE(CAppSharePluginModule, MenuSink)return pThis-OnQueryState(UIType, Id, Parameter, Text, State);END_DUAL_INTERFACE_PART(MenuSink)定義菜單響應(yīng)的接口函數(shù)：HRESULT OnInvoke(enum RTX

7、C_UI_TYPE UIType, long Id, VARIANT Parameter);HRESULT OnQueryState(enum RTXC_UI_TYPE UIType, long Id, VARIANT Parameter, BSTR* Text, enum RTXC_UI_ITEM_STATE* State); 第 8 頁 共 20 頁在 AppSharePluginModule.cpp 文件中，需要添加如下代碼：/ 實現(xiàn)標(biāo)準(zhǔn)的 IDispatch 方法DELEGATE_DUAL_INTERFACE(CAppSharePluginModule, MenuSink)/ 實現(xiàn)菜單

8、響應(yīng)的實現(xiàn)函數(shù)：HRESULT CAppSharePluginModule:OnQueryState(enum RTXC_UI_TYPE UIType, long Id, VARIANT Parameter, BSTR* Text, enum RTXC_UI_ITEM_STATE* State)return S_OK;HRESULT CAppSharePluginModule:OnInvoke(enum RTXC_UI_TYPE UIType, long Id, VARIANT Parameter)return S_OK;第二步：添加動態(tài)菜單。在 AppSharePluginModule.cp

9、p 文件中的 OnLoad 函數(shù)中，實現(xiàn)添加菜單的功能，代碼如下：/ 添加菜單，其中ID_BENGIN_SCREEN_SHARE 為自定義的菜單項的 IDIRTXCModulePtr& module = m_ptrRoot-ModuleRTX_MODULE_IDENTIFIER_CLIENT_OBJS;IClientObjectsModulePtr ClientObjects = module;CComPtr ptrMenu;if(FAILED(ClientObjects-get_Object(_bstr_t(_T(RTXCMenu),(IDispatch*)&ptrMenu)

10、 | ptrMenu = NULL)throw RTX_UNSPECIFIC_ERROR;/ 在主窗口的操作菜單中添加項if (FAILED(ptrMenu-AddItem(VARIANT_FALSE, -1, RTXC_UI_TYPE_MAINFRAME_ACTION, ID_BENGIN_SCREEN_SHARE, &m_xMenuSink, _T(應(yīng)用程序共享), NULL, RTXC_MENU_ITEM_SEPARATOR_BELOW, 3, VARIANT_FALSE)throw RTX_UNSPECIFIC_ERROR;/ 在組織架構(gòu)里的用戶上的右鍵菜單中添加項if (FA

11、ILED(ptrMenu-AddItem(VARIANT_FALSE, -1, RTXC_UI_TYPE_ORG_STRUCT_USER, 第 9 頁 共 20 頁ID_BENGIN_SCREEN_SHARE, &m_xMenuSink, _T(應(yīng)用程序共享), NULL, RTXC_MENU_ITEM_SEPARATOR_BELOW, 3, VARIANT_FALSE)throw RTX_UNSPECIFIC_ERROR;/ 在 IM 窗口添加第三方菜單if (FAILED(ptrMenu-AddItem(VARIANT_FALSE, -1, RTXC_UI_TYPE_IM_THIR

12、DPARTY, ID_BENGIN_SCREEN_SHARE, &m_xMenuSink, _T(應(yīng)用程序共享), NULL, RTXC_MENU_ITEM_SEPARATOR_BELOW, 3, VARIANT_FALSE)throw RTX_UNSPECIFIC_ERROR;至此，已經(jīng)完成了向 RTX 客戶端添加菜單的功能，該插件運(yùn)行之后，會在 RTX 客戶端添加一個新的菜單項“應(yīng)用程序共享” ，如下圖： 圖 1 在主面板菜單中添加新菜單 圖 2 在用戶右鍵菜單中添加新的菜單 第 10 頁 共 20 頁圖 3 在會話窗口里添加第三方菜單完成界面體現(xiàn)之后，接下來應(yīng)該做的用戶之間的交互

13、，當(dāng)一方提出邀請另一方來進(jìn)行程序共享的時候，另一方可以選擇接受或者拒絕；這些操作都是需要用戶自己在程序中控制，并且可以采用一定的方式表現(xiàn)出來。4、交互控制、交互控制以上已經(jīng)實現(xiàn)了插件在 RTX 客戶端添加菜單的功能，用戶在點(diǎn)擊菜單的時候，就可以發(fā)起一次程序共享的邀請，具體操作的步驟如下：第一步：得到當(dāng)前選中的用戶名。在 OnQueryState 和 OnInvoke 函數(shù)中，都可以得到當(dāng)前選中的用戶名；如下代碼是在OnQueryState 函數(shù)中得到當(dāng)前選中的用戶：HRESULT CAppSharePluginModule:OnQueryState(enum RTXC_UI_TYPE UITy

14、pe, long Id, VARIANT Parameter, BSTR* Text, enum RTXC_UI_ITEM_STATE* State)if( Id = ID_BENGIN_SCREEN_SHARE)/ 在組織架構(gòu)里的用戶上的右鍵菜單中得到選中的用戶CString strSelectName;if(UIType = RTXC_UI_TYPE_ORG_STRUCT_USER)/ 得到選中的用戶名if(Parameter.vt = VT_DISPATCH)IRTXCDataCollectionPtr ptrReceivers = Parameter.pdispVal;int nCou

15、nt = ptrReceivers-Count;if(nCount 0)IRTXCDataPtr pstrRtxData=ptrReceivers-GetItem(1);long nType=pstrRtxData-GetLong(RDK_TYPE);if(nType=OBJECT_RTX_BUDDY)_bstr_t bstrUserName=pstrRtxData-GetString(RDK_VALUE);strSelectName=OLE2T(bstrUserName);else if(Parameter.vt = VT_BSTR)_bstr_t bstrUserName= Paramet

16、er. bstrVal;strSelectName=OLE2T(bstrUserName); 第 11 頁 共 20 頁/ 在 IM 窗口里的第三方菜單中得到當(dāng)前會話窗口的用戶else if(UIType = RTXC_UI_TYPE_IM_THIRDPARTY)/ 得到選中的用戶名vector vecParticipants;IRTXCSessionPtr ptrSession = Parameter.pdispVal;_bstr_t bstrParticipants = ptrSession-Participant;CString str = (LPCTSTR)bstrParticipan

17、ts;int iStart = 0;int iIndex = str.Find(_T(;);BOOL bBreak = FALSE;while(!bBreak)CString strTmpToken ;if (iIndex != -1)strTmpToken = str.Mid(iStart, iIndex - iStart);iStart = iIndex + 1;iIndex = str.Find(_T(;), iStart); elsebBreak = TRUE;strTmpToken = str.Mid(iStart, _tcslen(LPCTSTR)str)-iStart);if (

18、strTmpToken.IsEmpty()return S_OK;/ 檢查當(dāng)前用戶是否是自己if (strTmpToken.CompareNoCase(LPCTSTR)m_ptrRoot-Account) != 0)vecParticipants.push_back(strTmpToken);strSelectName = vecParticipants.at(0); 第 12 頁 共 20 頁return S_OK;第二步：設(shè)置菜單項的狀態(tài)當(dāng)選中的用戶離線的時候，菜單會變成 Disable 狀態(tài)，可以在 OnQueryState 函數(shù)中設(shè)置菜單的狀態(tài)，如下代碼：HRESULT CAppSha

19、rePluginModule:OnQueryState(enum RTXC_UI_TYPE UIType, long Id, VARIANT Parameter, BSTR* Text, enum RTXC_UI_ITEM_STATE* State)if( Id = ID_BENGIN_SCREEN_SHARE)CString strSelectName;/ 得到選中的用戶名，如上代碼。if ( RTX_PRESENCE_OFFLINE = m_ptrRoot-Presence-RTXPresence_bstr_t(strSelectName) )/ 選中的用戶離線，菜單設(shè)置為 Disable

20、 狀態(tài)*State = RTXC_UI_ITEM_STATE_DISABLED;return S_OK;return S_OK;完成以上代碼之后，當(dāng)檢測到用戶離線的時候，可以讓“應(yīng)用程序共享”菜單項變?yōu)榛疑?，其效果如下圖所示： 第 13 頁 共 20 頁第三步：檢測對方是否安裝插件在發(fā)起邀請之前，需要檢測對方是否安裝過該插件，在響應(yīng)程序共享的菜單項的時候，向?qū)Ψ桨l(fā)送一個確認(rèn)數(shù)據(jù)包，如果對方?jīng)]有安裝插件，就會立即返回一個發(fā)送結(jié)果，根據(jù)發(fā)送的結(jié)果，可以得到對方是否安裝過插件。如下代碼：#define SCREEN_SHARE_TEST_T(ScrnShareTest)HRESULT CAppSha

21、rePluginModule:OnInvoke(enum RTXC_UI_TYPE UIType, long Id, VARIANT Parameter)if(Id = ID_BENGIN_SCREEN_SHARE)CString strSelectName;/ 得到當(dāng)前選中的用戶名，代碼如上。/ 發(fā)送一個數(shù)據(jù)包給對方，測試一下對方是否存在該插件IRTXCDataPtr& ptrSendData = m_ptrRoot-CreateRTXCData();ptrSendData-SetString(SRC_SENDER, _bstr_t(LPCTSTR)m_ptrRoot-Account

22、);ptrSendData-SetString(SRC_KEY, _bstr_t(SCREEN_SHARE_TEST);m_ptrModuleSite-SendData(_bstr_t(LPCTSTR) strSelectName), ptrSendData, RTXC_SEND_DATA_FLAG_FILTERING_IS_FORBIDDEN); 第 14 頁 共 20 頁return S_OK;在發(fā)送數(shù)據(jù)包之后，會觸發(fā) evt_OnSendDataResult 事件，響應(yīng) OnSendDataResult函數(shù)，如下代碼：HRESULT CAppShareModule:OnSendDataR

23、esult( RTXC_MODULE_SEND_DATA_RESULT Result, Const VARIANT* Extra)if(Result = RTXC_MODULE_SEND_DATA_RESULT_NOT_EXIST)/對方不存在本插件CString strRecverName;strRecverName = (LPCTSTR)_bstr_t(Extra-bstrVal);/ strRecverName 用戶沒有安裝插件！return S_OK;第四步：發(fā)送邀請。當(dāng)點(diǎn)擊菜單的時候，會執(zhí)行 OnInvoke 函數(shù)，可以在該函數(shù)中發(fā)起程序共享的邀請，如下代碼：#define SCRE

24、EN_SHARE_CMD_INVITE_T(ScrnShareCmdInvite)#define SCREEN_SHARE_CMD_ACCEPT_T(ScrnShareCmdAccept)HRESULT CAppSharePluginModule:OnInvoke(enum RTXC_UI_TYPE UIType, long Id, VARIANT Parameter)if(Id = ID_BENGIN_SCREEN_SHARE)CString strSelectName;/ 得到當(dāng)前選中的用戶名，代碼如上。/不能給自己發(fā)起程序共享的邀請if(strSelectName = (LPCTSTR)

25、m_ptrRoot-Account)return S_FALSE/ 發(fā)送一個數(shù)據(jù)包給對方，來邀請對方接受程序共享IRTXCDataPtr& ptrSendData = m_ptrRoot-CreateRTXCData();ptrSendData-SetString(SRC_SENDER, _bstr_t(LPCTSTR)m_ptrRoot-Account); 第 15 頁 共 20 頁/ SCREEN_SHARE_CMD_ INVIT 標(biāo)識發(fā)起邀請ptrSendData-SetString(SRC_KEY, _bstr_t(SCREEN_SHARE_CMD_INVIT);m_ptrMo

26、duleSite-SendData(_bstr_t(LPCTSTR) strSelectName), ptrSendData, RTXC_SEND_DATA_FLAG_FILTERING_IS_FORBIDDEN);return S_OK;第五步：接受邀請。接受方接收到發(fā)送放的程序共享邀請之后，會觸發(fā) evt_OnDataReceived 事件，響應(yīng) OnDataReceived 函數(shù)，用戶在此函數(shù)中，來處理該邀請，如下代碼：void CAppSharePluginModule:OnDataReceived(LPCTSTR Key)RTXCDataPtr& ptrData = m_pt

27、rModuleSite-GetData(Key, VARIANT_TRUE);_bstr_t& command = ptrData-GetString(SRC_KEY);/ 接收到程序共享的邀請if(command = _bstr_t(SCREEN_SHARE_CMD_INVITE)CString strSenderName;strSenderName = (LPCTSTR)ptrData-GetString(SRC_SENDER);/ 可以彈出一個自定義 TIP 的窗口，來提示用戶進(jìn)行選擇，如下圖。/ 當(dāng)用戶接受邀請，向發(fā)送方發(fā)送接受邀請的數(shù)據(jù)包IRTXCDataPtr& p

28、trSendData = m_ptrRoot-CreateRTXCData();ptrSendData-SetString(SRC_SENDER, _bstr_t(LPCTSTR)m_ptrRoot-Account);/ SCREEN_SHARE_CMD_ACCEPT 標(biāo)識接收邀請ptrSendData-SetString(SRC_KEY, _bstr_t(SCREEN_SHARE_CMD_ACCEPT);m_ptrModuleSite-SendData(_bstr_t(LPCTSTR) strSenderName), ptrSendData, RTXC_SEND_DATA_FLAG_FILT

29、ERING_IS_FORBIDDEN);下圖是一個自定義的對話框 TIP，當(dāng)用戶接收到邀請的時候，會在右下角彈出這個 TIP讓用戶進(jìn)行選擇接受和拒絕。 第 16 頁 共 20 頁5、收發(fā)數(shù)據(jù)處理、收發(fā)數(shù)據(jù)處理程序共享的網(wǎng)絡(luò)傳輸是采用兩種傳輸方式：RTX 傳輸通道和 P2P 通道；這兩種方式同時存在，傳輸數(shù)據(jù)量比較小的命令和控制信息，采用 RTX 傳輸通道來實現(xiàn)，這樣可以實現(xiàn)安全和穩(wěn)定的傳輸；針對數(shù)據(jù)量比較大的屏幕壓縮數(shù)據(jù)和鼠標(biāo)位置信息等，將采用 P2P 傳輸，這樣的傳輸高效，占用的資源比較少。RTX 傳輸通道的使用方式，是通過m_ptrModuleSite-SendData()來實現(xiàn)發(fā)送數(shù)據(jù)，

30、當(dāng)接收到數(shù)據(jù)的時候，會響應(yīng) OnDataReceived 函數(shù)，其具體操作，可以參看“交互控制”部分的描述；在此，主要說明 P2P 通道的使用，其步驟如下：第一步：創(chuàng)建 P2P 通道管理器。在 AppSharePluginModule.h 文件中添加 P2P 通道管理接口指針的定義：IP2PMgrExPtrm_ptrP2PMgrEx;CRTXP2PExEvent*m_P2MgrExEventSink;typedef map MAP_P2PCHANNEL_SEQ;MAP_P2PCHANNEL_SEQm_mapP2PChannelSeq;/ 定義一個接受者CStringm_strRecvName;

31、/ P2P 通道的事件響應(yīng)函數(shù)void OnCreateResult(LONG nSeq,BSTR pAccount,LONG nError);void OnRecv(LONG nSeq,BYTE * pData, LONG DataLen);void OnSend(LONG nSeq, LONG nResult);在 AppSharePluginModule.cpp 文件中的 OnLoginResult 函數(shù)中實現(xiàn)對該指針的初始化：HRESULT CAppSharePluginModule:OnLoginResult(RTXC_LOGIN_RESULT Result)RTX_TRYif(Re

32、sult = RTXC_LOGIN_RESULT_OK) 第 17 頁 共 20 頁/ 登陸成功，初始化 P2P 通道m(xù)_ptrP2PMgrEx = NULL;m_ptrP2PMgrEx = m_ptrRoot-CreateP2PMgr();if(m_ptrP2PMgrEx != NULL & m_ptrRoot != NULL)m_ptrP2PMgrEx-Init(m_ptrRoot);m_ptrP2PMgrEx-SetVerify(_bstr_t(_T(p2p_appshare);m_P2PMgrExEventSink = CRTXP2PExEvent:CreateObject()

33、;if(m_P2PMgrExEventSink) m_P2PMgrExEventSink-evt_OnRecv.bind(this,&CAppSharePluginModule:OnRecv); m_P2PMgrExEventSink-evt_OnCreateResult.bind(this,&CAppSharePluginModule:OnCreateResult); m_P2PMgrExEventSink-evt_OnSend.bind(this,&CAppSharePluginModule:OnSend); if (!m_P2PMgrExEventSink-Adv

34、ise(m_ptrP2PMgrEx) throw RTX_UNSPECIFIC_ERROR; RTX_CATCH_ALL(return E_FAIL);return S_OK;在 AppSharePluginModule.cpp 文件中添加事件響應(yīng)函數(shù)：/ 返回創(chuàng)建通道的結(jié)果void CAppSharePluginModule:OnCreateResult(LONG nSeq,BSTR pAccount, LONG nError) / 返回發(fā)送數(shù)據(jù)的結(jié)果void CAppSharePluginModule:OnSend(LONG nSeq, LONG nResult) / 接收到 P2P 通道

35、的數(shù)據(jù)void CAppSharePluginModule:OnRecv(LONG nSeq, BYTE *pData, LONG DataLen) 第 18 頁 共 20 頁第二步：創(chuàng)建一個 P2P 通道。在程序共享發(fā)起方接收到對方接受邀請的命名之后，發(fā)起方會跟接受方建立一個 P2P通道，在 OnDataReceived 函數(shù)中實現(xiàn)創(chuàng)建 P2P 通道，如下代碼：void CAppSharePluginModule:OnDataReceived(LPCTSTR Key)RTXCDataPtr& ptrData = m_ptrModuleSite-GetData(Key, VARIANT

36、_TRUE);_bstr_t& command = ptrData-GetString(SRC_KEY);/ 接收到程序共享的邀請if(command = _bstr_t(SCREEN_SHARE_CMD_INVITE)/ 代碼如上。./ 對方接受了發(fā)起方的邀請else if(command = _bstr_t(SCREEN_SHARE_CMD_ACCEPT)CString strSenderName;strSenderName = (LPCTSTR)ptrData-GetString(SRC_SENDER);/ 開始建立 P2P 通道if(m_ptrP2PMgrEx)m_ptrP2P

37、MgrEx-Create(_bstr_t(LPCTSTR) strSenderName);在創(chuàng)建 P2P 之后，需要去捕獲 OnCreateResult 事件，得到當(dāng)前創(chuàng)建 P2P 通道的結(jié)果，可以在如下函數(shù)中得到創(chuàng)建的 P2P 通道的序列號，該序列號可以唯一的標(biāo)識一個 P2P 通道，如下代碼：/ 返回創(chuàng)建通道的結(jié)果void CAppSharePluginModule:OnCreateResult(LONG nSeq,BSTR bstrAccount, LONG nError) CString strAccount(bstrAccount);if(nError)/ 當(dāng)前創(chuàng)建的 P2P 通道成功！把該通道的序列號保存在 m_mapP2PChannelSeq 中strAccount.MakeLower();m_mapP2PChannelSeqstrAccount = nSeq;m_strRecvName = strAccount; 第 19 頁 共 20 頁else/ 創(chuàng)建 P2P 通道失??！第三步：使用 P2P 通道。使用 P2P 通道來實現(xiàn)發(fā)送數(shù)據(jù),如下程序代碼：/ 發(fā)送程序共享數(shù)據(jù)包v