Martti Mela <Martti.Mela@nokia-email.address.hidden>
#include <sofia-sip/su_alloc.h>
#include <sofia-sip/su_tag.h>
#include <sofia-sip/nta.h>
#include <sofia-sip/nea_tag.h>
Include dependency graph for nea.h:
Go to the source code of this file.
Data Structures | |
struct | nea_subnode_t |
Description of subscription. More... | |
Defines | |
#define | NEATAG_RELIABLE(x) |
Reliable notify. | |
#define | NEATAG_VIEW(x) |
Event view handle. | |
#define | NEATAG_EVMAGIC(x) |
Event view magic. | |
#define | NEATAG_SUB(x) |
tag for nea_sub_t | |
Typedefs | |
typedef nea_server_s | nea_server_t |
Event notifier object. | |
typedef nea_sub_s | nea_sub_t |
Subscription object. | |
typedef nea_event_s | nea_event_t |
Event. | |
typedef nea_event_view_s | nea_event_view_t |
Event view. | |
typedef NEA_SMAGIC_T | nea_smagic_t |
NEA server context. | |
typedef NEA_EMAGIC_T | nea_emagic_t |
NEA server event context. | |
typedef NEA_EVMAGIC_T | nea_evmagic_t |
Event view context. | |
typedef nea_payloads_s | nea_payloads_t |
Multiple content types per event. | |
typedef int( | nea_new_event_f )(nea_smagic_t *context, nea_server_t *nes, nea_event_t **event_p, nea_event_view_t **view_p, nta_incoming_t *irq, sip_t const *sip) |
Unknown event callback. | |
typedef void( | nea_watcher_f )(nea_server_t *nes, nea_emagic_t *context, nea_event_t *event, nea_subnode_t *subnode, sip_t const *sip) |
QAUTH callback function type. | |
typedef nea_s | nea_t |
NEA Event Watcher. | |
typedef NEA_MAGIC_T | nea_magic_t |
NEA Event Agent context. | |
typedef int(*) | nea_notify_f (nea_t *nea, nea_magic_t *context, sip_t const *sip) |
Event notification callback type. | |
Functions | |
SOFIAPUBFUN 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. | |
SOFIAPUBFUN int | nea_server_shutdown (nea_server_t *nes, int retry_after) |
Shutdown an event server. | |
SOFIAPUBFUN void | nea_server_destroy (nea_server_t *nes) |
Destroy a server. | |
SOFIAPUBFUN void | nea_server_flush (nea_server_t *nes, nea_event_t *event) |
Zap terminated subscribtions. | |
SOFIAPUBFUN int | nea_server_update (nea_server_t *nes, nea_event_t *ev, tag_type_t tag, tag_value_t value,...) |
Update event information. | |
SOFIAPUBFUN int | nea_server_add_irq (nea_server_t *nes, nta_leg_t *leg, sip_contact_t const *local_target, nta_incoming_t *irq, sip_t const *sip) |
Add a new subscriber from subscribe transaction to an existing notifier. | |
SOFIAPUBFUN 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). | |
SOFIAPUBFUN nea_event_t * | nea_event_tcreate (nea_server_t *nes, nea_watcher_f *callback, nea_emagic_t *context, char const *name, char const *subname, tag_type_t, tag_value_t,...) |
Create a new event (or subevent) with tags. | |
SOFIAPUBFUN nea_emagic_t * | nea_emagic_get (nea_event_t *event) |
Return magic context bind to nea_event. | |
SOFIAPUBFUN nea_event_t * | nea_event_get (nea_server_t const *, char const *name) |
Find a nea event object with given event name. | |
SOFIAPUBFUN int | nea_server_active (nea_server_t *nes, nea_event_t const *ev) |
Get number of active subscribers. | |
int | nea_server_non_embryonic (nea_server_t *nes, nea_event_t const *ev) |
Get number of (non-embryonic) subscribers. | |
SOFIAPUBFUN nea_subnode_t const ** | nea_server_get_subscribers (nea_server_t *nes, nea_event_t const *ev) |
Obtain a list of subscriptions. | |
SOFIAPUBFUN void | nea_server_free_subscribers (nea_server_t *nes, nea_subnode_t const **) |
Free a list of subscriptions. | |
SOFIAPUBFUN int | nea_server_notify (nea_server_t *nes, nea_event_t *ev) |
Notify subscribers. | |
SOFIAPUBFUN int | nea_server_notify_one (nea_server_t *nes, nea_event_t *ev, nea_sub_t *ns) |
Notify a subscriber. | |
SOFIAPUBFUN nta_incoming_t * | nea_sub_get_request (nea_sub_t *sub) |
Get nta_incoming_t from nea_sub_t. | |
SOFIAPUBFUN int | nea_sub_auth (nea_sub_t *, nea_state_t state, tag_type_t, tag_value_t,...) |
Authorize a subscription. | |
SOFIAPUBFUN nta_incoming_t * | nea_subnode_get_incoming (nea_subnode_t *sn) |
Get nta_incoming_t from sn->sn_subscriber. | |
SOFIAPUBFUN int | nea_sub_version (nea_sub_t *, unsigned) |
Set subscriber version sequence. | |
SOFIAPUBFUN unsigned | nea_sub_pending (nea_sub_t const *) |
Return time until next notification can be sent. | |
SOFIAPUBFUN nea_event_view_t * | nea_event_view (nea_event_t *, char const *content_type) |
Get primary event view for given content type. | |
SOFIAPUBFUN sip_content_type_t const * | nea_view_content_type (nea_event_view_t const *) |
Get a content type for event's payload. | |
SOFIAPUBFUN sip_payload_t const * | nea_view_payload (nea_event_view_t *) |
Get actual payload for an event. | |
SOFIAPUBFUN nea_event_view_t * | nea_view_create (nea_server_t *nes, nea_event_t *ev, nea_evmagic_t *magic, tag_type_t tag, tag_value_t value,...) |
Create a private event view. | |
SOFIAPUBFUN void | nea_view_destroy (nea_server_t *nes, nea_event_view_t *ev) |
Destroy a private event view. | |
SOFIAPUBFUN nea_t * | nea_create (nta_agent_t *agent, su_root_t *root, nea_notify_f no_callback, nea_magic_t *context, tag_type_t tag, tag_value_t value,...) |
Create a subscription agent. | |
SOFIAPUBFUN int | nea_update (nea_t *nea, tag_type_t tag, tag_value_t value,...) |
Update SUBSCRIBE payload (filter rules). | |
SOFIAPUBFUN void | nea_end (nea_t *agent) |
Unsubscribe agent. | |
SOFIAPUBFUN void | nea_destroy (nea_t *agent) |
Destroy a subscription agent. |
typedef int( nea_new_event_f)(nea_smagic_t *context, nea_server_t *nes, nea_event_t **event_p, nea_event_view_t **view_p, nta_incoming_t *irq, sip_t const *sip) |
Unknown event callback.
The event server invokes this callback function when it has received a request for an unknown event or event with unknown content type.
The callback may be called twice for one watcher, once for an unknown event, another time for an unknown content type.
1 | application takes care of responding to request | |
0 | application has added new event or payload format | |
-1 | nea server rejects request |
typedef int(*) nea_notify_f(nea_t *nea, nea_magic_t *context, sip_t const *sip) |
Event notification callback type.
This callback is called also when initial or refresh subscribe transaction completes with the transaction result in sip.
typedef void( nea_watcher_f)(nea_server_t *nes, nea_emagic_t *context, nea_event_t *event, nea_subnode_t *subnode, sip_t const *sip) |
QAUTH callback function type.
The event server invokes this callback function upon each incoming SUBSCRIBE transaction when the subscription has expired. The sip is NULL if the subscription has expired.
The application determines if the subscription is authorized and relays the decision to event server via nea_server_auth() function.
SOFIAPUBFUN nea_emagic_t* nea_emagic_get | ( | nea_event_t * | ev | ) |
Return magic context bind to nea_event.
The function returns the magic context bound to the event.
ev | pointer to event object |
SOFIAPUBFUN 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).
The function nea_event_create() creates a new event for the event server.
SOFIAPUBFUN int nea_server_active | ( | nea_server_t * | nes, | |
nea_event_t const * | ev | |||
) |
Get number of active subscribers.
The function nea_server_active() counts the number of active subscribers watching the specified view. If the view is not specified (ev is NULL
), it counts the number of all subscribers.
nes | notifier | |
ev | event |
SOFIAPUBFUN 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.
The function nea_server_create() initializes an event server object and registers it with nta. An event server object takes care of all events for a particular URI (eventity).
agent | pointer to an nta agent object | |
root | pointer to an root object | |
url | url of the server to be created | |
max_subs | maximum number of subscriptions | |
callback | authorization function, or NULL if no authorization is required | |
context | server context (pointer to application data) | |
tag,value,... | optional list of tag parameters |
The default throttle value is used if the subscriber does not include a throttle parameter in Event header of SUBSCRIBE request.
NULL
upon an error. SOFIAPUBFUN void nea_server_flush | ( | nea_server_t * | nes, | |
nea_event_t * | event | |||
) |
Zap terminated subscribtions.
On first flush, mark as garbage, remove on second flush
int nea_server_non_embryonic | ( | nea_server_t * | nes, | |
nea_event_t const * | ev | |||
) |
Get number of (non-embryonic) subscribers.
The function nea_server_non_embryonic() counts the number of pending, active or terminated subscribers watching the specified view. If the view is not specified (ev is NULL
), it counts the number of all subscribers.
nes | notifier | |
ev | event view |
SOFIAPUBFUN int nea_server_notify | ( | nea_server_t * | nes, | |
nea_event_t * | ev | |||
) |
Notify subscribers.
SOFIAPUBFUN int nea_server_update | ( | nea_server_t * | nes, | |
nea_event_t * | ev, | |||
tag_type_t | tag, | |||
tag_value_t | value, | |||
... | ||||
) |
Update event information.
A nea event server has typed content that is delivered to the subscribers. Different content types are each assigned a separate primary view. There can be also primary views with "fake" content, content delivered to politely blocked subscribers.
In addition to primary views, there can be secondary views, views assigned to a single subscriber only.
The default throttle value is used if the subscriber does not include a throttle parameter in Event header of SUBSCRIBE request.
-1 | upon an error. | |
0 | if event document was not updated. | |
1 | if event document was updated. |
SOFIAPUBFUN int nea_sub_auth | ( | nea_sub_t * | s, | |
nea_state_t | state, | |||
tag_type_t | tag, | |||
tag_value_t | value, | |||
... | ||||
) |
Authorize a subscription.
Application can modify the subscription state and authorize the user. The subscription state has following simple state diagram:
+---------------+ +------------------+ | | | | +-----------+ | +---------+ V | +------------+ V +------------+ | embryonic |-+->| pending |--+-+->| authorized |--+->| terminated | +-----------+ +---------+ +------------+ +------------+
0 | if successful | |
-1 | upon an error |