MDL-12886 more external users api

diff --git a/user/externallib.php b/user/externallib.php
index 205d39677c5309e61818665f8e19183dfbd91d95..ee8d84711d14016cc70fba8125e7da1155636b58 100644 (file)
--- a/user/externallib.php
+++ b/user/externallib.php
@@ -78,9 +78,8 @@ class moodle_user_external extends external_api {
     /**
      * Create one or more users
      *
-     * @param array $params  An array of users to create.  Each user is defined by $usertocreate above.
-     *
-     * @return array An array of userids, one for each user that was created
+     * @param array $users  An array of users to create.
+     * @return array An array of arrays
      */
     public static function create_users($users) {
         global $CFG, $DB;
@@ -179,26 +178,38 @@ class moodle_user_external extends external_api {
      * @return external_function_parameters
      */
     public static function get_users_parameters() {
-
+        return new external_function_parameters(
+            array(
+                'userids' => new external_multiple_structure(new external_value(PARAM_INT, 'user ID')),
+            )
+        );
     }
 
-    public static function get_users($params) {
+    /**
+     * Get user information
+     *
+     * @param array $userids  array of user ids
+     * @return array An array of arrays describing users
+     */
+    public static function get_users($userids) {
         $context = get_context_instance(CONTEXT_SYSTEM);
         require_capability('moodle/user:viewdetails', $context);
         self::validate_context($context);
 
-        $params = self::validate_parameters(self::get_users_parameters(), $params);
+        $params = self::validate_parameters(self::get_users_parameters(), array('userids'=>$userids));
 
         //TODO: this search is probably useless for external systems because it is not exact
         //      1/ we should specify multiple search parameters including the mnet host id
         //      2/ custom profile fileds not included
 
         $result = array();
-
+/*
         $users = get_users(true, $params['search'], false, null, 'firstname ASC','', '', '', 1000, 'id, mnethostid, auth, confirmed, username, idnumber, firstname, lastname, email, emailstop, lang, theme, timezone, mailformat, city, description, country');
         foreach ($users as $user) {
             $result[] = (array)$user;
-        }
+        }*/
+
+        return $result;
     }
 
    /**
@@ -206,7 +217,33 @@ class moodle_user_external extends external_api {
      * @return external_description
      */
     public static function get_users_returns() {
-
+        return new external_multiple_structure(
+            new external_single_structure(
+                array(
+                    'username'    => new external_value(PARAM_RAW, 'Username policy is defined in Moodle security config'),
+                    'firstname'   => new external_value(PARAM_NOTAGS, 'The first name(s) of the user'),
+                    'lastname'    => new external_value(PARAM_NOTAGS, 'The family name of the user'),
+                    'email'       => new external_value(PARAM_EMAIL, 'A valid and unique email address'),
+                    'auth'        => new external_value(PARAM_SAFEDIR, 'Auth plugins include manual, ldap, imap, etc', false),
+                    'confirmed'   => new external_value(PARAM_NUMBER, 'Active user: 1 if confirmed, 0 otherwise', false),
+                    'idnumber'    => new external_value(PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', false),
+                    'emailstop'   => new external_value(PARAM_NUMBER, 'Email is blocked: 1 is blocked and 0 otherwise', false),
+                    'lang'        => new external_value(PARAM_SAFEDIR, 'Language code such as "en_utf8", must exist on server', false),
+                    'theme'       => new external_value(PARAM_SAFEDIR, 'Theme name such as "standard", must exist on server', false),
+                    'timezone'    => new external_value(PARAM_ALPHANUMEXT, 'Timezone code such as Australia/Perth, or 99 for default', false),
+                    'mailformat'  => new external_value(PARAM_INTEGER, 'Mail format code is 0 for plain text, 1 for HTML etc', false),
+                    'description' => new external_value(PARAM_TEXT, 'User profile description, as HTML', false),
+                    'city'        => new external_value(PARAM_NOTAGS, 'Home city of the user', false),
+                    'country'     => new external_value(PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', false),
+                    'customfields' => new external_multiple_structure(
+                        new external_single_structure(
+                            array(
+                                'type'  => new external_value(PARAM_ALPHANUMEXT, 'The name of the custom field'),
+                                'value' => new external_value(PARAM_RAW, 'The value of the custom field')
+                            )
+                        ), 'User custom fields', false)
+                )
+            )
+        );
     }
-
 }