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 < Pekka.Pessi@nokia-email.address.hidden>

状态:

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;
 }