【正文】 Peergine編程手冊Peergine編程手冊V 201205介紹1. 關于PeerginePeergine是一個功能強大的對等通信中間件，用C/C++編程語言開發(fā)。為了適應多種運行環(huán)境，Peergine被封裝成ActiveX控件(pgATX)、NPAPI插件和JNI插件等，能夠在Internet Explorer、Chrome、Firefox和Safari等瀏覽器以及Windows Script Host、Java Runtime Environment等環(huán)境中運行。支持Windows、Linux和Android操作系統(tǒng)。旨在能方便地構建具有豐富的對等通信功能的Web應用，包括瀏覽器端和服務器端。注：本編程手冊以ActiveX控件(pgATX)的編程接口為例，說明Peergine中間件的使用方法。NPAPI插件、JNI插件的編程接口與ActiveX控件是兼容的。2. Peergine的功能特性1) 全新的網(wǎng)絡編程模式以面向?qū)ο蟮姆椒?，把復雜的多點對等通信交互過程封裝成通信對象，提供簡單、直觀的編程接口。即便是對網(wǎng)絡通信知識缺乏了解的編程人員，也能夠構建出功能強大的對等通信應用。參考“基于對象的多點通信會話”章節(jié)。2) 強大的對等通信功能以通信對象類的形式實現(xiàn)各種對等通信功能，目前支持的通信對象類為：節(jié)點類：提供對象的兩點通信范圍控制。節(jié)點的登錄/注銷，兩個節(jié)點之間的遠程過程調(diào)用，兩個節(jié)點之間的消息傳輸，數(shù)據(jù)簽名的生成和校驗。參考“使用節(jié)點類”章節(jié)。通信組類：提供對象的多點通信范圍控制。支持手動控制組成員、自動控制組成員和主(Master)成員控制功能。參考“使用通信組類”章節(jié)消息傳輸類：多個節(jié)點之間單向傳輸消息。參考“使用消息傳輸類”章節(jié)。文件傳輸類：兩個節(jié)點之間的文件傳輸。支持PUT和GET傳輸方式，文件的斷點續(xù)傳。參考“使用文件傳輸類”章節(jié)音頻傳輸類：實時捕捉和傳輸音頻。支持兩點對話模式和多點會議模式。支持會議發(fā)言控制，實時音量變化顯示，音頻錄制。參考“使用音頻傳輸類”章節(jié)視頻傳輸類：實時捕捉和傳輸視頻。支持本地預覽模式、兩點對話模式和多點會議模式。支持會議模式中視頻的加入/離開，視頻顯示窗口的調(diào)整和轉(zhuǎn)移，抓拍視頻照片，視頻錄制。參考“使用視頻傳輸類”章節(jié)。白板共享類：多個節(jié)點共享白板，可設置繪制每種圖形的參數(shù)，可設置繪制每種圖形時的鼠標光標，保存白板內(nèi)容到圖片文件，從圖片文件裝入內(nèi)容到白板。參考“使用白板共享類”章節(jié)。文件分塊共享類：類似BitTorrent和eMule，多個節(jié)點以分塊的方式對等傳輸文件。順序傳輸模式，分散傳輸模式，可設置文件傳輸?shù)臄?shù)據(jù)塊大小，實時將獲取到的文件數(shù)據(jù)轉(zhuǎn)發(fā)到本地HTTP服務器上以便使用播放器或瀏覽器來播放文件。參考“使用文件分塊共享類”章節(jié)。數(shù)據(jù)表傳輸類：多個節(jié)點之間用訪問數(shù)據(jù)庫的方式傳輸數(shù)據(jù)。支持文件傳輸模式，每個文件對應到數(shù)據(jù)表的一條記錄進行傳輸，實現(xiàn)文件的批量同步。參考“使用數(shù)據(jù)表傳輸類”章節(jié)。媒體流直播類：多個節(jié)點之間對等直播媒體流。支持實時捕捉音頻流、實時捕捉視頻流和AVI文件播放的方式提供媒體源。支持媒體源的快速切換，丟幀重傳，自動選擇網(wǎng)絡狀況好的節(jié)點進行中繼轉(zhuǎn)發(fā)。支持媒體流錄制。參考“使用媒體流直播類”章節(jié)。3) 自適應的網(wǎng)絡互通機制以IPV4和IPV6的UDP協(xié)議為基礎進行網(wǎng)絡通信。對于UDP協(xié)議通信受限的節(jié)點，通過承載在TCP之上的隧道連接到中繼服務器，然后轉(zhuǎn)換成UDP協(xié)議通信。支持TCP、HTTP和WebSocket三種協(xié)議的隧道，以適應多種通信環(huán)境。通過中繼服務器還可以完成 IPV4和IPV6之間的轉(zhuǎn)換。支持位于IPV4私網(wǎng)中的節(jié)點的NAT穿越，自動探測NAT會話的老化時間，以恰當?shù)臅r間間隔刷新NAT會話，防止老化。各種協(xié)議之間的轉(zhuǎn)換互通，由Socket適配層自動適應，對上層通信對象透明。參考“配置和運行中繼服務器”章節(jié)。一個通信節(jié)點只占用一個UDP端口，并此端口上實現(xiàn)出多點通信機制，因此占用防火強或NAT的會話資源少。支持HTTP代理方式通信，在代理后面的主機也能連接到Peergine網(wǎng)絡。實現(xiàn)QOS機制，每個節(jié)點都有4個優(yōu)先級隊列，分別對消息/信令、音頻、視頻和文件4種流量進行優(yōu)先級調(diào)度，保證高優(yōu)先級流量的服務質(zhì)量。支持對通信數(shù)據(jù)進行加密，加密的密鑰自動協(xié)商生成，無需配置。4) 控件提供豐富的輔助功能Peergine在封裝成控件時，又增加實現(xiàn)了輔助功能，包括常用的文件操作、文件緩沖區(qū)操作、本地Cookie存儲、本地HTTP服務器、AVI文件播放等。這些輔助功能通過命令執(zhí)行函數(shù)utilCmd()來調(diào)用。請參考“控件的命令列表”章節(jié)。5) 多種OS和運行環(huán)境Peergine封裝成了ActiveX控件、NPAPI插件和JNI插件等接口形式，可以運行在Internet Explorer、Chrome、Firefox和Safari瀏覽器中，以及Windows Script Host和Java Runtime Enviroment運行環(huán)境中。 支持Windows、Linux和Android操作系統(tǒng)?？捎肑avaScript和Java編程語言構建Web應用的瀏覽器端和服務器端。各種OS和運行環(huán)境的支持情況及路標如下表：運行環(huán)境\OSWindowsLinuxAndroidMac OS XiOSInternet Explorer√Chrome√√√2012Q22012Q2Firefox√√√2012Q22012Q2Safari√2012Q22012Q2Java (JNI)√√√3. 基于對象的多點通信會話1) 概念在以往的網(wǎng)絡編程方法中，例如，TCP連接、SIP會話等，通信會話一般指兩點之間協(xié)商建立起來的通信交互。且也已經(jīng)有了相應成熟的網(wǎng)絡編程模型，例如Socket API。但在對等通信應用中，通信交互往往是多點對多點的，而且參與通信交互的節(jié)點會動態(tài)變化。如果依然使用兩點通信的模型去搭建對等通信應用，那將是相當復雜、困難的事情，需要富有經(jīng)驗的網(wǎng)絡編程人員才能完成。我們能否找到一種方法，讓對等通信編程也變得直觀、簡單呢？其實，人們使用網(wǎng)絡的行為可以簡單表達為一句話：“多個人通過網(wǎng)絡連接在一起做同一件事”。比如，多個人在一個聊天室里交談、多個人在頂一個帖子、多個人在觀看一個視頻等等。我們可以把其中的“多個人”抽象為多個通信節(jié)點，“同一件事”抽象為一個通信會話，也就是把使用網(wǎng)絡的行為抽象為一個“多點通信會話”。兩點通信會話與多點通信會話的比較示意圖，如下：(a)(b)圖1. (a) 兩點通信會話連接，(b) 多點通信會話連接進一步，我們把一個多點通信會話封裝成一個通信對象，用面向?qū)ο蟮姆椒▉肀硎鼍W(wǎng)絡通信的特征，這樣就使對等網(wǎng)絡編程變得更加簡單、直觀。Peergine就是這種以通信對象為基礎的對等通信系統(tǒng)。在系統(tǒng)中不同的通信業(yè)務類型表述為相對應的通信對象類，例如消息傳輸類、音頻傳輸類、視頻傳輸類等，而每一個通信對象實例表示一個通信會話。2) 同名通信對象Peergine系統(tǒng)中的一個通信對象通過一個名稱來標識。每個通信節(jié)點有一個節(jié)點自身對象，其對象名稱就是節(jié)點的名稱，這個節(jié)點自身對象的名稱必須是整個網(wǎng)絡中唯一的。在每個通信節(jié)點上除了節(jié)點自身對象以外，還可以創(chuàng)建多個各種類型的通信對象，這些通信對象的名稱必須在本節(jié)點范圍內(nèi)唯一。在不同的通信節(jié)點上就可以存在名稱相同的通信對象，我們把這樣的一套通信對象稱為“同名通信對象”。在Peergine系統(tǒng)中，一套同名通信對象就是一個多點通信會話。位于不同節(jié)點上的相同名稱的通信對象之間自動地建立起通信會話，然后在其中一個節(jié)點上調(diào)用該對象的方法，就可以完成與其它各節(jié)點之間的通信交互。同名通信對象建立通信會話的過程，稱為“通信對象的同步”。如下圖，有NodeA、NodeB、NodeC三個節(jié)點，它們的自身對象分別為 NodeA、NodeB、NodeC。在節(jié)點NodeA可以創(chuàng)建一個節(jié)點對象NodeB與節(jié)點NodeB的自身對象同名，這時節(jié)點NodeA上的NodeB和節(jié)點NodeB的自身對象就是同名通信對象，它們之間自動建立會話連接。同樣節(jié)點NodeA、NodeB、NodeC上都有通信組對象Group0和消息傳輸對象Data0，它們都組成相應的同名通信對象。節(jié)點NodeA節(jié)點NodeB節(jié)點NodeC自身對象NodeA節(jié)點對象NodeB節(jié)點對象NodeC自身對象NodeB節(jié)點對象NodeC節(jié)點對象NodeA自身對象NodeC節(jié)點對象NodeA節(jié)點對象NodeB通信組對象Group0成員NodeA成員NodeB成員NodeC通信組對象Group0成員NodeA成員NodeB成員NodeC通信組對象Group0成員NodeA成員NodeB成員NodeC消息傳輸對象Data0關聯(lián)Group0消息傳輸對象Data0關聯(lián)Group0消息傳輸對象Data0關聯(lián)Group0圖2. 同名通信對象機制3) 通信范圍控制當很多節(jié)點上都有名稱相同的通信對象時，如何確定哪些節(jié)點上的同名通信對象才能組成一個多點通信會話呢？這就涉及到同名通信對象的通信范圍問題。在Peergine系統(tǒng)中有兩種可以用來確定通信范圍的通信對象，它們分別是節(jié)點對象和通信組對象。對于節(jié)點對象，它的通信范圍由對象名稱決定。例如上圖中，在節(jié)點NodeA上創(chuàng)建節(jié)點對象NodeB，它跟節(jié)點NodeB的自身對象同名，所以它的通信范圍就是節(jié)點B。使用節(jié)點對象可以建立兩點之間的通信會話。對于通信組對象，它的通信范圍由它所包含的組成員決定。通信組對象的成員就是其通信范圍內(nèi)的節(jié)點的自身對象的名稱。添加或刪除通信組對象的成員可以改變通信組的通信范圍。使用通信組對象可以建立多點之間的通信會話。對于其它業(yè)務類型的通信對象，例如消息傳輸對象、文件傳輸對象，它們沒有控制通信范圍的機制，則可以通過關聯(lián)節(jié)點對象或通信組對象來控制通信范圍。當它們關聯(lián)節(jié)點對象時，實現(xiàn)兩點之間的通信交互，當它們關聯(lián)通信組對象時，實現(xiàn)多點之間的通信交互。一個節(jié)點對象或通信組對象可以被多個通信對象關聯(lián)。參考“使用通信組類”章節(jié)。4. 控件與應用程序的交互方式1) 系統(tǒng)概述Peergine中間件的系統(tǒng)框圖如下，它位于應用程序和網(wǎng)絡層的中間。上方通過控件提供的API與應用程序交互，下方通過OS的Socket API與網(wǎng)絡協(xié)議棧交互。應用程序/頁面 pgATX控件視頻I/O音頻I/O文件I/O白板I/OAVI I/OHTTP SVR節(jié)點類通信組類消息傳輸類文件傳輸類白板共享類文件分塊共享類音頻傳輸類視頻傳輸類數(shù)據(jù)表傳輸類媒體流直播類通信對象管理網(wǎng)絡層UDP v4/6TCP v4/6TCP、HTTP和WebSocket隧道Socket適配層輔助命令圖3. 系統(tǒng)框圖調(diào)用通信對象類的方法時，應用程序與pgATX控件之間的交互通過4個編程接口來完成。分別為發(fā)送請求ObjectRequest()、接收請求OnExtRequest()、發(fā)送應答ObjectExtReply()和接收應答OnReply()，其中OnExtRequest()和OnReply()是回調(diào)函數(shù)，需要在控件初始化時注冊才能使用。但并不是所有的方法的調(diào)用都需要4個函數(shù)的交互過程，有些方法只需要其中1個或2個函數(shù)的交互。Peergine系統(tǒng)用到的交互方式由下文的小章節(jié)逐個說明。2) 方式1：本端應用程序發(fā)送請求、接收應答。對端應用程序接收請求、發(fā)送應答。應用程序pgAtx控件pgAtx控件應用程序()()()()網(wǎng)絡發(fā)送請求接收請求發(fā)送應答接收應答節(jié)點A節(jié)點B圖4. 交互方式13) 方式2：本端應用程序發(fā)送請求、接收應答。對端控件接收請求、發(fā)送應答。應用程序pgAtx控件pgAtx控件應用程序()()網(wǎng)絡發(fā)送請求接收應答節(jié)點A節(jié)點B圖5. 交互方式24) 方式3：本端控件發(fā)送請求、接收應答。對端應用程序接收請求、發(fā)送應答。應用程序pgAtx控件pgAtx控件應用程序()()網(wǎng)絡接收請求發(fā)送應答節(jié)點A節(jié)點B圖6. 交互方式32) 方式4：本端應用程序發(fā)送請求。對端應用程序接收請求。應用程序pgAtx控件pgAtx控件應用程序()()發(fā)送請求接收請求節(jié)點A節(jié)點B網(wǎng)絡圖7. 交互方式45) 方式5：本端應用程序發(fā)送請求，本端應用程序接收應答。應用程序pgAtx控件()()發(fā)送請求接收應答節(jié)點A圖8. 交互方式56) 方式6：本端應用程序發(fā)送請求觸發(fā)本端控件上報事件給應用。應用程序pgAtx控件()()發(fā)送請求觸發(fā)上報節(jié)點A圖9. 交互方式67) 方式7：本端應用程序調(diào)用本端控件的方法但沒有輸出。應用程序pgAtx控件()發(fā)送請求節(jié)點A圖10. 交互方式78) 方式8：本端控件自行上報事件給應用程序。應用程序pgAtx控件()自行上報節(jié)點A圖11. 交互方式85. 常用的數(shù)據(jù)格式1) 地址的格式Peergine 系統(tǒng)中使用的地址格式為：X:X:X:X:Port:Info，其中4個X分別為32bit整數(shù)、HEX格式，Port為端口號，Info為選項信息(未使用)。此地址格式可以表示IPV4的地址端口和IPV6的地址端口。IPV4的地址端口樣例：0:0:0:7F