externallib.php

   1 <?php
   2 // This file is part of Moodle - http://moodle.org/
   3 //
   4 // Moodle is free software: you can redistribute it and/or modify
   5 // it under the terms of the GNU General Public License as published by
   6 // the Free Software Foundation, either version 3 of the License, or
   7 // (at your option) any later version.
   8 //
   9 // Moodle is distributed in the hope that it will be useful,
  10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12 // GNU General Public License for more details.
  13 //
  14 // You should have received a copy of the GNU General Public License
  15 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  16 /**
  17  * Externallib.php file for attendance plugin.
  18  *
  19  * @package    mod_attendance
  20  * @copyright  2015 Caio Bressan Doneda
  21  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  22  */
  23
  24 defined('MOODLE_INTERNAL') || die;
  25
  26 require_once("$CFG->libdir/externallib.php");
  27 require_once(dirname(__FILE__).'/classes/attendance_webservices_handler.php');
  28
  29 /**
  30  * Class mod_wsattendance_external
  31  * @copyright  2015 Caio Bressan Doneda
  32  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  33  */
  34 class mod_wsattendance_external extends external_api {
  35
  36     /**
  37      * Get parameter list.
  38      * @return external_function_parameters
  39      */
  40     public static function get_courses_with_today_sessions_parameters() {
  41         return new external_function_parameters (
  42                     array('userid' => new external_value(PARAM_INT, 'User id.',  VALUE_DEFAULT, 0)));
  43     }
  44
  45     /**
  46      * Get list of courses with active sessions for today.
  47      * @param int $userid
  48      * @return array
  49      */
  50     public static function get_courses_with_today_sessions($userid) {
  51         return attendance_handler::get_courses_with_today_sessions($userid);
  52     }
  53
  54     /**
  55      * Get structure of an attendance session.
  56      *
  57      * @return array
  58      */
  59     private static function get_session_structure() {
  60         $session = array('id' => new external_value(PARAM_INT, 'Session id.'),
  61                          'attendanceid' => new external_value(PARAM_INT, 'Attendance id.'),
  62                          'groupid' => new external_value(PARAM_INT, 'Group id.'),
  63                          'sessdate' => new external_value(PARAM_INT, 'Session date.'),
  64                          'duration' => new external_value(PARAM_INT, 'Session duration.'),
  65                          'lasttaken' => new external_value(PARAM_INT, 'Session last taken time.'),
  66                          'lasttakenby' => new external_value(PARAM_INT, 'ID of the last user that took this session.'),
  67                          'timemodified' => new external_value(PARAM_INT, 'Time modified.'),
  68                          'description' => new external_value(PARAM_TEXT, 'Session description.'),
  69                          'descriptionformat' => new external_value(PARAM_INT, 'Session description format.'),
  70                          'studentscanmark' => new external_value(PARAM_INT, 'Students can mark their own presence.'),
  71                          'absenteereport' => new external_value(PARAM_INT, 'Session included in absetee reports.'),
  72                          'autoassignstatus' => new external_value(PARAM_INT, 'Automatically assign a status to students.'),
  73                          'preventsharedip' => new external_value(PARAM_INT, 'Prevent students from sharing IP addresses.'),
  74                          'preventsharediptime' => new external_value(PARAM_INT, 'Time delay before IP address is allowed again.'),
  75                          'statusset' => new external_value(PARAM_INT, 'Session statusset.'));
  76
  77         return $session;
  78     }
  79
  80     /**
  81      * Show structure of return.
  82      * @return external_multiple_structure
  83      */
  84     public static function get_courses_with_today_sessions_returns() {
  85         $todaysessions = self::get_session_structure();
  86
  87         $attendanceinstances = array('name' => new external_value(PARAM_TEXT, 'Attendance name.'),
  88                                       'today_sessions' => new external_multiple_structure(
  89                                                           new external_single_structure($todaysessions)));
  90
  91         $courses = array('shortname' => new external_value(PARAM_TEXT, 'short name of a moodle course.'),
  92                          'fullname' => new external_value(PARAM_TEXT, 'full name of a moodle course.'),
  93                          'attendance_instances' => new external_multiple_structure(
  94                                                    new external_single_structure($attendanceinstances)));
  95
  96         return new external_multiple_structure(new external_single_structure(($courses)));
  97     }
  98
  99     /**
 100      * Get session params.
 101      *
 102      * @return external_function_parameters
 103      */
 104     public static function get_session_parameters() {
 105         return new external_function_parameters (
 106                     array('sessionid' => new external_value(PARAM_INT, 'session id')));
 107     }
 108
 109     /**
 110      * Get session.
 111      *
 112      * @param int $sessionid
 113      * @return mixed
 114      */
 115     public static function get_session($sessionid) {
 116         return attendance_handler::get_session($sessionid);
 117     }
 118
 119     /**
 120      * Show return values of get_session.
 121      *
 122      * @return external_single_structure
 123      */
 124     public static function get_session_returns() {
 125         $statuses = array('id' => new external_value(PARAM_INT, 'Status id.'),
 126                           'attendanceid' => new external_value(PARAM_INT, 'Attendance id.'),
 127                           'acronym' => new external_value(PARAM_TEXT, 'Status acronym.'),
 128                           'description' => new external_value(PARAM_TEXT, 'Status description.'),
 129                           'grade' => new external_value(PARAM_FLOAT, 'Status grade.'),
 130                           'visible' => new external_value(PARAM_INT, 'Status visibility.'),
 131                           'deleted' => new external_value(PARAM_INT, 'informs if this session was deleted.'),
 132                           'setnumber' => new external_value(PARAM_INT, 'Set number.'));
 133
 134         $users = array('id' => new external_value(PARAM_INT, 'User id.'),
 135                        'firstname' => new external_value(PARAM_TEXT, 'User first name.'),
 136                        'lastname' => new external_value(PARAM_TEXT, 'User last name.'));
 137
 138         $attendancelog = array('studentid' => new external_value(PARAM_INT, 'Student id.'),
 139                                 'statusid' => new external_value(PARAM_TEXT, 'Status id (last time).'),
 140                                 'remarks' => new external_value(PARAM_TEXT, 'Last remark.'),
 141                                 'id' => new external_value(PARAM_TEXT, 'log id.'));
 142
 143         $session = self::get_session_structure();
 144         $session['courseid'] = new external_value(PARAM_INT, 'Course moodle id.');
 145         $session['statuses'] = new external_multiple_structure(new external_single_structure($statuses));
 146         $session['attendance_log'] = new external_multiple_structure(new external_single_structure($attendancelog));
 147         $session['users'] = new external_multiple_structure(new external_single_structure($users));
 148
 149         return new external_single_structure($session);
 150     }
 151
 152     /**
 153      * Update user status params.
 154      *
 155      * @return external_function_parameters
 156      */
 157     public static function update_user_status_parameters() {
 158         return new external_function_parameters(
 159                     array('sessionid' => new external_value(PARAM_INT, 'Session id'),
 160                           'studentid' => new external_value(PARAM_INT, 'Student id'),
 161                           'takenbyid' => new external_value(PARAM_INT, 'Id of the user who took this session'),
 162                           'statusid' => new external_value(PARAM_INT, 'Status id'),
 163                           'statusset' => new external_value(PARAM_TEXT, 'Status set of session')));
 164     }
 165
 166     /**
 167      * Update user status.
 168      *
 169      * @param int $sessionid
 170      * @param int $studentid
 171      * @param int $takenbyid
 172      * @param int $statusid
 173      * @param int $statusset
 174      */
 175     public static function update_user_status($sessionid, $studentid, $takenbyid, $statusid, $statusset) {
 176         return attendance_handler::update_user_status($sessionid, $studentid, $takenbyid, $statusid, $statusset);
 177     }
 178
 179     /**
 180      * Show return values.
 181      * @return external_value
 182      */
 183     public static function update_user_status_returns() {
 184         return new external_value(PARAM_TEXT, 'Http code');
 185     }
 186 }