jsm.h File Reference

definition of the jsm API More...

#include "jabberd.h"

Go to the source code of this file.

Data Structures
struct	mapi_struct
struct	mlist_struct
struct	history_storage_conf
struct	jsmi_struct
struct	udata_struct
struct	session_struct
struct	jpq_struct
Defines
#define	SESSION_WAITERS   10
#define	HOSTS_PRIME   17
#define	USERS_PRIME   3001
#define	e_SESSION   0
#define	e_OFFLINE   1
#define	e_SERVER   2
#define	e_DELIVER   3
#define	e_SHUTDOWN   4
#define	e_AUTH   5
#define	e_REGISTER   6
#define	e_CREATE   7
#define	e_DELETE   8
#define	e_DESERIALIZE   9
#define	e_PRE_REGISTER   10
#define	e_PASSWORDCHANGE   11
#define	e_FILTER_IN   12
#define	e_FILTER_OUT   13
#define	e_ROSTERCHANGE   14
#define	e_LAST   15
#define	es_IN   0
#define	es_OUT   1
#define	es_END   2
#define	es_SERIALIZE   3
#define	es_FILTER_IN   4
#define	es_FILTER_OUT   5
#define	es_LAST   6
#define	ADMIN_MOTD   "motd"
#define	ADMIN_LISTSESSIONS   "listsessions"
#define	ADMIN_ADMINMSG   "adminmsg"
#define	ADMIN_SHOWPRES   "showpres"
#define	ADMIN_DYNAMIC   "dynamic"
#define	PACKET_FROM_OFFLINE_MAGIC   1768189505
#define	PACKET_FORCE_SENT_MAGIC   1836017748
#define	PACKET_PASS_FILTERS_MAGIC   20060704
Typedefs
typedef int	event
typedef struct udata_struct *	udata
typedef struct udata_struct	_udata
typedef struct session_struct *	session
typedef struct session_struct	_session
typedef struct jsmi_struct *	jsmi
typedef struct jsmi_struct	_jsmi
typedef struct mapi_struct *	mapi
typedef struct mapi_struct	_mapi
typedef mreturn(*	mcall )(mapi m, void *arg)
typedef struct mlist_struct *	mlist
typedef struct mlist_struct	_mlist
typedef struct jpq_struct	_jpq
typedef struct jpq_struct *	jpq
Enumerations
enum	mreturn { M_PASS, M_IGNORE, M_HANDLED }
Functions
xmlnode	js_config (jsmi si, const char *query, const char *lang)
udata	js_user (jsmi si, jid id, xht ht)
int	js_user_create (jsmi si, jid id)
int	js_user_delete (jsmi si, jid id)
void	js_deliver (jsmi si, jpacket p, session sending_s)
session	js_session_new (jsmi si, dpacket p)
session	js_sc_session_new (jsmi si, dpacket p, xmlnode sc_session)
void	js_session_end (session s, char *reason)
session	js_session_get (udata user, char const *res)
session	js_session_primary (udata user)
void	js_session_to (session s, jpacket p)
void	js_session_from (session s, jpacket p)
void	js_session_free_aux_data (void *arg)
void	js_server_main (void *arg)
void	js_offline_main (void *arg)
result	js_users_gc (void *arg)
void	js_psend (jsmi si, jpacket p, mtq_callback f)
void	js_bounce_xmpp (jsmi si, session s, xmlnode x, xterror xterr)
void	js_mapi_register (jsmi si, event e, mcall c, void *arg)
void	js_mapi_session (event e, session s, mcall c, void *arg)
int	js_mapi_call (jsmi si, event e, jpacket packet, udata user, session s)
int	js_mapi_call2 (jsmi si, event e, jpacket packet, udata user, session s, xmlnode serialization_node)
void	js_mapi_create_additional_iq_result (mapi m, const char *name, const char *prefix, const char *ns_iri)
void	js_authreg (void *arg)
result	js_packet (instance i, dpacket p, void *arg)
int	js_islocal (jsmi si, jid id)
int	js_trust (udata u, jid id)
jid	js_trustees (udata u)
jid	js_seen_jids (udata u)
void	js_remove_trustee (udata u, jid id)
int	js_seen (udata u, jid id)
void	js_remove_seen (udata u, jid id)
int	js_online (mapi m)
void	jsm_shutdown (void *arg)
void	jsm_serialize (jsmi si)
void	jsm_deserialize (jsmi si, const char *host)

---

Detailed Description

definition of the jsm API

---

Define Documentation

#define ADMIN_ADMINMSG   "adminmsg"

admin right to receive messages to admin address

#define ADMIN_DYNAMIC   "dynamic"

dynamic adding/removing hosts from session manager

#define ADMIN_LISTSESSIONS   "listsessions"

admin right to see online users

#define ADMIN_MOTD   "motd"

admin right to set/update/delete the message of the day

#define ADMIN_SHOWPRES   "showpres"

request presence and last info for any user

Referenced by js_trust().

#define e_AUTH   5

e_AUTH is the mapi event, that is used for processing jabber:iq:auth packets while the user did not yet authenticate. This processing is only done by the session manager for sessions using the traditional session control protocol of jabberd14. The jabberd2 compatible session control protocol implies that the authentication is already done by the client connection manager (or another component that starts the session).

This event is called for get requests as well as for set requests. Inside handling of get requests, the modules have to add their fields into the passed stanza and have to return M_PASS to let other modules add their fields as well. Inside handling of set requests, the modules have to try to authenticate the user. If the module handled the authentication (either by accepting or denying the authentication), it has to return M_HANDLED, else it has to return M_PASS. If no module registered for this event authenticated the set request, the session manager will deny the authentication request itself.

The registered module is passed the jpacket_struct (stanza) as well as the udata_struct (user data). No session_struct is passed to the module.

After this event returns, the session manager will return the content of the packet. Therefore do not free the packet, and use jutil_error_xmpp() to generate error replies instead of the normal js_bounce_xmpp().

Referenced by _js_authreg_auth(), mod_auth_crypt(), mod_auth_digest(), and mod_auth_plain().

#define e_CREATE   7

e_CREATE is the mapi event, that is fired if a new user has just been created.

Only the udata_struct of the new user is passed to the handler registered for this event. Nothing is passed as the jpacket_struct nor as the session_struct.

Do not be surprised, that there are no modules registering for this event at present. The event has been introduced as the jabberd2 compatible session control protocol has such an event, and it might be useful in the future. (The event is fired for users that have been created by the traditional session control protocol as well.)

Referenced by js_user_create().

#define e_DELETE   8

e_DELETE is the mapi event, that is fired if a user gets deleted.

This event can be used by modules to register handlers, that remove state, that has been kept for this user. This might be cancling subscritions of the user as well as just deleting the user's data stored in xdb.

The handler is passed the user's udata_struct. Nothing is passed as the session_struct nor as the ::jpacket__struct.

Referenced by js_user_delete(), mod_auth_crypt(), mod_auth_plain(), mod_browse(), mod_last(), mod_offline(), mod_presence(), mod_register(), mod_roster(), mod_vcard(), and mod_xml().

#define e_DELIVER   3

e_DELIVER is the first mapi event, that is fired on stanzas received for an address handled by the session manager. It is called for all incoming stanzas before the session manager calls the different events e_SERVER, e_OFFLINE, or es_IN. If the stanza is M_HANDLED by on of the modules registered for this event, the session manager will even not call one of these three other events.

The called module gets passed the jpacket_struct (stanza). If the packet is addressed to an existing user, the user's udata_struct is passed. If the stanza is for a valid session, the session_struct is passed as well.

The event is called in any case, even if the stanza is addressed to a non-existant user.

Referenced by mod_ping(), mod_presence(), mod_roster(), and mod_stat().

#define e_DESERIALIZE   9

e_DESERIALIZE is the mapi event, that is fired if the session manager wants the module to deserialize its data about a session

The handler gets passed the udata_struct of the session owning user, the session_struct for the session, that is deserialized. No stanza is passed in jpacket_struct.

As all es_ events, the e_DESERIALIZE event has to be registered for a session using the js_mapi_session() call.

Referenced by mod_agents(), mod_browse(), mod_last(), mod_log(), mod_offline(), mod_ping(), mod_presence(), mod_privacy(), mod_roster(), mod_vcard(), and mod_xml().

#define e_FILTER_IN   12

e_FILTER_IN is called for incoming stanzas, that are handled by a session. It is used to filter stanzas before they are delivered to the e_OFFLINE event.

The called module gets passed the jpacket_struct (stanza) and the udata_struct (user data), but gets passed no session_struct as there is no such session.

Referenced by js_offline_main(), and mod_privacy().

#define e_FILTER_OUT   13

e_FILTER_OUT is called for outgoing stanzas, that are not sent by a specific session of a user. It is used to filter stanzas before they are sent out.

The called module gets passed the jpacket_struct (stanza) and the udata_struct (user data) of the sending user, but gets passed no session_struct.

Referenced by js_deliver(), and mod_privacy().

#define e_LAST   15

flag for the highest event type

Referenced by js_mapi_register(), and jsm().

#define e_OFFLINE   1

e_OFFLINE is a mapi event, that is fired for an incoming stanza for a user, that is currently not online (or that is addressed to a resource, for which there is no active session).

The called module gets passed the jpacket_struct (stanza) and the udata_struct (user data), but gets passed no session_struct as there is no such session.

Referenced by js_offline_main(), mod_browse(), mod_disco(), mod_last(), mod_offline(), and mod_vcard().

#define e_PASSWORDCHANGE   11

e_PASSWORDCHANGE is called when a user changes his password, or the first password is set on registration of an account. Modules can register this event to change stored credentials.

A fictive stanza is passed as jpacket_struct containing the following XML data:

<query xmlns='jabber:iq:auth' to='user@server'> <password>newpass</password> &lt/query>

Referenced by mod_auth_crypt(), mod_auth_digest(), and mod_auth_plain().

#define e_PRE_REGISTER   10

e_PRE_REGISTER is called in the same situation as the e_REGISTER event, but called before. If the event gets handled by any module, no e_REGISTER event is generated. This can be used to cancel registration requests, i.e. to check a request and deny it if provided data is not acceptable.

Only the stanza is passed as jpacket_struct. No session and no user is passed to a handler registered for this event.

After this event returns, the session manager will return the content of the packet. Therefore do not free the packet, and use jutil_error_xmpp() to generate error replies instead of the normal js_bounce_xmpp().

Referenced by _js_authreg_register(), mod_register(), and mod_useridpolicy().

#define e_REGISTER   6

e_REGISTER is the mapi event, that is used for processing jabber:iq:register packets in case there is no session yet. Therefore it is used to process new user registration requests.

Only the stanza is passed as jpacket_struct. No session and no user is passed to a handler registered for this event.

After this event returns, the session manager will return the content of the packet. Therefore do not free the packet, and use jutil_error_xmpp() to generate error replies instead of the normal js_bounce_xmpp().

Referenced by _js_authreg_register(), mod_auth_crypt(), mod_auth_digest(), mod_auth_plain(), mod_last(), and mod_register().

#define e_ROSTERCHANGE   14

e_ROSTERCHANGE is called when the roster of a user has changed.

The called module gets passed the jpacket_struct containing the updated item inside a iq[@type='set']/roster:query, the udata_struct (user data) of the user owning the roster, but gets passed no session_struct.

Referenced by mod_privacy().

#define e_SERVER   2

e_SERVER is a mapi event, that is fired for an incoming stanza, that is addressed to a Jabber ID, that does not contain a node (user part), but just a domain and optionally a resource. In the session manager of jabberd14, these packets are considered to be addressed to the server.

The called module gets passed the jpacket_struct (stanza), but no session_struct (as there are no sessions for such addresses). If the stanza is sent by a local user, the udata_struct of the sending user is passed to the module (this is a preformance hack, the module should not rely on this fact and expect to get NULL passed for local users as well).

Referenced by js_server_main(), mod_admin(), mod_agents(), mod_announce(), mod_browse(), mod_disco(), mod_dynamic(), mod_echo(), mod_example(), mod_last(), mod_offline(), mod_ping(), mod_privacy(), mod_register(), mod_time(), mod_vcard(), and mod_version().

#define e_SESSION   0

e_SESSION is a mapi event, that is fired when a new session is created. The new session might just be created, but not yet authenticated by the user.

The called module gets passed the udata_struct structure of the user and the session_struct structure of the user. No jpacket_struct (stanza) is passed to the module.

Referenced by _js_session_start(), mod_agents(), mod_announce(), mod_browse(), mod_last(), mod_log(), mod_offline(), mod_ping(), mod_presence(), mod_privacy(), mod_roster(), mod_vcard(), and mod_xml().

#define e_SHUTDOWN   4

e_SHUTDOWN is the mapi event, that should be called if the session manager is shutting down.

The called module gets passed nothing (NULL) as the stanza, user, and session.

This event is disabled at present (since just before the release of version 1.4.4) as we have problems with the memory management else. We have to free memory in the right order, which is not guarantied the way it is impelemented at present. To not get a software crash at shutdown, we just don't free the memory we needed all the time at present. This is not really a problem, it just makes memory profilers unhappy as we do not free all memory before exiting the process.

Referenced by jsm_shutdown(), and mod_version().

#define es_END   2

es_END is the mapi event, that is fired if a session ends.

The handler gets passed the udata_struct of the user, that is logged out; and the session_struct for the session that is closed. No stanza is passed in jpacket_struct.

As all es_ events, the es_IN event has to be registered for a session using the js_mapi_session() call.

Referenced by _js_session_end().

#define es_FILTER_IN   4

es_FILTER_IN is the mapi event, that is fired for incoming messages, that will get delivered to a session afterwards

If the es_FILTER_IN handlers are all PASSing, the event is then sent to the es_IN event queue.

The handler is passed the udata_struct of the destination user, the jpacket_struct containing the stanza, and the session_struct for the correct user's session.

As all es_ events, the es_IN event has to be registered for a session using the js_mapi_session() call.

Referenced by _js_session_to().

#define es_FILTER_OUT   5

es_FILTER_OUT is the mapi event, that is fired for outgoing messages, send by a user's session

If the es_FILTER_OUT handlers are all PASSing, the packet is sent out. If one handler returns M_HANDLED, the packet is not further processed.

The handler gets passed the udata_struct of the sending user, the jpacket_struct containing the stanza, and the session_struct for the sending user's session.

As all es_ events, the es_FILTER_OUT event has to be registered for a session using the js_mapi_session() call.

Referenced by js_deliver().

#define es_IN   0

es_IN is the mapi event, that is fired for stanzas that are received from other entities on the Jabber network for a local user. (INcoming stanzas from the user's view.)

The handler is passed the udata_struct of the destination user, the jpacket_struct containing the stanza, and the session_struct for the correct user's session.

As all es_ events, the es_IN event has to be registered for a session using the js_mapi_session() call.

Referenced by _js_session_to().

#define es_LAST   6

flag for the highest session event type

Referenced by js_mapi_session(), js_sc_session_new(), and js_session_new().

#define es_OUT   1

es_OUT is the mapi event, that is fired for stanzas, that are received from a user (forwarded by the client connection manager). (OUTgoing stanzas from the user's view.)

The handler gets passed the udata_struct of the sending user, the jpacket_struct containing the stanza, and the session_struct for the session, that is sending this packet.

As all es_ events, the es_IN event has to be registered for a session using the js_mapi_session() call.

Referenced by _js_session_from().

#define es_SERIALIZE   3

es_SERIALIZE is the mapi event, that is fired if the session manager wants the module to serialize its data about a session

The handler gets passed the udata_struct of the session owning user, the session_struct for the session, that is serialized. No stanza is passed in jpacket_struct.

As all es_ events, the es_SERIALIZE event has to be registered for a session using the js_mapi_session() call.

#define HOSTS_PRIME   17

set to a prime number larger then the average max # of hosts

Referenced by jsm().

#define PACKET_FORCE_SENT_MAGIC   1836017748

this value is set as a flag to a jpacket for a subscription state change, that should be sent out in any case

#define PACKET_FROM_OFFLINE_MAGIC   1768189505

this value is set as a flag to a jpacket, for a message that has been read from offline storage

Referenced by _js_session_to().

#define PACKET_PASS_FILTERS_MAGIC   20060704

this value is set as a flag to a jpacket for a locally generated error stanza to pass privacy lists

Referenced by _js_session_to(), js_bounce_xmpp(), js_deliver(), and js_offline_main().

#define SESSION_WAITERS   10

worker thread max waiting pool size

#define USERS_PRIME   3001

set to a prime number larger then the average max # of users

Referenced by js_packet(), and jsm().

---

Typedef Documentation

typedef struct jpq_struct _jpq

structure used to pass a session manager instance and a packet using only one pointer

typedef struct jsmi_struct _jsmi

a jsmi_struct

typedef struct mapi_struct _mapi

typedef struct mlist_struct _mlist

typedef struct session_struct _session

a session_struct

typedef struct udata_struct _udata

a udata_struct

typedef int event

master event types

typedef struct jpq_struct * jpq

typedef struct jsmi_struct* jsmi

pointer to a jsmi_struct

typedef struct mapi_struct * mapi

structure that hold information passed to module calls

typedef mreturn(* mcall)(mapi m, void *arg)

prototype of a callback function to register with the MAPI

typedef struct mlist_struct * mlist

structure to build the list of registered callback functions

typedef struct session_struct* session

pointer to a session_struct

typedef struct udata_struct* udata

pointer to a udata_struct

---

Enumeration Type Documentation

enum mreturn

return codes for mapi callback calls

Enumerator:

M_PASS	we don't want this packet this time
M_IGNORE	we don't want packets of this stanza type ever
M_HANDLED	stop mapi processing on this packet

---

Function Documentation

void js_authreg

(

void *

arg

)

Handle authentication or new-user registration requests

If jsm is not configured to let an external component handle authentication and registration of new users, it will let this function handle these both jobs

Parameters:

arg	the packet containing the authentication or registration request

References _js_authreg_auth(), _js_authreg_register(), jpacket_struct::aux1, deliver(), dpacket_new(), xmppd::jabberid::has_node(), xmppd::jabberid::has_resource(), jsmi_struct::i, jpacket_struct::iq, JPACKET__GET, jpacket_subtype(), jutil_error_xmpp(), NS_AUTH, NS_REGISTER, NS_SERVER, NSCHECK, jpacket_struct::to, jpacket_struct::x, xmlnode_get_attrib_ns(), xmlnode_hide_attrib_ns(), xmlnode_put_attrib_ns(), xmlnode_wrap_ns(), and XTERROR_NOTACCEPTABLE.

Referenced by _js_routed_auth_packet().

void js_bounce_xmpp	(	jsmi	si,
		session	s,
		xmlnode	x,
		xterror	xterr
	)

generate an error packet, that bounces a packet back to the server

Parameters:

si	the session manger instance
s	the session this bounce is related to (for selecting the right filters), NULL if not related to any session
x	the xmlnode for which the bounce packet should be generated
xterr	the reason for the bounce

References xterror_struct::code, jpacket_struct::flag, j_strcmp(), jpacket_new(), js_deliver(), jutil_error_xmpp(), jutil_iqresult(), log_debug2, LOGT_DELIVER, xterror_struct::msg, NS_SERVER, PACKET_PASS_FILTERS_MAGIC, xmlnode_free(), xmlnode_get_attrib(), xmlnode_get_localname(), xmlnode_get_namespace(), xmlnode_insert_cdata(), xmlnode_insert_tag_ns(), xmlnode_put_attrib_ns(), xmlnode_serialize_string(), and ZONE.

Referenced by js_deliver(), js_offline_main(), and js_server_main().

xmlnode js_config	(	jsmi	si,
		const char *	query,
		const char *	lang
	)

get a configuration node inside the session manager configuration

Parameters:

si	the session manager instance data
query	the path through the tag hierarchy of the desired tag, eg. for the conf file <foo><bar>bar value</bar><baz/></foo> use "foo/bar" to retrieve the bar node, may be NULL to get the root node of the jsm config
lang	the prefered language, NULL for no prefered language

Returns:

a pointer to the xmlnode (has to be freed by the caller!), or NULL if no such node could be found

References jid_new(), js_config(), log_debug2, LOGT_CONFIG, NS_JABBERD_CONFIG_JSM, pool_free(), pool_new, jsmi_struct::std_namespace_prefixes, jsmi_struct::xc, xdb_get(), xmlnode_get_tags(), xmlnode_select_by_lang(), and ZONE.

Referenced by _js_authreg_register(), js_config(), js_packet(), jsm(), mod_auth_crypt(), mod_auth_digest(), mod_auth_plain(), mod_last(), mod_log(), mod_offline(), mod_presence(), mod_version(), and mod_xml().

void js_deliver	(	jsmi	si,
		jpacket	p,
		session	sending_s
	)

take a packet and deliver it either locally if it has ourself as the destination or deliver it using jabberd if it is for a non-instance-local host

This function checks if the packet is local, and will then call j_deliver_local() to deliver it. If it is not instance-local it will call deliver() to deliver it using jabberd.

Note:

any jpacket sent to deliver *MUST* match jpacket_new(p->x), jpacket is simply a convenience wrapper

Parameters:

si	the session manager instance this is called in
p	the packet to deliver
sending_s	the sending session of the packet (used to select the correct outgoing filter), NULL if packet is not related to a session

References deliver(), dpacket_new(), e_FILTER_OUT, es_FILTER_OUT, jpacket_struct::flag, jpacket_struct::from, xmppd::jabberid::get_domain(), xmppd::jabberid::has_node(), jsmi_struct::hosts, jsmi_struct::i, jid_cmpx(), jid_full(), JID_SERVER, JID_USER, js_bounce_xmpp(), js_mapi_call(), js_user(), log_debug2, log_warn(), LOGT_DELIVER, PACKET_PASS_FILTERS_MAGIC, jpacket_struct::to, jpacket_struct::type, session_struct::u, jpacket_struct::x, xhash_get(), xmlnode_free(), xmlnode_serialize_string(), XTERROR_BAD, and ZONE.

Referenced by _js_session_from(), _js_session_to(), and js_bounce_xmpp().

int js_islocal	(	jsmi	si,
		jid	id
	)

macro to make sure the jid is a local user

Parameters:

si	the session manager instance data
id	the user to test

Returns:

0 if the user is not local, 1 if the user is local

References xmppd::jabberid::get_domain(), xmppd::jabberid::has_node(), jsmi_struct::hosts, and xhash_get().

Referenced by js_server_main().

int js_mapi_call	(	jsmi	si,
		event	e,
		jpacket	packet,
		udata	user,
		session	s
	)

call all the module callbacks for a phase

Addes callbacks to the ignore mask for a given packet type if they return M_IGNORE.

Parameters:

si	the session manager instance data (MUST be NULL for a es_* event)
e	call the modules for which event type
packet	the packet being processed, may be NULL
user	the user data for the current session (or the sender for e_SERVER if it is local), may be NULL
s	the session for which to call the event, may be NULL

Returns:

1 if the call was handled by a module, 0 if it wasn't handled

References js_mapi_call2().

Referenced by _js_authreg_auth(), _js_authreg_register(), _js_session_end(), _js_session_from(), _js_session_start(), _js_session_to(), js_deliver(), js_offline_main(), js_server_main(), js_user_create(), js_user_delete(), and jsm_shutdown().

int js_mapi_call2	(	jsmi	si,
		event	e,
		jpacket	packet,
		udata	user,
		session	s,
		xmlnode	serialization_node
	)

call all the module callbacks for a phase

Only needed for the events es_SERIALIZE and es_DESERIALIZE. Other events can use the shorter interface of js_mapi_call()

Addes callbacks to the ignore mask for a given packet type if they return M_IGNORE.

Parameters:

si	the session manager instance data (MUST be NULL for a es_* event)
e	call the modules for which event type
packet	the packet being processed, may be NULL
user	the user data for the current session (or the sender for e_SERVER if it is local), may be NULL
s	the session for which to call the event, may be NULL
serialization_node	the xmlnode to pass for es_SERIALIZE, and es_DESERIALIZE event

Returns:

1 if the call was handled by a module, 0 if it wasn't handled

References mapi_struct::additional_result, mlist_struct::arg, mlist_struct::c, mapi_struct::e, jsmi_struct::events, session_struct::events, log_debug2, LOGT_EXECFLOW, M_HANDLED, M_IGNORE, mlist_struct::mask, mlist_struct::next, mapi_struct::packet, mapi_struct::s, mapi_struct::serialization_node, mapi_struct::si, session_struct::si, jpacket_struct::type, mapi_struct::user, jpacket_struct::x, xmlnode_free(), and ZONE.

Referenced by js_mapi_call().

void js_mapi_create_additional_iq_result	(	mapi	m,
		const char *	name,
		const char *	prefix,
		const char *	ns_iri
	)

create an additiona_result element in the mapi structure

checks if there is already an additional result in the mapi structure, if not, it generates an iq result for the current query in the packet inside the mapi strucutre (needs to by an iq query of type get or set).

If name, prefix, and ns_iri is not NULL, an element in inserted in the iq result having this data.

Parameters:

m	the mapi structure
name	the local name of the element contained in the iq result
prefix	the prefix of the element contained in the iq result
ns_iri	the namespace iri of the element contained in the iq result

References mapi_struct::additional_result, jpacket_struct::iq, JPACKET__GET, JPACKET__SET, JPACKET_IQ, jpacket_new(), jpacket_subtype(), jutil_iqresult(), mapi_struct::packet, jpacket_struct::type, jpacket_struct::x, xmlnode_dup(), and xmlnode_insert_tag_ns().

void js_mapi_register	(	jsmi	si,
		event	e,
		mcall	c,
		void *	arg
	)

let a module register a new callback for a specified phase

Takes a function pointer and argument and stores them in the callback list for the event e

Parameters:

si	the session manager instance data
e	the event type for which to register the callback
c	pointer to the function, that gets registered
arg	an argument to pass to c when it is called

References mlist_struct::arg, mlist_struct::c, e_LAST, jsmi_struct::events, log_debug2, LOGT_INIT, mlist_struct::mask, mlist_struct::next, jsmi_struct::p, pmalloco(), and ZONE.

Referenced by mod_admin(), mod_agents(), mod_announce(), mod_auth_crypt(), mod_auth_digest(), mod_auth_plain(), mod_browse(), mod_disco(), mod_dynamic(), mod_echo(), mod_example(), mod_last(), mod_log(), mod_offline(), mod_ping(), mod_presence(), mod_privacy(), mod_register(), mod_roster(), mod_stat(), mod_time(), mod_useridpolicy(), mod_vcard(), mod_version(), and mod_xml().

void js_mapi_session	(	event	e,
		session	s,
		mcall	c,
		void *	arg
	)

let a module register a new callback for a specified phase on a session

This is like js_mapi_register except that the call only applies to the specified session.

Parameters:

e	the event type for which to register the callback
s	the session for which the callback should be registered
c	pointer to the function, that gets registered
arg	an argument to pass to c when it is called

References mlist_struct::arg, mlist_struct::c, es_LAST, session_struct::events, log_debug2, LOGT_INIT, mlist_struct::mask, mlist_struct::next, session_struct::p, pmalloco(), and ZONE.

void js_offline_main

(

void *

arg

)

function that handles packets that are sent to a valid user account, that has no online session

First try if one of the e_OFFLINE modules handles the packet, if not it is bounced as recipient-unavailable

Parameters:

arg	the jpq_struct for this packet (contains the session manager instance data and the packet)

References jpacket_struct::aux1, e_FILTER_IN, e_OFFLINE, jpacket_struct::flag, udata_struct::id, jid_full(), js_bounce_xmpp(), js_mapi_call(), log_debug2, LOGT_DELIVER, jpq_struct::p, PACKET_PASS_FILTERS_MAGIC, udata_struct::ref, jpq_struct::si, jpacket_struct::x, xmlnode_serialize_string(), XTERROR_RECIPIENTUNAVAIL, and ZONE.

int js_online

(

mapi

m

)

check if a mapi call is for the "online" event

sucks, should just rewrite the whole mapi to make things like this better

Parameters:

m	the mapi call

Returns:

1 if the mapi call is for the "online" event, 0 else

References JPACKET__AVAILABLE, JPACKET__INVISIBLE, jpacket_subtype(), mapi_struct::packet, session_struct::priority, mapi_struct::s, and jpacket_struct::to.

result js_packet	(	instance	i,
		dpacket	p,
		void *	arg
	)

handle packets we get passed from the XML router (jabberd)

The JSM component receives the packets from the XML router by a call to this function. Therefore each incoming stanza (either from other servers received by the dialback component or from a client connection received by the client connection manager) generates a call of this function.

This function ensures, that there is a hash table for the destination domain containing all users, that are currently online on this host (it might be the first packet addresses to this host in which case this hash is not present before). After this is done, it checks if it is either a stanza, that has been forwarded by an other component on the XML router (typically this is the client connection manager) in which case the stanza is passed to _js_routed_packet(), or if it is a non-forwarded packet, which typically means it is an incoming stanza from either a remote server or another session manager instance on the same XML router, or a stanza from a transport/gateway. In the second case of a non-forwarded stanza, the stanza is passed to the function js_deliver_local().

Parameters:

i	the jsm instance we are running in
p	the packet we should receive
arg	our jsm instance internal data

Returns:

always r_DONE

References _js_routed_packet(), dpacket_struct::host, jsmi_struct::hosts, j_atoi(), jpacket_new(), js_config(), log_debug2, log_warn(), LOGT_DELIVER, jsmi_struct::p, p_ROUTE, pstrdup(), r_DONE, dpacket_struct::type, USERS_PRIME, dpacket_struct::x, xhash_get(), xhash_new(), xhash_put(), xmlnode_free(), xmlnode_get_data(), xmlnode_serialize_string(), and ZONE.

Referenced by jsm().

void js_psend	(	jsmi	si,
		jpacket	p,
		mtq_callback	f
	)

send a packet to a function

Parameters:

si	the instance local data
p	the packet to send
f	the function to send the packet to

References log_debug2, LOGT_DELIVER, mtq_send(), jpq_struct::p, jpacket_struct::p, pmalloco(), jpq_struct::si, and ZONE.

void js_remove_seen	(	udata	u,
		jid	id
	)

remove a user from the list of seen users

Parameters:

u	from which user's seen list the user 'id' should be removed
id	which user should be removed

References jid_cmpx(), JID_SERVER, JID_USER, xmppd::jabberid_pool::next, and udata_struct::useen.

void js_remove_trustee	(	udata	u,
		jid	id
	)

remove a user from the list of trustees

Parameters:

u	from which user's trustees list the user 'id' should be removed
id	which user should be removed

References jid_cmpx(), JID_SERVER, JID_USER, xmppd::jabberid_pool::next, and udata_struct::utrust.

session js_sc_session_new	(	jsmi	si,
		dpacket	dp,
		xmlnode	sc_session
	)

create a new session, that was signaled by the c2s with the session control protocol

Sets up all the data associated with a new session, then notify all modules that registered for e_SESSION about the newly created session

Parameters:

si	the session manager instance data
dp	the packet we received from the c2s instance, that requested the new session
sc_session	the xmlnode containing the sc:session element

Returns:

a pointer to the new session (NULL if input data is invalid)

References _js_session_start(), session_struct::aux_data, session_struct::c_in, session_struct::c_out, es_LAST, session_struct::events, session_struct::exit_flag, xmppd::jabberid::get_resource(), dpacket_struct::id, session_struct::id, j_strcmp(), jid_full(), jid_new(), JPACKET__UNAVAILABLE, js_session_end(), js_session_free_aux_data(), js_user(), jutil_presnew(), log_debug2, LOGT_SESSION, mtq_new(), mtq_send(), N_, session_struct::next, NS_SESSION, session_struct::p, pmalloco(), pool_cleanup(), pool_free(), pool_heap, session_struct::presence, session_struct::priority, pstrdup(), session_struct::q, session_struct::res, session_struct::roster, session_struct::route, session_struct::sc_c2s, jsmi_struct::sc_sessions, session_struct::sc_sm, udata_struct::sessions, session_struct::si, session_struct::sid, session_struct::u, dpacket_struct::x, xhash_new(), xhash_put(), xmlnode_get_attrib_ns(), xmlnode_put_attrib_ns(), and ZONE.

Referenced by _js_routed_session_control_packet().

int js_seen	(	udata	u,
		jid	id
	)

check if a id is seen (allowed to send presence to a user)

Parameters:

u	the user for which the check should be made
id	the jid which should be checked if it is trusted

Returns:

0 if it is not trusted, 1 if it is trusted

References _js_jidscanner(), and js_seen_jids().

jid js_seen_jids

(

udata

u

)

get the list of jids, that are allowed to send presence to a given user

Parameters:

u	for which user to get the list

Returns:

pointer to the first list entry

References udata_struct::useen.

Referenced by js_seen().

void js_server_main

(

void *

arg

)

handle a packet addressed to the server itself (no node part in the JID)

Pass the packet to the modules, that registered for the e_SERVER event. If none of the modules handled the packet, it is bounced as "not-found".

Parameters:

arg	jpq structure containing the session manager instance data and the packet

References e_SERVER, jpacket_struct::from, js_bounce_xmpp(), js_islocal(), js_mapi_call(), js_user(), log_debug2, LOGT_DELIVER, jpq_struct::p, udata_struct::ref, jpq_struct::si, jpacket_struct::x, xmlnode_serialize_string(), XTERROR_NOTFOUND, and ZONE.

void js_session_end	(	session	s,
		char *	reason
	)

shut down the session

This function gets called when the user disconnects or when the server shuts down. It changes the user's presence to offline, cleans up the session data and notifies all registered modules for the es_END event about the closed session

Parameters:

s	the session, that is closing
reason	textual reason for the shutdown

References _js_session_end(), session_struct::exit_flag, session_struct::id, j_strcmp(), jid_full(), JPACKET__UNAVAILABLE, jutil_presnew(), log_debug2, LOGT_SESSION, messages_get(), mtq_send(), session_struct::next, session_struct::p, session_struct::presence, session_struct::priority, session_struct::q, udata_struct::ref, jsmi_struct::sc_sessions, session_struct::sc_sm, udata_struct::sessions, session_struct::si, session_struct::u, xhash_zap(), xmlnode_free(), xmlnode_get_attrib_ns(), xmlnode_get_lang(), xmlnode_put_attrib_ns(), and ZONE.

Referenced by __jsm_shutdown(), _js_routed_error_packet(), _js_routed_session_control_packet(), js_sc_session_new(), and js_session_new().

void js_session_free_aux_data

(

void *

arg

)

delete the aux hash if a session structure is freed

References session_struct::aux_data, and xhash_free().

Referenced by js_sc_session_new(), and js_session_new().

void js_session_from	(	session	s,
		jpacket	p
	)

handle normal stanzas received inside a <route/> stanza from jabberd. These are packets we get from the client connection manager, that are from one of our users.

Pass them to _js_session_from() to get executed by an own execution thread.

Parameters:

s	the session of the user
p	the received packet

References _js_session_from(), jpacket_struct::aux1, log_debug, mtq_send(), jpacket_struct::p, session_struct::q, and ZONE.

Referenced by _js_routed_packet().

session js_session_get	(	udata	user,
		char const *	res
	)

find the session for a given resource

Given a user and a resource, find the corresponding session if the user is logged in. Otherweise return NULL.

Parameters:

user	the user's udata record
res	the resource to search for

Returns:

a pointer to the session if the user is logged in, NULL if the user isn't logged in on this resource

References j_strcmp(), j_strlen(), j_strncmp(), session_struct::next, session_struct::res, and udata_struct::sessions.

session js_session_new	(	jsmi	si,
		dpacket	dp
	)

create a new session, register the resource for it (initiated by the old c2s-sm-protocol)

Sets up all the data associated with a new session, then notify all modules that registered for e_SESSION about the newly created session

Parameters:

si	the session manager instance data
dp	the packet we received from the c2s instance, that requested the new session

Returns:

a pointer to the new session (NULL if input data is invalid)

References _js_session_start(), session_struct::aux_data, session_struct::c_in, session_struct::c_out, es_LAST, session_struct::events, session_struct::exit_flag, xmppd::jabberid::get_resource(), xmppd::jabberid::has_node(), xmppd::jabberid::has_resource(), session_struct::id, dpacket_struct::id, j_strcmp(), jid_full(), jid_new(), JID_RESOURCE, jid_set(), JPACKET__UNAVAILABLE, js_session_end(), js_session_free_aux_data(), js_user(), jutil_presnew(), log_debug2, LOGT_SESSION, mtq_new(), mtq_send(), N_, session_struct::next, session_struct::p, pmalloco(), pool_cleanup(), pool_heap, session_struct::presence, session_struct::priority, pstrdup(), session_struct::q, session_struct::res, session_struct::roster, session_struct::route, udata_struct::sessions, session_struct::si, session_struct::sid, session_struct::u, dpacket_struct::x, xhash_new(), xmlnode_get_attrib_ns(), xmlnode_put_attrib_ns(), and ZONE.

Referenced by _js_routed_session_packet().

session js_session_primary

(

udata

user

)

find the primary session for the user

Scan through the user's sessions to find the session with the highest priority and return a pointer to it.

Parameters:

user	the user to find the highest session for

Returns:

pointer to the primary session if the user is logged in with at least priority 0, NULL if there is no active session with a priority of at least 0

References session_struct::next, session_struct::priority, and udata_struct::sessions.

void js_session_to	(	session	s,
		jpacket	p
	)

handle packets addresses to a specific resource (session) of a user

pass them to _js_session_to() ...

Parameters:

s	the session the packet is addressed to
p	the packet

References _js_session_to(), jpacket_struct::aux1, log_debug, mtq_send(), jpacket_struct::p, session_struct::q, and ZONE.

Referenced by _js_session_from().

int js_trust	(	udata	u,
		jid	id
	)

check if a id is trusted (allowed to see the presence of a user)

Parameters:

u	the user for which the check should be made
id	the jid which should be checked if it is trusted

Returns:

0 if it is not trusted, 1 if it is trusted

References _js_jidscanner(), acl_check_access(), ADMIN_SHOWPRES, js_trustees(), udata_struct::si, and jsmi_struct::xc.

jid js_trustees

(

udata

u

)

get the list of jids, that are subscribed to a given user

Parameters:

u	for which user to get the list

Returns:

pointer to the first list entry

References udata_struct::utrust.

Referenced by js_trust().

udata js_user	(	jsmi	si,
		jid	id,
		xht	ht
	)

get the udata record for a user

js_user attempts to locate the user data record for the specifed id. First it looks in current list, if that fails, it looks in xdb and creates new list entry. If THAT fails, it returns NULL (not a user).

Parameters:

si	the session manager instance data
id	which user to load (some memory is allocated from this jid's pool)
ht	the hash table for the host the user belongs to (may be NULL)

Returns:

the udata record for the user, NULL if no such user

References udata_struct::aux_data, xmppd::jabberid::get_domain(), xmppd::jabberid::get_node(), xmppd::jabberid_pool::get_pool(), xmppd::jabberid::has_node(), jsmi_struct::hosts, udata_struct::id, jid_full(), jid_new(), jid_user(), js_user_free_aux_data(), log_debug2, LOGT_SESSION, NS_AUTH, NS_AUTH_CRYPT, udata_struct::p, pmalloco(), pool_cleanup(), pool_heap, udata_struct::si, jsmi_struct::xc, xdb_get(), xhash_get(), xhash_new(), xhash_put(), xmlnode_free(), and ZONE.

Referenced by _js_authreg_auth(), _js_authreg_register(), _js_routed_packet(), js_deliver(), js_sc_session_new(), js_server_main(), js_session_new(), js_user_create(), and js_user_delete().

int js_user_create	(	jsmi	si,
		jid	id
	)

inform registered modules of a newly created user

Parameters:

si	the session manager instance
id	the jid of the new user

Returns:

1 if the call was handled by a module, 0 if not

References e_CREATE, js_mapi_call(), and js_user().

Referenced by _js_routed_session_control_packet().

int js_user_delete	(	jsmi	si,
		jid	id
	)

inform registered modules of a deleted user

Parameters:

si	the session manager instance
id	the jid of the deleted user

Returns:

1 if the call was handled by a module, 0 if not

References e_DELETE, js_mapi_call(), and js_user().

Referenced by _js_routed_session_control_packet().

result js_users_gc

(

void *

arg

)

js_users_gc is a heartbeat that flushes old users from memory.

Parameters:

arg	the session manager internal data

Returns:

always r_DONE

References _js_hosts_del(), jsmi_struct::hosts, log_debug2, log_notice(), LOGT_STATUS, r_DONE, xhash_walk(), and ZONE.

Referenced by jsm().

void jsm_deserialize	(	jsmi	si,
		const char *	host
	)

deserialize session manager data

Parameters:

si	the session manager, that receives the deserialized data
host	the host to deserialize

References jsmi_struct::i, instance_struct::id, log_notice(), jsmi_struct::statefile, jsmi_struct::std_namespace_prefixes, xmlnode_file(), xmlnode_free(), xmlnode_get_tags(), and xmlnode_pool().

void jsm_serialize

(

jsmi

si

)

serialize session manager data

References jsmi_struct::hosts, NS_JABBERD_STOREDSTATE, jsmi_struct::statefile, xhash_walk(), xmlnode2file(), xmlnode_free(), and xmlnode_new_tag_ns().

void jsm_shutdown

(

void *

arg

)

callback function where jabberd signals the shutdown of the server

Parameters:

arg	instance internal jsm data

References _jsm_shutdown(), e_SHUTDOWN, jsmi_struct::hosts, js_mapi_call(), log_debug2, LOGT_CLEANUP, xhash_free(), xhash_walk(), and ZONE.