XMLRPC support for PHP - README
===============================

(1) Installation
(2) How to use it


(1) Installation
================

To use XMLRPC for PHP, you need a working Apache webserver
with PHP support.
If you are using SuSE Linux (tested with version 7.2), 
you just need to install the following packages with yast:

	- apache
	- mod_php4

All dependencies are solved automagically, everything is
setup and you have a working apache server with php support
within minutes.

To setup the XMLRPC part, you just need the XMLRPC package
developed by the Useful Information Company. You can find it at

	http://xmlrpc.usefulinc.com/php.html

As you dont need the XMLRPC server part, all you have to
do is to copy the file 'xmlrpc.inc' into your project
directory and include it in your PHP scripts (for your
convenience there are some ready-to-use SKYRiX classes,
see below)

(2) How to use it
=================

The Classic way :
~~~~~~~~~~~~~~~~
To show you the classic way to use the XMLRPC functions
within PHP, here's a (documented) code snippet that shows
the basic functions provided by xmlrpc.inc (it's just a
simple example, if you want to access SKYRiX with PHP, it's
easier to use the provided PHP classes shown below) :

--- snip ---
<?php

  // include the XMLRPC client functions
  include("xmlrpc.inc");

  // create a xmlrpc message for the method 'message.name'
  // with one string parameter "value"
  $message = new xmlrpcmsg('message.name',
	     array(new xmlrpcval("value", "string")));

  // create a XMLRPC client for the URL http://your.server.com:10000/xmlrpc
  $client = new xmlrpc_client("/xmlrpc", "your.server.com", 10000);

  // send the message
  $result = $client->send($message);

  // get the return value
  $value = $result->value();

  // check if there was an error
  if (!$result->faultCode())
  {
    // print the return value (here: string)
    print $value->scalarval();

    // print the result as XML
    print htmlentities($result->serialize());
  } 
  else 
  {
    // print the error code
    print "Fault: ";
    print "Code: " . $result->faultCode() . 
  }
--- snap ---

The SKYRiX way :
~~~~~~~~~~~~~~~~
If you are familiar with the functions provided by the
skyxmlrpcd and probably saw the python functions to
access the SKYRiX system, this will be easy for you, as
the PHP functions are modelled after the python ones.

This code sample shows how to fetch a contact from the
SKYRiX system :

--- snip ---
<?php

  // generic xml functions and datatypes
  include('xmlrpc.inc')

  // person document class
  include('Person.inc')

  // generic xml client
  include('XmlRpcClient.inc')

  // person data source
  include('PersonDataSource.inc')

  // create a client object
  $client = new XmlRpcDataSource("http://server:10000/Skyrix/xmlrpc",
				 "username",
                                 "password"),

  // create a dataSource, init it with the client created above
  $dataSource = new PersonDataSource($client);

  // set the keys for the fetch specification
  $fetch  = array("name","firstname","nickname");

  // set the hints the fetch should return
  $hints  = array("name","number","firstname");

  // set the fetch specification for your query
  $dataSource->setFetchSpecification("zaphod",$fetch,$hints);

  // your fetch specification looks now (internal) like this
  // 
  // fetchSpecification =
  // {
  //   qualifier = "name like '*zaphod*' OR firstname like '*zaphod*' OR
  //                nickname like '*zaphod*'"
  //   hints =
  //   {
  //     attributes = ["name","number","firstname"]
  //   }
  // }

  // fetch the objects matching your fetch specification
  $result = $dataSource->getObjects()

  // result has the results of your query, now you can parse them
  if ($result)
  {
    foreach ($result as $contact)
    {
      // get the name of the current contact (as string)
      $name = $contact->getValue("name")
    }
  }  

?>
--- snap --

The same functions also exist for enterprises within the classes
'EnterpriseDataSource' and 'Enterprise'. You only have to exchange
the 'Person' classes with the 'Enterprise' classes in the example
above to get enterprise objects (you have to change the keys and hints
too, of course).

