Source for file controller.php

Documentation is available at controller.php

  1. <?php
  2.     // This file is part of the Sloodle project (www.sloodle.org)
  3.     
  4.     /**
  5.     * This file defines the Sloodle Controller module sub-type.
  6.     *
  7.     * @package sloodle
  8.     * @copyright Copyright (c) 2008 Sloodle (various contributors)
  9.     * @license http://www.gnu.org/licenses/gpl-3.0.html GNU GPL v3
  10.     *
  11.     * @contributor Peter R. Bloomfield
  12.     */
  13.     
  14.     
  15.     /** General Sloodle functionality. */
  16.     require_once(SLOODLE_LIBROOT.'/general.php');
  17.     /** The active object structure. */
  18.     require_once(SLOODLE_LIBROOT.'/active_object.php');
  19.     
  20.     
  21.     /**
  22.     * Represents a Sloodle Controller, including data such as prim password.
  23.     * @package sloodle
  24.     */
  25.     class SloodleController
  26.     {
  27.     // DATA //
  28.     
  29.         /**
  30.         * Internal for Moodle only - course module instance.
  31.         * Corresponds to one record from the Moodle 'course_modules' table.
  32.         * @var object 
  33.         * @access private
  34.         */
  35.         var $cm = null;
  36.     
  37.         /**
  38.         * Internal only - Sloodle module instance database object.
  39.         * Corresponds to one record from the Moodle 'sloodle' table.
  40.         * @var object 
  41.         * @access private
  42.         */
  43.         var $sloodle_module_instance = null;
  44.         
  45.         /**
  46.         * Internal only - Sloodle Controller instance database object.
  47.         * Corresponds to one record from the Moodle 'sloodle_controller' table.
  48.         * @var object 
  49.         * @access private
  50.         */
  51.         var $sloodle_controller_instance = null;
  52.                 
  53.         
  54.     // FUNCTIONS //
  55.     
  56.         /**
  57.         * Constructor
  58.         */
  59.         function SloodleController()
  60.         {
  61.         }
  62.         
  63.         
  64.         /**
  65.         * Loads data from the database.
  66.         * Note: even if the function fails, it may still have overwritten some or all existing data in the object.
  67.         * @param mixed $id The site-wide unique identifier for all modules. Type depends on VLE. On Moodle, it is an integer course module identifier ('id' field of 'course_modules' table)
  68.         * @return bool True if successful, or false otherwise
  69.         */
  70.         function load($id)
  71.         {
  72.             // Make sure the ID is valid
  73.             $id = (int)$id;
  74.             if ($id <= 0) return false;
  75.             
  76.             // Fetch the course module data
  77.             if (!($this->cm = get_coursemodule_from_id('sloodle', $id))) {
  78.                 sloodle_debug("Failed to load controler course module.<br>");
  79.                 return false;
  80.             }
  81.             
  82.             // Load from the primary table: Sloodle instance
  83.             if (!($this->sloodle_module_instance = get_record('sloodle', 'id', $this->cm->instance))) {
  84.                 sloodle_debug("Failed to load controller Sloodle module instance.<br>");
  85.                 return false;
  86.             }
  87.             // Check that it is the correct type
  88.             if ($this->sloodle_module_instance->type != SLOODLE_TYPE_CTRL) {
  89.                 sloodle_debug("Loaded Sloodle module instance is not a controller.<br>");
  90.                 return false;
  91.             }
  92.             
  93.             // Load from the secondary table: Controller instance
  94.             if (!($this->sloodle_controller_instance = get_record('sloodle_controller', 'sloodleid', $this->cm->instance))) {
  95.                 sloodle_debug("Failed to load controller secondary data table.<br>");
  96.                 return false;
  97.             }
  98.             
  99.             return true;
  100.         }
  101.         
  102.         /**
  103.         * Updates the currently loaded entry in the database.
  104.         * Note: the data *must* have been previously loaded using {@link load_from_db()}.
  105.         * This function cannot be used to create new entries.
  106.         * @return bool True if successful, or false otherwise
  107.         */
  108.         function write()
  109.         {
  110.             // Make sure we have all the necessary data
  111.             if (empty($this->sloodle_module_instance) || empty($this->sloodle_controller_instance)) return false;
  112.             // Attempt to update the primary table
  113.             $this->sloodle_module_instance->timemodified = time();
  114.             if (!update_record('sloodle', $this->sloodle_module_instance)) return false;
  115.             // Attempt to update the secondary table
  116.             if (!update_record('sloodle_controller', $this->sloodle_controller_instance)) return false;
  117.             
  118.             // Everything seems OK
  119.             return true;
  120.         }
  121.         
  122.         
  123.     // ACCESSORS //
  124.     
  125.         /**
  126.         * Determines whether or not this controller is loaded.
  127.         * @return bool 
  128.         */
  129.         function is_loaded()
  130.         {
  131.             if (empty($this->cm) || empty($this->sloodle_module_instance) || empty($this->sloodle_controller_instance)) return false;
  132.             return true;
  133.         }
  134.     
  135.         /**
  136.         * Gets the site-wide unique identifier for this module.
  137.         * @return mixed Identifier. Type is dependent on VLE. On Moodle, it is an integer course module identifier.
  138.         */
  139.         function get_id()
  140.         {
  141.             return $this->cm->id;
  142.         }
  143.         
  144.         /**
  145.         * Gets the identifier for controller (unique among all Sloodle controlers - may be the same as {@link get_id()} in some environments
  146.         * @return mixed Identifier. Type is dependent on VLE. On Moodle, it is an integer relating to the 'id' field of the 'sloodle_controller' table
  147.         */
  148.         function get_controller_id()
  149.         {
  150.             return $this->sloodle_controller_instance->id;
  151.         }
  152.     
  153.         /**
  154.         * Gets the name of this controller.
  155.         * @return string The name of this controller
  156.         */
  157.         function get_name()
  158.         {
  159.             return $this->sloodle_module_instance->name;
  160.         }
  161.         
  162.         /**
  163.         * Sets the name of this controller.
  164.         * @param string $name The new name for this controller - ignored if empty
  165.         * @return void 
  166.         */
  167.         function set_name($name)
  168.         {
  169.             if (!empty($name)) $this->sloodle_module_instance->name = $name;
  170.         }
  171.         
  172.         /**
  173.         * Gets the intro description of this controller.
  174.         * @return string The intro description of this controller
  175.         */
  176.         function get_intro()
  177.         {
  178.             return $this->sloodle_module_instance->intro;
  179.         }
  180.         
  181.         /**
  182.         * Sets the intro description of this controller.
  183.         * @param string $intro The new intro for this controller - ignored if empty
  184.         * @return void 
  185.         */
  186.         function set_intro($intro)
  187.         {
  188.             if (!empty($intro)) $this->sloodle_module_instance->intro = $intro;
  189.         }
  190.         
  191.         /**
  192.         * Gets the identifier of the course this controller belongs to.
  193.         * @return mixed Course identifier. Type depends on VLE. (In Moodle, it will be an integer).
  194.         */
  195.         function get_course_id()
  196.         {
  197.             return (int)$this->sloodle_module_instance->course;
  198.         }
  199.         
  200.         /**
  201.         * Gets the time at which this controller was created.
  202.         * @return int Timestamp
  203.         */
  204.         function get_creation_time()
  205.         {
  206.             return $this->sloodle_module_instance->timecreated;
  207.         }
  208.         
  209.         /**
  210.         * Gets the time at which this controller was last modified.
  211.         * @return int Timestamp
  212.         */
  213.         function get_modification_time()
  214.         {
  215.             return $this->sloodle_module_instance->timemodified;
  216.         }
  217.         
  218.         /**
  219.         * Determines whether or not this controller is available (i.e. not hidden).
  220.         * Note: this is separate from being enabled or disabled.
  221.         * @return bool True if the controller is available.
  222.         */
  223.         function is_available()
  224.         {
  225.             return (bool)($this->cm->visible);
  226.         }
  227.         
  228.         /**
  229.         * Determines if this controller is enabled or not.
  230.         * @return bool True if the controller is enabled, or false otherwise.
  231.         */
  232.         function is_enabled()
  233.         {
  234.             return (bool)($this->sloodle_controller_instance->enabled);
  235.         }
  236.         
  237.         /**
  238.         * Enables this controller
  239.         * @return void 
  240.         */
  241.         function enable()
  242.         {
  243.             $this->sloodle_controller_instance->enabled = true;
  244.         }
  245.         
  246.         /**
  247.         * Disables this controller
  248.         * @return void 
  249.         */
  250.         function disable()
  251.         {
  252.             $this->sloodle_controller_instance->enabled = false;
  253.         }
  254.         
  255.         /**
  256.         * Gets the prim password of this controller.
  257.         * @return string The current prim password.
  258.         */
  259.         function get_password()
  260.         {
  261.             return $this->sloodle_controller_instance->password;
  262.         }
  263.         
  264.         /**
  265.         * Sets the prim password of this controller.
  266.         * Also checks for validity before storing.
  267.         * @param string $password The new prim password
  268.         * @return bool True if successfully stored, or false if the password is invalid
  269.         */
  270.         function set_password($password)
  271.         {
  272.             // Check validity
  273.             if (!sloodle_validate_prim_password($password)) return false;
  274.             // Store it
  275.             $this->sloodle_controller_instance->password = $password;
  276.             return true;
  277.         }
  278.  
  279.         
  280.         /**
  281.         * Registers a new active object (or renew an existing authorisation) with this controller.
  282.         * @param string $uuid The UUID of the object to be registered
  283.         * @param string $name Name of the object to be registered
  284.         * @param SloodleUser $user The user who is authorising the object
  285.         * @param string $password The password for the object
  286.         * @param string $type Type identifier of the object to be registered
  287.         * @param int $timestamp The timestamp of the object's registration, or null to use the current time.
  288.         * @return int|boolThe new authorisation ID if successful, or false if not
  289.         */
  290.         function register_object($uuid, $name, $user, $password, $type = '', $timestamp = null)
  291.         {
  292.             // Use the current timestamp if necessary
  293.             if ($timestamp == null) $timestamp = time();
  294.             // Extract the user ID, if available
  295.             $userid = 0;
  296.             if ($user->is_user_loaded()) $userid = $user->get_user_id();
  297.             
  298.             // Check to see if an entry already exists for this object
  299.             $entry = get_record('sloodle_active_object', 'uuid', $uuid);
  300.             if (!$entry) {
  301.                 // Create a new entry
  302.                 $entry = new stdClass();
  303.                 $entry->controllerid = $this->cm->id;
  304.                 $entry->uuid = $uuid;
  305.                 $entry->name = $name;
  306.                 $entry->userid = $userid;
  307.                 $entry->password = $password;
  308.                 $entry->type = $type;
  309.                 $entry->timeupdated = $timestamp;
  310.                 // Attempt to insert the entry
  311.                 $entry->id = insert_record('sloodle_active_object', $entry);
  312.                 if (!$entry->id) return false;
  313.                 
  314.             } else {
  315.                 // Update the existing entry
  316.                 $entry->controllerid = $this->cm->id;
  317.                 $entry->name = $name;
  318.                 $entry->userid = $userid;
  319.                 $entry->password = $password;
  320.                 $entry->type = $type;
  321.                 $entry->timeupdated = $timestamp;
  322.                 // Attempt to update the database
  323.                 if (!update_record('sloodle_active_object', $entry)) return false;
  324.             }
  325.             
  326.             return $entry->id;
  327.         }
  328.         
  329.         
  330.         /**
  331.         * Registers a new unauthorised object.
  332.         * (Can be called statically).
  333.         * Creates a new active object entry, not linked to any user or controller.
  334.         * @param string $uuid The UUID of the object to be registered
  335.         * @param string $name Name of the object to be registered
  336.         * @param string $password The password for the object
  337.         * @param string $type Type identifier of the object to be registered
  338.         * @param int $timestamp The timestamp of the object's registration, or null to use the current time.
  339.         * @return int|boolThe integer ID of the active object entry, or false if not
  340.         */
  341.         function register_unauth_object($uuid, $name, $password, $type = '', $timestamp = null)
  342.         {
  343.             // Use the current timestamp if necessary
  344.             if ($timestamp == null) $timestamp = time();
  345.             
  346.             // Check to see if an entry already exists for this object
  347.             $entry = get_record('sloodle_active_object', 'uuid', $uuid);
  348.             if (!$entry) {
  349.                 // Create a new entry
  350.                 $entry = new stdClass();
  351.                 $entry->controllerid = 0;
  352.                 $entry->uuid = $uuid;
  353.                 $entry->name = $name;
  354.                 $entry->userid = 0;
  355.                 $entry->password = $password;
  356.                 $entry->type = $type;
  357.                 $entry->timeupdated = $timestamp;
  358.                 // Attempt to insert the entry
  359.                 $entry->id = insert_record('sloodle_active_object', $entry);
  360.                 if (!$entry->id) return false;
  361.                 
  362.             } else {
  363.                 // Update the existing entry
  364.                 $entry->controllerid = 0;
  365.                 $entry->name = $name;
  366.                 $entry->password = $password;
  367.                 $entry->type = $type;
  368.                 $entry->userid = 0;
  369.                 $entry->timeupdated = $timestamp;
  370.                 // Attempt to update the database
  371.                 if (!update_record('sloodle_active_object', $entry)) return false;
  372.             }
  373.             
  374.             return $entry->id;
  375.         }
  376.         
  377.         /**
  378.         * Updates the type of a given active object to the specified type.
  379.         * @param string $uuid The UUID of the object being updated
  380.         * @param string $type Name of the new type identifier
  381.         * @return bool True if successful, or false if not
  382.         */
  383.         function update_object_type($uuid, $type)
  384.         {
  385.             // Attempt to find an entry for the object
  386.             $entry = get_record('sloodle_active_object', 'uuid', $uuid);
  387.             if (!$entry) return false;
  388.             // Update the type and time
  389.             $entry->type = $type;
  390.             $entry->timeupdated = time();
  391.             if (!update_record('sloodle_active_object', $entry)) return false;
  392.             return true;
  393.         }
  394.         
  395.         /**
  396.         * Authorises an otherwise unauthorised active object against the given user and the current controller.
  397.         * (NOTE: the object must previously have been registered using {@link register_object()}).
  398.         * <b>Must not be called statically.</b>
  399.         * @param string $uuid The UUID of the object being updated
  400.         * @param SloodleUser $user The user to authorise the object against
  401.         * @param string $type (Optional). Specifies the type to store for this object. Ignored if null.
  402.         * @return bool True if successful, or false if not
  403.         */
  404.         function authorise_object($uuid, $user, $type = null)
  405.         {
  406.             // Attempt to find an unauthorised entry for the object
  407.             $entry = get_record('sloodle_active_object', 'uuid', $uuid);
  408.             if (!$entry) return false;
  409.             // Update the controller, user and time
  410.             $entry->controllerid = $this->get_id();
  411.             $entry->userid = $user->get_user_id();
  412.             if (!empty($type)) $entry->type = $type;
  413.             $entry->timeupdated = time();
  414.             if (!update_record('sloodle_active_object', $entry)) return false;
  415.             return true;
  416.         }
  417.         
  418.         /**
  419.         * Checks if the specified object is authorised for this controller with the given password.
  420.         * @param string $uuid The UUID of the object to check
  421.         * @param string $password The password to check
  422.         * @return bool True if object is authorised, or false if not
  423.         */
  424.         function check_authorisation($uuid, $password)
  425.         {
  426.             // Attempt to find an entry for the object
  427.             $entry = get_record('sloodle_active_object', 'controllerid', $this->get_id(), 'uuid', $uuid);
  428.             if (!$entry) return false;
  429.             // Make sure we have the type data
  430.             if (empty($entry->type)) return false;
  431.             
  432.             // Verify the password
  433.             return ($password == $entry->password);
  434.         }
  435.         
  436.         /**
  437.         * Gets the ID of the user who authorised the specified object.
  438.         * @return mixed|boolReturns the user ID if successful, or FALSE if not
  439.         */
  440.         function get_authorizing_user($uuid)
  441.         {
  442.             // Attempt to find an entry for the object
  443.             $entry = get_record('sloodle_active_object', 'controllerid', $this->get_id(), 'uuid', $uuid);
  444.             if (!$entry) return false;
  445.             return (int)$entry->userid;
  446.         }
  447.         
  448.         
  449.         /**
  450.         * Removes an active object and all its related items.
  451.         * @param mixed $id If it is an integer, then it is treated as the active object ID. If a string, it is treated as the object UUID.
  452.         * @return void 
  453.         */
  454.         function remove_object($id)
  455.         {
  456.             // Check what type the ID is
  457.             if (is_string($id)) $entry = get_record('sloodle_active_object', 'uuid', $id);
  458.             else $entry = get_record('sloodle_active_object', 'id', (int)$id);
  459.             if (!$entry) return;
  460.             
  461.             // Delete all config entries and the object record itself
  462.             delete_records('sloodle_object_config', 'object', $entry->id);
  463.             delete_records('sloodle_active_object', 'id', $entry->id);
  464.         }
  465.         
  466.         /**
  467.         * Gets data about an active object.
  468.         * @param mixed $id If an integer, it is the ID of an active object. If it is a string it is the object's UUID.
  469.         * @return SloodleActiveObject|boolReturns false on failure
  470.         */
  471.         function get_object($id)
  472.         {
  473.             // Check what type the ID is
  474.             if (is_string($id)) $entry = get_record('sloodle_active_object', 'uuid', $id);
  475.             else $entry = get_record('sloodle_active_object', 'id', (int)$id);
  476.             if (!$entry) return false;
  477.             
  478.             // Create a dummy SloodleSession
  479.             $sloodle = new SloodleSession(false);
  480.             
  481.             // Construct a structure
  482.             $obj = new SloodleActiveObject();
  483.             $obj->uuid = $entry->uuid;
  484.             $obj->name = $entry->name;
  485.             $obj->password = $entry->password;
  486.             $obj->type = $entry->type;
  487.             
  488.             $obj->course = $sloodle->course;
  489.             $obj->course->load_by_controller($entry->controllerid);
  490.             
  491.             $obj->user = $sloodle->user;
  492.             if ($entry->id > 0) {
  493.                 $obj->user->load_user($entry->userid);
  494.                 $obj->user->load_linked_avatar();
  495.             }
  496.             
  497.             return $obj;
  498.         }
  499.         
  500.         /**
  501.         * Gets an array of object configuration settings.
  502.         * (Can be called statically).
  503.         * @param mixed $id If an integer, it is the ID of an active object. If it is a string it is the object's UUID.
  504.         * @return array Associative array of setting names to values. (Returns an empty array if unsuccessful.)
  505.         */
  506.         function get_object_configuration($id)
  507.         {
  508.             // Check what type the ID is and fetch the object
  509.             if (is_string($id)) $entry = get_record('sloodle_active_object', 'uuid', $id);
  510.             else $entry = get_record('sloodle_active_object', 'id', (int)$id);
  511.             if (!$entry) return array();
  512.             
  513.             // Fetch the values
  514.             $recs = get_records('sloodle_object_config', 'object', $entry->id);
  515.             if (!$recs) return false;
  516.             // Construct our associative array
  517.             $config = array();
  518.             foreach ($recs as $r) {
  519.                 $config[$r->name] = $r->value;
  520.             }
  521.             return $config;
  522.         }
  523.         
  524.         /**
  525.         * Updates the last active timer on an object.
  526.         * (Cannot be called statically... object must be authorised for this controller).
  527.         * @param mixed $id If an integer, it is the ID of an active object. If it is a string it is the object's UUID.
  528.         * @return bool True if successful, or false if not.
  529.         */
  530.         function ping_object($id)
  531.         {
  532.             // Check what type the ID is and fetch the object
  533.             if (is_string($id)) $entry = get_record('sloodle_active_object', 'controllerid', $this->get_id(), 'uuid', $id);
  534.             else $entry = get_record('sloodle_active_object', 'controllerid', $this->get_id(), 'id', (int)$id);
  535.             if (!$entry) return false;
  536.             
  537.             // Update the record
  538.             $entry->timeupdated = time();
  539.             return update_record('sloodle_active_object', $entry);
  540.         }
  541.         
  542.     }
  543.  
  544. ?>

Documentation generated on Mon, 16 Jun 2008 15:56:14 +0100 by phpDocumentor 1.4.0