001/*******************************************************************************
002 * Copyright (c) 2024, 2026, Olivier Ayache.  All rights reserved.
003 *
004 * This file is part of AVPKit.
005 *
006 * AVPKit is free software: you can redistribute it and/or modify
007 * it under the terms of the GNU Lesser General Public License as published by
008 * the Free Software Foundation, either version 3 of the License, or
009 * (at your option) any later version.
010 *
011 * AVPKit is distributed in the hope that it will be useful,
012 * but WITHOUT ANY WARRANTY; without even the implied warranty of
013 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
014 * GNU Lesser General Public License for more details.
015 *
016 * You should have received a copy of the GNU Lesser General Public License
017 * along with AVPKit.  If not, see <http://www.gnu.org/licenses/>.
018 *******************************************************************************/
019
020package com.avpkit.mediatool;
021
022import com.avpkit.core.IContainer;
023import com.avpkit.core.IStreamCoder;
024
025/**
026 * An {@link IMediaGenerator} that manages reading or writing to an {@link
027 * IContainer}.
028 * 
029 */
030
031public interface IMediaCoder extends IMediaGenerator
032{
033
034  /** 
035   * Get the underlying media {@link IContainer} that the {@link IMediaCoder} is
036   * reading from or writing to.  The returned {@link IContainer} can
037   * be further interrogated for media stream details.
038   *
039   * @return the media container.
040   */
041
042  public abstract IContainer getContainer();
043
044  /**
045   * The URL from which the {@link IContainer} is being read or written to.
046   * 
047   * @return the source or destination URL.
048   */
049
050  public abstract String getUrl();
051
052  /** 
053   * Open this {@link IMediaCoder}.  This will open the internal {@link
054   * IContainer}.  Typically the tool will open itself at the right
055   * time, but there may exist rare cases where the calling context
056   * may need to open the tool.
057   */
058
059  public abstract void open();
060
061  /**
062   * Test if this {@link IMediaCoder} is open.
063   * 
064   * @return true if the media tool is open.
065   */
066
067  public abstract boolean isOpen();
068    
069  /** 
070   * Close this {@link IMediaCoder}.  This will close all {@link IStreamCoder}s
071   * explicitly opened by tool, then close the internal {@link
072   * IContainer}, again only if it was explicitly opened by tool.
073   * 
074   * <p> Typically the tool will close itself at the right time, but there
075   * are instances where the calling context may need to close the
076   * tool. </p>
077   */
078
079  public abstract void close();
080}