Class used to return information to display for the message area. More...

Static Public Member Functions
static	add_contact (int $userid, int $contactid)
	Handles adding a contact. More...

static	add_members_to_conversation (array $userids, int $convid)
	Add some new members to an existing conversation. More...

static	block_user (int $userid, int $usertoblockid)
	Handles blocking a user. More...

static	can_create_contact (int $userid, int $requesteduserid)
	Checks if a user can create a contact request. More...

static	can_create_group_conversation (int $userid, context $context)
	Checks if a user can create a group conversation. More...

static	can_delete_conversation (int $userid, int $conversationid=null)
	Checks if a user can delete messages they have either received or sent. More...

static	can_delete_message ($userid, $messageid)
	Checks if a user can delete a message. More...

static	can_delete_message_for_all_users (int $userid, int $messageid)
	Checks if a user can delete a message for all users. More...

static	can_mark_all_messages_as_read (int $userid, int $conversationid)
	Checks if a user can mark all messages as read. More...

static	can_post_message ($recipient, $sender=null)
	Determines if a user is permitted to send another user a private message. More...

static	can_send_message (int $recipientid, int $senderid, bool $evenifblocked=false)
	Determines if a user is permitted to send another user a private message. More...

static	can_send_message_to_conversation (int $userid, int $conversationid)
	Determines if a user is permitted to send a message to a given conversation. More...

static	confirm_contact_request (int $userid, int $requesteduserid)
	Handles confirming a contact request. More...

static	count_blocked_users ($user=null)
	Count the number of users blocked by a user. More...

static	count_contacts (int $userid)
	Returns the contacts count. More...

static	count_conversation_members (int $convid)
	Count conversation members. More...

static	count_unread_conversations ($user=null)
	Returns the count of unread conversations (collection of messages from a single user) for the given user. More...

static	create_contact_request (int $userid, int $requesteduserid)
	Handles creating a contact request. More...

static	create_conversation (int $type, array $userids, string $name=null, int $enabled=self::MESSAGE_CONVERSATION_ENABLED, string $component=null, string $itemtype=null, int $itemid=null, int $contextid=null)
	Creates a conversation with selected users and messages. More...

static	create_conversation_between_users (array $userids)
	Creates a conversation between two users. More...

static	decline_contact_request (int $userid, int $requesteduserid)
	Handles declining a contact request. More...

static	delete_all_conversation_data (int $conversationid)
	Completely removes all related data in the DB for a given conversation. More...

static	delete_conversation ($userid, $otheruserid)
	Deletes a conversation. More...

static	delete_conversation_by_id (int $userid, int $conversationid)
	Deletes a conversation for a specified user. More...

static	delete_message ($userid, $messageid)
	Deletes a message. More...

static	delete_message_for_all_users (int $messageid)
	Delete a message for all users. More...

static	disable_conversation (int $conversationid)
	Disable a conversation. More...

static	does_contact_request_exist (int $userid, int $requesteduserid)
	Checks if a contact request already exists between users. More...

static	enable_conversation (int $conversationid)
	Enable a conversation. More...

static	get_all_message_preferences ($processors, $providers, $user)
	Returns message preferences. More...

static	get_blocked_users ($userid)
	Retrieve users blocked by $user1. More...

static	get_contact (int $userid, int $contactid)
	Returns the row in the database table message_contacts that represents the contact between two people. More...

static	get_contact_requests (int $userid, int $limitfrom=0, int $limitnum=0)
	Handles returning the contact requests for a user. More...

static	get_contact_requests_between_users (int $userid, int $requesteduserid)
	Get contact requests between users. More...

static	get_contacts ($userid, $limitfrom=0, $limitnum=0)
	Returns the contacts to display in the contacts area. More...

static	get_contacts_with_unread_message_count ($userid, $limitfrom=0, $limitnum=0)
	Returns the an array of the users the given user is in a conversation with who are a contact and the number of unread messages. More...

static	get_conversation (int $userid, int $conversationid, bool $includecontactrequests=false, bool $includeprivacyinfo=false, int $memberlimit=0, int $memberoffset=0, int $messagelimit=0, int $messageoffset=0, bool $newestmessagesfirst=true)
	Return a conversation. More...

static	get_conversation_between_users (array $userids)
	Returns the conversation between two users. More...

static	get_conversation_by_area (string $component, string $itemtype, int $itemid, int $contextid)
	Get conversation by area. More...

static	get_conversation_counts (int $userid)
	Returns the count of conversations (collection of messages from a single user) for the given user. More...

static	get_conversation_members (int $userid, int $conversationid, bool $includecontactrequests=false, bool $includeprivacyinfo=false, int $limitfrom=0, int $limitnum=0)
	Returns a list of conversation members. More...

static	get_conversation_messages (int $userid, int $convid, int $limitfrom=0, int $limitnum=0, string $sort='timecreated ASC', int $timefrom=0, int $timeto=0)
	Returns the messages for the defined conversation. More...

static	get_conversations ($userid, $limitfrom=0, $limitnum=20, int $type=null, bool $favourites=null, bool $mergeself=false)
	Returns the contacts and their conversation to display in the contacts area. More...

static	get_conversations_between_users (int $userid1, int $userid2, int $limitfrom=0, int $limitnum=20)
	Returns all conversations between two users. More...

static	get_individual_conversations_between_users (array $useridsets)
	Returns the conversations between sets of users. More...

static	get_message_processor ($name, $ready=false)
	Get specified message processor, validate corresponding plugin existence and system configuration. More...

static	get_messages ($userid, $otheruserid, $limitfrom=0, $limitnum=0, $sort='timecreated ASC', $timefrom=0, $timeto=0)
	Returns the messages to display in the message area. More...

static	get_most_recent_conversation_message (int $convid, int $currentuserid=0)
	Returns the most recent message in a conversation. More...

static	get_most_recent_message ($userid, $otheruserid)
	Returns the most recent message between two users. More...

static	get_non_contacts_with_unread_message_count ($userid, $limitfrom=0, $limitnum=0)
	Returns the an array of the users the given user is in a conversation with who are not a contact and the number of unread messages. More...

static	get_processed_processor_object (\stdClass $processor)
	Given a processor object, loads information about it's settings and configurations. More...

static	get_profile ($userid, $otheruserid)
	Returns the profile information for a contact for a user. More...

static	get_received_contact_requests_count (int $userid)
	Returns the number of contact requests the user has received. More...

static	get_self_conversation (int $userid)
	Returns the self conversation for a user. More...

static	get_unread_conversation_counts (int $userid)
	Get the unread counts for all conversations for the user, sorted by type, and including favourites. More...

static	get_user_contacts (int $userid, int $limitfrom=0, int $limitnum=0)
	Get the contacts for a given user. More...

static	get_user_privacy_messaging_preference (int $userid)
	Get the messaging preference for a user. More...

static	is_blocked (int $userid, int $blockeduserid)
	Checks if a user is already blocked. More...

static	is_contact (int $userid, int $contactid)
	Checks if users are already contacts. More...

static	is_conversation_area_enabled (string $component, string $itemtype, int $itemid, int $contextid)
	Checks whether or not a conversation area is enabled. More...

static	is_conversation_muted (int $userid, int $conversationid)
	Checks whether a conversation is muted or not. More...

static	is_processor_enabled ($name)
	Returns weather a given processor is enabled or not. More...

static	is_user_blocked ($recipientid, $senderid=null)
	Checks if the recipient has specifically blocked the sending user. More...

static	is_user_in_conversation (int $userid, int $conversationid)
	Checks if a user is already in a conversation. More...

static	is_user_non_contact_blocked ($recipient, $sender=null)
	Checks if the recipient is allowing messages from users that aren't a contact. More...

static	mark_all_messages_as_read ($userid, $conversationid=null)
	Marks all messages being sent to a user in a particular conversation. More...

static	mark_all_notifications_as_read ($touserid, $fromuserid=null, $timecreatedto=null)
	Marks all notifications being sent from one user to another user as read. More...

static	mark_all_read_for_user ()

static	mark_message_as_read ($userid, $message, $timeread=null)
	Mark a single message as read. More...

static	mark_notification_as_read ($notification, $timeread=null)
	Mark a single notification as read. More...

static	message_search_users (int $userid, string $search, int $limitfrom=0, int $limitnum=20)
	Handles searching for user. More...

static	mute_conversation (int $userid, int $conversationid)
	Handles muting a conversation. More...

static	remove_contact (int $userid, int $contactid)
	Handles removing a contact. More...

static	remove_members_from_conversation (array $userids, int $convid)
	Remove some members from an existing conversation. More...

static	search_messages ($userid, $search, $limitfrom=0, $limitnum=0)
	Handles searching for messages in the message area. More...

static	search_users ($userid, $search, $limitnum=0)
	Handles searching for user in the message area. More...

static	search_users_in_course ($userid, $courseid, $search, $limitfrom=0, $limitnum=0)
	Handles searching for user in a particular course in the message area. More...

static	send_message_to_conversation (int $userid, int $conversationid, string $message, int $format)
	Send a message from a user to a conversation. More...

static	set_favourite_conversation (int $conversationid, int $userid)
	Mark a conversation as a favourite for the given user. More...

static	unblock_user (int $userid, int $usertounblockid)
	Handles unblocking a user. More...

static	unmute_conversation (int $userid, int $conversationid)
	Handles unmuting a conversation. More...

static	unset_favourite_conversation (int $conversationid, int $userid)
	Unset a conversation as a favourite for the given user. More...

static	update_conversation_name (int $conversationid, string $name)
	Update the name of a conversation. More...

static	update_processor_status ($processor, $enabled)
	Set status of a processor. More...

Public Attributes
const	CONVERSATION_ACTION_MUTED = 1
	The action for reading a message.

const	MESSAGE_ACTION_DELETED = 2
	The action for deleting a message.

const	MESSAGE_ACTION_READ = 1
	The action for reading a message.

const	MESSAGE_CONVERSATION_DISABLED = 0
	The state for a disabled conversation area.

const	MESSAGE_CONVERSATION_ENABLED = 1
	The state for an enabled conversation area.

const	MESSAGE_CONVERSATION_TYPE_GROUP = 2
	A group conversation.

const	MESSAGE_CONVERSATION_TYPE_INDIVIDUAL = 1
	An individual conversation.

const	MESSAGE_CONVERSATION_TYPE_SELF = 3
	A self conversation.

const	MESSAGE_MAX_LENGTH = 4096
	The max message length.

const	MESSAGE_PRIVACY_COURSEMEMBER = 0
	The privacy setting for being messaged by anyone within courses user is member of.

const	MESSAGE_PRIVACY_ONLYCONTACTS = 1
	The privacy setting for being messaged only by contacts.

const	MESSAGE_PRIVACY_SITE = 2
	The privacy setting for being messaged by anyone on the site.

Static Protected Member Functions
static	can_contact_user (int $recipientid, int $senderid, bool $evenifblocked=false)
	Checks if the sender can message the recipient. More...

static	get_linked_conversation_extra_fields (array $conversations)
	Gets extra fields, like image url and subname for any conversations linked to components. More...

static	lazy_create_self_conversation (int $userid)
	Create a self conversation for a user, only if one doesn't already exist. More...

Detailed Description

Class used to return information to display for the message area.

Copyright: 2016 Mark Nelson markn.nosp@m.@moo.nosp@m.dle.c.nosp@m.om

License: http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

Member Function Documentation

◆ add_contact()

static core_message\api::add_contact	(	int	$userid,
		int	$contactid
	)

static

Handles adding a contact.

Parameters

int	$userid	The id of the user who requested to be a contact
int	$contactid	The id of the contact

◆ add_members_to_conversation()

static core_message\api::add_members_to_conversation	(	array	$userids,
		int	$convid
	)

static

Add some new members to an existing conversation.

Parameters

array	$userids	User ids array to add as members.
int	$convid	The conversation id. Must exists.

Exceptions

dml_missing_record_exception	If convid conversation doesn't exist
dml_exception	If there is a database error
moodle_exception	If trying to add a member(s) to a non-group conversation

◆ block_user()

static core_message\api::block_user	(	int	$userid,
		int	$usertoblockid
	)

static

Handles blocking a user.

Parameters

int	$userid	The id of the user who is blocking
int	$usertoblockid	The id of the user being blocked

◆ can_contact_user()

static core_message\api::can_contact_user	(	int	$recipientid,
		int	$senderid,
		bool	$evenifblocked = `false`
	)

staticprotected

Checks if the sender can message the recipient.

Parameters

int	$recipientid
int	$senderid
bool	$evenifblocked	This lets the user know, that even if the recipient has blocked the user the user is still able to send a message.

Return values

bool	true if recipient hasn't blocked sender and sender can contact to recipient, false otherwise.

◆ can_create_contact()

static core_message\api::can_create_contact	(	int	$userid,
		int	$requesteduserid
	)

static

Checks if a user can create a contact request.

Parameters

int	$userid	The id of the user who is creating the contact request
int	$requesteduserid	The id of the user being requested

Return values

bool

◆ can_create_group_conversation()

static core_message\api::can_create_group_conversation	(	int	$userid,
		context	$context
	)

static

Checks if a user can create a group conversation.

Parameters

int	$userid	The id of the user attempting to create the conversation
context	$context	The context they are creating the conversation from, most likely course context

Return values

bool

◆ can_delete_conversation()

static core_message\api::can_delete_conversation	(	int	$userid,
		int	$conversationid = `null`
	)

static

Checks if a user can delete messages they have either received or sent.

Parameters

int	$userid	The user id of who we want to delete the messages for (this may be done by the admin but will still seem as if it was by the user)
int	$conversationid	The id of the conversation

Return values

bool	Returns true if a user can delete the conversation, false otherwise.

◆ can_delete_message()

static core_message\api::can_delete_message	(	$userid,
		$messageid
	)

static

Checks if a user can delete a message.

Parameters

int	$userid	the user id of who we want to delete the message for (this may be done by the admin but will still seem as if it was by the user)
int	$messageid	The message id

Return values

bool	Returns true if a user can delete the message, false otherwise.

◆ can_delete_message_for_all_users()

static core_message\api::can_delete_message_for_all_users	(	int	$userid,
		int	$messageid
	)

static

Checks if a user can delete a message for all users.

Parameters

int	$userid	the user id of who we want to delete the message for all users
int	$messageid	The message id

Return values

bool	Returns true if a user can delete the message for all users, false otherwise.

◆ can_mark_all_messages_as_read()

static core_message\api::can_mark_all_messages_as_read	(	int	$userid,
		int	$conversationid
	)

static

Checks if a user can mark all messages as read.

Parameters

int	$userid	The user id of who we want to mark the messages for
int	$conversationid	The id of the conversation

Return values

bool	true if user is permitted, false otherwise

Since: 3.6

◆ can_post_message()

static core_message\api::can_post_message	(	$recipient,
		$sender = `null`
	)

static

Determines if a user is permitted to send another user a private message.

If no sender is provided then it defaults to the logged in user.

Deprecated:: since 3.8

Todo:: Final deprecation in MDL-66266

Parameters

stdClass	$recipient	The user object.
stdClass \| null	$sender	The user object.

Return values

bool	true if user is permitted, false otherwise.

◆ can_send_message()

static core_message\api::can_send_message	(	int	$recipientid,
		int	$senderid,
		bool	$evenifblocked = `false`
	)

static

Determines if a user is permitted to send another user a private message.

Parameters

int	$recipientid	The recipient user id.
int	$senderid	The sender user id.
bool	$evenifblocked	This lets the user know, that even if the recipient has blocked the user the user is still able to send a message.

Return values

bool	true if user is permitted, false otherwise.

◆ can_send_message_to_conversation()

static core_message\api::can_send_message_to_conversation	(	int	$userid,
		int	$conversationid
	)

static

Determines if a user is permitted to send a message to a given conversation.

If no sender is provided then it defaults to the logged in user.

Parameters

int	$userid	the id of the user on which the checks will be applied.
int	$conversationid	the id of the conversation we wish to check.

Return values

bool	true if the user can send a message to the conversation, false otherwise.

Exceptions

moodle_exception

◆ confirm_contact_request()

static core_message\api::confirm_contact_request	(	int	$userid,
		int	$requesteduserid
	)

static

Handles confirming a contact request.

Parameters

int	$userid	The id of the user who created the contact request
int	$requesteduserid	The id of the user confirming the request

◆ count_blocked_users()

static core_message\api::count_blocked_users ( $user = null )

static

Count the number of users blocked by a user.

Parameters

stdClass $user The user object

Return values

int	the number of blocked users

◆ count_contacts()

static core_message\api::count_contacts ( int $userid )

static

Returns the contacts count.

Parameters

int $userid The user id

Return values

array

◆ count_conversation_members()

static core_message\api::count_conversation_members ( int $convid )

static

Count conversation members.

Parameters

int $convid The conversation id.

Return values

int	Number of conversation members.

Exceptions

dml_exception

◆ count_unread_conversations()

static core_message\api::count_unread_conversations ( $user = null )

static

Returns the count of unread conversations (collection of messages from a single user) for the given user.

Parameters

stdClass $user the user who's conversations should be counted

Return values

int	the count of the user's unread conversations

◆ create_contact_request()

static core_message\api::create_contact_request	(	int	$userid,
		int	$requesteduserid
	)

static

Handles creating a contact request.

Parameters

int	$userid	The id of the user who is creating the contact request
int	$requesteduserid	The id of the user being requested

Return values

stdClass the request

◆ create_conversation()

static core_message\api::create_conversation	(	int	$type,
		array	$userids,
		string	$name = `null`,
		int	$enabled = `self::MESSAGE_CONVERSATION_ENABLED`,
		string	$component = `null`,
		string	$itemtype = `null`,
		int	$itemid = `null`,
		int	$contextid = `null`
	)

static

Creates a conversation with selected users and messages.

Parameters

int	$type	The type of conversation
int[]	$userids	The array of users to add to the conversation
string \| null	$name	The name of the conversation
int	$enabled	Determines if the conversation is created enabled or disabled
string \| null	$component	Defines the Moodle component which the conversation belongs to, if any
string \| null	$itemtype	Defines the type of the component
int \| null	$itemid	The id of the component
int \| null	$contextid	The id of the context

Return values

stdClass

◆ create_conversation_between_users()

static core_message\api::create_conversation_between_users ( array $userids )

static

Creates a conversation between two users.

Deprecated:: since 3.6

Parameters

array $userids

Return values

int	The id of the conversation

◆ decline_contact_request()

static core_message\api::decline_contact_request	(	int	$userid,
		int	$requesteduserid
	)

static

Handles declining a contact request.

Parameters

int	$userid	The id of the user who created the contact request
int	$requesteduserid	The id of the user declining the request

◆ delete_all_conversation_data()

static core_message\api::delete_all_conversation_data ( int $conversationid )

static

Completely removes all related data in the DB for a given conversation.

Parameters

int $conversationid The id of the conversation

◆ delete_conversation()

static core_message\api::delete_conversation	(	$userid,
		$otheruserid
	)

static

Deletes a conversation.

This function does not verify any permissions.

Deprecated:: since 3.6

Parameters

int	$userid	The user id of who we want to delete the messages for (this may be done by the admin but will still seem as if it was by the user)
int	$otheruserid	The id of the other user in the conversation

Return values

bool

◆ delete_conversation_by_id()

static core_message\api::delete_conversation_by_id	(	int	$userid,
		int	$conversationid
	)

static

Deletes a conversation for a specified user.

This function does not verify any permissions.

Parameters

int	$userid	The user id of who we want to delete the messages for (this may be done by the admin but will still seem as if it was by the user)
int	$conversationid	The id of the other user in the conversation

◆ delete_message()

static core_message\api::delete_message	(	$userid,
		$messageid
	)

static

Deletes a message.

This function does not verify any permissions.

Parameters

int	$userid	the user id of who we want to delete the message for (this may be done by the admin but will still seem as if it was by the user)
int	$messageid	The message id

Return values

bool

◆ delete_message_for_all_users()

static core_message\api::delete_message_for_all_users ( int $messageid )

static

Delete a message for all users.

This function does not verify any permissions.

Parameters

int $messageid The message id

Return values

void

◆ disable_conversation()

static core_message\api::disable_conversation ( int $conversationid )

static

Disable a conversation.

Parameters

int $conversationid The id of the conversation.

Return values

void

◆ does_contact_request_exist()

static core_message\api::does_contact_request_exist	(	int	$userid,
		int	$requesteduserid
	)

static

Checks if a contact request already exists between users.

Parameters

int	$userid	The id of the user who is creating the contact request
int	$requesteduserid	The id of the user being requested

Return values

bool	Returns true if a contact request exists, false otherwise

◆ enable_conversation()

static core_message\api::enable_conversation ( int $conversationid )

static

Enable a conversation.

Parameters

int $conversationid The id of the conversation.

Return values

void

◆ get_all_message_preferences()

static core_message\api::get_all_message_preferences	(	$processors,
		$providers,
		$user
	)

static

Returns message preferences.

Parameters

array	$processors
array	$providers
stdClass	$user

Return values

stdClass

Since: 3.2

◆ get_blocked_users()

static core_message\api::get_blocked_users ( $userid )

static

Retrieve users blocked by $user1.

Parameters

int $userid The user id of the user whos blocked users we are returning

Return values

array the users blocked

◆ get_contact()

static core_message\api::get_contact	(	int	$userid,
		int	$contactid
	)

static

Returns the row in the database table message_contacts that represents the contact between two people.

Parameters

int	$userid	The id of one of the users
int	$contactid	The id of the other user

Return values

mixed A fieldset object containing the record, false otherwise

◆ get_contact_requests()

static core_message\api::get_contact_requests	(	int	$userid,
		int	$limitfrom = `0`,
		int	$limitnum = `0`
	)

static

Handles returning the contact requests for a user.

This also includes the user data necessary to display information about the user.

It will not include blocked users.

Parameters

int	$userid
int	$limitfrom
int	$limitnum

Return values

array The list of contact requests

◆ get_contact_requests_between_users()

static core_message\api::get_contact_requests_between_users	(	int	$userid,
		int	$requesteduserid
	)

static

Get contact requests between users.

Parameters

int	$userid	The id of the user who is creating the contact request
int	$requesteduserid	The id of the user being requested

Return values

stdClass[]

◆ get_contacts()

static core_message\api::get_contacts	(	$userid,
		$limitfrom = `0`,
		$limitnum = `0`
	)

static

Returns the contacts to display in the contacts area.

TODO: This function should be removed once the related web service goes through final deprecation. The related web service is data_for_messagearea_contacts. Followup: MDL-63261

Parameters

int	$userid	The user id
int	$limitfrom
int	$limitnum

Return values

array

◆ get_contacts_with_unread_message_count()

static core_message\api::get_contacts_with_unread_message_count	(	$userid,
		$limitfrom = `0`,
		$limitnum = `0`
	)

static

Returns the an array of the users the given user is in a conversation with who are a contact and the number of unread messages.

Parameters

int	$userid	The user id
int	$limitfrom
int	$limitnum

Return values

array

◆ get_conversation()

static core_message\api::get_conversation	(	int	$userid,
		int	$conversationid,
		bool	$includecontactrequests = `false`,
		bool	$includeprivacyinfo = `false`,
		int	$memberlimit = `0`,
		int	$memberoffset = `0`,
		int	$messagelimit = `0`,
		int	$messageoffset = `0`,
		bool	$newestmessagesfirst = `true`
	)

static

Return a conversation.

Parameters

int	$userid	The user id to get the conversation for
int	$conversationid	The id of the conversation to fetch
bool	$includecontactrequests	Should contact requests be included between members
bool	$includeprivacyinfo	Should privacy info be included between members
int	$memberlimit	Limit number of members to load
int	$memberoffset	Offset members by this amount
int	$messagelimit	Limit number of messages to load
int	$messageoffset	Offset the messages
bool	$newestmessagesfirst	Order messages by newest first

Return values

stdClass

◆ get_conversation_between_users()

static core_message\api::get_conversation_between_users ( array $userids )

static

Returns the conversation between two users.

Parameters

array $userids

Return values

int|bool The id of the conversation, false if not found

◆ get_conversation_by_area()

static core_message\api::get_conversation_by_area	(	string	$component,
		string	$itemtype,
		int	$itemid,
		int	$contextid
	)

static

Get conversation by area.

Parameters

string	$component	Defines the Moodle component which the area was added to.
string	$itemtype	Defines the type of the component.
int	$itemid	The id of the component.
int	$contextid	The id of the context.

Return values

stdClass

◆ get_conversation_counts()

static core_message\api::get_conversation_counts ( int $userid )

static

Returns the count of conversations (collection of messages from a single user) for the given user.

Parameters

int $userid The user whose conversations should be counted.

Return values

array the array of conversations counts, indexed by type.

◆ get_conversation_members()

static core_message\api::get_conversation_members	(	int	$userid,
		int	$conversationid,
		bool	$includecontactrequests = `false`,
		bool	$includeprivacyinfo = `false`,
		int	$limitfrom = `0`,
		int	$limitnum = `0`
	)

static

Returns a list of conversation members.

Parameters

int	$userid	The user we are returning the conversation members for, used by helper::get_member_info.
int	$conversationid	The id of the conversation
bool	$includecontactrequests	Do we want to include contact requests with this data?
bool	$includeprivacyinfo	Do we want to include privacy requests with this data?
int	$limitfrom
int	$limitnum

Return values

array

◆ get_conversation_messages()

static core_message\api::get_conversation_messages	(	int	$userid,
		int	$convid,
		int	$limitfrom = `0`,
		int	$limitnum = `0`,
		string	$sort = `'timecreated ASC'`,
		int	$timefrom = `0`,
		int	$timeto = `0`
	)

static

Returns the messages for the defined conversation.

Parameters

int	$userid	The current user.
int	$convid	The conversation where the messages belong. Could be an object or just the id.
int	$limitfrom	Return a subset of records, starting at this point (optional).
int	$limitnum	Return a subset comprising this many records in total (optional, required if $limitfrom is set).
string	$sort	The column name to order by including optionally direction.
int	$timefrom	The time from the message being sent.
int	$timeto	The time up until the message being sent.

Return values

array of messages

◆ get_conversations()

static core_message\api::get_conversations	(		$userid,
			$limitfrom = `0`,
			$limitnum = `20`,
		int	$type = `null`,
		bool	$favourites = `null`,
		bool	$mergeself = `false`
	)

static

Returns the contacts and their conversation to display in the contacts area.

** WARNING ** It is HIGHLY recommended to use a sensible limit when calling this function. Trying to retrieve too much information in a single call will cause performance problems. ** WARNING **

This function has specifically been altered to break each of the data sets it requires into separate database calls. This is to avoid the performance problems observed when attempting to join large data sets (e.g. the message tables and the user table).

While it is possible to gather the data in a single query, and it may even be more efficient with a correctly tuned database, we have opted to trade off some of the benefits of a single query in order to ensure this function will work on most databases with default tunings and with large data sets.

Parameters

int	$userid	The user id
int	$limitfrom
int	$limitnum
int	$type	the type of the conversation, if you wish to filter to a certain type (see api constants).
bool	$favourites	whether to include NO favourites (false) or ONLY favourites (true), or null to ignore this setting.
bool	$mergeself	whether to include self-conversations (true) or ONLY private conversations (false) when private conversations are requested.

Return values

array the array of conversations

Exceptions

moodle_exception

◆ get_conversations_between_users()

static core_message\api::get_conversations_between_users	(	int	$userid1,
		int	$userid2,
		int	$limitfrom = `0`,
		int	$limitnum = `20`
	)

static

Returns all conversations between two users.

Parameters

int	$userid1	One of the user's id
int	$userid2	The other user's id
int	$limitfrom
int	$limitnum

Return values

array

Exceptions

dml_exception

◆ get_individual_conversations_between_users()

static core_message\api::get_individual_conversations_between_users ( array $useridsets )

static

Returns the conversations between sets of users.

The returned array of results will be in the same order as the requested arguments, null will be returned if there is no conversation for that user pair.

For example: If we have 6 users with ids 1, 2, 3, 4, 5, 6 where only 2 conversations exist. One between 1 and 2 and another between 5 and 6.

Then if we call: $conversations = get_individual_conversations_between_users([[1,2], [3,4], [5,6]]);

The conversations array will look like: [<conv_record>, null, <conv_record>];

Where null is returned for the pairing of [3, 4] since no record exists.

Deprecated:: since 3.8

Parameters

array $useridsets An array of arrays where the inner array is the set of user ids

Return values

stdClass[] Array of conversation records

◆ get_linked_conversation_extra_fields()

static core_message\api::get_linked_conversation_extra_fields ( array $conversations )

staticprotected

Gets extra fields, like image url and subname for any conversations linked to components.

The subname is like a subtitle for the conversation, to compliment it's name. The imageurl is the location of the image for the conversation, as might be seen on a listing of conversations for a user.

Parameters

array $conversations a list of conversations records.

Return values

array the array of subnames, index by conversation id.

Exceptions

coding_exception
dml_exception

◆ get_message_processor()

static core_message\api::get_message_processor	(	$name,
		$ready = `false`
	)

static

Get specified message processor, validate corresponding plugin existence and system configuration.

Parameters

string	$name	Name of the processor.
bool	$ready	only return ready-to-use processors.

Return values

mixed::$processor if processor present else empty array.

Since: Moodle 3.2

◆ get_messages()

static core_message\api::get_messages	(	$userid,
		$otheruserid,
		$limitfrom = `0`,
		$limitnum = `0`,
		$sort = `'timecreated ASC'`,
		$timefrom = `0`,
		$timeto = `0`
	)

static

Returns the messages to display in the message area.

TODO: This function should be removed once the related web service goes through final deprecation. The related web service is data_for_messagearea_messages. Followup: MDL-63261

Parameters

int	$userid	the current user
int	$otheruserid	the other user
int	$limitfrom
int	$limitnum
string	$sort
int	$timefrom	the time from the message being sent
int	$timeto	the time up until the message being sent

Return values

array

◆ get_most_recent_conversation_message()

static core_message\api::get_most_recent_conversation_message	(	int	$convid,
		int	$currentuserid = `0`
	)

static

Returns the most recent message in a conversation.

Parameters

int	$convid	The conversation identifier.
int	$currentuserid	The current user identifier.

Return values

stdClass|null The most recent message.

◆ get_most_recent_message()

static core_message\api::get_most_recent_message	(	$userid,
		$otheruserid
	)

static

Returns the most recent message between two users.

TODO: This function should be removed once the related web service goes through final deprecation. The related web service is data_for_messagearea_get_most_recent_message. Followup: MDL-63261

Parameters

int	$userid	the current user
int	$otheruserid	the other user

Return values

stdClass|null

◆ get_non_contacts_with_unread_message_count()

static core_message\api::get_non_contacts_with_unread_message_count	(	$userid,
		$limitfrom = `0`,
		$limitnum = `0`
	)

static

Returns the an array of the users the given user is in a conversation with who are not a contact and the number of unread messages.

Parameters

int	$userid	The user id
int	$limitfrom
int	$limitnum

Return values

array

◆ get_processed_processor_object()

static core_message\api::get_processed_processor_object ( \stdClass $processor )

static

Given a processor object, loads information about it's settings and configurations.

This is not a public api, instead use

See also: core_message::api::get_message_processor() or; get_message_processors()

Parameters

stdClass $processor processor object

Return values

stdClass processed processor object

Since: Moodle 3.2

◆ get_profile()

static core_message\api::get_profile	(	$userid,
		$otheruserid
	)

static

Returns the profile information for a contact for a user.

TODO: This function should be removed once the related web service goes through final deprecation. The related web service is data_for_messagearea_get_profile. Followup: MDL-63261

Parameters

int	$userid	The user id
int	$otheruserid	The id of the user whose profile we want to view.

Return values

stdClass

◆ get_received_contact_requests_count()

static core_message\api::get_received_contact_requests_count ( int $userid )

static

Returns the number of contact requests the user has received.

Parameters

int $userid The ID of the user we want to return the number of received contact requests for

Return values

int The count

◆ get_self_conversation()

static core_message\api::get_self_conversation ( int $userid )

static

Returns the self conversation for a user.

Parameters

int $userid The user id to get the self-conversations

Return values

stdClass|false The self-conversation object or false if it doesn't exist

Since: Moodle 3.7

◆ get_unread_conversation_counts()

static core_message\api::get_unread_conversation_counts ( int $userid )

static

Get the unread counts for all conversations for the user, sorted by type, and including favourites.

Parameters

int $userid the id of the user whose conversations we'll check.

Return values

array the unread counts for each conversation, indexed by type.

◆ get_user_contacts()

static core_message\api::get_user_contacts	(	int	$userid,
		int	$limitfrom = `0`,
		int	$limitnum = `0`
	)

static

Get the contacts for a given user.

Parameters

int	$userid
int	$limitfrom
int	$limitnum

Return values

array An array of contacts

◆ get_user_privacy_messaging_preference()

static core_message\api::get_user_privacy_messaging_preference ( int $userid )

static

Get the messaging preference for a user.

If the user has not any messaging privacy preference:

When $CFG->messagingallusers = false the default user preference is MESSAGE_PRIVACY_COURSEMEMBER.
When $CFG->messagingallusers = true the default user preference is MESSAGE_PRIVACY_SITE.

Parameters

int $userid The user identifier.

Return values

int	The default messaging preference.

◆ is_blocked()

static core_message\api::is_blocked	(	int	$userid,
		int	$blockeduserid
	)

static

Checks if a user is already blocked.

Parameters

int	$userid
int	$blockeduserid

Return values

bool	Returns true if they are a blocked, false otherwise

◆ is_contact()

static core_message\api::is_contact	(	int	$userid,
		int	$contactid
	)

static

Checks if users are already contacts.

Parameters

int	$userid	The id of one of the users
int	$contactid	The id of the other user

Return values

bool	Returns true if they are a contact, false otherwise

◆ is_conversation_area_enabled()

static core_message\api::is_conversation_area_enabled	(	string	$component,
		string	$itemtype,
		int	$itemid,
		int	$contextid
	)

static

Checks whether or not a conversation area is enabled.

Parameters

string	$component	Defines the Moodle component which the area was added to.
string	$itemtype	Defines the type of the component.
int	$itemid	The id of the component.
int	$contextid	The id of the context.

Return values

bool	Returns if a conversation area exists and is enabled, false otherwise

◆ is_conversation_muted()

static core_message\api::is_conversation_muted	(	int	$userid,
		int	$conversationid
	)

static

Checks whether a conversation is muted or not.

Parameters

int	$userid	The id of the user
int	$conversationid	The id of the conversation

Return values

bool	Whether or not the conversation is muted or not

◆ is_processor_enabled()

static core_message\api::is_processor_enabled ( $name )

static

Returns weather a given processor is enabled or not.

Note:- This doesn't check if the processor is configured or not.

Parameters

string $name Name of the processor

Return values

bool

◆ is_user_blocked()

static core_message\api::is_user_blocked	(	$recipientid,
		$senderid = `null`
	)

static

Checks if the recipient has specifically blocked the sending user.

Note: This function will always return false if the sender has the readallmessages capability at the system context level.

Deprecated:: since 3.6

Parameters

int	$recipientid	User ID of the recipient.
int	$senderid	User ID of the sender.

Return values

bool	true if $sender is blocked, false otherwise.

◆ is_user_in_conversation()

static core_message\api::is_user_in_conversation	(	int	$userid,
		int	$conversationid
	)

static

Checks if a user is already in a conversation.

Parameters

int	$userid	The id of the user we want to check if they are in a group
int	$conversationid	The id of the conversation

Return values

bool	Returns true if a contact request exists, false otherwise

◆ is_user_non_contact_blocked()

static core_message\api::is_user_non_contact_blocked	(	$recipient,
		$sender = `null`
	)

static

Checks if the recipient is allowing messages from users that aren't a contact.

If not then it checks to make sure the sender is in the recipient's contacts.

Deprecated:: since 3.6

Parameters

stdClass	$recipient	The user object.
stdClass \| null	$sender	The user object.

Return values

bool	true if $sender is blocked, false otherwise.

◆ lazy_create_self_conversation()

static core_message\api::lazy_create_self_conversation ( int $userid )

staticprotected

Create a self conversation for a user, only if one doesn't already exist.

Parameters

int $userid the user to whom the conversation belongs.

◆ mark_all_messages_as_read()

static core_message\api::mark_all_messages_as_read	(	$userid,
		$conversationid = `null`
	)

static

Marks all messages being sent to a user in a particular conversation.

If $conversationdid is null then it marks all messages as read sent to $userid.

Parameters

int	$userid
int \| null	$conversationid	The conversation the messages belong to mark as read, if null mark all

◆ mark_all_notifications_as_read()

static core_message\api::mark_all_notifications_as_read	(	$touserid,
		$fromuserid = `null`,
		$timecreatedto = `null`
	)

static

Marks all notifications being sent from one user to another user as read.

If the from user is null then it marks all notifications as read sent to the to user.

Parameters

int	$touserid	the id of the message recipient
int \| null	$fromuserid	the id of the message sender, null if all messages
int \| null	$timecreatedto	mark notifications created before this time as read

Return values

void

◆ mark_all_read_for_user()

static core_message\api::mark_all_read_for_user ( )

static

Deprecated:: since 3.5

◆ mark_message_as_read()

static core_message\api::mark_message_as_read	(	$userid,
		$message,
		$timeread = `null`
	)

static

Mark a single message as read.

Parameters

int	$userid	The user id who marked the message as read
stdClass	$message	The message
int \| null	$timeread	The time the message was marked as read, if null will default to time()

◆ mark_notification_as_read()

static core_message\api::mark_notification_as_read	(	$notification,
		$timeread = `null`
	)

static

Mark a single notification as read.

Parameters

stdClass	$notification	The notification
int \| null	$timeread	The time the message was marked as read, if null will default to time()

◆ message_search_users()

static core_message\api::message_search_users	(	int	$userid,
		string	$search,
		int	$limitfrom = `0`,
		int	$limitnum = `20`
	)

static

Handles searching for user.

Parameters

int	$userid	The user id doing the searching
string	$search	The string the user is searching
int	$limitfrom
int	$limitnum

Return values

array

◆ mute_conversation()

static core_message\api::mute_conversation	(	int	$userid,
		int	$conversationid
	)

static

Handles muting a conversation.

Parameters

int	$userid	The id of the user
int	$conversationid	The id of the conversation

◆ remove_contact()

static core_message\api::remove_contact	(	int	$userid,
		int	$contactid
	)

static

Handles removing a contact.

Parameters

int	$userid	The id of the user who is removing a user as a contact
int	$contactid	The id of the user to be removed as a contact

◆ remove_members_from_conversation()

static core_message\api::remove_members_from_conversation	(	array	$userids,
		int	$convid
	)

static

Remove some members from an existing conversation.

Parameters

array	$userids	The user ids to remove from conversation members.
int	$convid	The conversation id. Must exists.

Exceptions

dml_exception
moodle_exception	If trying to remove a member(s) from a non-group conversation

◆ search_messages()

static core_message\api::search_messages	(	$userid,
		$search,
		$limitfrom = `0`,
		$limitnum = `0`
	)

static

Handles searching for messages in the message area.

Parameters

int	$userid	The user id doing the searching
string	$search	The string the user is searching
int	$limitfrom
int	$limitnum

Return values

array

◆ search_users()

static core_message\api::search_users	(	$userid,
		$search,
		$limitnum = `0`
	)

static

Handles searching for user in the message area.

TODO: This function should be removed once the related web service goes through final deprecation. The related web service is data_for_messagearea_search_users. Followup: MDL-63261

Parameters

int	$userid	The user id doing the searching
string	$search	The string the user is searching
int	$limitnum

Return values

array

◆ search_users_in_course()

static core_message\api::search_users_in_course	(	$userid,
		$courseid,
		$search,
		$limitfrom = `0`,
		$limitnum = `0`
	)

static

Handles searching for user in a particular course in the message area.

TODO: This function should be removed once the related web service goes through final deprecation. The related web service is data_for_messagearea_search_users_in_course. Followup: MDL-63261

Parameters

int	$userid	The user id doing the searching
int	$courseid	The id of the course we are searching in
string	$search	The string the user is searching
int	$limitfrom
int	$limitnum

Return values

array

◆ send_message_to_conversation()

static core_message\api::send_message_to_conversation	(	int	$userid,
		int	$conversationid,
		string	$message,
		int	$format
	)

static

Send a message from a user to a conversation.

This method will create the basic eventdata and delegate to message creation to message_send. The message_send() method is responsible for event data that is specific to each recipient.

Parameters

int	$userid	the sender id.
int	$conversationid	the conversation id.
string	$message	the message to send.
int	$format	the format of the message to send.

Return values

stdClass the message created.

Exceptions

coding_exception
moodle_exception	if the user is not permitted to send a message to the conversation.

◆ set_favourite_conversation()

static core_message\api::set_favourite_conversation	(	int	$conversationid,
		int	$userid
	)

static

Mark a conversation as a favourite for the given user.

Parameters

int	$conversationid	the id of the conversation to mark as a favourite.
int	$userid	the id of the user to whom the favourite belongs.

Return values

favourite the favourite object.

Exceptions

moodle_exception if the user or conversation don't exist.

◆ unblock_user()

static core_message\api::unblock_user	(	int	$userid,
		int	$usertounblockid
	)

static

Handles unblocking a user.

Parameters

int	$userid	The id of the user who is unblocking
int	$usertounblockid	The id of the user being unblocked

◆ unmute_conversation()

static core_message\api::unmute_conversation	(	int	$userid,
		int	$conversationid
	)

static

Handles unmuting a conversation.

Parameters

int	$userid	The id of the user
int	$conversationid	The id of the conversation

◆ unset_favourite_conversation()

static core_message\api::unset_favourite_conversation	(	int	$conversationid,
		int	$userid
	)

static

Unset a conversation as a favourite for the given user.

Parameters

int	$conversationid	the id of the conversation to unset as a favourite.
int	$userid	the id to whom the favourite belongs.

Exceptions

moodle_exception if the favourite does not exist for the user.

◆ update_conversation_name()

static core_message\api::update_conversation_name	(	int	$conversationid,
		string	$name
	)

static

Update the name of a conversation.

Parameters

int	$conversationid	The id of a conversation.
string	$name	The main name of the area

Return values

void

◆ update_processor_status()

static core_message\api::update_processor_status	(	$processor,
		$enabled
	)

static

Set status of a processor.

Parameters

stdClass	$processor	processor record.
0 \| 1	$enabled	0 or 1 to set the processor status.

Return values

bool

Since: Moodle 3.2

The documentation for this class was generated from the following file:

message/classes/api.php

Static Public Member Functions

Public Attributes

Static Protected Member Functions

Detailed Description

Member Function Documentation

◆ add_contact()

◆ add_members_to_conversation()

◆ block_user()

◆ can_contact_user()

◆ can_create_contact()

◆ can_create_group_conversation()

◆ can_delete_conversation()

◆ can_delete_message()

◆ can_delete_message_for_all_users()

◆ can_mark_all_messages_as_read()

◆ can_post_message()

◆ can_send_message()

◆ can_send_message_to_conversation()

◆ confirm_contact_request()

◆ count_blocked_users()

◆ count_contacts()

◆ count_conversation_members()

◆ count_unread_conversations()

◆ create_contact_request()

◆ create_conversation()

◆ create_conversation_between_users()

◆ decline_contact_request()

◆ delete_all_conversation_data()

◆ delete_conversation()

◆ delete_conversation_by_id()

◆ delete_message()

◆ delete_message_for_all_users()

◆ disable_conversation()

◆ does_contact_request_exist()

◆ enable_conversation()

◆ get_all_message_preferences()

◆ get_blocked_users()

◆ get_contact()

◆ get_contact_requests()

◆ get_contact_requests_between_users()

◆ get_contacts()

◆ get_contacts_with_unread_message_count()

◆ get_conversation()

◆ get_conversation_between_users()

◆ get_conversation_by_area()

◆ get_conversation_counts()

◆ get_conversation_members()

◆ get_conversation_messages()

◆ get_conversations()

◆ get_conversations_between_users()

◆ get_individual_conversations_between_users()

◆ get_linked_conversation_extra_fields()

◆ get_message_processor()

◆ get_messages()

◆ get_most_recent_conversation_message()

◆ get_most_recent_message()

◆ get_non_contacts_with_unread_message_count()

◆ get_processed_processor_object()

◆ get_profile()

◆ get_received_contact_requests_count()

◆ get_self_conversation()

◆ get_unread_conversation_counts()

◆ get_user_contacts()

◆ get_user_privacy_messaging_preference()

◆ is_blocked()

◆ is_contact()

◆ is_conversation_area_enabled()

◆ is_conversation_muted()

◆ is_processor_enabled()

◆ is_user_blocked()

◆ is_user_in_conversation()

◆ is_user_non_contact_blocked()

◆ lazy_create_self_conversation()

◆ mark_all_messages_as_read()

◆ mark_all_notifications_as_read()

◆ mark_all_read_for_user()

◆ mark_message_as_read()

◆ mark_notification_as_read()

◆ message_search_users()

◆ mute_conversation()