Sofia-SIP輔助文檔十一 - Sofia SIP用戶代理庫 - "nea" - SIP事件模塊

http://sofia-sip.sourceforge.net/refdocs/nea/index.html，翻譯自官網的這張網頁。

模塊元信息

Sofia Event API提供操作SIP在線和會議服務中使用的事件接口。<sofia-sip/nea.h>頭文件中定義了無論是服務端還是客戶端都可以使用的接口。

聯繫人:

Pekka Pessi <[email protected]>

狀態:

Sofia SIP Core library

許可:

LGPL

NEA服務器和事件

創建NEA服務器

NEA服務器生成、接收和發送事件給訂閱方。服務器是發佈特定的，爲每個發佈功能創建一個服務器（need translate again）。

首先，server對象被創建。server對象使用NTA agent（nta_agent_t）用來處理出入的SIP消息。

下面的例子展示了創建NEA服務器的一種方式。函數nea_server_create()創建服務器。參數agent和root定義了事務引擎。第三個參數是發佈者的地址。event_callback是回調函數指針，當一個新的用戶訂閱一個不存在的事件或者請求了一個不匹配的負載類型，回調函數會被調用。

 presence_t *presence_create(su_root_t *root,
                             nta_agent_t *agent,
                             sip_contact_t const *m)
 {
   presentity_t *pr = su_home_clone(p->p_home, sizeof (*pr));
   ...
   pr->pr_nes =
     nea_server_create(agent, root,
                       m->m_url,
                       MAX_SUBSCRIBERS,
                       event_callback, pr,
                       SIPTAG_CONTACT(m),
                       SIPTAG_SERVER_STR("Sofia-SIP NEA"),
                       TAG_NULL());
 ...
 }

創建事件

下一步創建事件。nea_event_create ()函數定義一個事件，它的包和內容類型（逗號分隔的列表）。presence_callback參數是一個回調函數。當有人訂閱一個預定義的事件時會調用回調函數。

 #define PRESENCE_PACKAGE "presence"
 #define XPIDF_MIME_TYPE "application/xpidf+xml"
 #define PIDF_MIME_TYPE "application/cpim-pidf+xml"

 ne = nea_event_create(pr->pr_nes, presence_callback, ep,
                       PRESENCE_PACKAGE, NULL,
                       PIDF_MIME_TYPE,
                       PIDF_MIME_TYPE "," XPIDF_MIME_TYPE);

Operating with event payloads

一個新的負載可以通過nea_server_update()函數插入到事件中。第四個參數描述了是否已更新的內容是假的（爲非授權訂閱者）。如果第四個參數是0那麼一個真的負載會被插入。如果事件之前未被內容類型ct所更新，那麼將會爲事件創建新的內容類型格式。否則，老的負載將會被新的所替換。

更新後，事件的訂閱者會收到通知，被告知負載改變了。

 nea_server_update(pr->pr_nes, home, event, 1,
                   SIPTAG_CONTENT_TYPE(ct),
                   SIPTAG_PAYLOAD(pl),
                   TAG_END());

 nea_server_notify(pr->pr_nes, event);

在下面的代碼中展示了獲取事件的負載以及移除它。事件作爲package_t結構體的一部分被定義。nea_payloads_get()函數被用來返回負載（在這個例子中內容類型被預定義爲application/cpim-pidf+xml）。真的和假的負載被保存在nea_payloads_t結構體中。最後可以用nea_payload_remove()函數移除負載。

 int remove_old_payload(package_t *ep)
 {
   nea_payloads_t *np;
   sip_content_type_t *ct;
   sip_payload_t *real;
   sip_payload_t *fake;

   event = ep->ep_event;

   np = nea_payloads_get(event, PIDF_MIME_TYPE);
   ct = nea_content_type_get(np);
   real = nea_payload_get(np);
   fake = nea_fake_get(np);
   nea_payload_remove(ep->ep_home, np);

   return 0;
 }