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.             return true;
  227.         }
  228.         
  229.         /**
  230.         * Determines if this controller is enabled or not.
  231.         * @return bool True if the controller is enabled, or false otherwise.
  232.         */
  233.         function is_enabled()
  234.         {
  235.             return (bool)($this->sloodle_controller_instance->enabled);
  236.         }
  237.         
  238.         /**
  239.         * Enables this controller
  240.         * @return void 
  241.         */
  242.         function enable()
  243.         {
  244.             $this->sloodle_controller_instance->enabled = true;
  245.         }
  246.         
  247.         /**
  248.         * Disables this controller
  249.         * @return void 
  250.         */
  251.         function disable()
  252.         {
  253.             $this->sloodle_controller_instance->enabled = false;
  254.         }
  255.         
  256.         /**
  257.         * Gets the prim password of this controller.
  258.         * @return string The current prim password.
  259.         */
  260.         function get_password()
  261.         {
  262.             return $this->sloodle_controller_instance->password;
  263.         }
  264.         
  265.         /**
  266.         * Sets the prim password of this controller.
  267.         * Also checks for validity before storing.
  268.         * @param string $password The new prim password
  269.         * @return bool True if successfully stored, or false if the password is invalid
  270.         */
  271.         function set_password($password)
  272.         {
  273.             // Check validity
  274.             if (!sloodle_validate_prim_password($password)) return false;
  275.             // Store it
  276.             $this->sloodle_controller_instance->password = $password;
  277.             return true;
  278.         }
  279.  
  280.         
  281.         /**
  282.         * Registers a new active object (or renew an existing authorisation) with this controller.
  283.         * @param string $uuid The UUID of the object to be registered
  284.         * @param string $name Name of the object to be registered
  285.         * @param SloodleUser $user The user who is authorising the object
  286.         * @param string $password The password for the object
  287.         * @param string $type Type identifier of the object to be registered
  288.         * @param int $timestamp The timestamp of the object's registration, or null to use the current time.
  289.         * @return int|boolThe new authorisation ID if successful, or false if not
  290.         */
  291.         function register_object($uuid, $name, $user, $password, $type = '', $timestamp = null)
  292.         {
  293.             // Use the current timestamp if necessary
  294.             if ($timestamp == null) $timestamp = time();
  295.             // Extract the user ID, if available
  296.             $userid = 0;
  297.             if ($user->is_user_loaded()) $userid = $user->get_user_id();
  298.             
  299.             // Check to see if an entry already exists for this object
  300.             $entry = get_record('sloodle_active_object', 'uuid', $uuid);
  301.             if (!$entry) {
  302.                 // Create a new entry
  303.                 $entry = new stdClass();
  304.                 $entry->controllerid = $this->cm->id;
  305.                 $entry->uuid = $uuid;
  306.                 $entry->name = $name;
  307.                 $entry->userid = $userid;
  308.                 $entry->password = $password;
  309.                 $entry->type = $type;
  310.                 $entry->timeupdated = $timestamp;
  311.                 // Attempt to insert the entry
  312.                 $entry->id = insert_record('sloodle_active_object', $entry);
  313.                 if (!$entry->id) return false;
  314.                 
  315.             } else {
  316.                 // Update the existing entry
  317.                 $entry->controllerid = $this->cm->id;
  318.                 $entry->name = $name;
  319.                 $entry->userid = $userid;
  320.                 $entry->password = $password;
  321.                 $entry->type = $type;
  322.                 $entry->timeupdated = $timestamp;
  323.                 // Attempt to update the database
  324.                 if (!update_record('sloodle_active_object', $entry)) return false;
  325.             }
  326.             
  327.             return $entry->id;
  328.         }
  329.         
  330.     /**
  331.     * Configures a registered object based on the defaults for its layout entry id
  332.     * @param int $authid The ID of the object as registered by register_object in the active_objects table
  333.      * @param int $layout_entry_id The ID of the layout entry corresponding to this object
  334.     *  NB The reverse of this process, where we create a layout entry config based on the active object,
  335.         *  ...is in the SloodleLayoutEntry class.
  336.     *  TODO: Would this be better there?
  337.     */
  338.     function configure_object_from_layout_entry($authid, $layout_entry_id) {
  339.  
  340.        $configs = get_records('sloodle_layout_entry_config','layout_entry',$layout_entry_id);
  341.        $ok = true;
  342.        if (count($configs) > 0) {
  343.           foreach($configs as $config) {
  344.              $config->id = null;
  345.              $config->object = $authid;
  346.              if (!insert_record('sloodle_object_config',$config)) {
  347.             $ok = false;
  348.              }
  349.           }
  350.        }
  351.        return $ok;
  352.  
  353.     }
  354.         
  355.     function configure_object_from_parent($authid, $parent_object) {
  356.  
  357.        // Fetch the UUID of the current object from the header
  358.        // ...then clone its config
  359.  
  360.            // Check to see if an entry already exists for this object
  361.            $parententry = get_record('sloodle_active_object', 'uuid', $parent_object);
  362. /*
  363.            if (!$parententry) {
  364.               return false;
  365.            }
  366. */
  367.  
  368.            $parentconfigs = get_records('sloodle_object_config','object',$parententry->id);
  369.            $ok = true;
  370.            if (count($parentconfigs) > 0) {
  371.               $clonedconfig = new stdClass();
  372.               foreach($parentconfigs as $config) {
  373.                  $clonedconfig->object = $authid;
  374.                  $clonedconfig->name = $config->name;
  375.                  $clonedconfig->value = $config->value;
  376.                  if (!insert_record('sloodle_object_config',$clonedconfig)) {
  377.                     $ok = false;
  378.                  }
  379.               }
  380.            }
  381.  
  382.            return $ok;
  383.  
  384.     }
  385.  
  386.         /**
  387.         * Registers a new unauthorised object.
  388.         * (Can be called statically).
  389.         * Creates a new active object entry, not linked to any user or controller.
  390.         * @param string $uuid The UUID of the object to be registered
  391.         * @param string $name Name of the object to be registered
  392.         * @param string $password The password for the object
  393.         * @param string $type Type identifier of the object to be registered
  394.         * @param int $timestamp The timestamp of the object's registration, or null to use the current time.
  395.         * @return int|boolThe integer ID of the active object entry, or false if not
  396.         */
  397.         function register_unauth_object($uuid, $name, $password, $type = '', $timestamp = null)
  398.         {
  399.             // Use the current timestamp if necessary
  400.             if ($timestamp == null) $timestamp = time();
  401.             
  402.             // Check to see if an entry already exists for this object
  403.             $entry = get_record('sloodle_active_object', 'uuid', $uuid);
  404.             if (!$entry) {
  405.                 // Create a new entry
  406.                 $entry = new stdClass();
  407.                 $entry->controllerid = 0;
  408.                 $entry->uuid = $uuid;
  409.                 $entry->name = $name;
  410.                 $entry->userid = 0;
  411.                 $entry->password = $password;
  412.                 $entry->type = $type;
  413.                 $entry->timeupdated = $timestamp;
  414.                 // Attempt to insert the entry
  415.                 $entry->id = insert_record('sloodle_active_object', $entry);
  416.                 if (!$entry->id) return false;
  417.                 
  418.             } else {
  419.                 // Update the existing entry
  420.                 $entry->controllerid = 0;
  421.                 $entry->name = $name;
  422.                 $entry->password = $password;
  423.                 $entry->type = $type;
  424.                 $entry->userid = 0;
  425.                 $entry->timeupdated = $timestamp;
  426.                 // Attempt to update the database
  427.                 if (!update_record('sloodle_active_object', $entry)) return false;
  428.             }
  429.             
  430.             return $entry->id;
  431.         }
  432.         
  433.         /**
  434.         * Updates the type of a given active object to the specified type.
  435.         * @param string $uuid The UUID of the object being updated
  436.         * @param string $type Name of the new type identifier
  437.         * @return bool True if successful, or false if not
  438.         */
  439.         function update_object_type($uuid, $type)
  440.         {
  441.             // Attempt to find an entry for the object
  442.             $entry = get_record('sloodle_active_object', 'uuid', $uuid);
  443.             if (!$entry) return false;
  444.             // Update the type and time
  445.             $entry->type = $type;
  446.             $entry->timeupdated = time();
  447.             if (!update_record('sloodle_active_object', $entry)) return false;
  448.             return true;
  449.         }
  450.         
  451.         /**
  452.         * Authorises an otherwise unauthorised active object against the given user and the current controller.
  453.         * (NOTE: the object must previously have been registered using {@link register_object()}).
  454.         * <b>Must not be called statically.</b>
  455.         * @param string $uuid The UUID of the object being updated
  456.         * @param SloodleUser $user The user to authorise the object against
  457.         * @param string $type (Optional). Specifies the type to store for this object. Ignored if null.
  458.         * @return bool True if successful, or false if not
  459.         */
  460.         function authorise_object($uuid, $user, $type = null)
  461.         {
  462.             // Attempt to find an unauthorised entry for the object
  463.             $entry = get_record('sloodle_active_object', 'uuid', $uuid);
  464.             if (!$entry) return false;
  465.             // Update the controller, user and time
  466.             $entry->controllerid = $this->get_id();
  467.             $entry->userid = $user->get_user_id();
  468.             if (!empty($type)) $entry->type = $type;
  469.             $entry->timeupdated = time();
  470.             if (!update_record('sloodle_active_object', $entry)) return false;
  471.             return true;
  472.         }
  473.         
  474.         /**
  475.         * Checks if the specified object is authorised for this controller with the given password.
  476.         * @param string $uuid The UUID of the object to check
  477.         * @param string $password The password to check
  478.         * @return bool True if object is authorised, or false if not
  479.         */
  480.         function check_authorisation($uuid, $password)
  481.         {
  482.             // Attempt to find an entry for the object
  483.             $entry = get_record('sloodle_active_object', 'controllerid', $this->get_id(), 'uuid', $uuid);
  484.             if (!$entry) return false;
  485.             // Make sure we have the type data
  486.  
  487.             // Edmund Edgar, 2009-01-31: 
  488.             // The type-checking is breaking the auto-configuration based on a profile.
  489.             // It should probably already have been filled in somewhere, so this is probably an auto-configuration bug.
  490.             // But we should probably be doing this check somewhere else, as it's not an authorization check.
  491.             // Maybe it needs its own error code?
  492.             //if (empty($entry->type)) return false;
  493.             
  494.             // Verify the password
  495.             return ($password == $entry->password);
  496.         }
  497.         
  498.         /**
  499.         * Gets the ID of the user who authorised the specified object.
  500.         * @return mixed|boolReturns the user ID if successful, or FALSE if not
  501.         */
  502.         function get_authorizing_user($uuid)
  503.         {
  504.             // Attempt to find an entry for the object
  505.             $entry = get_record('sloodle_active_object', 'controllerid', $this->get_id(), 'uuid', $uuid);
  506.             if (!$entry) return false;
  507.             return (int)$entry->userid;
  508.         }
  509.         
  510.         
  511.         /**
  512.         * Removes an active object and all its related items.
  513.         * @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.
  514.         * @return void 
  515.         */
  516.         function remove_object($id)
  517.         {
  518.             // Check what type the ID is
  519.             if (is_string($id)) $entry = get_record('sloodle_active_object', 'uuid', $id);
  520.             else $entry = get_record('sloodle_active_object', 'id', (int)$id);
  521.             if (!$entry) return;
  522.             
  523.             // Delete all config entries and the object record itself
  524.             delete_records('sloodle_object_config', 'object', $entry->id);
  525.             delete_records('sloodle_active_object', 'id', $entry->id);
  526.         }
  527.         
  528.         /**
  529.         * Gets data about an active object.
  530.         * @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.
  531.         * @return SloodleActiveObject|boolReturns false on failure
  532.         */
  533.         function get_object($id)
  534.         {
  535.             // Check what type the ID is
  536.             if (is_string($id)) $entry = get_record('sloodle_active_object', 'uuid', $id);
  537.             else $entry = get_record('sloodle_active_object', 'id', (int)$id);
  538.             if (!$entry) return false;
  539.             
  540.             // Create a dummy SloodleSession
  541.             $sloodle = new SloodleSession(false);
  542.             
  543.             // Construct a structure
  544.             $obj = new SloodleActiveObject();
  545.             $obj->uuid = $entry->uuid;
  546.             $obj->name = $entry->name;
  547.             $obj->password = $entry->password;
  548.             $obj->type = $entry->type;
  549.             
  550.             $obj->course = $sloodle->course;
  551.             $obj->course->load_by_controller($entry->controllerid);
  552.             
  553.             $obj->user = $sloodle->user;
  554.             if ($entry->id > 0) {
  555.                 $obj->user->load_user($entry->userid);
  556.                 $obj->user->load_linked_avatar();
  557.             }
  558.             
  559.             return $obj;
  560.         }
  561.         
  562.         /**
  563.         * Gets an array of object configuration settings.
  564.         * (Can be called statically).
  565.         * @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.
  566.         * @return array Associative array of setting names to values. (Returns an empty array if unsuccessful.)
  567.         */
  568.         function get_object_configuration($id)
  569.         {
  570.             // If the ID is empty, then we have no configuration settings to get
  571.             if (empty($id)) return array();
  572.         
  573.             // Check what type the ID is and fetch the object
  574.             if (is_string($id)) $entry = get_record('sloodle_active_object', 'uuid', $id);
  575.             else $entry = get_record('sloodle_active_object', 'id', (int)$id);
  576.             if (!$entry) return array();
  577.             
  578.             // Fetch the values
  579.             $recs = get_records('sloodle_object_config', 'object', $entry->id);
  580.             if (!$recs) return false;
  581.             // Construct our associative array
  582.             $config = array();
  583.             foreach ($recs as $r) {
  584.                 $config[$r->name] = $r->value;
  585.             }
  586.             return $config;
  587.         }
  588.         
  589.         /**
  590.         * Updates the last active timer on an object.
  591.         * (Cannot be called statically... object must be authorised for this controller).
  592.         * @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.
  593.         * @return bool True if successful, or false if not.
  594.         */
  595.         function ping_object($id)
  596.         {
  597.             // Check what type the ID is and fetch the object
  598.             if (is_string($id)) $entry = get_record('sloodle_active_object', 'controllerid', $this->get_id(), 'uuid', $id);
  599.             else $entry = get_record('sloodle_active_object', 'controllerid', $this->get_id(), 'id', (int)$id);
  600.             if (!$entry) return false;
  601.             
  602.             // Update the record
  603.             $entry->timeupdated = time();
  604.             return update_record('sloodle_active_object', $entry);
  605.         }
  606.         
  607.     }
  608.  
  609. ?>

Documentation generated on Fri, 17 Jul 2009 11:01:07 +0100 by phpDocumentor 1.4.0