<?php
/**
 * This file is part of the ZBateson\MailMimeParser project.
 *
 * @license http://opensource.org/licenses/bsd-license.php BSD
 */

namespace ZBateson\MailMimeParser\Parser;

use ZBateson\MailMimeParser\Parser\Proxy\ParserMimePartProxy;
use ZBateson\MailMimeParser\Parser\Proxy\ParserPartProxy;
use ZBateson\MailMimeParser\Parser\Proxy\ParserPartProxyFactory;

/**
 * Interface defining a message part parser.
 *
 * @author Zaahid Bateson
 */
interface IParserService
{
    /**
     * Sets up the passed ParserManager as the ParserManager for this part,
     * which should be used when a new part is created (after its headers are
     * read and a PartBuilder is created from it.)
     *
     * @param ParserManagerService $pm The ParserManager to set.
     */
    public function setParserManager(ParserManagerService $pm) : static;

    /**
     * Called by the ParserManager to determine if the passed PartBuilder is a
     * part handled by this IParser.
     */
    public function canParse(PartBuilder $part) : bool;

    /**
     * Returns the ParserPartProxyFactory responsible for creating IMessage
     * parts for this parser.
     *
     * This is called by ParserManager after 'canParse' if it returns true so
     * a ParserPartProxy can be created out of the PartBuilder.
     */
    public function getParserMessageProxyFactory() : ParserPartProxyFactory;

    /**
     * Returns the ParserPartProxyFactory responsible for creating IMessagePart
     * parts for this parser.
     *
     * This is called by ParserManager after 'canParse' if it returns true so
     * a ParserPartProxy can be created out of the PartBuilder.
     */
    public function getParserPartProxyFactory() : ParserPartProxyFactory;

    /**
     * Performs read operations for content from the stream of the passed
     * ParserPartProxy, and setting content bounds for the part in the passed
     * ParserPartProxy.
     *
     * The implementation should call $proxy->setStreamContentStartPos() and
     * $proxy->setStreamContentAndPartEndPos() so an IMessagePart can return
     * content from the raw message.
     *
     * Reading should stop once the end of the current part's content has been
     * reached or the end of the message has been reached.  If the end of the
     * message has been reached $proxy->setEof() should be called in addition to
     * setStreamContentAndPartEndPos().
     */
    public function parseContent(ParserPartProxy $proxy) : static;

    /**
     * Performs read operations to read children from the passed $proxy, using
     * its stream, and reading up to (and not including) the beginning of the
     * child's content if another child exists.
     *
     * The implementation should:
     *  1. Return null if there are no more children.
     *  2. Read headers
     *  3. Create a PartBuilder (adding the passed $proxy as its parent)
     *  4. Call ParserManager::createParserProxyFor() on the ParserManager
     *     previously set by a call to setParserManager(), which may determine
     *     that a different parser is responsible for parts represented by
     *     the headers and PartBuilder passed to it.
     *
     * The method should then return the ParserPartProxy returned by the
     * ParserManager, or null if there are no more children to read.
     *
     * @return ParserPartProxy|null The child ParserPartProxy or null if there
     *         are no more children under $proxy.
     */
    public function parseNextChild(ParserMimePartProxy $proxy) : ?ParserPartProxy;
}