We have to do it in the same way as delete_users

OK David, in delet user you talked about the parameters BUT ... We should talk about HOW do we want the USER OBJECT to be returned ?

I'm not so sure what you're talking about.

the service web could return something like:
<User xmlns:xsd="http://www.w3.org/2001/XMLSchema" ...>
    <Login>jerome</Login>
    <Email>jerome@moodle.com</Email>
     ...
</User>

the function get_users could return:
- an associative array: array("login" => "jerome", "email" => "jerome@mouneyrac.com");
- a user object, but I'm not sure that we got a user class in Moodle

Let me know what you decide that I update the technical specification.
Thanks.

the database get_record() function returns an object. It should probably be this "user" object which is returned by the get_users() function.

Again get_record returns something very "moodle inside" when this api is much more oriented for "outsiders" who do not ned to know the kind of object that is "user" .
I beliebe that an associative array would be the perfect solution. We just need to define which fields to include in the documentation.
The user picture should b refered with the URL, I supose.

I think it should be as many of the original user fields as possible, with some of the "internal" ones fixed up. Like the "picture" field should be a URL instead of 1/0, I agree. Can you start a list in the docs for all the major objects? user / course / group etc

sure, getting to it. I'll coment when is ready for review.
L.

Hi,

First of all, I'm sorry for this delay in this forum.
In the webservices specification we have defined return as a list of objects (list of user).
This is the easy return way for this kind of data, but if you need something like an associative array we can implement a functionality to do it or convert this object at "posteriori"

More PHPDocs to discuss about.

/**
 * Returns an user
 *
 * Returns user record with optional fields set (Moodle 1.8 and later)
 * and maybe some fields filtered out (password, email if user said
 * not to disclose it ...) depending of the identity of the "caller"
 * (admin or the user himself)
 *
 * @private ?
 *
 * @param string $field Possible values:
 * <ul>
 * <li>id</li>
 * <li>idnumber</li>
 * <li>login</li>
 * <li>email</li>
 * </ul>
 *
 * @param string $value
 *
 * @return array User record from database
 */
function get_user($field, $values){
}

/**
 * Returns an array of users
 *
 * Returns user records with optional fields set (Moodle 1.8 and later)
 * and maybe some fields filtered out (password, email if user said
 * not to disclose it ...) depending of the identity of the "caller"
 * (admin or the user himself)
 *
 * @param string $field Possible values:
 * <ul>
 * <li>id</li>
 * <li>idnumber</li>
 * <li>login</li>
 * <li>email</li>
 * </ul>
 *
 * @param array $values
 *
 * @uses get_user
 *
 * @return array Array of user records
 */
function get_users($field, $values){
}

What should this function return? Do we want to return the entire user record?

Ok, picture must be an URL. For instance, what's up with password hash?

Hello,

 I think password should never be returned.

A md5 hash can be cracked by brute force, so this hash should stay in Moodle internals for ever.

Same situation, although less severe with user's email. If site policy (or user will) is not to disclose them, they should be filtered out .

Custom profile fields are more tricky to return, since there actual key name in the returned associative array will be dependent of the Moodle site, so the corresponding WSDL complex type ( for SOAP clients) must be generated "on the fly" ... We reach here the limitation of SOAP where tools such as wsdl2java, wsdl2python,wsdl2php ... relie on a clean WSDL description to generate client's classes and must be "rerun", and clients recompiled, if the WSDL changes. I don't know how this is managed in XML-RPC, REST or others ...



Cheers.
 

I agree with you patrick, but this functions are not in the WS layer but one layer below.

All right, as I done with delete_users (http://tracker.moodle.org/browse/MDL-13127), I've just commit get_users with criteria ans users array params. The code can be found here:

http://cvs.moodle.org/contrib/patches/dfws/webservice/apis/user.lib.php?revision=1.6&view=markup

The name of the function is:

array mdl_user_delete_instances (criteria, users)

For the moment, function returns an array of user objects. user objects is not as long as using get_record and return only some necessary fields:

-id
-auth
-username
-idnumber
-deleted
-firstname
-lastname
-email
-institution
-department
-address
-city
-country
-lang
-lastaccess
-url
-description

I think this information is enough to show a "character sheet" in any application, but I will add photo support tomorrow, returning a url of the image as Martin says (http://tracker.moodle.org/browse/MDL-12887?focusedCommentId=51667#action_51667)

Implemented and finished on CVS.

The params of this functionality has changed.
There are more information returned in this operation.

When you guys commit to CVS, could you please always include the tracker issue number (eg MDL-12886) in the commit message? That way checkins are linked to and from these issues here.