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_CONTACT(m),
SIPTAG_SERVER_STR("Sofia-SIP NEA"),
TAG_NULL());
...
}
sip_contact_t
struct sip_contact_s sip_contact_t
SIPTAG_CONTACT
#define SIPTAG_CONTACT(x)
SIPTAG_SERVER_STR
#define SIPTAG_SERVER_STR(s)
nea_server_create
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
nta_agent_t
struct nta_agent_s nta_agent_t
sip_contact_s::m_url
url_t m_url[1]
su_home_clone
void * su_home_clone(su_home_t *parent, isize_t size))
TAG_NULL
#define TAG_NULL()
su_root_t
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_create
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,
SIPTAG_CONTENT_TYPE(ct),
SIPTAG_PAYLOAD(pl),
TAG_END());
nea_server_notify(pr->pr_nes, event);
SIPTAG_CONTENT_TYPE
#define SIPTAG_CONTENT_TYPE(x)
SIPTAG_PAYLOAD
#define SIPTAG_PAYLOAD(x)
nea_server_notify
int nea_server_notify(nea_server_t *nes, nea_event_t *ev)
Notify subscribers.
Definition nea_server.c:1018
nea_server_update
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
TAG_END
#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)
{
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;
}
sip_content_type_t
struct msg_content_type_s sip_content_type_t
sip_payload_t
msg_payload_t sip_payload_t
nea_payloads_t
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.