MDL-50557 mod_scorm: New WS mod_scorm_get_scorm_sco_tracks
[moodle.git] / mod / scorm / classes / external.php
index cb0d1c1..b1da28a 100644 (file)
@@ -490,4 +490,97 @@ class mod_scorm_external extends external_api {
             )
         );
     }
+
+    /**
+     * Describes the parameters for get_scorms_by_courses.
+     *
+     * @return external_function_parameters
+     * @since Moodle 3.0
+     */
+    public static function get_scorm_sco_tracks_parameters() {
+        return new external_function_parameters(
+            array(
+                'scoid' => new external_value(PARAM_INT, 'sco id'),
+                'userid' => new external_value(PARAM_INT, 'user id'),
+                'attempt' => new external_value(PARAM_INT, 'attempt number (0 for last attempt)', VALUE_DEFAULT, 0)
+            )
+        );
+    }
+
+    /**
+     * Retrieves SCO tracking data for the given user id and attempt number
+     *
+     * @param int $scoid the sco id
+     * @param int $userid the user id
+     * @param int $attempt the attempt number
+     * @return array warnings and the scoes data
+     * @since Moodle 3.0
+     */
+    public static function get_scorm_sco_tracks($scoid, $userid, $attempt = 0) {
+        global $USER, $DB;
+
+        $params = self::validate_parameters(self::get_scorm_sco_tracks_parameters(),
+                                            array('scoid' => $scoid, 'userid' => $userid, 'attempt' => $attempt));
+
+        $data = array();
+        $warnings = array();
+
+        $sco = scorm_get_sco($params['scoid'], SCO_ONLY);
+        if (!$sco) {
+            throw new moodle_exception('cannotfindsco', 'scorm');
+        }
+
+        $scorm = $DB->get_record('scorm', array('id' => $sco->scorm), '*', MUST_EXIST);
+        $cm = get_coursemodule_from_instance('scorm', $scorm->id);
+
+        $context = context_module::instance($cm->id);
+        self::validate_context($context);
+
+        // Validate the user obtaining the context, it will fail if the user doesn't exists or have been deleted.
+        context_user::instance($params['userid']);
+
+        // Extra checks so only users with permissions can view other users attempts.
+        if ($USER->id != $params['userid']) {
+            require_capability('mod/scorm:viewreport', $context);
+        }
+
+        scorm_require_available($scorm, true, $context);
+
+        if ($tracks = scorm_get_tracks($sco->id, $params['userid'], $params['attempt'])) {
+            foreach ($tracks as $element => $value) {
+                $data[] = array(
+                    'element' => $element,
+                    'value' => $value,
+                );
+            }
+        }
+
+        $result = array();
+        $result['data'] = $data;
+        $result['warnings'] = $warnings;
+        return $result;
+    }
+
+    /**
+     * Describes the get_scorm_sco_tracks return value.
+     *
+     * @return external_single_structure
+     * @since Moodle 3.0
+     */
+    public static function get_scorm_sco_tracks_returns() {
+
+        return new external_single_structure(
+            array(
+                'data' => new external_multiple_structure(
+                    new external_single_structure(
+                        array(
+                            'element' => new external_value(PARAM_RAW, 'element name'),
+                            'value' => new external_value(PARAM_RAW, 'element value')
+                        ), 'SCO data'
+                    )
+                ),
+                'warnings' => new external_warnings(),
+            )
+        );
+    }
 }