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                          'statusset' => new external_value(PARAM_INT, 'Session statusset.'));
  74
  75         return $session;
  76     }
  77
  78     /**
  79      * Show structure of return.
  80      * @return external_multiple_structure
  81      */
  82     public static function get_courses_with_today_sessions_returns() {
  83         $todaysessions = self::get_session_structure();
  84
  85         $attendanceinstances = array('name' => new external_value(PARAM_TEXT, 'Attendance name.'),
  86                                       'today_sessions' => new external_multiple_structure(
  87                                                           new external_single_structure($todaysessions)));
  88
  89         $courses = array('shortname' => new external_value(PARAM_TEXT, 'short name of a moodle course.'),
  90                          'fullname' => new external_value(PARAM_TEXT, 'full name of a moodle course.'),
  91                          'attendance_instances' => new external_multiple_structure(
  92                                                    new external_single_structure($attendanceinstances)));
  93
  94         return new external_multiple_structure(new external_single_structure(($courses)));
  95     }
  96
  97     /**
  98      * Get session params.
  99      *
 100      * @return external_function_parameters
 101      */
 102     public static function get_session_parameters() {
 103         return new external_function_parameters (
 104                     array('sessionid' => new external_value(PARAM_INT, 'session id')));
 105     }
 106
 107     /**
 108      * Get session.
 109      *
 110      * @param int $sessionid
 111      * @return mixed
 112      */
 113     public static function get_session($sessionid) {
 114         return attendance_handler::get_session($sessionid);
 115     }
 116
 117     /**
 118      * Show return values of get_session.
 119      *
 120      * @return external_single_structure
 121      */
 122     public static function get_session_returns() {
 123         $statuses = array('id' => new external_value(PARAM_INT, 'Status id.'),
 124                           'attendanceid' => new external_value(PARAM_INT, 'Attendance id.'),
 125                           'acronym' => new external_value(PARAM_TEXT, 'Status acronym.'),
 126                           'description' => new external_value(PARAM_TEXT, 'Status description.'),
 127                           'grade' => new external_value(PARAM_FLOAT, 'Status grade.'),
 128                           'visible' => new external_value(PARAM_INT, 'Status visibility.'),
 129                           'deleted' => new external_value(PARAM_INT, 'informs if this session was deleted.'),
 130                           'setnumber' => new external_value(PARAM_INT, 'Set number.'));
 131
 132         $users = array('id' => new external_value(PARAM_INT, 'User id.'),
 133                        'firstname' => new external_value(PARAM_TEXT, 'User first name.'),
 134                        'lastname' => new external_value(PARAM_TEXT, 'User last name.'));
 135
 136         $attendancelog = array('studentid' => new external_value(PARAM_INT, 'Student id.'),
 137                                 'statusid' => new external_value(PARAM_TEXT, 'Status id (last time).'),
 138                                 'remarks' => new external_value(PARAM_TEXT, 'Last remark.'),
 139                                 'id' => new external_value(PARAM_TEXT, 'log id.'));
 140
 141         $session = self::get_session_structure();
 142         $session['courseid'] = new external_value(PARAM_INT, 'Course moodle id.');
 143         $session['statuses'] = new external_multiple_structure(new external_single_structure($statuses));
 144         $session['attendance_log'] = new external_multiple_structure(new external_single_structure($attendancelog));
 145         $session['users'] = new external_multiple_structure(new external_single_structure($users));
 146
 147         return new external_single_structure($session);
 148     }
 149
 150     /**
 151      * Update user status params.
 152      *
 153      * @return external_function_parameters
 154      */
 155     public static function update_user_status_parameters() {
 156         return new external_function_parameters(
 157                     array('sessionid' => new external_value(PARAM_INT, 'Session id'),
 158                           'studentid' => new external_value(PARAM_INT, 'Student id'),
 159                           'takenbyid' => new external_value(PARAM_INT, 'Id of the user who took this session'),
 160                           'statusid' => new external_value(PARAM_INT, 'Status id'),
 161                           'statusset' => new external_value(PARAM_TEXT, 'Status set of session')));
 162     }
 163
 164     /**
 165      * Update user status.
 166      *
 167      * @param int $sessionid
 168      * @param int $studentid
 169      * @param int $takenbyid
 170      * @param int $statusid
 171      * @param int $statusset
 172      */
 173     public static function update_user_status($sessionid, $studentid, $takenbyid, $statusid, $statusset) {
 174         return attendance_handler::update_user_status($sessionid, $studentid, $takenbyid, $statusid, $statusset);
 175     }
 176
 177     /**
 178      * Show return values.
 179      * @return external_value
 180      */
 181     public static function update_user_status_returns() {
 182         return new external_value(PARAM_TEXT, 'Http code');
 183     }
 184 }