nea.docs 3.96 KB
Newer Older
Pekka Pessi's avatar
Pekka Pessi committed
1 2
/* -*- c -*- */

3
/**@MODULEPAGE "nea" - SIP Events Module
Pekka Pessi's avatar
Pekka Pessi committed
4 5 6 7 8 9 10 11 12
 * 
 * @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 <nea.h>.
 *
 * @CONTACT Pekka Pessi <Pekka.Pessi@nokia.com>
 *
13
 * @STATUS @SofiaSIP Core library
Pekka Pessi's avatar
Pekka Pessi committed
14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123
 *
 * @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
 */