mod/chat/classes/external.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 /**
  18  * Chat external API
  19  *
  20  * @package    mod_chat
  21  * @category   external
  22  * @copyright  2015 Juan Leyva <juan@moodle.com>
  23  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  24  * @since      Moodle 3.0
  25  */
  26
  27 defined('MOODLE_INTERNAL') || die;
  28
  29 require_once($CFG->libdir . '/externallib.php');
  30 require_once($CFG->dirroot . '/mod/chat/lib.php');
  31
  32 /**
  33  * Chat external functions
  34  *
  35  * @package    mod_chat
  36  * @category   external
  37  * @copyright  2015 Juan Leyva <juan@moodle.com>
  38  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  39  * @since      Moodle 3.0
  40  */
  41 class mod_chat_external extends external_api {
  42
  43     /**
  44      * Returns description of method parameters
  45      *
  46      * @return external_function_parameters
  47      * @since Moodle 3.0
  48      */
  49     public static function login_user_parameters() {
  50         return new external_function_parameters(
  51             array(
  52                 'chatid' => new external_value(PARAM_INT, 'chat instance id'),
  53                 'groupid' => new external_value(PARAM_INT, 'group id, 0 means that the function will determine the user group',
  54                                                 VALUE_DEFAULT, 0),
  55             )
  56         );
  57     }
  58
  59     /**
  60      * Log the current user into a chat room in the given chat.
  61      *
  62      * @param int $chatid the chat instance id
  63      * @param int $groupid the user group id
  64      * @return array of warnings and the chat unique session id
  65      * @since Moodle 3.0
  66      * @throws moodle_exception
  67      */
  68     public static function login_user($chatid, $groupid = 0) {
  69         global $DB;
  70
  71         $params = self::validate_parameters(self::login_user_parameters(),
  72                                             array(
  73                                                 'chatid' => $chatid,
  74                                                 'groupid' => $groupid
  75                                             ));
  76         $warnings = array();
  77
  78         // Request and permission validation.
  79         $chat = $DB->get_record('chat', array('id' => $params['chatid']), '*', MUST_EXIST);
  80         list($course, $cm) = get_course_and_cm_from_instance($chat, 'chat');
  81
  82         $context = context_module::instance($cm->id);
  83         self::validate_context($context);
  84
  85         require_capability('mod/chat:chat', $context);
  86
  87         if (!empty($params['groupid'])) {
  88             $groupid = $params['groupid'];
  89             // Determine is the group is visible to user.
  90             if (!groups_group_visible($groupid, $course, $cm)) {
  91                 throw new moodle_exception('notingroup');
  92             }
  93         } else {
  94             // Check to see if groups are being used here.
  95             if ($groupmode = groups_get_activity_groupmode($cm)) {
  96                 $groupid = groups_get_activity_group($cm);
  97                 // Determine is the group is visible to user (this is particullary for the group 0).
  98                 if (!groups_group_visible($groupid, $course, $cm)) {
  99                     throw new moodle_exception('notingroup');
 100                 }
 101             } else {
 102                 $groupid = 0;
 103             }
 104         }
 105
 106         // Get the unique chat session id.
 107         // Since we are going to use the chat via Web Service requests we set the ajax version (since it's the most similar).
 108         if (!$chatsid = chat_login_user($chat->id, 'ajax', $groupid, $course)) {
 109             throw moodle_exception('cantlogin', 'chat');
 110         }
 111
 112         $result = array();
 113         $result['chatsid'] = $chatsid;
 114         $result['warnings'] = $warnings;
 115         return $result;
 116     }
 117
 118     /**
 119      * Returns description of method result value
 120      *
 121      * @return external_description
 122      * @since Moodle 3.0
 123      */
 124     public static function login_user_returns() {
 125         return new external_single_structure(
 126             array(
 127                 'chatsid' => new external_value(PARAM_ALPHANUM, 'unique chat session id'),
 128                 'warnings' => new external_warnings()
 129             )
 130         );
 131     }
 132
 133     /**
 134      * Returns description of method parameters
 135      *
 136      * @return external_function_parameters
 137      * @since Moodle 3.0
 138      */
 139     public static function get_chat_users_parameters() {
 140         return new external_function_parameters(
 141             array(
 142                 'chatsid' => new external_value(PARAM_ALPHANUM, 'chat session id (obtained via mod_chat_login_user)')
 143             )
 144         );
 145     }
 146
 147     /**
 148      * Get the list of users in the given chat session.
 149      *
 150      * @param int $chatsid the chat session id
 151      * @return array of warnings and the user lists
 152      * @since Moodle 3.0
 153      * @throws moodle_exception
 154      */
 155     public static function get_chat_users($chatsid) {
 156         global $DB;
 157
 158         $params = self::validate_parameters(self::get_chat_users_parameters(),
 159                                             array(
 160                                                 'chatsid' => $chatsid
 161                                             ));
 162         $warnings = array();
 163
 164         // Request and permission validation.
 165         if (!$chatuser = $DB->get_record('chat_users', array('sid' => $params['chatsid']))) {
 166             throw new moodle_exception('notlogged', 'chat');
 167         }
 168         $chat = $DB->get_record('chat', array('id' => $chatuser->chatid), '*', MUST_EXIST);
 169         list($course, $cm) = get_course_and_cm_from_instance($chat, 'chat');
 170
 171         $context = context_module::instance($cm->id);
 172         self::validate_context($context);
 173
 174         require_capability('mod/chat:chat', $context);
 175
 176         // First, delete old users from the chats.
 177         chat_delete_old_users();
 178
 179         $users = chat_get_users($chatuser->chatid, $chatuser->groupid, $cm->groupingid);
 180         $returnedusers = array();
 181
 182         foreach ($users as $user) {
 183             $usercontext = context_user::instance($user->id, IGNORE_MISSING);
 184             $profileimageurl = '';
 185
 186             if ($usercontext) {
 187                 $profileimageurl = moodle_url::make_webservice_pluginfile_url(
 188                                     $usercontext->id, 'user', 'icon', null, '/', 'f1')->out(false);
 189             }
 190
 191             $returnedusers[] = array(
 192                 'id' => $user->id,
 193                 'fullname' => fullname($user),
 194                 'profileimageurl' => $profileimageurl
 195             );
 196         }
 197
 198         $result = array();
 199         $result['users'] = $returnedusers;
 200         $result['warnings'] = $warnings;
 201         return $result;
 202     }
 203
 204     /**
 205      * Returns description of method result value
 206      *
 207      * @return external_description
 208      * @since Moodle 3.0
 209      */
 210     public static function get_chat_users_returns() {
 211         return new external_single_structure(
 212             array(
 213                 'users' => new external_multiple_structure(
 214                     new external_single_structure(
 215                         array(
 216                             'id' => new external_value(PARAM_INT, 'user id'),
 217                             'fullname' => new external_value(PARAM_NOTAGS, 'user full name'),
 218                             'profileimageurl' => new external_value(PARAM_URL, 'user picture URL'),
 219                         )
 220                     ),
 221                     'list of users'
 222                 ),
 223                 'warnings' => new external_warnings()
 224             )
 225         );
 226     }
 227
 228     /**
 229      * Returns description of method parameters
 230      *
 231      * @return external_function_parameters
 232      * @since Moodle 3.0
 233      */
 234     public static function send_chat_message_parameters() {
 235         return new external_function_parameters(
 236             array(
 237                 'chatsid' => new external_value(PARAM_ALPHANUM, 'chat session id (obtained via mod_chat_login_user)'),
 238                 'messagetext' => new external_value(PARAM_RAW, 'the message text'),
 239                 'beepid' => new external_value(PARAM_RAW, 'the beep id', VALUE_DEFAULT, ''),
 240
 241             )
 242         );
 243     }
 244
 245     /**
 246      * Send a message on the given chat session.
 247      *
 248      * @param int $chatsid the chat session id
 249      * @param string $messagetext the message text
 250      * @param string $beepid the beep message id
 251      * @return array of warnings and the new message id (0 if the message was empty)
 252      * @since Moodle 3.0
 253      * @throws moodle_exception
 254      */
 255     public static function send_chat_message($chatsid, $messagetext, $beepid = '') {
 256         global $DB;
 257
 258         $params = self::validate_parameters(self::send_chat_message_parameters(),
 259                                             array(
 260                                                 'chatsid' => $chatsid,
 261                                                 'messagetext' => $messagetext,
 262                                                 'beepid' => $beepid
 263                                             ));
 264         $warnings = array();
 265
 266         // Request and permission validation.
 267         if (!$chatuser = $DB->get_record('chat_users', array('sid' => $params['chatsid']))) {
 268             throw new moodle_exception('notlogged', 'chat');
 269         }
 270         $chat = $DB->get_record('chat', array('id' => $chatuser->chatid), '*', MUST_EXIST);
 271         list($course, $cm) = get_course_and_cm_from_instance($chat, 'chat');
 272
 273         $context = context_module::instance($cm->id);
 274         self::validate_context($context);
 275
 276         require_capability('mod/chat:chat', $context);
 277
 278         $chatmessage = clean_text($params['messagetext'], FORMAT_MOODLE);
 279
 280         if (!empty($params['beepid'])) {
 281             $chatmessage = 'beep ' . $params['beepid'];
 282         }
 283
 284         if (!empty($chatmessage)) {
 285             // Send the message.
 286             $messageid = chat_send_chatmessage($chatuser, $chatmessage, 0, $cm);
 287             // Update ping time.
 288             $chatuser->lastmessageping = time() - 2;
 289             $DB->update_record('chat_users', $chatuser);
 290         } else {
 291             $messageid = 0;
 292         }
 293
 294         $result = array();
 295         $result['messageid'] = $messageid;
 296         $result['warnings'] = $warnings;
 297         return $result;
 298     }
 299
 300     /**
 301      * Returns description of method result value
 302      *
 303      * @return external_description
 304      * @since Moodle 3.0
 305      */
 306     public static function send_chat_message_returns() {
 307         return new external_single_structure(
 308             array(
 309                 'messageid' => new external_value(PARAM_INT, 'message sent id'),
 310                 'warnings' => new external_warnings()
 311             )
 312         );
 313     }
 314
 315 }