[Summary view]

Differences Between: [Versions 310 and 400] [Versions 310 and 401] [Versions 310 and 402] [Versions 310 and 403]

   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   * External functions
  19   *
  20   * @package    message_airnotifier
  21   * @category   external
  22   * @copyright  2012 Jerome Mouneyrac <jerome@moodle.com>
  23   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  24   * @since Moodle 2.7
  25   */
  26  
  27  defined('MOODLE_INTERNAL') || die;
  28  
  29  require_once("$CFG->libdir/externallib.php");
  30  
  31  /**
  32   * External API for airnotifier web services
  33   *
  34   * @package    message_airnotifier
  35   * @category   external
  36   * @copyright  2012 Jerome Mouneyrac <jerome@moodle.com>
  37   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  38   * @since Moodle 2.7
  39   */
  40  class message_airnotifier_external extends external_api {
  41  
  42      /**
  43       * Returns description of method parameters
  44       *
  45       * @since Moodle 2.7
  46       */
  47      public static function is_system_configured_parameters() {
  48          return new external_function_parameters(
  49                  array()
  50          );
  51      }
  52  
  53      /**
  54       * Tests whether the airnotifier settings have been configured
  55       *
  56       * @since Moodle 2.7
  57       */
  58      public static function is_system_configured() {
  59          global $DB;
  60  
  61          // First, check if the plugin is disabled.
  62          $processor = $DB->get_record('message_processors', array('name' => 'airnotifier'), '*', MUST_EXIST);
  63          if (!$processor->enabled) {
  64              return 0;
  65          }
  66  
  67          // Then, check if the plugin is completly configured.
  68          $manager = new message_airnotifier_manager();
  69          return (int) $manager->is_system_configured();
  70      }
  71  
  72      /**
  73       * Returns description of method result value
  74       *
  75       * @return external_single_structure
  76       * @since Moodle 2.7
  77       */
  78      public static function is_system_configured_returns() {
  79          return new external_value( PARAM_INT, '0 if the system is not configured, 1 otherwise');
  80      }
  81  
  82      /**
  83       * Returns description of method parameters
  84       *
  85       * @since Moodle 2.7
  86       */
  87      public static function are_notification_preferences_configured_parameters() {
  88          return new external_function_parameters(
  89                  array(
  90                      'userids' => new external_multiple_structure(new external_value(PARAM_INT, 'user ID')),
  91                  )
  92          );
  93      }
  94  
  95      /**
  96       * Check if the users have notification preferences configured for the airnotifier plugin
  97       *
  98       * @param array $userids Array of user ids
  99       * @since Moodle 2.7
 100       */
 101      public static function are_notification_preferences_configured($userids) {
 102          global $CFG, $USER, $DB;
 103  
 104          require_once($CFG->dirroot . '/message/lib.php');
 105          $params = self::validate_parameters(self::are_notification_preferences_configured_parameters(),
 106                  array('userids' => $userids));
 107  
 108          list($sqluserids, $params) = $DB->get_in_or_equal($params['userids'], SQL_PARAMS_NAMED);
 109          $uselect = ', ' . context_helper::get_preload_record_columns_sql('ctx');
 110          $ujoin = "LEFT JOIN {context} ctx ON (ctx.instanceid = u.id AND ctx.contextlevel = :contextlevel)";
 111          $params['contextlevel'] = CONTEXT_USER;
 112          $usersql = "SELECT u.* $uselect
 113                        FROM {user} u $ujoin
 114                       WHERE u.id $sqluserids";
 115          $users = $DB->get_recordset_sql($usersql, $params);
 116  
 117          $result = array(
 118              'users' => array(),
 119              'warnings' => array()
 120          );
 121          $hasuserupdatecap = has_capability('moodle/user:update', context_system::instance());
 122          foreach ($users as $user) {
 123  
 124              $currentuser = ($user->id == $USER->id);
 125  
 126              if ($currentuser or $hasuserupdatecap) {
 127  
 128                  if (!empty($user->deleted)) {
 129                      $warning = array();
 130                      $warning['item'] = 'user';
 131                      $warning['itemid'] = $user->id;
 132                      $warning['warningcode'] = '1';
 133                      $warning['message'] = "User $user->id was deleted";
 134                      $result['warnings'][] = $warning;
 135                      continue;
 136                  }
 137  
 138                  $preferences = array();
 139                  $preferences['userid'] = $user->id;
 140                  $preferences['configured'] = 0;
 141  
 142                  // Now we get for all the providers and all the states
 143                  // the user preferences to check if at least one is enabled for airnotifier plugin.
 144                  $providers = message_get_providers_for_user($user->id);
 145                  $configured = false;
 146  
 147                  foreach ($providers as $provider) {
 148                      if ($configured) {
 149                          break;
 150                      }
 151  
 152                      foreach (array('loggedin', 'loggedoff') as $state) {
 153  
 154                          $prefstocheck = array();
 155                          $prefname = 'message_provider_'.$provider->component.'_'.$provider->name.'_'.$state;
 156  
 157                          // First get forced settings.
 158                          if ($forcedpref = get_config('message', $prefname)) {
 159                              $prefstocheck = array_merge($prefstocheck, explode(',', $forcedpref));
 160                          }
 161  
 162                          // Then get user settings.
 163                          if ($userpref = get_user_preferences($prefname, '', $user->id)) {
 164                              $prefstocheck = array_merge($prefstocheck, explode(',', $userpref));
 165                          }
 166  
 167                          if (in_array('airnotifier', $prefstocheck)) {
 168                              $preferences['configured'] = 1;
 169                              $configured = true;
 170                              break;
 171                          }
 172  
 173                      }
 174                  }
 175  
 176                  $result['users'][] = $preferences;
 177              } else if (!$hasuserupdatecap) {
 178                  $warning = array();
 179                  $warning['item'] = 'user';
 180                  $warning['itemid'] = $user->id;
 181                  $warning['warningcode'] = '2';
 182                  $warning['message'] = "You don't have permissions for view user $user->id preferences";
 183                  $result['warnings'][] = $warning;
 184              }
 185  
 186          }
 187          $users->close();
 188  
 189          return $result;
 190      }
 191  
 192      /**
 193       * Returns description of method result value
 194       *
 195       * @return external_single_structure
 196       * @since Moodle 2.7
 197       */
 198      public static function are_notification_preferences_configured_returns() {
 199          return new external_single_structure(
 200              array(
 201                  'users' => new external_multiple_structure(
 202                      new external_single_structure(
 203                          array (
 204                              'userid'     => new external_value(PARAM_INT, 'userid id'),
 205                              'configured' => new external_value(PARAM_INT,
 206                                  '1 if the user preferences have been configured and 0 if not')
 207                          )
 208                      ),
 209                      'list of preferences by user'),
 210                  'warnings' => new external_warnings()
 211              )
 212          );
 213      }
 214  
 215      /**
 216       * Returns description of method parameters
 217       *
 218       * @since Moodle 3.2
 219       */
 220      public static function get_user_devices_parameters() {
 221          return new external_function_parameters(
 222              array(
 223                  'appid' => new external_value(PARAM_NOTAGS, 'App unique id (usually a reversed domain)'),
 224                  'userid' => new external_value(PARAM_INT, 'User id, 0 for current user', VALUE_DEFAULT, 0)
 225              )
 226          );
 227      }
 228  
 229      /**
 230       * Return the list of mobile devices that are registered in Moodle for the given user.
 231       *
 232       * @param  string  $appid  app unique id (usually a reversed domain)
 233       * @param  integer $userid the user id, 0 for current user
 234       * @return array warnings and devices
 235       * @throws moodle_exception
 236       * @since Moodle 3.2
 237       */
 238      public static function get_user_devices($appid, $userid = 0) {
 239          global $USER;
 240  
 241          $params = self::validate_parameters(
 242              self::get_user_devices_parameters(),
 243              array(
 244                  'appid' => $appid,
 245                  'userid' => $userid,
 246              )
 247          );
 248  
 249          $context = context_system::instance();
 250          self::validate_context($context);
 251  
 252          if (empty($params['userid'])) {
 253              $user = $USER;
 254          } else {
 255              $user = core_user::get_user($params['userid'], '*', MUST_EXIST);
 256              core_user::require_active_user($user);
 257              // Allow only admins to retrieve other users devices.
 258              if ($user->id != $USER->id) {
 259                  require_capability('moodle/site:config', $context);
 260              }
 261          }
 262  
 263          $warnings = array();
 264          $devices = array();
 265          // Check if mobile notifications are enabled.
 266          if (!self::is_system_configured()) {
 267              $warnings[] = array(
 268                  'item' => 'user',
 269                  'itemid' => $user->id,
 270                  'warningcode' => 'systemnotconfigured',
 271                  'message' => 'Mobile notifications are not configured'
 272              );
 273          } else {
 274              // We catch exceptions here because get_user_devices may try to connect to Airnotifier.
 275              try {
 276                  $manager = new message_airnotifier_manager();
 277                  $devices = $manager->get_user_devices($appid, $user->id);
 278              } catch (Exception $e) {
 279                  $warnings[] = array(
 280                      'item' => 'user',
 281                      'itemid' => $user->id,
 282                      'warningcode' => 'errorgettingdevices',
 283                      'message' => $e->getMessage()
 284                  );
 285              }
 286          }
 287  
 288          return array(
 289              'devices' => $devices,
 290              'warnings' => $warnings
 291          );
 292      }
 293  
 294      /**
 295       * Returns description of method result value
 296       *
 297       * @return external_single_structure
 298       * @since Moodle 3.2
 299       */
 300      public static function get_user_devices_returns() {
 301          return new external_single_structure(
 302              array(
 303                  'devices' => new external_multiple_structure(
 304                      new external_single_structure(
 305                          array (
 306                              'id' => new external_value(PARAM_INT, 'Device id (in the message_airnotifier table)'),
 307                              'appid' => new external_value(PARAM_NOTAGS, 'The app id, something like com.moodle.moodlemobile'),
 308                              'name' => new external_value(PARAM_NOTAGS, 'The device name, \'occam\' or \'iPhone\' etc.'),
 309                              'model' => new external_value(PARAM_NOTAGS, 'The device model \'Nexus4\' or \'iPad1,1\' etc.'),
 310                              'platform' => new external_value(PARAM_NOTAGS, 'The device platform \'iOS\' or \'Android\' etc.'),
 311                              'version' => new external_value(PARAM_NOTAGS, 'The device version \'6.1.2\' or \'4.2.2\' etc.'),
 312                              'pushid' => new external_value(PARAM_RAW, 'The device PUSH token/key/identifier/registration id'),
 313                              'uuid' => new external_value(PARAM_RAW, 'The device UUID'),
 314                              'enable' => new external_value(PARAM_INT, 'Whether the device is enabled or not'),
 315                              'timecreated' => new external_value(PARAM_INT, 'Time created'),
 316                              'timemodified' => new external_value(PARAM_INT, 'Time modified'),
 317                          )
 318                      ),
 319                      'List of devices'
 320                  ),
 321                  'warnings' => new external_warnings()
 322              )
 323          );
 324      }
 325  
 326      /**
 327       * Returns description of method parameters
 328       *
 329       * @since Moodle 3.2
 330       */
 331      public static function enable_device_parameters() {
 332          return new external_function_parameters(
 333              array(
 334                  'deviceid' => new external_value(PARAM_INT, 'The device id'),
 335                  'enable' => new external_value(PARAM_BOOL, 'True for enable the device, false otherwise')
 336              )
 337          );
 338      }
 339  
 340      /**
 341       * Enables or disables a registered user device so it can receive Push notifications
 342       *
 343       * @param  integer $deviceid the device id
 344       * @param  bool $enable whether to enable the device
 345       * @return array warnings and success status
 346       * @throws moodle_exception
 347       * @since Moodle 3.2
 348       */
 349      public static function enable_device($deviceid, $enable) {
 350          global $USER;
 351  
 352          $params = self::validate_parameters(
 353              self::enable_device_parameters(),
 354              array(
 355                  'deviceid' => $deviceid,
 356                  'enable' => $enable,
 357              )
 358          );
 359  
 360          $context = context_system::instance();
 361          self::validate_context($context);
 362          require_capability('message/airnotifier:managedevice', $context);
 363  
 364          if (!message_airnotifier_manager::enable_device($params['deviceid'], $params['enable'])) {
 365              throw new moodle_exception('unknowndevice', 'message_airnotifier');
 366          }
 367  
 368          return array(
 369              'success' => true,
 370              'warnings' => array()
 371          );
 372      }
 373  
 374      /**
 375       * Returns description of method result value
 376       *
 377       * @return external_single_structure
 378       * @since Moodle 3.2
 379       */
 380      public static function enable_device_returns() {
 381          return new external_single_structure(
 382              array(
 383                  'success' => new external_value(PARAM_BOOL, 'True if success'),
 384                  'warnings' => new external_warnings()
 385              )
 386          );
 387      }
 388  }