Proyectos de Subversion Moodle

<?php

// This file is part of Moodle - http://moodle.org/

//

// Moodle is free software: you can redistribute it and/or modify

// it under the terms of the GNU General Public License as published by

// the Free Software Foundation, either version 3 of the License, or

// (at your option) any later version.

//

// Moodle is distributed in the hope that it will be useful,

// but WITHOUT ANY WARRANTY; without even the implied warranty of

// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

// GNU General Public License for more details.

//

// You should have received a copy of the GNU General Public License

// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.

/**

 * The Mail Pickup Manager.

 *

 * @package    tool_messageinbound

 * @copyright  2014 Andrew Nicols

 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

 */

namespace tool_messageinbound;

/**

 * Mail Pickup Manager.

 *

 * @copyright  2014 Andrew Nicols

 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

 */

class manager {

    /**

     * @var string The main mailbox to check.

     */

    const MAILBOX = 'INBOX';

    /**

     * @var string The mailbox to store messages in when they are awaiting confirmation.

     */

    const CONFIRMATIONFOLDER = 'tobeconfirmed';

    /**

     * @var string The flag for seen/read messages.

     */

    const MESSAGE_SEEN = '\seen';

    /**

     * @var string The flag for flagged messages.

     */

    const MESSAGE_FLAGGED = '\flagged';

    /**

     * @var string The flag for deleted messages.

     */

    const MESSAGE_DELETED = '\deleted';

    /**

     * @var \string IMAP folder namespace.

     */

    protected $imapnamespace = null;

    /**

     * @var \rcube_imap_generic A reference to the IMAP client.

     */

    protected $client = null;

    /**

     * @var \core\message\inbound\address_manager A reference to the Inbound Message Address Manager instance.

     */

    protected $addressmanager = null;

    /**

     * @var \stdClass The data for the current message being processed.

     */

    protected $currentmessagedata = null;

    /**

     * Mail Pickup Manager.

     */

    public function __construct() {

        // Load dependencies.

        $this->load_dependencies();

    }

    /**

     * Retrieve the connection to the IMAP client.

     *

     * @param string $mailbox The mailbox to connect to.

     *

     * @return bool Whether a connection was successfully established.

     */

    protected function get_imap_client(

        string $mailbox = self::MAILBOX,

    ): bool {

        global $CFG;

        if (!\core\message\inbound\manager::is_enabled()) {

            // E-mail processing not set up.

            mtrace("Inbound Message not fully configured - exiting early.");

            return false;

        }

        mtrace("Connecting to {$CFG->messageinbound_host} as {$CFG->messageinbound_hostuser}...");

        $configuration = [

            'username' => $CFG->messageinbound_hostuser,

            'password' => $CFG->messageinbound_hostpass,

            'hostspec' => $CFG->messageinbound_host,

            'options' => [

                'ssl_mode' => strtolower($CFG->messageinbound_hostssl),

                'auth_type' => 'CHECK',

            ],

        ];

        if (strpos($configuration['hostspec'], ':')) {

            $hostdata = explode(':', $configuration['hostspec']);

            if (count($hostdata) === 2) {

                // A hostname in the format hostname:port has been provided.

                $configuration['hostspec'] = $hostdata[0];

                $configuration['options']['port'] = $hostdata[1];

            }

        }

        // XOAUTH2.

        if (isset($CFG->messageinbound_hostoauth) && $CFG->messageinbound_hostoauth != '') {

            // Get the issuer.

            $issuer = \core\oauth2\api::get_issuer($CFG->messageinbound_hostoauth);

            // Validate the issuer and check if it is enabled or not.

            if ($issuer && $issuer->get('enabled')) {

                // Get the OAuth Client.

                if ($oauthclient = \core\oauth2\api::get_system_oauth_client($issuer)) {

                    $configuration['password'] = 'Bearer ' . $oauthclient->get_accesstoken()->token;

                    $configuration['options']['auth_type'] = 'XOAUTH2';

                }

            }

        }

        $this->client = new \rcube_imap_generic();

        if (!empty($CFG->debugimap)) {

            $this->client->setDebug(debug: true);

        }

        $success = $this->client->connect(

            host: $configuration['hostspec'],

            user: $configuration['username'],

            password: $configuration['password'],

            options: $configuration['options'],

        );

        if ($success) {

            mtrace("Connection established.");

            // Ensure that mailboxes exist.

            $this->ensure_mailboxes_exist();

            // Select mailbox.

            $this->select_mailbox(mailbox: $mailbox);

            return true;

        } else {

            throw new \moodle_exception('imapconnectfailure', 'tool_messageinbound', '', null, 'Could not connect to IMAP server.');

        }

    }

    /**

     * Shutdown and close the connection to the IMAP client.

     */

    protected function close_connection(): void {

        if ($this->client) {

            // Close the connection and return to authenticated state.

            $isclosed = $this->client->close();

            if ($isclosed) {

                // Connection was closed unsuccessfully. Send the LOGOUT command and close the socket.

                $this->client->closeConnection();

            }

        }

        $this->client = null;

    }

    /**

     * Get the confirmation folder imap name

     *

     * @return string

     */

    protected function get_confirmation_folder(): string {

        if ($this->imapnamespace === null) {

            $namespaces = $this->client->getNamespace();

            if ($namespaces != $this->client::ERROR_BAD && is_array($namespaces)) {

                $nspersonal = reset($namespaces['personal']);

                if (is_array($nspersonal) && !empty($nspersonal[0])) {

                    // Personal namespace is an array, the first part is the name, the second part is the delimiter.

                    $this->imapnamespace = $nspersonal[0] . $nspersonal[1];

                } else {

                    $this->imapnamespace = '';

                }

            } else {

                $this->imapnamespace = '';

            }

        }

        return $this->imapnamespace . self::CONFIRMATIONFOLDER;

    }

    /**

     * Get the current mailbox name.

     *

     * @return string The current mailbox name.

     * @throws \core\message\inbound\processing_failed_exception if the mailbox could not be opened.

     */

    protected function get_mailbox(): string {

        // Get the current mailbox.

        if ($this->client->selected) {

            return $this->client->selected;

        } else {

            throw new \core\message\inbound\processing_failed_exception('couldnotopenmailbox', 'tool_messageinbound');

        }

    }

    /**

     * Execute the main Inbound Message pickup task.

     *

     * @return bool

     */

    public function pickup_messages(): bool {

        if (!$this->get_imap_client()) {

            return false;

        }

        // Restrict results to messages which are unseen, and have not been flagged.

        mtrace("Searching for Unseen, Unflagged email in the folder '" . self::MAILBOX . "'");

        $result = $this->client->search(

            mailbox: $this->get_mailbox(),

            criteria: 'UNSEEN UNFLAGGED',

            return_uid: true,

        );

        if (empty($result->count())) {

            return false;

        }

        mtrace("Found " . $result->count() . " messages to parse. Parsing...");

        // Retrieve the message id.

        $messages = $result->get();

        $this->addressmanager = new \core\message\inbound\address_manager();

        foreach ($messages as $messageuid) {

            $messageuid = is_numeric($messageuid) ? intval($messageuid) : $messageuid;

            $this->process_message(messageuid: $messageuid);

        }

        // Close the client connection.

        $this->close_connection();

        return true;

    }

    /**

     * Process a message received and validated by the Inbound Message processor.

     *

     * @param \stdClass $maildata The data retrieved from the database for the current record.

     * @return bool Whether the message was successfully processed.

     * @throws \core\message\inbound\processing_failed_exception if the message cannot be found.

     */

    public function process_existing_message(

        \stdClass $maildata,

    ): bool {

        // Grab the new IMAP client.

        if (!$this->get_imap_client(mailbox: $this->get_confirmation_folder())) {

            return false;

        }

        // When dealing with Inbound Message messages, we mark them as flagged and seen. Restrict the search to those criterion.

        mtrace("Searching for a Seen, Flagged message in the folder '" . $this->get_confirmation_folder() . "'");

        // Build the search.

        $result = $this->client->search(

            mailbox: $this->get_mailbox(),

            criteria: 'SEEN FLAGGED TO "' . $maildata->address . '"',

            return_uid: true,

        );

        $this->addressmanager = new \core\message\inbound\address_manager();

        if (!empty($result->count())) {

            $messages = $result->get();

            $targetsequence = 0;

            mtrace("Found " . $result->count() . " messages to parse. Parsing...");

            foreach ($messages as $messageuid) {

                $messageuid = is_numeric($messageuid) ? intval($messageuid) : $messageuid;

                $results = $this->client->fetch(

                    mailbox: $this->get_mailbox(),

                    message_set: $messageuid,

                    is_uid: true,

                    query_items: [

                        'BODY.PEEK[HEADER.FIELDS (Message-ID)]',

                    ],

                );

                $messagedata = reset($results);

                // Match the message id.

                if (htmlentities($messagedata->get('Message-ID', false)) == $maildata->messageid) {

                    // Found the message.

                    $targetsequence = $messageuid;

                    break;

                }

            }

            mtrace("--> Found the message. Passing back to the pickup system.");

            // Process the message.

            $this->process_message(

                messageuid: $targetsequence,

                viewreadmessages: true,

                skipsenderverification: true,

            );

            // Close the client connection.

            $this->close_connection();

            mtrace("============================================================================");

            return true;

        } else {

            // Close the client connection.

            $this->close_connection();

            mtrace("============================================================================");

            throw new \core\message\inbound\processing_failed_exception('oldmessagenotfound', 'tool_messageinbound');

        }

    }

    /**

     * Tidy up old messages in the confirmation folder.

     *

     * @return bool Whether tidying occurred successfully.

     */

    public function tidy_old_messages(): bool {

        // Grab the new IMAP client.

        if (!$this->get_imap_client()) {

            return false;

        }

        // Switch to the confirmation folder.

        $this->select_mailbox(mailbox: $this->get_confirmation_folder());

        // Open the mailbox.

        mtrace("Searching for messages older than 24 hours in the '" .

                $this->get_confirmation_folder() . "' folder.");

        // Delete messages older than 24 hours old.

        $date = date(

            format: 'Y-m-d',

            timestamp: time() - DAYSECS

        );

        // Retrieve the messages and mark them for removal.

        $result = $this->client->search(

            mailbox: $this->get_mailbox(),

            criteria: 'BEFORE "' . $date . '"',

            return_uid: true,

        );

        if (empty($result->count())) {

            $this->close_connection();

            return false;

        }

        mtrace("Found " . $result->count() . " messages for removal.");

        $messages = $result->get();

        foreach ($messages as $messageuid) {

            $messageuid = is_numeric($messageuid) ? intval($messageuid) : $messageuid;

            $this->add_flag_to_message(

                messageuid: $messageuid,

                flag: self::MESSAGE_DELETED

            );

        }

        mtrace("Finished removing messages.");

        $this->close_connection();

        return true;

    }

    /**

     * Remove older verification failures.

     *

     * @return void

     */

    public function tidy_old_verification_failures() {

        global $DB;

        $DB->delete_records_select('messageinbound_messagelist', 'timecreated < :time', ['time' => time() - DAYSECS]);

    }

    /**

     * Process a message and pass it through the Inbound Message handling systems.

     *

     * @param int $messageuid The message uid to process

     * @param bool $viewreadmessages Whether to also look at messages which have been marked as read

     * @param bool $skipsenderverification Whether to skip the sender verification stage

     */

    public function process_message(

        int $messageuid,

        bool $viewreadmessages = false,

        bool $skipsenderverification = false,

    ): void {

        global $USER;

        mtrace("- Parsing message " . $messageuid);

        // First flag this message to prevent another running hitting this message while we look at the headers.

        $this->add_flag_to_message(

            messageuid: $messageuid,

            flag: self::MESSAGE_FLAGGED,

        );

        if ($this->is_bulk_message(messageuid: $messageuid)) {

            mtrace("- The message " . $messageuid . " has a bulk header set. This is likely an auto-generated reply - discarding.");

            return;

        }

        // Record the user that this script is currently being run as.  This is important when re-processing existing

        // messages, as \core\cron::setup_user is called multiple times.

        $originaluser = $USER;

        $envelope = $this->client->fetch(

            mailbox: $this->get_mailbox(),

            message_set: $messageuid,

            is_uid: true,

            query_items: [

                'BODY.PEEK[HEADER.FIELDS (SUBJECT FROM TO)]',

                'ENVELOPE',

            ],

        );

        $envelope = array_shift($envelope);

        $recipients = $this->get_address_from_envelope(addresslist: $envelope->envelope[5]);

        foreach ($recipients as $recipient) {

            if (!\core\message\inbound\address_manager::is_correct_format($recipient)) {

                // Message did not contain a subaddress.

                mtrace("- Recipient '{$recipient}' did not match Inbound Message headers.");

                continue;

            }

            // Message contained a match.

            $senders = $this->get_address_from_envelope(addresslist: $envelope->envelope[2]);

            if (count($senders) !== 1) {

                mtrace("- Received multiple senders. Only the first sender will be used.");

            }

            $sender = array_shift($senders);

            mtrace("-- Subject:\t"      . $envelope->subject);

            mtrace("-- From:\t"         . $sender);

            mtrace("-- Recipient:\t"    . $recipient);

            // Check whether this message has already been processed.

            if (

                !$viewreadmessages &&

                $this->message_has_flag(

                    messageuid: $messageuid,

                    flag: self::MESSAGE_SEEN,

                )

            ) {

                // Something else has already seen this message. Skip it now.

                mtrace("-- Skipping the message - it has been marked as seen - perhaps by another process.");

                continue;

            }

            // Mark it as read to lock the message.

            $this->add_flag_to_message(

                messageuid: $messageuid,

                flag: self::MESSAGE_SEEN,

            );

            // Now pass it through the Inbound Message processor.

            $status = $this->addressmanager->process_envelope($recipient, $sender);

            if (($status & ~ \core\message\inbound\address_manager::VALIDATION_DISABLED_HANDLER) !== $status) {

                // The handler is disabled.

                mtrace("-- Skipped message - Handler is disabled. Fail code {$status}");

                // In order to handle the user error, we need more information about the message being failed.

                $this->process_message_data(

                    envelope: $envelope,

                    messageuid: $messageuid,

                );

                $this->inform_user_of_error(get_string('handlerdisabled', 'tool_messageinbound', $this->currentmessagedata));

                return;

            }

            // Check the validation status early. No point processing garbage messages, but we do need to process it

            // for some validation failure types.

            if (!$this->passes_key_validation(status: $status)) {

                // None of the above validation failures were found. Skip this message.

                mtrace("-- Skipped message - it does not appear to relate to a Inbound Message pickup. Fail code {$status}");

                // Remove the seen flag from the message as there may be multiple recipients.

                $this->remove_flag_from_message(

                    messageuid: $messageuid,

                    flag: self::MESSAGE_SEEN,

                );

                // Skip further processing for this recipient.

                continue;

            }

            // Process the message as the user.

            $user = $this->addressmanager->get_data()->user;

            mtrace("-- Processing the message as user {$user->id} ({$user->username}).");

            \core\cron::setup_user($user);

            // Process and retrieve the message data for this message.

            // This includes fetching the full content, as well as all headers, and attachments.

            if (

                !$this->process_message_data(

                    envelope: $envelope,

                    messageuid: $messageuid,

                )

            ) {

                mtrace("--- Message could not be found on the server. Is another process removing messages?");

                return;

            }

            // When processing validation replies, we need to skip the sender verification phase as this has been

            // manually completed.

            if (!$skipsenderverification && $status !== 0) {

                // Check the validation status for failure types which require confirmation.

                // The validation result is tested in a bitwise operation.

                mtrace("-- Message did not meet validation but is possibly recoverable. Fail code {$status}");

                // This is a recoverable error, but requires user input.

                if (

                    $this->handle_verification_failure(

                        messageuid: $messageuid,

                        recipient: $recipient,

                    )

                ) {

                    mtrace("--- Original message retained on mail server and confirmation message sent to user.");

                } else {

                    mtrace("--- Invalid Recipient Handler - unable to save. Informing the user of the failure.");

                    $this->inform_user_of_error(get_string('invalidrecipientfinal', 'tool_messageinbound', $this->currentmessagedata));

                }

                // Returning to normal cron user.

                mtrace("-- Returning to the original user.");

                \core\cron::setup_user($originaluser);

                return;

            }

            // Add the content and attachment data.

            mtrace("-- Validation completed. Fetching rest of message content.");

            $this->process_message_data_body(messageuid: $messageuid);

            // The message processor throws exceptions upon failure. These must be caught and notifications sent to

            // the user here.

            try {

                $result = $this->send_to_handler();

            } catch (\core\message\inbound\processing_failed_exception $e) {

                // We know about these kinds of errors and they should result in the user being notified of the

                // failure. Send the user a notification here.

                $this->inform_user_of_error($e->getMessage());

                // Returning to normal cron user.

                mtrace("-- Returning to the original user.");

                \core\cron::setup_user($originaluser);

                return;

            } catch (\Exception $e) {

                // An unknown error occurred. The user is not informed, but the administrator is.

                mtrace("-- Message processing failed. An unexpected exception was thrown. Details follow.");

                mtrace($e->getMessage());

                // Returning to normal cron user.

                mtrace("-- Returning to the original user.");

                \core\cron::setup_user($originaluser);

                return;

            }

            if ($result) {

                // Handle message cleanup. Messages are deleted once fully processed.

                mtrace("-- Marking the message for removal.");

                $this->add_flag_to_message(

                    messageuid: $messageuid,

                    flag: self::MESSAGE_DELETED

                );

            } else {

                mtrace("-- The Inbound Message processor did not return a success status. Skipping message removal.");

            }

            // Returning to normal cron user.

            mtrace("-- Returning to the original user.");

            \core\cron::setup_user($originaluser);

            mtrace("-- Finished processing " . $messageuid);

            // Skip the outer loop too. The message has already been processed and it could be possible for there to

            // be two recipients in the envelope which match somehow.

            return;

        }

    }

    /**

     * Process a message to retrieve it's header data without body.

     *

     * @param \rcube_message_header $envelope The Envelope of the message

     * @param int $messageuid The message Uid to process

     * @return \stdClass|null The current value of the messagedata

     */

    private function process_message_data(

        \rcube_message_header $envelope,

        int $messageuid,

    ): ?\stdClass {

        // Retrieve the message with necessary information.

        $messages = $this->client->fetch(

            mailbox: $this->get_mailbox(),

            message_set: $messageuid,

            is_uid: true,

            query_items: [

                'BODY.PEEK[HEADER.FIELDS (Message-ID SUBJECT DATE)]',

            ],

        );

        $messagedata = reset($messages);

        if (!$messagedata) {

            // Message was not found! Somehow it has been removed or is no longer returned.

            return null;

        }

        // The message ID should always be in the first part.

        $data = new \stdClass();

        $data->messageid = htmlentities($messagedata->get('Message-ID', false));

        $data->subject = $messagedata->get('SUBJECT', false);

        $data->timestamp = strtotime($messagedata->get('DATE', false));

        $data->envelope = $envelope;

        $data->data = $this->addressmanager->get_data();

        $this->currentmessagedata = $data;

        return $this->currentmessagedata;

    }

    /**

     * Process a message again to add body and attachment data.

     *

     * @param int $messageuid The message Uid

     * @return \stdClass|null The current value of the messagedata

     */

    private function process_message_data_body(

        int $messageuid,

    ): ?\stdClass {

        $messages = $this->client->fetch(

            mailbox: $this->get_mailbox(),

            message_set: $messageuid,

            is_uid: true,

            query_items: [

                'BODYSTRUCTURE',

            ],

        );

        $messagedata = reset($messages);

        $structure = $messagedata->bodystructure;

        // Store the data for this message.

        $contentplain = '';

        $contenthtml = '';

        $attachments = [

            'inline' => [],

            'attachment' => [],

        ];

        $parameters = [];

        foreach ($structure as $partno => $part) {

            if (!is_array($part)) {

                continue;

            }

            $section = $partno + 1;

            // Subpart recursion.

            if (is_array($part[0])) {

                foreach ($part as $subpartno => $subpart) {

                    if (!is_array($subpart)) {

                        continue;

                    }

                    $subsection = $subpartno + 1;

                    $this->process_message_data_body_part(

                        messageuid: $messageuid,

                        partstructure: $subpart,

                        section: $section . '.' . $subsection,

                        contentplain: $contentplain,

                        contenthtml: $contenthtml,

                        attachments: $attachments,

                        parameters: $parameters,

                    );

                }

            } else {

                $this->process_message_data_body_part(

                    messageuid: $messageuid,

                    partstructure: $part,

                    section: $section,

                    contentplain: $contentplain,

                    contenthtml: $contenthtml,

                    attachments: $attachments,

                    parameters: $parameters,

                );

            }

        }

        // The message ID should always be in the first part.

        $this->currentmessagedata->plain = $contentplain;

        $this->currentmessagedata->html = $contenthtml;

        $this->currentmessagedata->attachments = $attachments;

        return $this->currentmessagedata;

    }

    /**

     * Process message data body part.

     *

     * @param int $messageuid Message uid to process.

     * @param array $partstructure Body part structure.

     * @param string $section Section number.

     * @param string $contentplain Plain text content.

     * @param string $contenthtml HTML content.

     * @param array $attachments Attachments.

     * @param array $parameters Parameters.

     */

    private function process_message_data_body_part(

        int $messageuid,

        array $partstructure,

        string $section,

        string &$contentplain,

        string &$contenthtml,

        array &$attachments,

        array &$parameters,

    ): void {

        $messages = $this->client->fetch(

            mailbox: $this->get_mailbox(),

            message_set: $messageuid,

            is_uid: true,

            query_items: [

                'BODY[' . $section . ']',

            ],

        );

        if ($messages) {

            $messagedata = reset($messages);

            // Parse encoding.

            $encoding = array_search(

                needle: strtoupper($partstructure[5]),

                haystack: utils::get_body_encoding(),

            );

            // Parse subtype.

            $subtype = strtoupper($partstructure[1]);

            // Section part may be encoded, even plain text messages, so check everything.

            if ($encoding == utils::ENCQUOTEDPRINTABLE) {

                $data = quoted_printable_decode($messagedata->bodypart[$section]);

            } else if ($encoding == utils::ENCBASE64) {

                $data = base64_decode($messagedata->bodypart[$section]);

            } else {

                $data = $messagedata->bodypart[$section];

            }

            // Parse parameters.

            $parameters = $this->process_message_body_structure_parameters(

                attributes: $partstructure[2],

                parameters: $parameters,

            );

            // Parse content id.

            $contentid = '';

            if (!empty($partstructure[3])) {

                $contentid = htmlentities($partstructure[3]);

            }

            // Parse description.

            $description = '';

            if (!empty($partstructure[4])) {

                $description = $partstructure[4];

            }

            // Parse size of contents in bytes.

            $bytes = intval($partstructure[6]);

            // PLAIN text.

            if ($subtype == 'PLAIN') {

                $contentplain = $this->process_message_part_body(

                    bodycontent: $data,

                    charset: $parameters['CHARSET'],

                );

            }

            // HTML.

            if ($subtype == 'HTML') {

                $contenthtml = $this->process_message_part_body(

                    bodycontent: $data,

                    charset: $parameters['CHARSET'],

                );

            }

            // ATTACHMENT.

            if (isset($parameters['NAME']) || isset($parameters['FILENAME'])) {

                $filename = $parameters['NAME'] ?? $parameters['FILENAME'];

                if (

                    $attachment = $this->process_message_part_attachment(

                        filename: $filename,

                        filecontent: $data,

                        contentid: $contentid,

                        filesize: $bytes,

                        description: $description,

                    )

                ) {

                    // Parse disposition.

                    $disposition = null;

                    if (is_array($partstructure[8])) {

                        $disposition = strtolower($partstructure[8][0]);

                    }

                    $disposition = $disposition == 'inline' ? 'inline' : 'attachment';

                    $attachments[$disposition][] = $attachment;

                }

            }

        }

    }

    /**

     * Process message data body parameters.

     *

     * @param array $attributes List of attributes.

     * @param array $parameters List of parameters.

     * @return array

     */

    private function process_message_body_structure_parameters(

        array $attributes,

        array $parameters,

    ): array {

        if (empty($attributes)) {

            return [];

        }

        $attribute = null;

        foreach ($attributes as $value) {

            if (empty($attribute)) {

                $attribute = [

                    'attribute' => $value,

                    'value' => null,

                ];

            } else {

                $attribute['value'] = $value;

                $parameters[] = (object) $attribute;

                $attribute = null;

            }

        }

        $params = [];

        foreach ($parameters as $parameter) {

            if (isset($parameter->attribute)) {

                $params[$parameter->attribute] = $parameter->value;

            }

        }

        return $params;

    }

    /**

     * Process the message body content.

     *

     * @param string $bodycontent The message body.

     * @param string $charset The charset of the message body.

     * @return string Processed content.

     */

    private function process_message_part_body(

        string $bodycontent,

        string $charset,

    ): string {

        // This is a content section for the main body.

        // Convert the text from the current encoding to UTF8.

        $content = \core_text::convert($bodycontent, $charset);

        // Fix any invalid UTF8 characters.

        // Note: XSS cleaning is not the responsibility of this code. It occurs immediately before display when

        // format_text is called.

        $content = clean_param($content, PARAM_RAW);

        return $content;

    }

    /**

     * Process a message again to add body and attachment data.

     *

     * @param string $filename The filename of the attachment.

     * @param string $filecontent The content of the attachment.

     * @param string $contentid The content id of the attachment.

     * @param int $filesize The size of the attachment.

     * @param string $description The description of the attachment.

     * @return \stdClass

     */

    private function process_message_part_attachment(

        string $filename,

        string $filecontent,

        string $contentid,

        int $filesize,

        string $description = '',

    ): \stdClass {

        global $CFG;

        // If a filename is present, assume that this part is an attachment.

        $attachment = new \stdClass();

        $attachment->filename = $filename;

        $attachment->content = $filecontent;

        $attachment->description = $description;

        $attachment->contentid = $contentid;

        $attachment->filesize = $filesize;

        if (!empty($CFG->antiviruses)) {

            // Virus scanning is removed and will be brought back by MDL-50434.

        }

        return $attachment;

    }

    /**

     * Check whether the key provided is valid.

     *

     * @param int $status The status to validate.

     * @return bool

     */

    private function passes_key_validation(

        int $status,

    ): bool {

        // The validation result is tested in a bitwise operation.

        if ((

            $status & ~ \core\message\inbound\address_manager::VALIDATION_SUCCESS

                    & ~ \core\message\inbound\address_manager::VALIDATION_UNKNOWN_DATAKEY

                    & ~ \core\message\inbound\address_manager::VALIDATION_EXPIRED_DATAKEY

                    & ~ \core\message\inbound\address_manager::VALIDATION_INVALID_HASH

                    & ~ \core\message\inbound\address_manager::VALIDATION_ADDRESS_MISMATCH) !== 0) {

            // One of the above bits was found in the status - fail the validation.

            return false;

        }

        return true;

    }

    /**

     * Add the specified flag to the message.

     *

     * @param int $messageuid Message uid to process

     * @param string $flag The flag to add

     */

    private function add_flag_to_message(

        int $messageuid,

        string $flag,

    ): void {

        // Add flag to the message.

        $this->client->flag(

            mailbox: $this->get_mailbox(),

            messages: $messageuid,

            flag: strtoupper(substr($flag, 1)),

        );

    }

    /**

     * Remove the specified flag from the message.

     *

     * @param int $messageuid Message uid to process

     * @param string $flag The flag to remove

     */

    private function remove_flag_from_message(

        int $messageuid,

        string $flag,

    ): void {

        // Remove the flag from the message.

        $this->client->unflag(

            mailbox: $this->get_mailbox(),

            messages: $messageuid,

            flag: strtoupper(substr($flag, 1)),

        );

    }

    /**

     * Check whether the message has the specified flag

     *

     * @param int $messageuid Message uid to check.

     * @param string $flag The flag to check.

     * @return bool True if the message has the flag, false otherwise.

     */

    private function message_has_flag(

        int $messageuid,

        string $flag,

    ): bool {

        // Grab the message data with flags.

        $messages = $this->client->fetch(

            mailbox: $this->get_mailbox(),

            message_set: $messageuid,

            is_uid: true,

            query_items: [

                'FLAGS',

            ],

        );

        $messagedata = reset($messages);

        $flags = $messagedata->flags;

        return array_key_exists(

            key: strtoupper(substr($flag, 1)),

            array: $flags,

        );

    }

    /**

     * Ensure that all mailboxes exist.

     */

    private function ensure_mailboxes_exist(): void {

        $requiredmailboxes = [

            self::MAILBOX,