Event API for SIP. More...

#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	NEA_H
	Defined when <sofia-sip/nea.h> has been included.
#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 struct nea_server_s	nea_server_t
	Event notifier object.
typedef struct nea_sub_s	nea_sub_t
	Subscription object.
typedef struct nea_event_s	nea_event_t
	Event.
typedef struct 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 struct nea_subnode_t	nea_subnode_t
	Description of subscription.
typedef struct 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 struct 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
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.
int	nea_server_shutdown (nea_server_t *nes, int retry_after)
	Shutdown an event server.
void	nea_server_destroy (nea_server_t *nes)
	Destroy a server.
void	nea_server_flush (nea_server_t nes, nea_event_t event)
	Zap terminated subscribtions.
int	nea_server_update (nea_server_t nes, nea_event_t ev, tag_type_t tag, tag_value_t value,...)
	Update event information.
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.
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).
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.
nea_emagic_t *	nea_emagic_get (nea_event_t *event)
	Return magic context bind to nea_event.
nea_event_t *	nea_event_get (nea_server_t const , char const name)
	Find a nea event object with given event name.
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.
nea_subnode_t const **	nea_server_get_subscribers (nea_server_t nes, nea_event_t const ev)
	Obtain a list of subscriptions.
void	nea_server_free_subscribers (nea_server_t nes, nea_subnode_t const *)
	Free a list of subscriptions.
int	nea_server_notify (nea_server_t nes, nea_event_t ev)
	Notify subscribers.
int	nea_server_notify_one (nea_server_t nes, nea_event_t ev, nea_sub_t *ns)
	Notify a subscriber.
nta_incoming_t *	nea_sub_get_request (nea_sub_t *sub)
	Get nta_incoming_t from nea_sub_t.
int	nea_sub_auth (nea_sub_t *, nea_state_t state, tag_type_t, tag_value_t,...)
	Authorize a subscription.
nta_incoming_t *	nea_subnode_get_incoming (nea_subnode_t *sn)
	Get nta_incoming_t from sn->sn_subscriber.
int	nea_sub_version (nea_sub_t *, unsigned)
	Set subscriber version sequence.
unsigned	nea_sub_pending (nea_sub_t const *)
	Return time until next notification can be sent.
nea_event_view_t *	nea_event_view (nea_event_t , char const content_type)
	Get primary event view for given content type.
sip_content_type_t const *	nea_view_content_type (nea_event_view_t const *)
	Get a content type for event's payload.
sip_payload_t const *	nea_view_payload (nea_event_view_t *)
	Get actual payload for an event.
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.
void	nea_view_destroy (nea_server_t nes, nea_event_view_t ev)
	Destroy a private event view.
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.
int	nea_update (nea_t *nea, tag_type_t tag, tag_value_t value,...)
	Update SUBSCRIBE payload (filter rules).
void	nea_end (nea_t *agent)
	Unsubscribe agent.
void	nea_destroy (nea_t *agent)
	Destroy a subscription agent.

Detailed Description

Event API for SIP.

Author:: Pekka Pessi <Pekka.Pessi@nokia-email.address.hidden>; Martti Mela <Martti.Mela@nokia-email.address.hidden>

Date:: Created: Fri Feb 7 13:23:44 EET 2003 ppessi

Define Documentation

#define NEA_H

Defined when <sofia-sip/nea.h> has been included.

#define NEATAG_EVMAGIC ( x )

Event view magic.

Typedef Documentation

typedef struct nea_event_s nea_event_t

Event.

typedef struct nea_event_view_s nea_event_view_t

Event view.

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.

Return values:

	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 struct nea_payloads_s nea_payloads_t

Multiple content types per event.

typedef struct nea_server_s nea_server_t

Event notifier object.

typedef struct nea_sub_s nea_sub_t

Subscription object.

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.

Function Documentation

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.

void nea_destroy ( nea_t * agent )

Destroy a subscription agent.

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.

Parameters:

ev

pointer to event object

Returns:: The function nea_emagic_get() returns the magic context bound to the event.

void nea_end ( nea_t * nea )

Unsubscribe agent.

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.

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.

Parameters:

	nes	notifier
	ev	event

The function nea_server_active() returns number of active subscribers.

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.

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).

Parameters:

	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

Related Tags:

The function nea_server_create() takes the following tag values as its arguments:

SIPTAG_CONTACT() or SIPTAG_CONTACT_STR()

The target address of the event server.

SIPTAG_ALLOW_EVENTS()

The initial list of events supported by eventity. This list is extended whenever a new event is created with nea_event_tcreate().

SIPTAG_SERVER_STR()

The Server header for the event server.

NEATAG_MINSUB()

Minimum duration of a subscription.

NEATAG_THROTTLE()

Default value for event throttle (by default, 5 seconds). Throttle determines the minimum interval betweeen notifications. Note that the notification indicating that the subscription has terminated will be sent regardless of throttle.

The default throttle value is used if the subscriber does not include a throttle parameter in Event header of SUBSCRIBE request.

NEATAG_MINTHROTTLE()

Minimum allowed throttle value (by default, 5 seconds).

NEATAG_EVENTLIST()

If true, the subscribers must support eventlists. If SIPTAG_REQUIRE() is given, it must contain the "eventlist" feature.

NEATAG_DIALOG()

Give an optional NTA destination leg to event server.

SIPTAG_REQUIRE()/SIPTAG_REQUIRE_STR()

The Require header for the event server. The subscribers must indicate support the specified features.

Returns:: The function nea_server_create() returns a pointer to an event server object, or NULL upon an error.

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

void nea_server_free_subscribers	(	nea_server_t *	nes,
		nea_subnode_t const **	sn_list
	)

Free a list of subscriptions.

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.

Parameters:

	nes	notifier
	ev	event view

The function nea_server_active() returns number of active subscribers.

int nea_server_notify	(	nea_server_t *	nes,
		nea_event_t *	ev
	)

Notify subscribers.

Returns:: The function nea_server_notify() returns number of subscribers that the notification could be sent, or -1 upon an error.

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.

Related Tags:

The following tagged arguments are accepted:

SIPTAG_PAYLOAD() or SIPTAG_PAYLOAD_STR()

Updated event content.

SIPTAG_CONTENT_TYPE() or SIPTAG_CONTENT_TYPE_STR().

MIME type of the content.

NEATAG_FAKE(fak)

If fake is true, 'fake' view is updated.

NEATAG_VIEW(view)

If included in tagged arguments, view is * updated. Used when updating secondary view.

NEATAG_VERSION(version)

The application-provided version for event content. After updated content has been sent to subscriber, version is copied to subscriber information structure.

NEATAG_EVMAGIC(context)

Application-provided context pointer. The context pointer is returned by nea_view_magic() function.

NEATAG_RELIABLE(reliable)

The reliable flag determines how overlapping updates are handled. If reliable is true, all updates are delivered to the subscribers.

NEATAG_THROTTLE(throttl)

Default value for event throttle for updated event view. Throttle determines the minimum interval in seconds betweeen notifications. Note that the notification indicating that the subscription has terminated will be sent regardless of throttle.

The default throttle value is used if the subscriber does not include a throttle parameter in Event header of SUBSCRIBE request.

NEATAG_MINTHROTTLE()

Minimum allowed throttle value for updated event view.

Return values:

	-1	upon an error.
	0	if event document was not updated.
	1	if event document was updated.

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 |
 +-----------+    +---------+       +------------+     +------------+

Related Tags:: IF NEATAG_VIEW(view) is included in tagged arguments, view is assigned to the subscriber and the content from the view is delivered to the subscriber.

If NEATAG_FAKE(1) is included in tags, content marked as 'fake' is delivered to the subscriber.

Return values:

	0	if successful
	-1	upon an error

sofia-sip/nea.h File Reference

Data Structures

Defines

Typedefs

Functions

Detailed Description

Define Documentation

Typedef Documentation

Function Documentation