<?php
/**
 * This file contains the ezcImageHandler interface.
 *
 * @package ImageConversion
 * @version 1.0beta2
 * @copyright Copyright (C) 2005 eZ systems as. All rights reserved.
 * @license http://ez.no/licenses/new_bsd New BSD License
 * @filesource
 */

/**
 * Driver interface to access different image manipulation backends of PHP.
 * This interface has to be implemented by a handler class in order to be
 * used with the ImageConversion package.
 *
 * @see ezcImageConverter
 *
 * @package ImageConversion
 */
abstract class ezcImageHandler
{
    /**
     * Name of the handler
     *
     * @var string
     */
    private $name;

    /**
     * Create a new image handler.
     * Creates an image handler. This should never be done directly,
     * but only through the manager for configuration reasons. One can
     * get a direct refernce through manager afterwards. When overwriting
     * the constructor.
     *
     * @param ezcImageHandlerSettings $settings
     *        Settings for the handler.
     */
    public function __construct( ezcImageHandlerSettings $settings )
    {
        $this->name = $settings->referenceName;
    }

    /**
     * Sets the property $name to $value.
     *
     * @throws ezcBasePropertyNotFoundException if the property does not exist.
     * @throws ezcBasePropertyReadOnlyException if the property cannot be modified.
     * @param string $name
     * @param mixed $value
     * @return void
     */
    public function __set( $name, $value )
    {
        switch ( $name )
        {
            case 'name':
                throw new ezcBasePropertyReadOnlyException( $name );
            default:
                throw new ezcBasePropertyNotFoundException( $name );
        }
    }

    /**
     * Returns the property $name.
     *
     * @throws ezcBasePropertyNotFoundException if the property does not exist.
     * @param string $name
     * @return mixed
     */
    public function __get( $name )
    {
        switch ( $name )
        {
            case 'name':
                return $this->$name;
            default:
                throw new ezcBasePropertyNotFoundException( $name );
        }
    }

    /**
     * Checks if the property $name exist and returns the result.
     *
     * @param string $name
     * @return bool
     */
    public function __isset( $name )
    {
        switch ( $name )
        {
            case 'name':
                return true;
            default:
                return false;
        }
    }

    /**
     * Load an image file.
     * Loads an image file and returns a reference to it.
     *
     * For developers: The use of ezcImageHandler::loadCommon() is highly
     * recommended for the implementation of this method!
     *
     * @param string $file File to load.
     * @param string $mime The MIME type of the file.
     * @return string Reference to the file in this handler.
     */
    abstract public function load( $file, $mime = null );

    /**
     * Save an image file.
     * Saves a given open file. Can optionally save to a new file name.
     * The image reference is not freed automatically, so you need to call
     * the close() method explicitly to free the referenced data.
     *
     * @see ezcImageHandler::load()
     * @see ezcImageHandler::close()
     *
     * @param string $image   File reference created through.
     * @param string $newFile Filename to save the image to.
     * @param string $mime    New MIME type, if differs from initial one.
     * @return void
     */
    abstract public function save( $image, $newFile = null, $mime = null );

    /**
     * Close the file referenced by $image.
     * Frees the image reference. You should call close() before.
     *
     * @see ezcImageHandler::load()
     * @see ezcImageHandler::save()
     * @param string $image The image reference.
     * @return void
     */
    abstract public function close( $reference );

    /**
     * Check wether a specific MIME type is allowed as input for this handler.
     *
     * @param string $mime MIME type to check if it's allowed.
     * @return bool
     */
    abstract public function allowsInput( $mime );

    /**
     * Checks wether a specific MIME type is allowed as output for this handler.
     *
     * @param string $mime MIME type to check if it's allowed.
     * @return bool
     */
    abstract public function allowsOutput( $mime );

    /**
     * Checks if a given filter is available in this handler.
     *
     * @param string $name Name of the filter to check for.
     * @return bool
     *
     * @throws ezcImageHandlerException
     *         If the filters object for the current filter does not exist.
     *         {@link ezcImageHandlerException::IMPLEMENTATION_ERROR}.
     */
    abstract public function hasFilter( $name );

    /**
     * Returns a list of filters this handler provides.
     * The list returned is in format:
     *
     * <code>
     * array(
     *  0 => <string filtername>,
     *  1 => <string filtername>,
     *  ...
     * )
     * </code>
     *
     * @return array(string)
     *
     * @throws ezcImageHandlerException
     *         If the filters object for the current filter does not exist.
     *         {@link ezcImageHandlerException::IMPLEMENTATION_ERROR}.
     */
    abstract public function getFilterNames();

    /**
     * Applies a filter to a given image.
     *
     * @internal This method is the main one, which will dispatch the
     * filter action to the specific function of the backend.
     *
     * @see ezcImageHandler::load()
     * @see ezcImageHandler::save()
     *
     * @param string $image          Image reference to apply the filter on.
     * @param ezcImageFilter $filter Contains which filter operation to apply.
     * @return void
     *
     * @throws ezcImageHandlerException
     *         If the filters object for the current filter does not exist.
     *         {@link ezcImageHandlerException::IMPLEMENTATION_ERROR}.
     * @throws ezcImageFiltersException
     *         If the desired filter does not exist.
     *         {@link ezcImageFiltersException::NOT_AVAILABLE}.
     * @throws ezcImageFiltersException
     *         If a parameter for the filter is missing.
     *         {@link ezcImageFiltersException::MISSING_PARAMETER}.
     * @throws ezcImageFiltersException
     *         If the operation performed by the the filter failed
     *         {@link ezcImageFiltersException::FAILED}.
     * @throws ezcImageFiltersException
     *         If a parameter was not within the expected range between 0 and 1
     *         {@link ezcImageFiltersException::INVALID_PARAMETER}.
     */
    abstract public function applyFilter( $image, ezcImageFilter $filter );

    /**
     * Converts an image to another MIME type.
     *
     * Use {@link ezcImageHandler::allowsOutput()} to determine,
     * if the output MIME type is supported by this handler!
     *
     * @see ezcImageHandler::load()
     * @see ezcImageHandler::save()
     *
     * @param string $image Image reference to convert.
     * @param string $mime  MIME type to convert to.
     * @return void
     *
     * @throws ezcImageHandlerException
     *         If the given MIME type is not supported by the filter
     *         {@link ezcImageHandlerException::UNKNOWN_TYPE}.
     */
    abstract public function convert( $image, $mime );
}
?>