nea_server.c File Reference


Detailed Description

Nokia Event API - event notifier implementation.

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

Martti Mela <Martti.Mela@nokia-email.address.hidden>

Date:
Created: Wed Feb 14 18:37:04 EET 2001 ppessi

#include "config.h"
#include <sofia-sip/sip.h>
#include <sofia-sip/sip_header.h>
#include <sofia-sip/sip_util.h>
#include <sofia-sip/sip_status.h>
#include <sofia-sip/su_tagarg.h>
#include "nea_debug.h"
#include <sofia-sip/nea.h>
#include <sofia-sip/htable.h>
#include <stddef.h>
#include <stdlib.h>
#include <string.h>
#include <stdio.h>
#include <stdarg.h>
#include <assert.h>
#include <limits.h>

Include dependency graph for nea_server.c:


Data Structures

struct  nea_server_s
 Server object, created for every notifier. More...
struct  nea_event_s
 Supported events and their subscribers. More...
struct  nea_event_view_s
 Object representing particular view of event. More...
struct  nea_event_view_s::nea_event_queue_s
 Queued notification. More...
struct  nea_sub_s
 Subscription object. More...

Defines

#define NEA_VIEW_MAX
 Number of primary views (with different MIME type or content).

Functions

void nea_sub_assign_view (nea_sub_t *s, nea_event_view_t *evv)
 Assign an event view to subscriber.
nea_server_tnea_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.
int nea_server_update (nea_server_t *nes, nea_event_t *ev, tag_type_t tag, tag_value_t value,...)
 Update event information.
nea_event_view_tnea_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 *evv)
 Destroy a private event view.
nea_event_view_tnea_event_view (nea_event_t *ev, 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 *evv)
 Get a content type for event's payload.
int nea_server_notify (nea_server_t *nes, nea_event_t *ev)
 Notify subscribers.
void nea_server_flush (nea_server_t *nes, nea_event_t *event)
 Zap terminated subscribtions.
nta_incoming_t * nea_subnode_get_incoming (nea_subnode_t *sn)
 Get nta_incoming_t from sn->sn_subscriber.
nea_event_tnea_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_tnea_event_tcreate (nea_server_t *nes, nea_watcher_f *callback, nea_emagic_t *context, char const *name, char const *subname, tag_type_t tag, tag_value_t value,...)
 Create a new event (or subevent) with tags.
nea_emagic_tnea_emagic_get (nea_event_t *ev)
 Return magic context bind to nea_event.
nea_event_tnea_event_get (nea_server_t const *nes, char const *e)
 Find a nea event object with given event name.
nta_incoming_t * nea_sub_get_request (nea_sub_t *sub)
 Get nta_incoming_t from nea_sub_t.
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.
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.
int nea_sub_version (nea_sub_t *s, unsigned version)
 Set subscriber version sequence.
int nea_sub_auth (nea_sub_t *s, nea_state_t state, tag_type_t tag, tag_value_t value,...)
 Authorize a subscription.
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 **sn_list)
 Free a list of subscriptions.

Function Documentation

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.

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.

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

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 1.12.6 - Copyright (C) 2006 Nokia Corporation. All rights reserved. Licensed under the terms of the GNU Lesser General Public License.