File: API.txt

$Id: API.txt,v 1.1 2001/03/09 23:14:34 sandipb Exp $ 

CLASS SlashHeadlines
=====================

Constructor takes no arguments.

Other functions intended for public use are:

1. function set_local_file($f)
2. function set_url($u)
3. function set_cache($docache)
4. function set_image_prefix($prefix)
5. function set_update_interval($intervalsecs)
6. function update()
7. function get_last_update()
8. function get_num_stories()

public member variables are:

$stories : Array of SlashStory

CLASS SlashStory
=================


public variables are:

 1. title : Title of the story
 2. url   : Full URL of the article
 3. time  : Time the article was posted
 4. author: The name of the author of the article
 5. department: The name of the pseudo-department which posted this
                article
 6. topic: The broad topic under which the article lies.
 7. comments: The number of comments the article has received
 8. section: The section of slashdot in which this article lies
 9. image: The full URL of the image file associated with this article


--------------------------------------------------------------------- 

1. function set_local_file($f)

   Description:
      Sets the file name into which the current headlines is going to
      be cached.

   Parameters:
      $f = local cache file of the headlines. Make sure you have write
           permissions to this file! Default is "slashdot.dat"

   Returns:
      nothing.

------------------------------------------------------------------------

2. function set_url($u)

   Description:
      Set the url from which Slashdot XML compliant headlines have to be
      leeched.

   Parameters:
      $u = URL of the headlines XML file. Default is
           "http://www.slashdot.org/slashdot.xml". 

   Returns:
      Nothing.
-------------------------------------------------------------------------

3. function set_cache($docache)

   Description: 
      Set headlines caching on and off. Headlines are cached
      to a local file by default. This might be a security
      risk, or you might not have write permission for the
      cache file. So either you can set the cache file path
      to somewhere more appropriate using set_local_file() 
      or you can turn caching off using this function. Be
      aware that turning the cache off would cause the
      Slashdot Headlines to be fetched from the Slashdot.org
      website EVERYTIME! So if your site has heavy traffic,
      the Slashdot folks can get really pissed! Respecting
      the request from these folks I have set the update
      interval to half an hour, you can change it to your
      requirements using set_update_interval().

   Parameters:
      $docache = Set to 0 to turn caching off and 1 to turn on
                 caching. Caching is turned on by default.

   Returns:
      Nothing.
      
-------------------------------------------------------------------------

4. function set_image_prefix($prefix)

   Description: 
      Sets the image location of Slashdot images. The Slashdot image
      locations are NOT part of the headlines XML file - only the
      image names are. To get the actual url of the images, the URL of
      the image directory has to be prefixed to the image name.

   Parameters:
      $prefix = The URL of the image directory that has to be prefixed to the
                image  name. The default is "http://images.slashdot.org/topics/"
		which is the currently used path. You need not change this
                unless you are planning the fetch the images from elsewhere.
   Returns:
      Nothing.
      
-------------------------------------------------------------------------

5. function set_update_interval()

   Description: 
      Sets the time interval after which the cache has to be
      updated. Note, that the cache wil be updated only at the first
      request after the interval time.

   Parameters:
      The update interval in seconds.  Default is 30*60(half an
      hour). See description of function set_cache() for more details.

   Returns:
      Nothing.

-------------------------------------------------------------------------

6. function update()

   Description: 
     Call this to update headlines intelligently. If caching
     is on, it reads in the cache file, and checks the date of
     update. If required it fetches fresh headlines and updates
     cache. At the end of this program, the stories are available for
     retreival.

   Parameters:
     Nothing.

   Returns:
     0 for failure, 1 for success.
      
-------------------------------------------------------------------------

7. function get_last_update()

   Description:
      Returns the last time this cache was updated.

   Parameters:
      Nothing.

   Returns:
      String having the formatted update time.
-------------------------------------------------------------------------

8. function get_num_stories()

   Description:
     Returns the number of stories extracted from the last update.

   Parameters:
     None.

   Returns: 
     Number of stories available for retreival.
-------------------------------------------------------------------------