* @since Moodle 2.2
*/
class core_message_external extends external_api {
+ /**
+ * Returns description of method parameters
+ *
+ * @return external_function_parameters
+ * @since Moodle 3.6
+ */
+ public static function send_messages_to_conversation_parameters() {
+ return new external_function_parameters(
+ array(
+ 'conversationid' => new external_value(PARAM_INT, 'id of the conversation'),
+ 'messages' => new external_multiple_structure(
+ new external_single_structure(
+ array(
+ 'text' => new external_value(PARAM_RAW, 'the text of the message'),
+ 'textformat' => new external_format_value('text', VALUE_DEFAULT, FORMAT_MOODLE),
+ )
+ )
+ )
+ )
+ );
+ }
+
+ /**
+ * Send messages from the current USER to a conversation.
+ *
+ * This conversation may be any type of conversation, individual or group.
+ *
+ * @param int $conversationid the id of the conversation to which the messages will be sent.
+ * @param array $messages An array of message to send.
+ * @return array the array of messages which were sent (created).
+ * @since Moodle 3.6
+ */
+ public static function send_messages_to_conversation(int $conversationid, array $messages = []) {
+ global $CFG, $USER;
+
+ // Check if messaging is enabled.
+ if (empty($CFG->messaging)) {
+ throw new moodle_exception('disabled', 'message');
+ }
+
+ // Ensure the current user is allowed to run this function.
+ $context = context_system::instance();
+ self::validate_context($context);
+
+ $params = self::validate_parameters(self::send_messages_to_conversation_parameters(), [
+ 'conversationid' => $conversationid,
+ 'messages' => $messages
+ ]);
+
+ $messages = [];
+ foreach ($params['messages'] as $message) {
+ $messages[] = \core_message\api::send_message_to_conversation($USER->id, $params['conversationid'], $message['text'],
+ $message['textformat']);
+ }
+
+ return $messages;
+ }
+
+ /**
+ * Returns description of method result value.
+ *
+ * @return external_description
+ * @since Moodle 3.6
+ */
+ public static function send_messages_to_conversation_returns() {
+ return new external_multiple_structure(
+ self::get_conversation_message_structure()
+ );
+ }
+
/**
* Returns description of method parameters
public static function get_contact_requests_parameters() {
return new external_function_parameters(
[
- 'userid' => new external_value(PARAM_INT, 'The id of the user we want the requests for')
+ 'userid' => new external_value(PARAM_INT, 'The id of the user we want the requests for'),
+ 'limitfrom' => new external_value(PARAM_INT, 'Limit from', VALUE_DEFAULT, 0),
+ 'limitnum' => new external_value(PARAM_INT, 'Limit number', VALUE_DEFAULT, 0)
]
);
}
* It will not include blocked users.
*
* @param int $userid The id of the user we want to get the contact requests for
+ * @param int $limitfrom
+ * @param int $limitnum
*/
- public static function get_contact_requests(int $userid) {
+ public static function get_contact_requests(int $userid, int $limitfrom = 0, int $limitnum = 0) {
global $CFG, $USER;
// Check if messaging is enabled.
$context = context_system::instance();
self::validate_context($context);
- $params = ['userid' => $userid];
+ $params = [
+ 'userid' => $userid,
+ 'limitfrom' => $limitfrom,
+ 'limitnum' => $limitnum
+ ];
$params = self::validate_parameters(self::get_contact_requests_parameters(), $params);
$capability = 'moodle/site:manageallmessaging';
throw new required_capability_exception($context, $capability, 'nopermissions', '');
}
- return \core_message\api::get_contact_requests($params['userid']);
+ return \core_message\api::get_contact_requests($params['userid'], $params['limitfrom'], $params['limitnum']);
}
/**
*/
public static function get_contact_requests_returns() {
return new external_multiple_structure(
- new external_single_structure(
- [
- 'id' => new external_value(core_user::get_property_type('id'), 'ID of the user'),
- 'contactrequestid' => new external_value(PARAM_INT, 'The ID of the contact request'),
- 'picture' => new external_value(core_user::get_property_type('picture'), 'The picture'),
- 'firstname' => new external_value(core_user::get_property_type('firstname'),
- 'The first name(s) of the user'),
- 'lastname' => new external_value(core_user::get_property_type('lastname'),
- 'The family name of the user'),
- 'firstnamephonetic' => new external_value(core_user::get_property_type('firstnamephonetic'),
- 'The phonetic first name of the user'),
- 'lastnamephonetic' => new external_value(core_user::get_property_type('lastnamephonetic'),
- 'The phonetic last name of the user'),
- 'middlename' => new external_value(core_user::get_property_type('middlename'),
- 'The middle name of the user'),
- 'alternatename' => new external_value(core_user::get_property_type('alternatename'),
- 'The alternate name of the user'),
- 'email' => new external_value(core_user::get_property_type('email'), 'An email address')
- ]
- )
+ self::get_conversation_member_structure()
);
}
* @return external_single_structure
* @since Moodle 3.6
*/
+
private static function get_conversation_structure() {
return new external_single_structure(
array(
'id' => new external_value(PARAM_INT, 'The conversation id'),
'name' => new external_value(PARAM_NOTAGS, 'The conversation name, if set', VALUE_DEFAULT, null),
'subname' => new external_value(PARAM_NOTAGS, 'A subtitle for the conversation name, if set', VALUE_DEFAULT, null),
+ 'imageurl' => new external_value(PARAM_URL, 'A link to the conversation picture, if set', VALUE_DEFAULT, null),
'type' => new external_value(PARAM_INT, 'The type of the conversation (1=individual,2=group)'),
'membercount' => new external_value(PARAM_INT, 'Total number of conversation members'),
'isfavourite' => new external_value(PARAM_BOOL, 'If the user marked conversation this conversation as a favourite'),
'unreadcount' => new external_value(PARAM_INT, 'The number of unread messages in this conversation',
VALUE_DEFAULT, null),
'members' => new external_multiple_structure(
- self::get_conversation_member_structure()
+ self::get_conversation_member_structure(true)
),
'messages' => new external_multiple_structure(
self::get_conversation_message_structure()
* Return the structure of a conversation member.
*
* @param bool $includecontactrequests Are we including contact requests?
+ * @param bool $includeconversations Are we including conversations?
* @return external_single_structure
* @since Moodle 3.6
*/
- private static function get_conversation_member_structure(bool $includecontactrequests = false) {
+ private static function get_conversation_member_structure(bool $includecontactrequests = false,
+ bool $includeconversations = false) {
$result = [
'id' => new external_value(PARAM_INT, 'The user id'),
'fullname' => new external_value(PARAM_NOTAGS, 'The user\'s name'),
'showonlinestatus' => new external_value(PARAM_BOOL, 'Show the user\'s online status?'),
'isblocked' => new external_value(PARAM_BOOL, 'If the user has been blocked'),
'iscontact' => new external_value(PARAM_BOOL, 'Is the user a contact?'),
+ 'isdeleted' => new external_value(PARAM_BOOL, 'Is the user deleted?'),
+ 'canmessage' => new external_value(PARAM_BOOL, 'If the user can be messaged'),
+ 'requirescontact' => new external_value(PARAM_BOOL, 'If the user requires to be contacts'),
];
if ($includecontactrequests) {
);
}
+ if ($includeconversations) {
+ $result['conversations'] = new external_multiple_structure(new external_single_structure(
+ array(
+ 'id' => new external_value(PARAM_INT, 'Conversations id'),
+ 'type' => new external_value(PARAM_INT, 'Conversation type: private or public'),
+ 'name' => new external_value(PARAM_TEXT, 'Multilang compatible conversation name'. VALUE_OPTIONAL),
+ 'timecreated' => new external_value(PARAM_INT, 'The timecreated timestamp for the conversation'),
+ ), 'information about conversation', VALUE_OPTIONAL),
+ 'Conversations between users', VALUE_OPTIONAL
+ );
+ }
+
return new external_single_structure(
$result
);
/**
* Get messagearea search users in course parameters.
*
+ * @deprecated since 3.6
+ *
* @return external_function_parameters
* @since 3.2
*/
/**
* Get messagearea search users in course results.
*
+ * @deprecated since 3.6
+ *
+ * NOTE: We are deprecating this function but not search_users_in_course API function for backwards compatibility
+ * with messaging UI. But should be removed once new group messaging UI is in place and old messaging UI is removed.
+ * Followup: MDL-63915
+ *
* @param int $userid The id of the user who is performing the search
* @param int $courseid The id of the course
* @param string $search The string being searched
/**
* Get messagearea search users in course returns.
*
+ * @deprecated since 3.6
+ *
* @return external_single_structure
* @since 3.2
*/
);
}
+ /**
+ * Marking the method as deprecated.
+ *
+ * @return bool
+ */
+ public static function data_for_messagearea_search_users_in_course_is_deprecated() {
+ return true;
+ }
+
/**
* Get messagearea search users parameters.
*
+ * @deprecated since 3.6
+ *
* @return external_function_parameters
* @since 3.2
*/
/**
* Get messagearea search users results.
*
+ * @deprecated since 3.6
+ *
+ * NOTE: We are deprecating this function but not search_users API function for backwards compatibility
+ * with messaging UI. But should be removed once new group messaging UI is in place and old messaging UI is removed.
+ * Followup: MDL-63915
+ *
* @param int $userid The id of the user who is performing the search
* @param string $search The string being searched
* @param int $limitnum
/**
* Get messagearea search users returns.
*
+ * @deprecated since 3.6
+ *
* @return external_single_structure
* @since 3.2
*/
);
}
+ /**
+ * Marking the method as deprecated.
+ *
+ * @return bool
+ */
+ public static function data_for_messagearea_search_users_is_deprecated() {
+ return true;
+ }
+
+ /**
+ * Get messagearea message search users parameters.
+ *
+ * @return external_function_parameters
+ * @since 3.6
+ */
+ public static function message_search_users_parameters() {
+ return new external_function_parameters(
+ array(
+ 'userid' => new external_value(PARAM_INT, 'The id of the user who is performing the search'),
+ 'search' => new external_value(PARAM_RAW, 'The string being searched'),
+ 'limitfrom' => new external_value(PARAM_INT, 'Limit from', VALUE_DEFAULT, 0),
+ 'limitnum' => new external_value(PARAM_INT, 'Limit number', VALUE_DEFAULT, 0),
+ )
+ );
+ }
+
+ /**
+ * Get search users results.
+ *
+ * @param int $userid The id of the user who is performing the search
+ * @param string $search The string being searched
+ * @param int $limitfrom
+ * @param int $limitnum
+ * @return array
+ * @throws moodle_exception
+ * @since 3.6
+ */
+ public static function message_search_users($userid, $search, $limitfrom = 0, $limitnum = 0) {
+ global $CFG, $USER;
+
+ // Check if messaging is enabled.
+ if (empty($CFG->messaging)) {
+ throw new moodle_exception('disabled', 'message');
+ }
+
+ $systemcontext = context_system::instance();
+
+ $params = array(
+ 'userid' => $userid,
+ 'search' => $search,
+ 'limitfrom' => $limitfrom,
+ 'limitnum' => $limitnum
+ );
+ $params = self::validate_parameters(self::message_search_users_parameters(), $params);
+ self::validate_context($systemcontext);
+
+ if (($USER->id != $params['userid']) && !has_capability('moodle/site:readallmessages', $systemcontext)) {
+ throw new moodle_exception('You do not have permission to perform this action.');
+ }
+
+ list($contacts, $noncontacts) = \core_message\api::message_search_users(
+ $params['userid'],
+ $params['search'],
+ $params['limitfrom'],
+ $params['limitnum']);
+
+ return array('contacts' => $contacts, 'noncontacts' => $noncontacts);
+ }
+
+ /**
+ * Get messagearea message search users returns.
+ *
+ * @return external_single_structure
+ * @since 3.2
+ */
+ public static function message_search_users_returns() {
+ return new external_single_structure(
+ array(
+ 'contacts' => new external_multiple_structure(
+ self::get_conversation_member_structure(false, true)
+ ),
+ 'noncontacts' => new external_multiple_structure(
+ self::get_conversation_member_structure(false, true)
+ )
+ )
+ );
+ }
+
/**
* Get messagearea search messages parameters.
*
/**
* The messagearea contacts return parameters.
*
+ * @deprecated since 3.6
* @return external_function_parameters
* @since 3.2
*/
/**
* Get messagearea contacts parameters.
*
+ * @deprecated since 3.6
* @param int $userid The id of the user who we are viewing conversations for
* @param int $limitfrom
* @param int $limitnum
/**
* The messagearea contacts return structure.
*
+ * @deprecated since 3.6
* @return external_single_structure
* @since 3.2
*/
return self::data_for_messagearea_conversations_returns();
}
+ /**
+ * Marking the method as deprecated.
+ *
+ * @return bool
+ */
+ public static function data_for_messagearea_contacts_is_deprecated() {
+ return true;
+ }
+
/**
* The messagearea messages parameters.
*
+ * @deprecated since 3.6
* @return external_function_parameters
* @since 3.2
*/
/**
* Get messagearea messages.
*
+ * @deprecated since 3.6
* @param int $currentuserid The current user's id
* @param int $otheruserid The other user's id
* @param int $limitfrom
/**
* The messagearea messages return structure.
*
+ * @deprecated since 3.6
* @return external_single_structure
* @since 3.2
*/
);
}
+ /**
+ * Marking the method as deprecated.
+ *
+ * @return bool
+ */
+ public static function data_for_messagearea_messages_is_deprecated() {
+ return true;
+ }
+
/**
* The conversation messages parameters.
*
/**
* The get most recent message return parameters.
*
+ * @deprecated since 3.6
* @return external_function_parameters
* @since 3.2
*/
/**
* Get the most recent message in a conversation.
*
+ * @deprecated since 3.6
* @param int $currentuserid The current user's id
* @param int $otheruserid The other user's id
* @return stdClass
/**
* The get most recent message return structure.
*
+ * @deprecated since 3.6
* @return external_single_structure
* @since 3.2
*/
return self::get_messagearea_message_structure();
}
+ /**
+ * Marking the method as deprecated.
+ *
+ * @return bool
+ */
+ public static function data_for_messagearea_get_most_recent_message_is_deprecated() {
+ return true;
+ }
+
/**
* The get profile parameters.
*
+ * @deprecated since 3.6
* @return external_function_parameters
* @since 3.2
*/
/**
* Get the profile information for a contact.
*
+ * @deprecated since 3.6
* @param int $currentuserid The current user's id
* @param int $otheruserid The id of the user whose profile we are viewing
* @return stdClass
/**
* The get profile return structure.
*
+ * @deprecated since 3.6
* @return external_single_structure
* @since 3.2
*/
);
}
+ /**
+ * Marking the method as deprecated.
+ *
+ * @return bool
+ */
+ public static function data_for_messagearea_get_profile_is_deprecated() {
+ return true;
+ }
+
/**
* Get contacts parameters description.
*
