> Using the XML-RPC Server

XML-RPC is "a spec and a set of implementations that allow software running on disparate operating systems, running in different environments to make procedure calls over the Internet. It's remote procedure calling using HTTP as the transport and XML as the encoding. XML-RPC is designed to be as simple as possible, while allowing complex data structures to be transmitted, processed and returned." To use this service, you need to: open an account or login to this site. Configure your XML-RPC client using the information below. All methods on the server require that you give your user login and password (MD5 encoded) as strings in the first two parameters. At this time, there are three methods configured on the server (see samples below): hpe.getSource : retrieve the meta data AND list of news items for a given source. To find an ID for a source, use the source browsing page. hpe.getSourceInfo : retrieve the meta data for a given source. hpe.getSourceItems : retrieve the list of news items for a given source. hpe.searchSources : search for sources which contain a string in their name. hpe.createUser : creates a new user. This site uses the PHP implementation of XML-RPC client and server by useFull Inc. To test the output, use this page.

Host	www.newsisfree.com
Port	80
Path	/RPC

This RPC interface is part Premium Export Service (if you've just opened an account, it's available freely for the first 30 days, it will be disable if you don't sign up before). By using it, you aggree to comply with the Terms of Service.

> Get source data

Use methode "hpe.getSource" to retrieve for all data concerning a source (name, link and all news items) if you know it's ID.

First two parameters are your user id and password respectively;
Third is the (integer) id of the source you want;
Fourth (optional) is the maximum number of items you want to get (default is zero, i.e. all the items);
Fifth (optional) is a integer indicating how you want to get the description of the news items (if available):
- 0 means no description,
- 1 means normal description (if available)
- 2 prepends the source name and quotes the description
Sixth (optional) is the maximum length of the description field. If non zero, the description field is stripped of all HTML tags and cut to the appropriate length.

Sample code:


<?
/*

HPE - News Portal Engine
Copyright (C) 2000-2003 Mike Krus

This program is free software; it 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.  

READ LICENSE.TXT IN THE BASE DIRECTORY FOR INFORMATION 
ABOUT REDISTRIBUTING THIS SOURCE CODE

*/


// uncomment if used in stand alone
$c = new xmlrpc_client("/RPC", "www.newsisfree.com", 80); 

$f = new xmlrpcmsg('hpe.getSource',
                   array(new xmlrpcval($login),
                            new xmlrpcval($password),
                            new xmlrpcval("18", 'int') )
                  );

echo "<!--\n";
$r = $c->send($f);
if($r == 0)
    echo "<B>Error $c->errno: $c->errstring</B>\n";
$v = $r->value();
echo "-->\n";

if (!$r->faultCode())
{
    $data = xmlrpc_decode($v);
    print "Source name for siteid 18 is <A href=" . $data["info"] . "><B>" . $data["name"] . 
          "</B></A>. It has currently " . $data["itemcount"] . " news items.\n";
    if($data["itemcount"]) print "<BR>The first one is '<em>" . $data["items"][0]["title"] . 
                                 "</em>' (" . date("r", $data["items"][0]["date"]) . ")\n";
}
else
{
    print "Error Code: " . $r->faultCode() . " Reason '" .$r->faultString()."'<BR>";
}

?>

This method returns an array with all the information concerning the source. The named items are:

"title": the name of the source
"link": direct URL to the original source (this might not the page page which contained the news items, it usually is the home page of the site).
"description": slogan, moto, short description.
"info": direct URL to page on this site describing the source.
"ttl": the number of seconds for which the current data for this source will remain valid (i.e. the number of seconds to the next update).
"itemcount": number of news items for this source
"items": an array containing the news items. Each entry is itself an structure with the following named elements:
- "title": the title of the news item
- "link": link to the news item
- "description": short description, might be empty, not all sources provide it
- "date": the timestamp at which the news item was added to the database