/* 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.
 *
 */


#ifndef _NMM_STREAM_TIMER_HPP_
#define _NMM_STREAM_TIMER_HPP_

#include "nmm/nmm_prefix.hpp"

#include "nmm/utils/NamedObject.hpp"
#include "nmm/multimedia/Node.hpp"
#include "nmm/utils/time/TimedElement.hpp"
#include "nmm/utils/time/Interval.hpp"
#include "nmm/comm/messaging/Timestamp.hpp"

namespace NMM {

  class Message;

  /** Stream timer.
   * A stream timer is a helper class which assigns timestamps to messages.
   * It is typically used by source nodes which produce data.
   *
   * The stream timer supports different timing modes. Currently real-time timing and
   * constant rate timing are supported. In real-time timing mode, the current system time
   * when is used as the presentation time of the buffer. In this mode, it is important
   * at which time the StreamTimer is invoked. In constant rate timing mode, subsequent
   * messages have constant offsets in their presentation time. Buffers will be presented
   * at a constant rate.
   */
  class StreamTimer
    : public TimedElement,
      public NamedObject
  {
  public:
    /** Timing mode.
     */
    enum MODE {
      REAL_TIME,  ///< Real time
      CONST_RATE  ///< Constant rate
    };

    static const MODE DEFAULT_MODE = REAL_TIME;   ///< Default timing mode

  private:
    Node* parent;            ///< Parent node which owns this timer
    int rate;                ///< Buffers per second (constant rate timing)
    Interval interval;       ///< Time different between two buffers (constant rate timing)
    Timestamp timestamp;     ///< Current timestamp
    MODE mode;               ///< Timing mode

    bool interval_set;       ///< Time between two buffers has already been computed
    bool delay_set;          ///< Not used

  public:
    /** Constructor.
     *
     * @param mode Timing mode
     */
    StreamTimer(const MODE mode);

    /** Constructor.
     *
     * @param parent Parent node which owns the timer
     * @param mode Timing mode
     */
    StreamTimer(const Node* parent = 0,
                const MODE mode = DEFAULT_MODE);

    /** Virtual destructor.
     */
    virtual ~StreamTimer();

    /** Reset the stream timer.
     * This method resets all variables.
     */
    void reset();

    /** Set the timing mode.
     *
     * @param mode Timing mode
     * @return SUCCESS if the mode was valid, FAILURE otherwise
     */
    Result setMode(const MODE mode);

    /** Set the number of buffers per second.
     * If the timing mode is CONSTANT_RATE, this method sets the number of buffers per second
     * and therefore the offset of the presentation time of each buffer relative to the
     * presentation time of the previous buffer.
     * The rate must be positive. Otherwise, this method fails.
     *
     * @param rate Buffers per second
     * @return SUCCESS if the rate was valid, FAILURE otherwise
     */
    Result setRate(const float rate);

    /** Set the time interval between two buffers.
     * If the timing mode is CONSTANT_RATE, this method sets the offset of the presentation time
     * of each buffer relative to the presentation time of the previous buffer.
     * The interval must be positive. Otherwise, this method fails.
     *
     * @param interval Time interval between two buffers
     * @return SUCCESS if the interval was valid, FAILURE otherwise
     */
    Result setInterval(const Interval interval);

    /** Set the timestamp of a message using this timer.
     * This method assigns a presentation time to the given message using the selected timing mode
     * and timing parameters.
     * If the timing mode is CONSTANT_RATE and no rate or interval was set, this method fails.
     *
     * @param message A message
     * @return SUCCESS if this method succeeded, FAILURE otherwise
     */
    Result setTimestamp(Message* message);
  };
}

#include "nmm/nmm_suffix.hpp"

#endif // _NMM_STREAM_TIMER_HPP_
