// Copyright (C) 2001,2002,2004 Federico Montesino Pouzols <fedemp@altern.org>.
//
// This program 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; either version 2 of the License, or
// (at your option) any later version.
//
// This program 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 this program; if not, write to the Free Software
// Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
//
// As a special exception, you may use this file as part of a free software
// library without restriction.  Specifically, if other files instantiate
// templates or use macros or inline functions from this file, or you compile
// this file and link it with other files to produce an executable, this
// file does not by itself cause the resulting executable to be covered by
// the GNU General Public License.  This exception does not however
// invalidate any other reasons why the executable file might be covered by
// the GNU General Public License.
//
// This exception applies only to the code released under the name GNU
// ccRTP.  If you copy code from other releases into a copy of GNU
// ccRTP, as the General Public License permits, the exception does
// not apply to the code that you add in this way.  To avoid misleading
// anyone as to the status of such modified files, you must delete
// this exception notice from them.
//
// If you write modifications of your own for GNU ccRTP, it is your choice
// whether to permit this exception to apply to your modifications.
// If you do not wish that, delete this exception notice.
//

/**
 * @file queuebase.h
 *
 * @short Base classes for RTP queues.
 **/

#ifndef CCXX_RTP_QUEUEBASE_H_
#define CCXX_RTP_QUEUEBASE_H_

#include <commoncpp/pointer.h>
#include <ccrtp/rtppkt.h>
#include <ccrtp/sources.h>

NAMESPACE_COMMONCPP

/**
 * @defgroup queuebase Base classes for RTP queues.
 * @{
 **/

/**
 * @class AppDataUnit
 * @short Interface (envelope) to data received over RTP packets.
 *
 * A class of objects representing data transmitted over RTP packets.
 * Tipically, this object will apply to received data. Data blocks
 * received via RTP connections as well as its related objects
 * (source, etc), are accessed through the methods of this class.
 *
 * @author Federico Montesino Pouzols <fedemp@altern.org>
 **/
class __EXPORT AppDataUnit
{
public:
    AppDataUnit(const IncomingRTPPkt& packet, const SyncSource& src);

    inline ~AppDataUnit()
    { }

    /**
     * @param src the AppDataUnit object being copied
     */
    AppDataUnit(const AppDataUnit& src);

    /**
     * Assignment operator
     *
     * @param source the AppDataUnit object being assigned @return
     * the result of the assignment
     */
    AppDataUnit&
    operator=(const AppDataUnit& source);

    /**
     * @return type of this data
     */
    inline PayloadType
    getType() const
    { return datablock->getPayloadType(); }

    /**
     *  Get data as it is received in RTP packets (i.e. for
     *  multi-octet encodings, octets are in network
     *  order.
     *
     * @return Raw pointer to data block.
     **/
    inline const uint8* const
    getData() const
    { return datablock->getPayload(); }

    /**
     * @return length of data in octets
     **/
    size_t
    getSize() const
    { return datablock->getPayloadSize(); }

    /**
     * @return Source that sent this data
     */
    inline const SyncSource&
    getSource() const
    { return *source; }

    /**
     * Is this data unit marked?.
     *
     * @return true if marked.
     **/
    inline bool
    isMarked() const
    { return datablock->isMarked(); }

    /**
     * Get data unit sequence number.
     **/
    inline uint16
    getSeqNum() const
    { return datablock->getSeqNum(); }

    /**
     * Get the number of contributing sources in the CSRC list.
     **/
    inline uint8
    getContributorsCount() const
    { return (uint8)datablock->getCSRCsCount(); }

    /**
     * Get the array of 32-bit CSRC identifiers.
     *
     * @return NULL if (getContributorsCount() == 0)
     **/
    inline const uint32*
    getContributorsID() const
    { return datablock->getCSRCs(); }

private:
    Pointer<const IncomingRTPPkt> datablock;
    const SyncSource* source;
};

/**
 * @class RTPQueueBase
 *
 * A virtual base class for RTP queue hierarchies.
 *
 * @author Federico Montesino Pouzols <fedemp@altern.org>
 **/
class __EXPORT RTPQueueBase
{
public:
    /**
     * Set the payload format in use, for timing and payload type
     * identification purposes.
     *
     * @param pf payload format to use from now on.
     * @return whether the payload format has been successfully set.
     **/
    inline bool
    setPayloadFormat(const PayloadFormat& pf)
    {
        currentPayloadType = pf.getPayloadType();
        currentRTPClockRate = pf.getRTPClockRate();
        return true;
    }

    inline uint32 getLocalSSRC() const
    { return localSSRC; }

    /**
     * Get the clock rate in RTP clock units (for instance, 8000
     * units per second for PCMU, or 90000 units per second for
     * MP2T). This value depends on what payload format has been
     * selected using setPayloadFormat().
     *
     * @return clock rate in RTP clock units.
     **/
    inline uint32 getCurrentRTPClockRate() const
    { return currentRTPClockRate; }

    inline PayloadType getCurrentPayloadType() const
    { return currentPayloadType; }

    inline timeval getInitialTime() const
    { return initialTime; }

protected:
    /**
     * @param ssrc If not null, the local SSRC identifier for this
     * session.
     **/
    RTPQueueBase(uint32 *ssrc = NULL);

    inline void setLocalSSRC(uint32 ssrc)
    { localSSRC = ssrc; localSSRCNetwork = htonl(ssrc); }

    inline uint32 getLocalSSRCNetwork() const
    { return localSSRCNetwork; }

    virtual
    ~RTPQueueBase()
    { }

    /**
     * A plugin point for posting of BYE messages.
     *
     * @param - reason to leave the RTP session.
     * @return number of octets sent.
     **/
    inline virtual size_t
    dispatchBYE(const std::string&)
    { return 0; }

    inline virtual void
    renewLocalSSRC()
    { }

private:
    // local SSRC 32-bit identifier
    uint32 localSSRC;
    // SSRC in network byte order
    uint32 localSSRCNetwork;
    // RTP clock rate for the current payload type.
    uint32 currentRTPClockRate;
    // Current payload type set for outgoing packets and expected
    // from incoming packets.
    PayloadType currentPayloadType;
    // when the queue is created
    timeval initialTime;
};

/**
 * @class OutgoingDataQueueBase
 *
 * @author Federico Montesino Pouzols <fedemp@altern.org>
 **/
class __EXPORT OutgoingDataQueueBase:
    public virtual RTPQueueBase
{
public:
    inline size_t
    getDefaultMaxSendSegmentSize()
    { return defaultMaxSendSegmentSize;}

    /**
     * Set maximum payload segment size before fragmenting sends.
     *
     * @param size Maximum payload size.
     * @return Whether segment size was successfully set.
     **/
    inline void
    setMaxSendSegmentSize(size_t size)
    { maxSendSegmentSize = size; }

    inline size_t
    getMaxSendSegmentSize()
    { return maxSendSegmentSize; }

protected:
    OutgoingDataQueueBase();

    inline virtual
    ~OutgoingDataQueueBase()
    { }

private:
    static const size_t defaultMaxSendSegmentSize;
    // maximum packet size before fragmenting sends.
    size_t maxSendSegmentSize;
};

/**
 * @class IncomingDataQueueBase
 *
 * @author Federico Montesino Pouzols <fedemp@altern.org>
 **/
class __EXPORT IncomingDataQueueBase:
    public virtual RTPQueueBase
{
public:
    inline size_t getDefaultMaxRecvPacketSize() const
    { return defaultMaxRecvPacketSize; }

    inline size_t
    getMaxRecvPacketSize() const
    { return maxRecvPacketSize; }

    /**
     * @param maxsize maximum length of received RTP data packets,
     * in octets. Defaults to the value returned by
     * getDefaultMaxRecvPacketSize().
     *
     * @note This method sets a filter for incoming
     * packets. Setting higher values does not necessarily imply
     * higher memory usage (this method does not set any buffer
     * size).
     **/
    inline void
    setMaxRecvPacketSize(size_t maxsize)
    { maxRecvPacketSize = maxsize; }

protected:
    IncomingDataQueueBase()
    { setMaxRecvPacketSize(getDefaultMaxRecvPacketSize()); }

    inline virtual
    ~IncomingDataQueueBase()
    { }

private:
    static const size_t defaultMaxRecvPacketSize;
    // filter value for received packets length.
    size_t maxRecvPacketSize;
};

/** @}*/ // queuebase

END_NAMESPACE

#endif  //CCXX_RTP_QUEUEBASE_H_

/** EMACS **
 * Local variables:
 * mode: c++
 * c-basic-offset: 8
 * End:
 */