codecs.h

radius协议源码÷The Radius Stack will connect to a Radius Server. This stack implementation is built upo

/*
 * codecs.h
 *
 * H.323 protocol handler
 *
 * Open H323 Library
 *
 * Copyright (c) 1998-2000 Equivalence Pty. Ltd.
 *
 * The contents of this file are subject to the Mozilla Public License
 * Version 1.0 (the "License"); you may not use this file except in
 * compliance with the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS"
 * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 * the License for the specific language governing rights and limitations
 * under the License.
 *
 * The Original Code is Open H323 Library.
 *
 * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
 *
 * Portions of this code were written with the assisance of funding from
 * Vovida Networks, Inc. http://www.vovida.com.
 *
 * Contributor(s): ______________________________________.
 *
 * $Log: codecs.h,v $
 * Revision 1.43  2000/05/16 02:04:16  craigs
 * Added access functions for silence compression mode
 *
 * Revision 1.42  2000/05/02 04:32:24  robertj
 * Fixed copyright notice comment.
 *
 * Revision 1.41  2000/04/14 20:11:16  robertj
 * Removed redundent member variable from H323FramedAudioCodec.
 *
 * Revision 1.40  2000/03/30 23:10:50  robertj
 * Fixed error in comments regarding GetFramerate() function.
 *
 * Revision 1.39  2000/03/21 03:06:47  robertj
 * Changes to make RTP TX of exact numbers of frames in some codecs.
 *
 * Revision 1.38  2000/02/28 13:00:22  robertj
 * Added some virtual keywords at the request of Yura Ershov
 *
 * Revision 1.37  2000/02/10 03:08:02  craigs
 * Added ability to specify NTSC or PAL video format
 *
 * Revision 1.36  2000/02/04 05:00:08  craigs
 * Changes for video transmission
 *
 * Revision 1.35  2000/01/13 04:03:45  robertj
 * Added video transmission
 *
 * Revision 1.34  1999/12/31 00:05:36  robertj
 * Added Microsoft ACM G.723.1 codec capability.
 *
 * Revision 1.33  1999/12/29 01:19:16  craigs
 * Fixed problem with RTP payload type variable
 *
 * Revision 1.32  1999/12/23 23:02:34  robertj
 * File reorganision for separating RTP from H.323 and creation of LID for VPB support.
 *
 * Revision 1.31  1999/11/29 09:01:46  craigs
 * Added new code for new video code interface
 *
 * Revision 1.30  1999/11/29 04:50:11  robertj
 * Added adaptive threshold calculation to silence detection.
 *
 * Revision 1.29  1999/11/20 00:53:46  robertj
 * Fixed ability to have variable sized frames in single RTP packet under G.723.1
 *
 * Revision 1.28  1999/11/13 14:10:32  robertj
 * Changes to make silence detection selectable.
 *
 * Revision 1.27  1999/11/11 23:28:52  robertj
 * Added first cut silence detection algorithm.
 *
 * Revision 1.26  1999/11/04 00:43:42  robertj
 * Added extra constructors for nonStandard codecs.
 *
 * Revision 1.25  1999/10/14 12:03:08  robertj
 * Fixed comment.
 *
 * Revision 1.24  1999/10/08 09:59:01  robertj
 * Rewrite of capability for sending multiple audio frames
 *
 * Revision 1.23  1999/10/08 04:58:37  robertj
 * Added capability for sending multiple audio frames in single RTP packet
 *
 * Revision 1.22  1999/09/23 07:25:12  robertj
 * Added open audio and video function to connection and started multi-frame codec send functionality.
 *
 * Revision 1.21  1999/09/21 14:51:33  robertj
 * Fixed NonStandardCapabilityInfo class virtual destructor (and name).
 *
 * Revision 1.20  1999/09/21 14:04:41  robertj
 * Added non-standard codec capability classes
 *
 * Revision 1.19  1999/09/21 08:12:49  craigs
 * Added support for video codecs and H261
 *
 * Revision 1.18  1999/09/18 13:27:24  craigs
 * Added ability disable jitter buffer for codecs
 * Added ability to access entire RTP frame from codec Write
 *
 * Revision 1.17  1999/09/08 04:05:48  robertj
 * Added support for video capabilities & codec, still needs the actual codec itself!
 *
 * Revision 1.16  1999/08/31 12:34:18  robertj
 * Added gatekeeper support.
 *
 * Revision 1.15  1999/08/25 03:08:23  robertj
 * Added UserInput capability.
 * Allowed the attachment of a channel on a codec to optionally delete the channel object,
 *
 * Revision 1.14  1999/07/22 14:32:48  robertj
 * Fixed erroneous comments
 *
 * Revision 1.13  1999/07/16 16:05:48  robertj
 * Added "human readable" codec type name display.
 *
 * Revision 1.12  1999/07/15 14:45:35  robertj
 * Added propagation of codec open error to shut down logical channel.
 * Fixed control channel start up bug introduced with tunnelling.
 *
 * Revision 1.11  1999/07/13 09:53:24  robertj
 * Fixed some problems with jitter buffer and added more debugging.
 *
 * Revision 1.10  1999/07/09 06:09:49  robertj
 * Major implementation. An ENORMOUS amount of stuff added everywhere.
 *
 * Revision 1.9  1999/06/24 13:32:45  robertj
 * Fixed ability to change sound device on codec and fixed NM3 G.711 compatibility
 *
 * Revision 1.8  1999/06/22 13:49:40  robertj
 * Added GSM support and further RTP protocol enhancements.
 *
 * Revision 1.7  1999/06/14 15:08:40  robertj
 * Added GSM codec class frame work (still no actual codec).
 *
 * Revision 1.6  1999/06/14 06:39:08  robertj
 * Fixed problem with getting transmit flag to channel from PDU negotiator
 *
 * Revision 1.5  1999/06/14 05:15:55  robertj
 * Changes for using RTP sessions correctly in H323 Logical Channel context
 *
 * Revision 1.4  1999/06/13 12:41:14  robertj
 * Implement logical channel transmitter.
 * Fixed H245 connect on receiving call.
 *
 * Revision 1.3  1999/06/09 05:26:19  robertj
 * Major restructuring of classes.
 *
 * Revision 1.2  1999/06/06 06:06:36  robertj
 * Changes for new ASN compiler and v2 protocol ASN files.
 *
 * Revision 1.1  1999/01/16 01:31:01  robertj
 * Initial revision
 *
 */

#ifndef __CODECS_H
#define __CODECS_H


/* The following classes have forward references to avoid including the VERY
   large header files for H225 and H245. If an application requires access
   to the protocol classes they can include them, but for simple usage their
   inclusion can be avoided.
 */
class H245_MiscellaneousCommand_type;
class H245_MiscellaneousIndication_type;

class H323Connection;
class H323VideoDevice;

#include <rtp.h>


///////////////////////////////////////////////////////////////////////////////

/**This class embodies the implementation of a specific codec instance
   used to transfer data via the logical channels opened and managed by the
   H323 control channel.

   An application may create a descendent off this class and override
   functions as required for descibing a codec.
 */
class H323Codec : public PObject
{
  PCLASSINFO(H323Codec, PObject);

  public:
    enum Direction {
      Encoder,
      Decoder
    };

    H323Codec(
      Direction direction   /// Direction in which this instance runs
    );


    /**Open the codec.
       This will open the codec for encoding or decoding, it is called after
       the logical channel have been established and the background threads to
       drive them have been started. This is primarily used to delay allocation
       of resources until the last millisecond.

       A descendent class may be created by the application and it may cast
       the connection parameter to the application defined descendent of 
       H323Connection to obtain information needed to open the codec.

       The default behaviour does nothing.
      */
    virtual BOOL Open(
      H323Connection & connection /// Connection between the endpoints
    );

    /**Close the codec.
      */
    virtual void Close() = 0;

    /**Encode the data from the appropriate device.
       This will encode a frame of data for transmission. The exact size and
       description of the data placed in the buffer is codec dependent but
       should be less than H323Capability::GetTxFramesInPacket() *
       H323Capability::GetMaxFrameSize() in length.

       The length parameter is filled with the actual length of the encoded
       data, often this will be the same as the size parameter.

       This function is called every GetFrameRate() timestamp units, so MUST
       take less than (or equal to) that amount of time to complete!

       Note that a returned length of zero indicates that time has passed but
       there is no data encoded. This is typically used for silence detection
       in an audio codec.
     */
    virtual BOOL Read(
      BYTE * buffer,            /// Buffer of encoded data
      unsigned & length,        /// Actual length of encoded data buffer
      RTP_DataFrame & rtpFrame  /// RTP data frame
    ) = 0;

    /**Decode the data and output it to appropriate device.
       This will decode a single frame of received data. The exact size and
       description of the data required in the buffer is codec dependent but
       should be less than H323Capability::GetRxFramesInPacket() *
       H323Capability::GetMaxFrameSize()  in length.

       It is expected this function anunciates the data. That is, for example
       with audio data, the sound is output on a speaker.

       This function is called every GetFrameRate() timestamp units, so MUST
       take less than that amount of time to complete!
     */
    virtual BOOL Write(
      const BYTE * buffer,          /// Buffer of encoded data
      unsigned length,              /// Length of encoded data buffer
      const RTP_DataFrame & frame,  /// Entire RTP frame
      unsigned & written            /// Number of bytes used from data buffer
    ) = 0;

    /**Get the frame rate in RTP timestamp units.
      */
    virtual unsigned GetFrameRate() const = 0;

    /**Get the number of RTP timestamp units per millisecond.
      */
    virtual unsigned GetTimeUnits() const = 0;

    /**Get the bandwidth used by the channel in 100's of bits/sec.
       The default behaviour is pure.
     */
    virtual unsigned GetBandwidth() const = 0;

    /**Indicate whether the codec requires jitter buffering.
      */
    virtual BOOL NeedsJitterBuffer() const = 0;

    /**Limit bit flow for the logical channel.
       The default behaviour does nothing.
     */
    virtual void OnFlowControl(
      long bitRateRestriction   /// Bit rate limitation
    );

    /**Process a miscellaneous command on the logical channel.
       The default behaviour does nothing.
     */
    virtual void OnMiscellaneousCommand(
      const H245_MiscellaneousCommand_type & type  /// Command to process
    );

    /**Process a miscellaneous indication on the logical channel.
       The default behaviour does nothing.
     */
    virtual void OnMiscellaneousIndication(
      const H245_MiscellaneousIndication_type & type  /// Indication to process
    );

    Direction GetDirection()   const { return direction; }
    RTP_DataFrame::PayloadTypes GetRTPPayloadType() const { return rtpPayloadType; }


  protected:
    Direction  direction;
    RTP_DataFrame::PayloadTypes rtpPayloadType;
};


/**This class defines a codec class that will use the standard platform PCM
   output device.

   An application may create a descendent off this class and override
   functions as required for descibing a specific codec.
 */
class H323AudioCodec : public H323Codec
{
  PCLASSINFO(H323AudioCodec, H323Codec);

  public:
    /** Create a new audio codec.
        This opens the standard PCM audio output device, for input and output
        and allows descendent codec classes to do audio I/O after
        decoding/encoding.
      */
    H323AudioCodec(
      Direction direction,      /// Direction in which this instance runs
      unsigned samplesPerFrame  /// Number of samples in a frame
    );

    ~H323AudioCodec();

    /**Open the codec.
       This will open the codec for encoding or decoding. This is primarily
       used to delay allocation of resources until the last minute.

       The default behaviour calls the H323EndPoint::OpenAudioChannel()
       function and assigns the result of that function to the raw data
       channel in the H323Codec class.
      */
    virtual BOOL Open(
      H323Connection & connection /// Connection between the endpoints
    );

    /**Close down the codec.
       This will close the codec breaking any block on the Read() or Write()
       functions.

       The default behaviour will close the rawDataChannel if it is not NULL
       and thene delete it if delteChannel is TRUE.
      */
    virtual void Close();

    /**Get the frame rate in timestamp units.
      */
    virtual unsigned GetFrameRate() const;

    /**Get the number of RTP timestamp units per millisecond.
      */
    virtual unsigned GetTimeUnits() const;

    /**Indicate whether the codec requires jitter buffering.
       Default behaviour returns TRUE, audio codecs require jitter buffering.
      */
    virtual BOOL NeedsJitterBuffer() const;

    /**Attach the raw data channel for use by codec.
       Note the channel provided will be deleted on destruction of the codec.
      */
    virtual BOOL AttachChannel(
      PChannel * channel,     /// Channel to read/write raw codec data
      BOOL autoDelete = TRUE  /// Channel is to be automatically deleted
    );


    enum SilenceDetectionMode {
      NoSilenceDetection,
      FixedSilenceDetection,
      AdaptiveSilenceDetection
    };

    /**Enable/Disable silence detection.
       The deadband periods are in audio samples of 8kHz.
      */
    void SetSilenceDetectionMode(
      SilenceDetectionMode mode,   /// New silence detection mode
      unsigned threshold = 0,      /// Threshold value if FixedSilenceDetection
      unsigned signalDeadband = 480, /// 60 milliseconds of signal needed
      unsigned silenceDeadband = 3200, /// 400 milliseconds of silence needed
      unsigned adaptivePeriod = 4800   /// 600 millisecond window for adaptive threshold
    );

    /**Get silence detection mode
      */
    SilenceDetectionMode GetSilenceDetectionMode() const;
    
    /**Check frame for a talk burst.
       This does the deadband calculations on the average signal levels
       returned by the GetAverageSignalLevel() function and based on the