Description
===========
MPS stands for MySQL+PHP Phone Search, just about the worst name I could think
of. It's is meant to be a library to query a MySQL address database
compatible with the one generated by FoonRIP. This library consists of 2 classes
defined in clientlib.php. Apart from querying a MySQL database it's also
possible to query a remote XML-RPC server (server included as xmlserver.php).
Also included in this distribution is a sample html interface
(search.(php|html)) which must be configured through config.php.
Everthing was created with the idea of creating fast SQL queries, either
by making really slow queries impossible or altering the db in such a way to
take maximum advantage of indices.
The database is compatible with the FoonRIP 0.71 database, but not 0.72. As it
has a different format searches on surname will fail. As the 0.72 format is
expected to change again soon (see TODO for idea if this doesn't happen) no
changes have been implemented to make MPS work with that new version.
MPS is not affiliated with FoonRIP, nor does it in any way encourage
anything not legal. It's just a way to search in an address database compatible
with FoonRIP's. Please consider the present 0.1 release of alpha quality.

Files
=====
*   db/add-idx.sql          : sql commands to add indices to the MySQL DB to
                              improve speed
*   db/alter-table.sql      : sql commands to alter table in the MySQL DB to
                              improve speed
*   db/new-db-def.sql       : new database definition
*   doc/colors.txt          : some colors ideas for the HTML interface
*   doc/config.php.example  : example configuration file needed for search.php
                              and xmlserver.php
*   clientlib.php           : classes to query the MySQL database or
                              XML-RPC server
*   COPYING                 : license information
*   README                  : you're looking at it :)
*   search.html             : together with search.php the sample html
                              interface
*   search.php              : together with search.html the sample html
                              interface
*   styles.css              : CSS definitions for search.(php|html)
*   TODO                    : old/implemented and new ideas
*   xmlserver.php           : XML-RPC server implementation


Install
=======
First the preparation of the MySQL database. new-db-def.sql contains the db
definition. In case you want to use FoonRIP's database you should consider 2
changes. Neither of the 2 changes are necessary, everything should work with
an unaltered FoonRIP db, but the proposed db changes improve query speed
significantly. Neither change depends on the other.

alter-table.sql makes some alterations to 2 tables. This means MySQL creates
a temporary table with the new table definition and copies the data from the
old to it. So you need at least as much temporary disk space as the subscriber
table uses (in my case about 450meg). Of course it also takes quite some time
to do this.
add-idx.sql adds some indices. These extra indices take up permanent extra disk
space, it also takes quite some time to create the indices.

Unless you want to use one of the sample interfaces (html or XML-RPC server) you
only need to include clientlib.php and use the classes defined in it. search.php
and xmlserver.php should provide enough clues how.


MySQL
=====
The classes in clientlib.php expect that a connection to the MySQL server has
already been made.
If you decide to use the sample html interface you also need search.html,
search.php and config.php in the same directory as clientlib.php. An example of
config.php has been included in /doc/config.php.example. search.html contains
the html form to start a search with.
If you also want to offer a XML-RPC interface you also need xmlserver.php
which also needs config.php


XML-RPC
=======
As a result of discussions on the FoonRIP forums about querying remote servers
both an XML-RPC server and client has been included. XML-RPC was chosen as the
protocol because there are libraries available for just about every programming
language you can think of.
The included server and client both depend on the XML-RPC library for PHP which
can be found at http://phpxmlrpc.sourceforge.net/. You need to put xmlrpc.inc
and xmlrpcs.inc in PHP's include path or in the same directory as clientlib.php
and xmlserver.php. The speed is a bit dissappointing (1.5sec per query
using XML-RPC (xmlserver on loclahost), 0.3sec in case of direct MySQL). I'm
planning to implement a version wich takes advantage of PHP's built in XML-RPC
functions. Those should be faster but are only availble in 4.1.0 and higher and
aren't considered stable yet.
If you want to use xmlserver.php be sure you edit config.php to contain the
correct MySQL connection details.


XML-RPC info for developers
===========================
xmlserver.php expects the request as HTTP POST action. The request should be a
struct containing the following entries:

Name       Type
phone   => string
srname  => string
strt    => string
town    => string
pc      => string
limit   => int
offset  => int
order   => string

The server replies with an array of structs. With each struct containing:

Name       Type
id      => int
phone   => string
aclen   => int
inis    => string
srname  => string
strt    => string
hno     => int
hnpf    => string
company => string
pc      => string
town    => string


Contact Information
===================
Email: xim@cb3rob.net
IRC: XiM on irc.icerealm.net (you can usually find me in #icerealm or #xim)
Website: http://xim.d2g.com

$Id: README,v 1.3.2.1 2002/02/19 20:08:56 M Boerwinkel Exp $
