[訊息論壇] ICE
Messaging Forum 蔣居裕
技術篇：與
Developer 息息相關的 iPush® API (上)
對於 Software Developer (應用程式開發者) 來說，除了伺服器端軟體外，一個中介軟體
(Middleware) 產品最重要的，即是在客戶端使用的 API (應用程式開發介面) 了。
iPush® Server 也是這樣的，它具備了多種 API
─ 如 Windows DLL、ActiveX、Java Package、Linux C Library 等，可供
Developer 自由選用。
對於即時訊息應用系統的 Developer 而言，iPush®
API 扮演著下列角色：
-
是 Developer 撰寫的應用程式對
iPush® Server 收送訊息的橋樑。也就是說，iPush®
API 封裝了 iPush® Server 底層的通訊協定，而只提供了較易懂、高層次的函式呼叫介面
(High-level Function Call)，供 Developer 設計的應用程式叫用，以便收發即時訊息。
-
是 iPush®
Server 特性的具體實踐者。也就是說，iPush® Server 被設計成為一個容易使用的即時鉅量連線訊息中介軟體
(Massive Connection MOM)，必須將其系統設計理念，體現在 Developer 直接使用的
API 上，在應用程式撰寫的函式呼叫中，讓 Developer 實際體會得到其精神。
若要用一句話來描述 Developer 用來撰寫即時訊息應用系統的 iPush®
API，那麼應該就是：
直覺、易上手
iPush® API 的高直覺性，表現在訊息的發送與訊息的接收上。以
ActiveX API (iPushX.ocx) 為例，全部呼叫介面 (Methods) 只有 11 個，列出如下：
| iPush®
ActiveX Methods |
簡述 |
| ipushConnect() |
讓應用程式與
iPush® Server 連線。 |
| ipushDisconnect() |
讓應用程式與
iPush® Server 中斷連線。 |
| ipushSend(LPCTSTR
strChannel, LPCTSTR strData) |
發送純文字
(Text) 訊息至 iPush®Server，並指定所屬 Channel (訊息發送者)。 |
| ipushSendBin(LPCTSTR
channel, const VARIANT FAR& data, long datalen) |
發送二進位
(Binary) 訊息至 iPush® Server，並指定所屬 Channel
(訊息發送者)。 |
| ipushSendBlock(LPCTSTR
channel, LPCTSTR name, const VARIANT FAR& data, long
datalen) |
發送超過
1024 Bytes (1 KB) 的訊息至 iPush® Server，並指定所屬
Channel (訊息發送者)。 |
| ipushSub(LPCTSTR
strParam) |
向
iPush® Server 訂閱指定的 Channel (訊息接收者)。 |
| ipushUnsub(LPCTSTR
strParam) |
向
iPush® Server 取消訂閱指定的 Channel (訊息接收者)。 |
| packData(const
VARIANT FAR& dest, long destlen, const VARIANT FAR&
src, long srclen) |
發送訊息至
iPush® Server 時，使用編碼運算法則 1 (訊息發送者)。 |
| packBlock(const
VARIANT FAR& dest, long destlen, const VARIANT FAR&
src, long srclen) |
發送訊息至
iPush® Server 時，使用編碼運算法則 2 (訊息發送者)。 |
| unpackData(const
VARIANT FAR& dest, long destlen, const VARIANT FAR&
src, long srclen) |
接收來自
iPush® Server 的訊息時，使用運算法則 1 來解碼；與 packData()
配對使用 (訊息接收者)。 |
| unpackBlock(const
VARIANT FAR& dest, long destlen, const VARIANT FAR&
src, long srclen) |
接收來自
iPush® Server 的訊息時，使用運算法則 2 來解碼；與 packBlock()
配對使用 (訊息接收者)。 |
以上 11 個呼叫介面，再依功能細分下去，可以單純化到 4 類：
一. 連線類：
- ipushConnect()
- ipushDisconnect()
二. 訊息發送類：
- ipushSend()
- ipushSendBin()
- ipushSendBlock()
三. 訊息訂閱(接收)類：
四. 訊息編碼/解碼類：
- packData()
- packBlock()
- unpackData()
- unpackBlock()
→ 直覺性的訊息發送動作
所以當 Developer 要讓應用程式進行訊息的發送，其表現在實際的呼叫介面上，會是這樣的：
< 第 1 動 ─ 讓應用程式與
iPush® Server 連線 >
將連線所需的諸屬性資訊 (Properties)
準備好，然後呼叫 ipushConnect()。
< 第 2 動 ─ 發送訊息，並指定
Channel >
與 iPush® Server 連結成功後 (應用程式收到
Event: ConnectReady)，接著就可依您訊息格式(純文字或是二進位)的不同，以及大小，分別叫用適當的函式來發送訊息：
- ipushSend()：發送小於
1KB 的純文字訊息。
- ipushSendBin()：發送小於
1KB 的二進位訊息。
- ipushSendBlock()：發送大於
1KB 的純文字或二進位訊息。
除了訊息內容之外，當然您也必須在函式呼叫中，為訊息指定所屬的 Channel。
還有非常重要的一點，我們強烈建議 Developer，儘量在呼叫上述任一函式來發送訊息之前，先為您的訊息進行編碼，尤其是二進位格式的訊息，如此方可避免訊息中的部分內容，與
iPush® Server 保留字元衝突的可能性。您可視需要，選擇函式
packData() 或 packBlock()，來為訊息編碼。但請記得，在撰寫應用程式的訊息接收功能時，要記得對應叫用函式
unpackData() 或 unpackBlock()
來解碼還原訊息。
< 第 3 動 ─ 中斷應用程式與
iPush® Server 連線 >
Developer 可以在第 2 動中，多次呼叫
<訊息編碼 + 訊息發送> 的函式，完成多個訊息的發送作業。最後要終止與 iPush®
Server 的連線，只要呼叫函式 ipushDisconnect()
即可。
利用 iPush® Server 來發送訊息，是不是真的很直覺？就好像是您要與朋友說話，第一個動作當然是撥打電話；待接通對方後，第二個動作當然就是張家長、李家短用力地聊；說過癮了，最後再掛斷即可。
→ 直覺性的訊息接收動作
這樣的直覺反應，也表現在 Developer 要讓應用程式進行訊息的接收上，其實際的函式呼叫，是如此的類似：
< 第 1 動 ─ 讓應用程式與
iPush® Server 連線 >
將連線所需的諸屬性資訊 (Properties)
準備好，然後呼叫 ipushConnect()。
< 第 2 動 ─ 訂閱 Channel，準備接收訊息
>
與 iPush® Server 連結成功後 (應用程式收到
Event: ConnectReady )，將該應用程式要讓使用者訂閱的
Channel(s)，利用 ipushSub()
函式呼叫告知 iPush® Server。
接下來，應用程式可以不必苦苦等待已訂閱 Channel 所屬的訊息到來，Developer
可以讓應用程式在等待訊息到來的時間裡，同時進行其他的邏輯處理。當訊息到來時，系統會依訊息的型態，以下列任一 Event
(事件) 來告知應用程式，並帶來訊息內容與其所屬的 Channel：
- DataReceived：收到一個小於
1KB 的純文字或二進位格式訊息。
- SetData：收到一個小於
1KB 的純文字或二進位格式，以陣列形式攜帶內容的訊息。
- SetData2：收到一個小於
1KB 的純文字或二進位格式，以陣列形式攜帶 Channel 與內容的訊息。
- BlockDataReceived：收到一個大於
1KB 的訊息。
當然，若訊息內容在被發送至 iPush® Server
之前，已經被編碼處理過，那麼 Developer 就該在撰寫接收功能時，再加上叫用對應的 unpackData()
或 unpackBlock() 函式，來解碼還原訊息才對。
< 第 3 動 ─ 中斷應用程式與
iPush® Server 連線 >
Developer 可以在第 2 動中，接收多個訊息。最後要終止與 iPush®
Server 的連線，只要呼叫函式 ipushDisconnect()
即可。
| Developer
可以不必擔心大型訊息 (檔案) 的收發問題 |
iPush® API 直覺性的用法，還表現在一個地方，就是當
Developer 要傳送一個大小超過 1KB 的訊息(或檔案)時，只要告訴 iPush®
API 這是一個 Block 訊息 (透過使用如 ipushSendBlock()
這個函式呼叫)，那就無論訊息(或檔案)是 100KB，還是 10MB，發送端的 API ，就會自動為該訊息進行切割、傳送；然後再由訂閱接收端的
API ，自動重組還原該訊息，然後觸發一個 Event: BlockDataReceived，以告知應用程式，讓其進行後續的處理。
所以，對於 Developer 來說，除了叫用專門處理 Block 訊息的函式外，對於大型訊息(或檔案)的收發處理流程，並不會與短小的訊息有所不同，都是同樣地直覺與容易。
也難怪我們可以看到，居然有 Developer 使用 iPush®
Server 來實作類似 FTP 檔案上傳與下載的功能。因為複雜的動作，都由 iPush®
API 幫應用程式做完了。
| Thread
Safe Coding ─ 實踐 Asynchronous Programming 的必要手段 |
在本週報中，我們一直不斷地強調：使用訊息中介軟體，如 iPush®
Server 者，配合非同步的程式設計 (Asynchronous Programming)，可以讓整個應用系統，達成低耦合度
(Loosely-coupled)，進而提高系統的強固性 (Robustness)。
為了讓 Developer 實作出具備這樣特性的應用系統，所以每一種 iPush®
API，都會配合對應程式語言的特性，讓 iPush® API 充分支援 Thread
Safe 程式設計。
所以，Developer 可以將程式設計成，用一個 Thread 來訂閱 Channels
、準備接收來自這些 Channels 的訊息；但同時，使用另外的 Threads，來執行其他的程式邏輯。
而對於發送訊息而言，由於 iPush® API 在對 iPush®
Server 傳送完該訊息之後，才會返回呼叫傳送函式的應用程式 (iPush® Client)，所以若訊息太大(也許也要考慮頻寬太低的情況)，則應該也是要使用另外的
Threads ，來執行其他的程式邏輯。
在上述訊息接收與傳送兩種情況下，由於 iPush® API
支援 Thread Safe 程式設計，所以只要 Developer 遵循所使用程式語言的 Multi-thread
設計規則，就可以輕易撰寫出一個具高強固性的即時訊息應用系統了。
| 您該選擇使用哪一種平台的
iPush® API ? |
雖然以上我們使用 ActiveX (OCX) 來做為 iPush®
API 說明的範例，但基本上，艾揚科技完全尊重 Developer 既有的程式設計技能，以及對程式設計工具的選擇，也將這個理念貫徹在對每一種
iPush® API 的支援上。
也就是說，對於每一種可供 Developer 開發即時訊息應用程式的 iPush®
API，艾揚的重視程度都是一樣的，並不會說有某一類的 API，其與 iPush® Server
之間的訊息收送運作方式，跟其他種類者有所不同。
不過，倒是可以與諸位分享的一個現象是，目前在 ICE Developer Center
即時訊息技術社群中，隱隱可以發覺一個趨勢，那就是在諸 iPush® API 中，ActiveX
(OCX) 與 Java Package (Class) 被使用的機率，有越來越高的現象，而這似乎也與程式設計朝兩大架構陣營
── .NET 與 Java 的發展呼應。另外，喜歡 C/C++ 靈活的軟體工程師們，當然還是依然有 Windows
DLL 或 Linux C Library 可以選用。
相較於只提供單一種類，或是少數種類 API 的其他中介軟體，iPush®
Server 以一種更圓融的態度，來支援跨平台的客戶端應用程式開發，所以同一個訊息，可以在同一時間，傳送給不同資訊設備的不同使用者接收。
而 Developer 在開發執行於不同資訊設備上的應用程式時，都叫用了具備相同直覺性的各類 iPush®
API。
- 詳細的 iPush® API 說明 (Programming
Guide) 與各平台類型的 iPush® API 檔案，您都可登入 ICE
Developer Center，於 Download 區下載取得
|
