Moodle APIs 3.9
Moodle 3.9.13+ (Build: 20220325)
Static Public Member Functions | Public Attributes | Static Protected Member Functions | List of all members
core_message\api Class Reference

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.

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$useridThe id of the user who requested to be a contact
int$contactidThe 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$useridsUser ids array to add as members.
int$convidThe conversation id. Must exists.
Exceptions
dml_missing_record_exceptionIf convid conversation doesn't exist
dml_exceptionIf there is a database error
moodle_exceptionIf 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$useridThe id of the user who is blocking
int$usertoblockidThe 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$evenifblockedThis lets the user know, that even if the recipient has blocked the user the user is still able to send a message.
Return values
booltrue 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$useridThe id of the user who is creating the contact request
int$requesteduseridThe 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$useridThe id of the user attempting to create the conversation
context$contextThe 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$useridThe 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$conversationidThe id of the conversation
Return values
boolReturns 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$useridthe 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$messageidThe message id
Return values
boolReturns 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$useridthe user id of who we want to delete the message for all users
int$messageidThe message id
Return values
boolReturns 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$useridThe user id of who we want to mark the messages for
int$conversationidThe id of the conversation
Return values
booltrue 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$recipientThe user object.
stdClass | null$senderThe user object.
Return values
booltrue 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$recipientidThe recipient user id.
int$senderidThe sender user id.
bool$evenifblockedThis lets the user know, that even if the recipient has blocked the user the user is still able to send a message.
Return values
booltrue 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$useridthe id of the user on which the checks will be applied.
int$conversationidthe id of the conversation we wish to check.
Return values
booltrue 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$useridThe id of the user who created the contact request
int$requesteduseridThe 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$userThe user object
Return values
intthe number of blocked users

◆ count_contacts()

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

Returns the contacts count.

Parameters
int$useridThe user id
Return values
array

◆ count_conversation_members()

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

Count conversation members.

Parameters
int$convidThe conversation id.
Return values
intNumber 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$userthe user who's conversations should be counted
Return values
intthe 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$useridThe id of the user who is creating the contact request
int$requesteduseridThe id of the user being requested
Return values
stdClassthe 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$typeThe type of conversation
int[]$useridsThe array of users to add to the conversation
string | null$nameThe name of the conversation
int$enabledDetermines if the conversation is created enabled or disabled
string | null$componentDefines the Moodle component which the conversation belongs to, if any
string | null$itemtypeDefines the type of the component
int | null$itemidThe id of the component
int | null$contextidThe 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
intThe 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$useridThe id of the user who created the contact request
int$requesteduseridThe 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$conversationidThe 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$useridThe 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$otheruseridThe 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$useridThe 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$conversationidThe 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$useridthe 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$messageidThe 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$messageidThe message id
Return values
void

◆ disable_conversation()

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

Disable a conversation.

Parameters
int$conversationidThe 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$useridThe id of the user who is creating the contact request
int$requesteduseridThe id of the user being requested
Return values
boolReturns true if a contact request exists, false otherwise

◆ enable_conversation()

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

Enable a conversation.

Parameters
int$conversationidThe 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$useridThe user id of the user whos blocked users we are returning
Return values
arraythe 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$useridThe id of one of the users
int$contactidThe id of the other user
Return values
mixedA 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
arrayThe 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$useridThe id of the user who is creating the contact request
int$requesteduseridThe 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$useridThe 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$useridThe 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$useridThe user id to get the conversation for
int$conversationidThe id of the conversation to fetch
bool$includecontactrequestsShould contact requests be included between members
bool$includeprivacyinfoShould privacy info be included between members
int$memberlimitLimit number of members to load
int$memberoffsetOffset members by this amount
int$messagelimitLimit number of messages to load
int$messageoffsetOffset the messages
bool$newestmessagesfirstOrder 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|boolThe 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$componentDefines the Moodle component which the area was added to.
string$itemtypeDefines the type of the component.
int$itemidThe id of the component.
int$contextidThe 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$useridThe user whose conversations should be counted.
Return values
arraythe 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$useridThe user we are returning the conversation members for, used by helper::get_member_info.
int$conversationidThe id of the conversation
bool$includecontactrequestsDo we want to include contact requests with this data?
bool$includeprivacyinfoDo 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$useridThe current user.
int$convidThe conversation where the messages belong. Could be an object or just the id.
int$limitfromReturn a subset of records, starting at this point (optional).
int$limitnumReturn a subset comprising this many records in total (optional, required if $limitfrom is set).
string$sortThe column name to order by including optionally direction.
int$timefromThe time from the message being sent.
int$timetoThe time up until the message being sent.
Return values
arrayof 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$useridThe user id
int$limitfrom
int$limitnum
int$typethe type of the conversation, if you wish to filter to a certain type (see api constants).
bool$favouriteswhether to include NO favourites (false) or ONLY favourites (true), or null to ignore this setting.
bool$mergeselfwhether to include self-conversations (true) or ONLY private conversations (false) when private conversations are requested.
Return values
arraythe 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$userid1One of the user's id
int$userid2The 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$useridsetsAn 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$conversationsa list of conversations records.
Return values
arraythe 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$nameName of the processor.
bool$readyonly return ready-to-use processors.
Return values
mixed::$processorif 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$useridthe current user
int$otheruseridthe other user
int$limitfrom
int$limitnum
string$sort
int$timefromthe time from the message being sent
int$timetothe 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$convidThe conversation identifier.
int$currentuseridThe current user identifier.
Return values
stdClass|nullThe 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$useridthe current user
int$otheruseridthe 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$useridThe 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$processorprocessor object
Return values
stdClassprocessed 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$useridThe user id
int$otheruseridThe 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$useridThe ID of the user we want to return the number of received contact requests for
Return values
intThe count

◆ get_self_conversation()

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

Returns the self conversation for a user.

Parameters
int$useridThe user id to get the self-conversations
Return values
stdClass|falseThe 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$useridthe id of the user whose conversations we'll check.
Return values
arraythe 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
arrayAn 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$useridThe user identifier.
Return values
intThe 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
boolReturns 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$useridThe id of one of the users
int$contactidThe id of the other user
Return values
boolReturns 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$componentDefines the Moodle component which the area was added to.
string$itemtypeDefines the type of the component.
int$itemidThe id of the component.
int$contextidThe id of the context.
Return values
boolReturns 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$useridThe id of the user
int$conversationidThe id of the conversation
Return values
boolWhether 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$nameName 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$recipientidUser ID of the recipient.
int$senderidUser ID of the sender.
Return values
booltrue 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$useridThe id of the user we want to check if they are in a group
int$conversationidThe id of the conversation
Return values
boolReturns 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$recipientThe user object.
stdClass | null$senderThe user object.
Return values
booltrue 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$useridthe 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$conversationidThe 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$touseridthe id of the message recipient
int | null$fromuseridthe id of the message sender, null if all messages
int | null$timecreatedtomark 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$useridThe user id who marked the message as read
stdClass$messageThe message
int | null$timereadThe 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$notificationThe notification
int | null$timereadThe 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$useridThe user id doing the searching
string$searchThe 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$useridThe id of the user
int$conversationidThe id of the conversation

◆ remove_contact()

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

Handles removing a contact.

Parameters
int$useridThe id of the user who is removing a user as a contact
int$contactidThe 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$useridsThe user ids to remove from conversation members.
int$convidThe conversation id. Must exists.
Exceptions
dml_exception
moodle_exceptionIf 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$useridThe user id doing the searching
string$searchThe 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$useridThe user id doing the searching
string$searchThe 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$useridThe user id doing the searching
int$courseidThe id of the course we are searching in
string$searchThe 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$useridthe sender id.
int$conversationidthe conversation id.
string$messagethe message to send.
int$formatthe format of the message to send.
Return values
stdClassthe message created.
Exceptions
coding_exception
moodle_exceptionif 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$conversationidthe id of the conversation to mark as a favourite.
int$useridthe id of the user to whom the favourite belongs.
Return values
favouritethe favourite object.
Exceptions
moodle_exceptionif 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$useridThe id of the user who is unblocking
int$usertounblockidThe 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$useridThe id of the user
int$conversationidThe 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$conversationidthe id of the conversation to unset as a favourite.
int$useridthe id to whom the favourite belongs.
Exceptions
moodle_exceptionif 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$conversationidThe id of a conversation.
string$nameThe 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$processorprocessor record.
0 | 1$enabled0 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: