Development:Groups API for modules

<?php
/*******************************************************************************
 * modulelib.php
 * 
 * This file contains functions to be used by modules to support groups. More
 * documentation is available on the Developer's Notes section of the Moodle 
 * wiki. 
 * 
 * For queries, suggestions for improvements etc. please post on the Groups 
 * forum on the moodle.org site.
 ******************************************************************************/

/*******************************************************************************
 * Permission types
 * 
 * There are six types of permission that a user can hold for a particular
 * group - 'student view', 'student contribute', 'teacher view', 
 * 'teacher contribute', 'view members list' and 'view group existence'. 
 * 
 * A particular user need not to be a member of the group to have a specific 
 * permission and may have more than one permission type. The permission that a 
 * particular user has for a group used by an particular instance of the module 
 * depends on whether the student is a teacher or student for the course and on 
 * the settings for the set of groups (the 'grouping') being used by the 
 * instance of the module  
 * 
 * It is up to each module to decide how to interpret the different permission 
 * types. The only exception is with 'view members list' and 'view group 
 * existence'. The former means that the user can view the members of the group 
 * while the latter means that the user can view information such as the group 
 * name and description. It is possible that a user may have 'view members list' 
 * permission without 'view group existence' permission - the members would just 
 * appear as the other users on the course. 
 * 
 * Permission types can be combined with boolean expressions where they are used 
 * if necessary. 
 * 
 * @name GROUPS_STUDENT Either 'student view' or 'student contribute' permission
 * @name GROUPS_TEACHER Either 'teacher view' or 'teacher contribute' permission
 * @name GROUPS_VIEW Either 'teacher view' or 'student view' permission
 * @name GROUPS_CONTRIBUTE Either 'teacher contribute' or 'student contribute' 
 * permission
 * @name GROUPS_VIEW_GROUP_EXISTENCE 'view group existence' permission
 * @name GROUPS_VIEW_MEMBERS_LIST 'view members list' permission
 * @name GROUPS_STUDENT_VIEW 'student view' permission
 * @name GROUPS_STUDENT_CONTRIBUTE 'student contribute' permission
 * @name GROUPS_TEACHER_VIEW 'teacher view' permission
 * @name GROUPS_TEACHER_CONTRIBUTE 'teacher contribute' permission
 ******************************************************************************/
define('GROUPS_STUDENT', 1);
define('GROUPS_TEACHER', 2);
define('GROUPS_VIEW', 4);
define('GROUPS_CONTRIBUTE', 8);
define('GROUPS_VIEW_GROUP_EXISTENCE', 16);
define('GROUPS_VIEW_MEMBERS_LIST', 48);
define('GROUPS_STUDENT_VIEW', 5);
define('GROUPS_STUDENT_CONTRIBUTE', 9);
define('GROUPS_TEACHER_VIEW', 6);
define('GROUPS_TEACHER_CONTRIBUTE', 10);

/**
 * Indicates if the instance of the module has been set up by an editor of the 
 * course to use groups. This functionality can also be obtained using the 
 * groups_m_get_groups() function, however it is sufficiently commonly needed 
 * that this separate function has been provided and should be used instead. 
 * @param int $cmid The id of the module instance
 * @return boolean True if the instance is set up to use groups, false otherwise
 */
function groups_m_uses_groups($cmid) {
}

/**
 * Prints a dropdown box to enable a user to select between the groups for the 
 * module instance of which they are a member. If a user belongs to 0 or 1 
 * groups, no form is printed. The dropdown box belongs to a form and when a 
 * user clicks on the box this form is automatically submitted so that the page 
 * knows about the change. 
 * @param int $cmid The id of the module instance
 * @param string $urlroot The url of the page - this is necessary so the form 
 * can submit to the correct page. 
 * @param int $permissiontype - see note on permissiontypes above. 
 * @return boolean True unless an error occurred or the module instance does not 
 * use groups in which case returns false. 
 */
function groups_m_print_group_selector($cmid, $urlroot, $permissiontype) {
}

/**
 * Gets the group that a student has selected from the drop-down menu printed
 * by groups_m_print_group_selector and checks that the student has the 
 * specified permission for the group and that the group is one of the groups
 * assigned for this module instance.
 * 
 * Groups selected are saved between page changes within the module instance but 
 * not necessarily if the user leaves the instance e.g. returns to the main 
 * course page. If the selector has not been printed anywhere during the user's 
 * 'visit' to the module instance, then the function returns false. This means 
 * that you need to be particularly careful about pages that might be 
 * bookmarked by the user.  
 * 
 * @uses $USER   
 * @param int $cmid The id of the module instance
 * @param int $permissiontype The permission type - see note on permission types 
 * above
 * @param int $userid The id of the user, defaults to the current user 
 * @return boolean True if no error occurred, false otherwise. 
 */
function groups_m_get_selected_group($cmid, $permissiontype, 
                                     $userid = $USER->id) {
}
	 
/**
 * Gets an array of the groupids of all the groups that the specified user has
 * particular permission for in this particular instance of the module
 * @uses $USER     
 * @param int $cmid The id of the module instance
 * @param int $permissiontype The permission type - see note on permission types 
 * above
 * @param int $userid The id of the user, defaults to the current user 
 * @return array An array of the group ids 
 */	
function groups_m_get_groups_for_user($cmid, $permissiontype, 
                                      $userid = $USER->id) {
}  

/**
 * Indicates if a specified user has a particular type of permission for a 
 * particular group for this module instance.
 * @uses $USER      
 * @param int $cmid The id of the module instance. This is necessary because the 
 * same group can be used in different module instances with different 
 * permission setups. 
 * @param int $groupid The id of the group
 * @param int $permissiontype The permission type - see note on permission types 
 * above
 * @userid int $userid The id of the user, defaults to the current user
 * @return boolean True if the user has the specified permission type, false 
 * otherwise or if an error occurred. 
 */
 function groups_m_has_permission($cmid, $groupid, $permissiontype, 
                                  $userid = $USER->id) {
 } 

/**
 * Gets an array of members of a group that have a particular permission type 
 * for this instance of the module and that are enrolled on the course that
 * the module instance belongs to. 
 * 
 * @param int $cmid The id of the module instance. This is necessary because the 
 * same group can be used in different module instances with different 
 * permission setups. 
 * @param int $groupid The id of the group
 * @param int $permissiontype The permission type - see note on permission types 
 * above
 * @return array An array containing the ids of the users with the specified 
 * permission. 
 */
function groups_m_get_members_with_permission($cmid, $groupid, 
                                              $permissiontype) {
}

/**
 * Gets the group object associated with a group id. This group object can be 
 * used to get information such as the name of the group and the file for the 
 * group icon if it exists. (Look at the groups table in the database to see
 * the fields). 
 * @param int $groupid The id of the group
 * @return group The group object 
 */
function groups_m_get_group($groupid) {
}

/**
 * Gets the groups for the module instance. In general, you should use 
 * groups_m_get_groups_for_user, however this function is provided for 
 * circumstances where this function isn't sufficient for some reason. 
 * @param int $cmid The id of the module instance. 
 * @return array An array of the ids of the groups for the module instance 
 */
function groups_m_get_groups($cmid) {
}

/**
 * Gets the members of group that are enrolled on the course that the specified
 * module instance belongs to. 
 * @param int $cmid The id of the module instance
 * @param int $groupid The id of the group
 * @return array An array of the userids of the members. 
 */
function groups_m_get_members($cmid, $groupid) {
}

/**
 * Indicates if a user is a member of a particular group. In general you should 
 * use groups_m_has_permission, however this function is provided for 
 * circumstances where this function isn't sufficient for some reason. 
 * @param int $groupid The id of the group
 * @param int $userid The id of the user 
 * @return boolean True if the user is a member of the group, false otherwise 
 */
function groups_m_is_member($groupid, $userid) {
}
?>