MDL-50537 mod_chat: New WS mod_chat_get_chats_by_courses
[moodle.git] / mod / chat / classes / external.php
index 26204d6..311c2a0 100644 (file)
@@ -493,4 +493,134 @@ class mod_chat_external extends external_api {
         );
     }
 
+    /**
+     * Describes the parameters for get_chats_by_courses.
+     *
+     * @return external_external_function_parameters
+     * @since Moodle 3.0
+     */
+    public static function get_chats_by_courses_parameters() {
+        return new external_function_parameters (
+            array(
+                'courseids' => new external_multiple_structure(
+                    new external_value(PARAM_INT, 'course id'),
+                    'Array of course ids', VALUE_DEFAULT, array()
+                ),
+            )
+        );
+    }
+    /**
+     * Returns a list of chats in a provided list of courses,
+     * if no list is provided all chats that the user can view will be returned.
+     *
+     * @param array $courseids the course ids
+     * @return array of chats details
+     * @since Moodle 3.0
+     */
+    public static function get_chats_by_courses($courseids = array()) {
+        global $CFG;
+        $params = self::validate_parameters(self::get_chats_by_courses_parameters(), array('courseids' => $courseids));
+        $warnings = array();
+        if (!empty($params['courseids'])) {
+            $courses = array();
+            $courseids = $params['courseids'];
+        } else {
+            $courses = enrol_get_my_courses();
+            $courseids = array_keys($courses);
+        }
+        // Array to store the chats to return.
+        $arrchats = array();
+        // Ensure there are courseids to loop through.
+        if (!empty($courseids)) {
+            // Array of the courses we are going to retrieve the chats from.
+            $arraycourses = array();
+            // Go through the courseids.
+            foreach ($courseids as $cid) {
+                // Check the user can function in this context.
+                try {
+                    $context = context_course::instance($cid);
+                    self::validate_context($context);
+                    // Check if this course was already loaded (by enrol_get_my_courses).
+                    if (!isset($courses[$cid])) {
+                        $courses[$cid] = get_course($cid);
+                    }
+                    $arraycourses[$cid] = $courses[$cid];
+                } catch (Exception $e) {
+                    $warnings[] = array(
+                        'item' => 'course',
+                        'itemid' => $cid,
+                        'warningcode' => '1',
+                        'message' => 'No access rights in course context '.$e->getMessage()
+                    );
+                }
+            }
+            // Get the chats in this course, this function checks users visibility permissions.
+            // We can avoid then additional validate_context calls.
+            $chats = get_all_instances_in_courses("chat", $arraycourses);
+            foreach ($chats as $chat) {
+                $chatcontext = context_module::instance($chat->coursemodule);
+                // Entry to return.
+                $chatdetails = array();
+                // First, we return information that any user can see in the web interface.
+                $chatdetails['id'] = $chat->id;
+                $chatdetails['coursemodule']      = $chat->coursemodule;
+                $chatdetails['course']            = $chat->course;
+                $chatdetails['name']              = $chat->name;
+                // Format intro.
+                list($chatdetails['intro'], $chatdetails['introformat']) =
+                    external_format_text($chat->intro, $chat->introformat,
+                                            $chatcontext->id, 'mod_chat', 'intro', null);
+                if (has_capability('moodle/course:manageactivities', $chatcontext)) {
+                    $chatdetails['keepdays']      = $chat->keepdays;
+                    $chatdetails['studentlogs']   = $chat->studentlogs;
+                    $chatdetails['chattime']      = $chat->chattime;
+                    $chatdetails['schedule']      = $chat->schedule;
+                    $chatdetails['timemodified']  = $chat->timemodified;
+                    $chatdetails['section']       = $chat->section;
+                    $chatdetails['visible']       = $chat->visible;
+                    $chatdetails['groupmode']     = $chat->groupmode;
+                    $chatdetails['groupingid']    = $chat->groupingid;
+                }
+                $arrchats[] = $chatdetails;
+            }
+        }
+        $result = array();
+        $result['chats'] = $arrchats;
+        $result['warnings'] = $warnings;
+        return $result;
+    }
+    /**
+     * Describes the get_chats_by_courses return value.
+     *
+     * @return external_single_structure
+     * @since Moodle 3.0
+     */
+    public static function get_chats_by_courses_returns() {
+        return new external_single_structure(
+            array(
+                'chats' => new external_multiple_structure(
+                    new external_single_structure(
+                        array(
+                            'id' => new external_value(PARAM_INT, 'Chat id'),
+                            'coursemodule' => new external_value(PARAM_INT, 'Course module id'),
+                            'course' => new external_value(PARAM_TEXT, 'Course id'),
+                            'name' => new external_value(PARAM_TEXT, 'Chat name'),
+                            'intro' => new external_value(PARAM_RAW, 'The Chat intro'),
+                            'introformat' => new external_format_value('intro'),
+                            'keepdays' => new external_value(PARAM_INT, 'keep days', VALUE_OPTIONAL),
+                            'studentlogs' => new external_value(PARAM_INT, 'student logs visible to everyone', VALUE_OPTIONAL),
+                            'chattime' => new external_value(PARAM_RAW, 'chat time', VALUE_OPTIONAL),
+                            'schedule' => new external_value(PARAM_INT, 'schedule type', VALUE_OPTIONAL),
+                            'timemodified' => new external_value(PARAM_RAW, 'time of last modification', VALUE_OPTIONAL),
+                            'section' => new external_value(PARAM_INT, 'course section id', VALUE_OPTIONAL),
+                            'visible' => new external_value(PARAM_BOOL, 'visible', VALUE_OPTIONAL),
+                            'groupmode' => new external_value(PARAM_INT, 'group mode', VALUE_OPTIONAL),
+                            'groupingid' => new external_value(PARAM_INT, 'group id', VALUE_OPTIONAL),
+                        ), 'Chats'
+                    )
+                ),
+                'warnings' => new external_warnings(),
+            )
+        );
+    }
 }