
# $Id: README,v 1.1 2003/10/18 02:03:07 pcurtis Exp $

             Jabber Component Runtime (JCR)
                (c) 2003 Paul Curtis

COPYRIGHTS

For the JCR functions, provided Makefiles, and the main() function:
    Copyright (c) 2003 Paul Curtis
                                                                                
    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.
                                                                                
    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.
                                                                                
For the functions fom the jabberd 1.4.x codebase:
   The contents of these files are subject to the Jabber Open Source License
   Version 1.0 (the "JOSL").  You may not copy or use this file, in either
   source code or executable form, except in compliance with the JOSL. You
   may obtain a copy of the JOSL at http://www.jabber.org/ or at
   http://www.opensource.org/.

   Software distributed under the JOSL is distributed on an "AS IS" basis,
   WITHOUT WARRANTY OF ANY KIND, either express or implied.  See the JOSL
   for the specific language governing rights and limitations under the
   JOSL.

   Portions created by or assigned to Jabber.com, Inc. are
   Copyright (c) 1999-2002 Jabber.com, Inc.  All Rights Reserved.

   Portions Copyright (c) 1998-1999 Jeremie Miller.



This is the README file for the Jabber Component Runtime (JCR). The
jcr is designed to allow components written in "C" for the jabberd
1.4.x codebase to be run as standalone processes. What this means is
that you compile the library, and then compile your component
against this library (and the included 'main.c') to produce a
standalone component.

To see a list of functions that the library includes, see the
'FUNCTIONS' file. Most of the commonly used jabberd 1.4.x functions
are included with some notable exceptions:

 --- mtq_* functions: 
     These functions allow the developer to queue up data for a
     function using 'pth' queues. While this is a nice feature, it
     is not necessary (for the most part) to handle the packet
     volume.

 --- mio_* functions:
     Currently, the mio_* functions are not ported (or wrapped) for
     inclusion in the library. I have found that using the 'glib'
     I/O channels provide the same functionality. For porting
     purposes, the code will have to be altered slightly to use
     'g_io' rather than mio.

The porting effort will depend how many of the above functions are
used. To maintain compatibility with compiling using the jabberd
1.4.x codebase, a define is set at compile time to allow the
developer to know whether the component is being compiled normally,
or with the jcr. The define, '_JCOMP' is set in the Makefile
provided (jcomp.mk) as an example.

The only dependency for the JCR is glib-2.0. This library provides
the asynchronous I/O as well as the event loop used in the main()
function.

The library is simple: after establishing a connection to the
server, a 'deliver' thread is spawned, and the main event loop is
started. Incoming packets are read and parsed, and then delivered to
the 'phandler' that the component has registered. In addition, the
conponent's 'shutdown' function can be registered to close down all
component files, etc. before the server exits.

Outgoing packets are queued for writing back to the server using the
library call 'deliver()'. See the FUNCTIONS file for a detailed list
of what other calls are available.

The goal of this project is to allow for standalone processes to be
created using already written "C" language components that were
based around the jabberd 1.4.x code base and server. The advantages
of this type of component are speed, ease of administration, and
forward compatibility with the new jabberd 2 server.

The limitations are few: the component can register only one
'phandler' and one 'shutdown' function. Other functions that require
processing while the component is running (heartbeat functions) can
be added to the main event loop using standard glib 'add_watch'
functions.

The initial component tested with JCR is the mu-conference component
written by David Sutton and available from jabberstudio.org. For
examples of the type of changes required, a quick scan of the
mu-conference source code (searching for the _JCOMP define) will
yield the type of changes needed to move mu-conference from the
jabberd 1.4.x server to a JCR standalone process.

Configuration and running of the new JCR component as a process is
detailed in the CONFIGURATION file included in the JCR source
distribution.



