/* Network-Integrated Multimedia Middleware (NMM)
 * http://www.motama.com/nmm.html
 *
 * Copyright (C) 2006-2007
 * Motama GmbH, Saarbruecken, Germany
 * http://www.motama.com
 *
 * This file is part of NMM. 
 * 
 * NMM 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; only version 2 of the License.      
 * 
 * NMM 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 NMM; if not, write to the Free Software Foundation,    
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 */

#include "nmm/multimedia/IDevice.idl"

module NMM {
  
  /**
   *  @brief DVD Interface
   *
   *  This interface is used for direct navigation on DVDs. It can be used for determining the number
   *  of chapters, titles and view angles and for selecting which title, chapter and view angle to play.
   *
   *  The interface is derived from IDevice to provide methods for getting and setting the DVD device.
   */
  interface IDVD : IDevice {
    
    /**
     *  @brief Select chapter, title and view angle
     *  @param title Title to play
     *  @param chapter Chapter to play
     *  @param angle View angle to play
     *  @return SUCCESS if the method succeeds, otherwise FAILURE
     *
     *  This method sets the @a title, @a chapter and view @a angle to play. The title must be between 1 and getTitles()
     *  inclusive, the chapter must be between 1 and getChapters(title) inclusive and the view angle must be between
     *  1 and getAngles(title) inclusive. Otherwise the method fails.
     */
    Result select(in nmm_uint32 title, in nmm_uint32 chapter, in nmm_uint32 angle);
    
    /**
     *  @brief Get current title
     *  @return The current title number
     *
     *  This method returns the number of the title currently being played. If no title is being played, or the
     *  current title is invalid, the result is zero.
     */
    nmm_uint32 getCurrentTitle() const;
    
    /**
     *  @brief Get current chapter
     *  @return The current chapternumber
     *
     *  This method returns the number of the chapter currently being played. If no chapter is being played, or the
     *  current chapter is invalid, the result is zero.
     */
    nmm_uint32 getCurrentChapter() const;
    
    /**
     *  @brief Get number of titles
     *  @return The number of titles on the DVD
     *
     *  This method returns the number of titles on the DVD, which is also the highest possible title number.
     */
    nmm_uint32 getTitles() const;

    /**
     *  @brief Get number of chapters in a title
     *  @param title Title number
     *  @return The number of chapters in the title
     *
     *  This method returns the number of chapters in the given @a title, which is also the highest possible chapter
     *  number for that title. The title number must be between 1 and getTitles() inclusive.
     */
    nmm_uint32 getChapters(in nmm_uint32 title) const;
    
    /**
     *  @brief Get number of view angles in a title
     *  @param title Title number
     *  @return The number of angles in the title
     *
     *  This method returns the number of angles in the given @a title, which is also the highest possible angle
     *  number for that title. The title number must be between 1 and getTitles() inclusive.
     */
    nmm_uint32 getAngles(in nmm_uint32 title) const;
    
    /**
     *  @brief Send a flush event
     *
     *  This method causes the ndoe to send a flush event.
     *  Currently, applications using the DVDNavReadNode do this explicitly before changing the chapter.
     *  If this is really necessary, the node should do it itself, but it has to be tested.
     */
    void sendFlush();
    
    /**
     *  @brief Reset the DVD
     *
     *  Reset the DVD to the beginning.
     */
    void reset();
  };
  
}
