1.4、透明通道的實現方法 · AnyChat數據通信技術手冊

**1.4.1、接口方法說明：** **1.4.1.1、客戶端之間或與服務器使用透明通道傳輸數據接口** DWORD **BRAS_TransBuffer**(DWORD dwUserid, LPBYTE lpBuf, DWORD dwLen); 功能：透明通道傳送緩沖區，向指定的用戶傳輸緩沖區返回值：0表示成功，否則為出錯代碼參數： dwUserid：目標用戶編號，不能為-1 lpBuf：緩沖區 dwLen：緩沖區的大小備注：可以利用該方法實現自定義功能，緩沖區采用透明傳輸，效率與BRAS_SendBufToRoom、BRAS_SendBufToUser兩個方法相同，只是觸發客戶端的回調函數不同。該方法為V4.1版本新增API接口，主要是為了兼容客戶端API接口而設計。該方法將會觸發接收到數據的客戶端的BRAC_TransBuffer_CallBack回調函數。該方法不需要用戶進入房間，即可以在服務器內部的任意用戶之間傳輸數據。 **1.4.1.2、客戶端之間或與服務器使用透明通道擴展傳輸數據** DWORD BRAS_**TransBufferEx** (DWORD dwUserid, LPBYTE lpBuf, DWORD dwLen, DWORD wParam, DWORD lParam, DWORD dwFlags , DWORD& dwTaskId); 功能：透明通道傳送緩沖區，傳輸更大容量的緩沖區數據，而且可以附帶參數返回值：0表示成功，否則為出錯代碼參數： dwUserid：目標用戶編號，只針對某一個用戶，不能為-1（所有人） lpBuf：緩沖區，≤1024KB（1MB），內部會自動分包處理 dwLen：緩沖區的大小 wParam：附帶參數，由上層應用自定義 lParam：附帶參數2，由上層應用自定義 dwFlags：特殊功能標志，當對該緩沖區有特殊要求時，可通過使用相關的功能標志，通知SDK進行特殊的處理，默認為0，SDK將自動根據網絡狀態選擇合適的傳輸途徑（TCP、UDP or P2P） dwTaskId 與該緩沖區對應的任務ID（只有任務添加成功后，該ID才會自動生成，可利用該ID查詢該任務的傳輸進度） **備注：** 該方法與“BRAS_TransBuffer”功能相同，都是傳輸上層應用自定義（透明通道）數據，區別在于該方法通過設置相應的功能標識，如可選擇采用UDP通道傳輸，但是只針對指定的用戶傳輸，而“BRAS_TransBuffer”方法則固定采用TCP通道傳輸，且緩沖區大小不能超過1024個字節，但可以針對所有用戶傳輸。從應用來看：（1）、BRAS_TransBuffer適合數據量小、要求實時傳輸的緩沖區傳遞，如控制指令等；（2）、BRAS_TransBufferEx適合數據量大、對實時性要求不高的需求；該方法將會觸發接收到數據的客戶端的BRAC_TransBufferEx_CallBack回調函數。該方法不需要用戶進入房間，即可以在服務器內部的任意用戶之間傳輸數據。 **1.4.1.3、客戶端與服務器之間傳輸緩沖區數據（SDK Filter Data接口）** （1）客戶端向服務器發送數據 DWORD BRAC_SendSDKFilterData(LPBYTE lpBuf, DWORD dwLen); 功能：向服務器發送SDK Filter通信數據返回值：0表示成功，否則為出錯代碼參數： lpBuf：緩沖區 dwLen：緩沖區的大小備注：服務器收到數據后，會將該緩沖區數據全部提交給SDK Filter，由SDK Filter來解析，該緩沖區的內容對于本SDK和服務器來說，都是透明的。當服務器向客戶端發送SDKFilterData數據時，將會觸發SDK的回調：SDK Filter通信數據回調函數（參考：BRAC_SetSDKFilterData_CallBack）（2）向指定用戶發送數據接口 DWORD **BRAS_SendBufToUser**(DWORD dwUserId, LPCTSTR lpBuf, DWORD dwLen); 功能：向指定用戶發送自定義數據。返回值：0表示成功，否則為出錯代碼參數： dwUserId 目標用戶ID lpBuf 所發送緩沖區地址 dwLen 所發送緩沖區長度，不能大于1024個字節備注：當用戶登錄成功之后，無論該用戶是否在房間，業務層服務器均可調用該方法向指定的客戶端發送數據，數據內容由上層應用自定義。客戶端程序收到服務器所發送的緩沖區數據后，將會觸發客戶端的回調函數“BRAC_SDKFilterData_CallBack”。（3）向指定房間的所有用戶發送數據 DWORD **BRAS_SendBufToRoom**(DWORD dwRoomId, LPCTSTR lpBuf, DWORD dwLen); 功能：向指定房間的所有用戶發送數據。返回值：0表示成功，否則為出錯代碼參數： dwRoomId 目標房間ID，為-1表示向系統中的所有用戶廣播 lpBuf 所發送緩沖區地址 dwLen 所發送緩沖區長度，不能大于1024個字節備注：業務層服務器可使用該方法向指定房間的所有用戶廣播數據，也可向系統中所有用戶廣播數據，數據內容由上層應用自定義。客戶端程序收到服務器所發送的緩沖區數據后，將會觸發客戶端的回調函數“BRAC_SDKFilterData_CallBack”。 **回調函數說明：** **1.4.2、透明通道數據回調函數** typedef void (CALLBACK * BRAS_TransBuffer_CallBack)(DWORD dwUserid, LPBYTE lpBuf, DWORD dwLen, LPVOID lpUserValue); 參數： dwUserid：用戶ID，指示發送用戶 lpBuf：緩沖區地址 dwLen：緩沖區大小 lpUserValue：用戶自定義參數，在設置回調函數時傳入 AnyChat Server SDK 開發指南佰銳科技版權所有備注：當收到客戶端使用“BRAC_TransBuffer”方法發送的數據，且目標用戶ID為0時，服務器將會觸發該回調函數。由于該函數傳遞的數據是一個與本SDK無關的緩沖區（由上層應用自己填充內容），相對于本SDK來說是透明的，故稱為透明通道，利用該通道，可以向當前房間內的任何用戶傳輸上層應用自定義的數據。 **1.4.3、透明通道數據擴展回調函數** typedef void (CALLBACK * BRAS_TransBufferEx_CallBack)(DWORD dwUserid, LPBYTE lpBuf, DWORD dwLen, DWORD wParam, DWORD lParam, DWORD dwTaskId, LPVOID lpUserValue); 參數： dwUserid：用戶ID，指示發送用戶 lpBuf：緩沖區地址 dwLen：緩沖區大小 wParam：緩沖區附帶參數（由發送者設置，上層應用可自定義用途） lParam：緩沖區附帶參數2 dwTaskId：該緩沖區所對應的傳輸任務編號 lpUserValue：用戶自定義參數，在設置回調函數時傳入備注：當收到客戶端使用“BRAC_TransBufferEx”方法發送的數據（目標用戶為0）時，將會觸發該回調函數。 **1.4.4、服務器通信數據回調函數** DWORD BRAC_SetSDKFilterDataCallBack(BRAC_SDKFilterData_CallBack lpFunction, LPVOID lpUserValue=NULL); 功能：設置SDK Filter通信數據回調函數，當服務器SDK Filter發送數據給客戶端時，將觸發該回調函數，將服務器SDK Filter傳遞的緩沖區數據回調給上層應用。返回值：0表示成功，否則為出錯代碼參數： lpFunction 回調函數地址。 lpUserValue 用戶自定義參數，該參數在回調函數中被返回，默認為NULL，通常傳入一個對象的地址（指針）。備注：當客戶端向服務器發送自定義通信數據時，服務器將觸發所設置的回調函數，數據內容可由上層應用自己定義，可以為任何數據類型，業務層服務器可在回調函數中分析所收到的緩沖區內容并進行對應的處理。