nea 1.12.11devel
Loading...
Searching...
No Matches
Sofia SIP User Agent Library - "nea" - SIP Events Module

Module Meta Information

Sofia Event API provides an interface to different events used in SIP presence and conferencing. Interface used both in client and server sides is presented in <sofia-sip/nea.h>.

Contact:\n Pekka Pessi <Pekka.Pessi@nokia-email.address.hidden>
Status:\n Sofia SIP Core library
License:\n LGPL

NEA server and events

Creating NEA server

NEA server generates, receives and sends events to subscribed parties. The server is presentity specific, ie. a different server is created for every presentity.

First, a server object is created. The object uses the NTA agent (nta_agent_t) that handles incoming and outgoing SIP messages.

The example below provides a way to create the NEA server. The function nea_server_create() creates the server. Parameters agent, root define the transaction engine. Third parameter is the address of the presentity. event_callback is a callback function pointer and is called every time a new user subscribes to an event that does not exist or requests for payload type that doesn't match.

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_SERVER_STR("Sofia-SIP NEA"),
...
}
#define SIPTAG_CONTACT(x)
#define SIPTAG_SERVER_STR(s)
nea_server_t * nea_server_create(nta_agent_t *agent, su_root_t *root, url_t const *url, int max_subs, nea_new_event_f *callback, nea_smagic_t *context, tag_type_t tag, tag_value_t value,...)
Create a notifier server.
Definition nea_server.c:372
struct nta_agent_s nta_agent_t
void * su_home_clone(su_home_t *parent, isize_t size))
#define TAG_NULL()
struct su_root_t su_root_t

Creating Events

Next, events are created. The function nea_event_create () defines an event, its package and content types (a comma separated list). The parameter presence_callback defines the callback function that is called when a someone subscribes to a defined event.

#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);
nea_event_t * nea_event_create(nea_server_t *nes, nea_watcher_f *callback, nea_emagic_t *context, char const *name, char const *subname, char const *default_content_type, char const *accept)
Create a new event (or subevent)
Definition nea_server.c:1198

Operating with event payloads

A new payload can be inserted to a event with the function nea_server_update(). The 4th parameter describes if the updated content is a fake (for unauthorized subscribers). A real payload is inserted (updated) with the 4th parameter being 0. If the event is not updated with the content type ct before, a new content type format for the event is created. Otherwise the old payload is replaced with the new one.

After the update, subscribers of the event are notified (with SIP NOTIFY) of the changed payload with nea_server_update ().

nea_server_update(pr->pr_nes, home, event, 1,
TAG_END());
nea_server_notify(pr->pr_nes, event);
#define SIPTAG_CONTENT_TYPE(x)
#define SIPTAG_PAYLOAD(x)
int nea_server_notify(nea_server_t *nes, nea_event_t *ev)
Notify subscribers.
Definition nea_server.c:1018
int nea_server_update(nea_server_t *nes, nea_event_t *ev, tag_type_t tag, tag_value_t value,...)
Update event information.
Definition nea_server.c:667
#define TAG_END()

Obtaining the event's payload and removing it is presented in the example below. The event is defined as a part of the package_t structure. Function nea_payloads_get() is used to return a payload (in this case content type being predefined "application/cpim-pidf+xml"). The real and fake payloads are stored in the structure nea_payloads_t. Finally, the payload is removed with nea_payload_remove().

int remove_old_payload(package_t *ep)
{
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;
}
struct nea_payloads_s nea_payloads_t
Multiple content types per event.
Definition nea.h:114

Sofia-SIP 1.12.11devel - Copyright (C) 2006 Nokia Corporation. All rights reserved. Licensed under the terms of the GNU Lesser General Public License.