<?php
    /**
     * 
     * SWX Identi.ca API by Folkert Hielema
     * 
     * You can call this API using SWX, Amfphp, JSON and XML-RPC.
     * 
     * @author    Folkert Hielema
     * @copyright    2008 Folkert Hielema All Rights Reserved. 
     * @link     http://tjunar.com
     * @link     http://swxformat.org
     * @link    mailto://nederflash@gmail.com
     * 
    **/
    
    // Require base service class
    require_once("../BaseService.php");

    /**
     * SWX Identi.ca API by Folkert Hielema. You can call this API using SWX, Amfphp, JSON and XML-RPC.
    **/
    class Identica extends BaseService
    {
        //////////////////////////////////////////////////////////////////////////////////////////
        //
        // Official Identi.ca API methods: These implement a spinoff from the official twitter API.
        // See http://groups.google.com/group/twitter-development-talk/web/api-documentation
        // for the full official documentation.
        //
        //////////////////////////////////////////////////////////////////////////////////////////
        
        //
        // Status methods.
        //
        
        /**
         * Returns the 20 most recent statuses from non-protected users who have set a custom user icon.  Does not require authentication.
         * @return Array of statuses.
         * @author Folkert Hielema
         **/
        function publicTimeline()
        {
            $url = 'identi.ca/api/statuses/public_timeline.json';

            $response = $this->_jsonCall($url, NULL, 'GET');
            
            return $response;
        }
        
        /**
         * Returns the 20 most recent statuses posted in the last 24 hours from the authenticating user and that user's friends.  It's also possible to request another user's friends_timeline via the id parameter.
         * 
         * @param    Your username.
         * @param    Your password.
         * @param    (optional)    ID or screen name of the user for whom to return the friends_timeline.
         * @param     (optional) The number of the page you want
         *
         * @return Array of statuses.
         * @author Folkert Hielema
         **/
        function friendsTimeline($user, $pass, $id = NULL, $count = 50, $page = 0)
        {
            $url = 'identi.ca/api/statuses/friends_timeline.json';
            
            $vars = array('id' => $id, 'count' => $count, 'page' => $page);
            
            $response = $this->_jsonCall($url, $vars, 'GET', $user, $pass);
            
            return $response;
        }
        
        /**
         * Returns the 20 most recent statuses posted in the last 24 hours from the authenticating user.  It's also possible to request another user's timeline via the id parameter below.
         * 
         *
         * @return 20 most recent statuses.
         * @author Folkert Hielema
         **/
        function userTimeline($user, $pass, $id = NULL, $count = 50)
        {
            $url = 'identi.ca/api/statuses/user_timeline.json';
            
            $vars = array('id' => $id, 'count' => $count);
            
            $response = $this->_jsonCall($url, $vars, 'GET', $user, $pass);
            
            return $response;
        }
        
        /**
         * Returns a single status, specified by the id parameter below.  The status's author will be returned inline.
         * 
         * @param The numerical ID of the status you're trying to retrieve. 
         *
         * @return A single status.
         * @author Folkert Hielema
         **/
        function show($id)
        {
            $url = "identi.ca/api/statuses/show/$id.json";
            
            $response = $this->_jsonCall($url, NULL, 'GET');
            
            return $response;
        }

        /**
         * Posts a identi.ca update.
         *
         * @param (str) update message
         * @param (str) Your user name
         * @param (str) Your password
         * @param (optional, str) Source string. If enabled by Twitter, this will appear in the "from" section of the update.  
         * 
         * @return     (array)    Success/failure message.
         * 
         * @author     Folkert Hielema
         **/
        function update($update, $user, $pass, $source = NULL, $reply_id = NULL)
        {
            $url = 'identi.ca/api/statuses/update.json';
            $args = array('status' => $update, 'in_reply_to_status_id' => $reply_id);
            
            if ($source != NULL) 
            {
                $args['source'] = $source;                    
            }
            
            $response = $this->_jsonCall($url, $args, 'POST', $user, $pass);
            
            return $response;
        }
        
        /**
         * Returns the 20 most recent replies (status updates prefixed with @username posted by users who are friends with the user being replied to) to the authenticating user.  Replies are only available to the authenticating user; you can not request a list of replies to another user whether public or protected.
         * 
         * @param (str) Your user name
         * @param (str) Your password
         * @param (optional, int) Page number
         *
         * @return 20 most recent replies
         * @author Folkert Hielema
         **/
        function replies($user, $pass, $page = NULL)
        {
            $url = 'identi.ca/api/statuses/replies.json';
            $args = array('page' => $page);
            
            $response = $this->_jsonCall($url, $args, 'POST', $user, $pass);
            
            return $response;            
        }
        
        
            
        //
        // User methods.
        //

        /**
         * Gets friends for the passed user.
         *
         * @param    (str) Username.
         * @param    (str) Password.
         * @param    (optional) The ID or screen name of a user
         *
         * @return     (array)    List of friends.
         * @author Folkert Hielema
         **/
        function friends($user, $pass, $id = NULL, $page = 1)
        {
            if($id !== NULL)
                $url = "identi.ca/api/statuses/friends/$id.json";
            else
                $url = "identi.ca/api/statuses/friends/$user.json";
            
            $vars = array('page' => $page);
            
            $response = $this->_jsonCall($url,  $vars, 'GET', $user, $pass);
            return $response;
        }
        
        /**
         * Gets followers for authenticated user.
         * 
         * @param    (str) Your username.
         * @param    (str) Your password.
         * 
         * @return (array) List of followers.
         * @author Folkert Hielema
         **/
        function followers($user, $pass)
        {
            $url = 'identi.ca/api/statuses/followers.json';
            
            $response = $this->_jsonCall($url, NULL, 'GET', $user, $pass);
            
            return $response;    
        }
        
        

        //
        // Friendship methods.
        //
        
        /**
         * Befriends the user specified in the ID parameter as the authenticating user. Returns the befriended user in the requested format when successful. Returns a string describing the failure condition when unsuccessful.
         * 
         * @param (str) The ID or screen name of the user to befriend.
         * @param (str) Your username
         * @param (str) Your password
         *
         * @return Befriended user or error string.
         * @author Folkert Hielema
         **/
        function friendshipCreate($id, $user, $pass)
        {
            $url = "identi.ca/api/friendships/create/$id.json";

            $response = $this->_jsonCall($url, NULL, 'POST', $user, $pass);
            
            return $response;
        }
        
        /**
         * Discontinues friendship with the user specified in the ID parameter as the authenticating user.  Returns the un-friended user in the requested format when successful.  Returns a string describing the failure condition when unsuccessful.
         * 
         * @param (str) The ID or screen name of the user with whom to discontinue friendship.
         * @param (str) Your username
         * @param (str) Your password
         *
         * @return Un-friended user or error string.
         * @author Folkert Hielema
         **/
        function friendshipDestroy($id, $user, $pass)
        {
            $url = "identi.ca/api/friendships/destroy/$id.json";

            $response = $this->_jsonCall($url, NULL, 'POST', $user, $pass);
            
            return $response;
        }        
        
        /**
         * Test if a friendShip exists between two users
         *
         * @param (str) Your username
         * @param (str) Your password
         * @param (str) The ID or screen_name of the first user to test friendship for
         * @param (str) The ID or screen_name of the second user to test friendship for
         * @author Folkert Hielema
         **/
        function friendshipExists($user, $pass, $user_a, $user_b)
        {
            $url = "identi.ca/api/friendships/exists.json";
            $args = array('user_a'=>$user_a, 'user_b'=>$user_b);
            
            $response = $this->_jsonCall($url, $args, 'GET', $user, $pass);
            return $response;
        }
         
        //
        // Account methods.
        //
        
        /**
         * Returns an HTTP 200 OK response code and a format-specific response if authentication was successful.  Use this method to test if supplied user credentials are valid with minimal overhead.
         *
         * @return authorized = "true" on success. null on failure.
         * @author Folkert Hielema for Identi.ca/Aral Balkan for Twitter API
         **/
        function verifyCredentials($user, $pass)
        {
            $url = 'identi.ca/api/account/verify_credentials.json';
            
            $response = $this->_jsonCall($url, NULL, 'GET', $user, $pass);
            
            return $response;
        }
        
        
        
        // Help methods
        
        /**
         *    Returns the string "ok" in requested format with a 200 OK HTTP status code
         */
        function test()
        {
            $url = "identi.ca/api/help/test.json";
            $response = $this->_jsonCall($url, NULL, 'GET');
            return $response;
        }
    }
?>