124 lines
4.0 KiB
C
124 lines
4.0 KiB
C
/* -*- c -*- */
|
|
|
|
/**@MODULEPAGE "nea" - SIP Events Module
|
|
*
|
|
* @section nea_meta 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 Pekka Pessi <Pekka.Pessi@nokia.com>
|
|
*
|
|
* @STATUS @SofiaSIP Core library
|
|
*
|
|
* @LICENSE LGPL
|
|
*
|
|
* @section Creating NEA server and events
|
|
*
|
|
* @section nea_server_create 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 @e 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 @e
|
|
* agent, @e 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.
|
|
*
|
|
* @code
|
|
* 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());
|
|
* ...
|
|
* }
|
|
* @endcode
|
|
*
|
|
* @section nea_event_create 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.
|
|
*
|
|
* @code
|
|
* #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);
|
|
* @endcode
|
|
*
|
|
* @section nea_server_update 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 @a 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 ().
|
|
*
|
|
* @code
|
|
* 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);
|
|
* @endcode
|
|
*
|
|
* Obtaining the event's payload and removing it is presented in the
|
|
* example below. The event is defined as a part of the @a 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().
|
|
*
|
|
* @code
|
|
* 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;
|
|
* }
|
|
* @endcode
|
|
*/
|