home *** CD-ROM | disk | FTP | other *** search
/ ftp.muug.mb.ca / 2014.06.ftp.muug.mb.ca.tar / ftp.muug.mb.ca / pub / openh323.tar.gz / openh323.tar / openh323 / include / h323caps.h < prev    next >
C/C++ Source or Header  |  2003-06-05  |  71KB  |  2,009 lines
  1. /*
  2.  * h323caps.h
  3.  *
  4.  * H.323 protocol handler
  5.  *
  6.  * Open H323 Library
  7.  *
  8.  * Copyright (c) 1998-2000 Equivalence Pty. Ltd.
  9.  *
  10.  * The contents of this file are subject to the Mozilla Public License
  11.  * Version 1.0 (the "License"); you may not use this file except in
  12.  * compliance with the License. You may obtain a copy of the License at
  13.  * http://www.mozilla.org/MPL/
  14.  *
  15.  * Software distributed under the License is distributed on an "AS IS"
  16.  * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
  17.  * the License for the specific language governing rights and limitations
  18.  * under the License.
  19.  *
  20.  * The Original Code is Open H323 Library.
  21.  *
  22.  * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
  23.  *
  24.  * Portions of this code were written with the assisance of funding from
  25.  * Vovida Networks, Inc. http://www.vovida.com.
  26.  *
  27.  * Contributor(s): ______________________________________.
  28.  *
  29.  * $Log: h323caps.h,v $
  30.  * Revision 1.39  2003/06/06 02:13:10  rjongbloed
  31.  * Changed non-standard capability semantics so can use C style strings as
  32.  *   the embedded data block (ie automatically call strlen)
  33.  *
  34.  * Revision 1.38  2003/04/28 07:00:00  robertj
  35.  * Fixed problem with compiler(s) not correctly initialising static globals
  36.  *
  37.  * Revision 1.37  2003/04/27 23:49:21  craigs
  38.  * Fixed some comments and made list of registered codecs
  39.  * available outside h323caps.cxx
  40.  *
  41.  * Revision 1.36  2002/11/09 04:24:01  robertj
  42.  * Fixed minor documentation errors.
  43.  *
  44.  * Revision 1.35  2002/09/16 01:14:15  robertj
  45.  * Added #define so can select if #pragma interface/implementation is used on
  46.  *   platform basis (eg MacOS) rather than compiler, thanks Robert Monaghan.
  47.  *
  48.  * Revision 1.34  2002/09/03 06:19:36  robertj
  49.  * Normalised the multi-include header prevention ifdef/define symbol.
  50.  *
  51.  * Revision 1.33  2002/08/05 10:03:47  robertj
  52.  * Cosmetic changes to normalise the usage of pragma interface/implementation.
  53.  *
  54.  * Revision 1.32  2002/05/29 03:55:17  robertj
  55.  * Added protocol version number checking infrastructure, primarily to improve
  56.  *   interoperability with stacks that are unforgiving of new features.
  57.  *
  58.  * Revision 1.31  2002/05/10 05:44:50  robertj
  59.  * Added the max bit rate field to the data channel capability class.
  60.  *
  61.  * Revision 1.30  2002/01/22 06:25:02  robertj
  62.  * Moved payload type to ancestor so any capability can adjust it on logical channel.
  63.  *
  64.  * Revision 1.29  2002/01/17 07:04:57  robertj
  65.  * Added support for RFC2833 embedded DTMF in the RTP stream.
  66.  *
  67.  * Revision 1.28  2002/01/16 05:37:41  robertj
  68.  * Added missing mode change functions on non standard capabilities.
  69.  *
  70.  * Revision 1.27  2002/01/09 00:21:36  robertj
  71.  * Changes to support outgoing H.245 RequstModeChange.
  72.  *
  73.  * Revision 1.26  2001/12/22 01:44:05  robertj
  74.  * Added more support for H.245 RequestMode operation.
  75.  *
  76.  * Revision 1.25  2001/10/24 01:20:34  robertj
  77.  * Added code to help with static linking of H323Capability names database.
  78.  *
  79.  * Revision 1.24  2001/09/21 02:48:51  robertj
  80.  * Added default implementation for PDU encode/decode for codecs
  81.  *   that have simple integer as frames per packet.
  82.  *
  83.  * Revision 1.23  2001/09/11 10:21:40  robertj
  84.  * Added direction field to capabilities, thanks Nick Hoath.
  85.  *
  86.  * Revision 1.22  2001/07/19 09:50:40  robertj
  87.  * Added code for default session ID on data channel being three.
  88.  *
  89.  * Revision 1.21  2001/07/17 04:44:29  robertj
  90.  * Partial implementation of T.120 and T.38 logical channels.
  91.  *
  92.  * Revision 1.20  2001/05/21 07:20:47  robertj
  93.  * Removed redundent class name in declaration.
  94.  *
  95.  * Revision 1.19  2001/05/14 05:56:26  robertj
  96.  * Added H323 capability registration system so can add capabilities by
  97.  *   string name instead of having to instantiate explicit classes.
  98.  *
  99.  * Revision 1.18  2001/05/02 16:22:21  rogerh
  100.  * Add IsAllow() for a single capability to check if it is in the
  101.  * capabilities set. This fixes the bug where OpenH323 would accept
  102.  * incoming H261 video even when told not to accept it.
  103.  *
  104.  * Revision 1.17  2001/03/16 23:00:21  robertj
  105.  * Improved validation of codec selection against capability set, thanks Chris Purvis.
  106.  *
  107.  * Revision 1.16  2001/02/09 05:16:24  robertj
  108.  * Added #pragma interface for GNU C++.
  109.  *
  110.  * Revision 1.15  2001/01/25 07:27:14  robertj
  111.  * Major changes to add more flexible OpalMediaFormat class to normalise
  112.  *   all information about media types, especially codecs.
  113.  *
  114.  * Revision 1.14  2001/01/09 23:05:22  robertj
  115.  * Fixed inability to have 2 non standard codecs in capability table.
  116.  *
  117.  * Revision 1.13  2000/10/16 08:49:30  robertj
  118.  * Added single function to add all UserInput capability types.
  119.  *
  120.  * Revision 1.12  2000/08/23 14:23:11  craigs
  121.  * Added prototype support for Microsoft GSM codec
  122.  *
  123.  * Revision 1.11  2000/07/13 12:25:47  robertj
  124.  * Fixed problems with fast start frames per packet adjustment.
  125.  *
  126.  * Revision 1.10  2000/07/10 16:01:50  robertj
  127.  * Started fixing capability set merging, still more to do.
  128.  *
  129.  * Revision 1.9  2000/07/04 01:16:49  robertj
  130.  * Added check for capability allowed in "combinations" set, still needs more done yet.
  131.  *
  132.  * Revision 1.8  2000/06/03 03:16:47  robertj
  133.  * Fixed using the wrong capability table (should be connections) for some operations.
  134.  *
  135.  * Revision 1.7  2000/05/23 11:32:27  robertj
  136.  * Rewrite of capability table to combine 2 structures into one and move functionality into that class
  137.  *    allowing some normalisation of usage across several applications.
  138.  * Changed H323Connection so gets a copy of capabilities instead of using endponts, allows adjustments
  139.  *    to be done depending on the remote client application.
  140.  *
  141.  * Revision 1.6  2000/05/18 11:53:34  robertj
  142.  * Changes to support doc++ documentation generation.
  143.  *
  144.  * Revision 1.5  2000/05/10 04:05:26  robertj
  145.  * Changed capabilities so has a function to get name of codec, instead of relying on PrintOn.
  146.  *
  147.  * Revision 1.4  2000/05/02 04:32:24  robertj
  148.  * Fixed copyright notice comment.
  149.  *
  150.  * Revision 1.3  2000/04/05 19:01:12  robertj
  151.  * Added function so can change desired transmit packet size.
  152.  *
  153.  * Revision 1.2  2000/03/21 03:06:47  robertj
  154.  * Changes to make RTP TX of exact numbers of frames in some codecs.
  155.  *
  156.  * Revision 1.1  1999/12/23 23:02:35  robertj
  157.  * File reorganision for separating RTP from H.323 and creation of LID for VPB support.
  158.  *
  159.  */
  160.  
  161. #ifndef __OPAL_H323CAPS_H
  162. #define __OPAL_H323CAPS_H
  163.  
  164. #ifdef P_USE_PRAGMA
  165. #pragma interface
  166. #endif
  167.  
  168.  
  169. #include "codecs.h"
  170. #include "channels.h"
  171.  
  172.  
  173. /* The following classes have forward references to avoid including the VERY
  174.    large header files for H225 and H245. If an application requires access
  175.    to the protocol classes they can include them, but for simple usage their
  176.    inclusion can be avoided.
  177.  */
  178. class PASN_Choice;
  179. class H245_Capability;
  180. class H245_DataType;
  181. class H245_ModeElement;
  182. class H245_AudioCapability;
  183. class H245_AudioMode;
  184. class H245_VideoCapability;
  185. class H245_VideoMode;
  186. class H245_DataApplicationCapability;
  187. class H245_DataMode;
  188. class H245_DataProtocolCapability;
  189. class H245_H2250LogicalChannelParameters;
  190. class H245_TerminalCapabilitySet;
  191. class H245_NonStandardParameter;
  192. class H323Connection;
  193. class H323Capabilities;
  194.  
  195.  
  196.  
  197. ///////////////////////////////////////////////////////////////////////////////
  198.  
  199. /**This class describes the interface to a capability of the endpoint, usually
  200.    a codec, used to transfer data via the logical channels opened and managed
  201.    by the H323 control channel.
  202.  
  203.    Note that this is not an instance of the codec itself. Merely the
  204.    description of that codec. There is typically only one instance of this
  205.    class contained in the capability tables of the endpoint. There may be
  206.    several instances of the actualy codec managing the conversion of an
  207.    individual stream of data.
  208.  
  209.    An application may create a descendent off this class and override
  210.    functions as required for describing a codec that it implements.
  211.  */
  212. class H323Capability : public PObject
  213. {
  214.   PCLASSINFO(H323Capability, PObject);
  215.  
  216.   public:
  217.   /**@name Construction */
  218.   //@{
  219.     /**Create a new capability specification.
  220.      */
  221.     H323Capability();
  222.   //@}
  223.  
  224.   /**@name Overrides from class PObject */
  225.   //@{
  226.     /**Compare two capability instances. This compares the main and sub-types
  227.        of the capability.
  228.      */
  229.     Comparison Compare(const PObject & obj) const;
  230.  
  231.     /**Print out the object to the stream, virtual version of << operator.
  232.      */
  233.     void PrintOn(ostream & strm) const;
  234.   //@}
  235.  
  236.   /**@name Identification functions */
  237.   //@{
  238.     enum MainTypes {
  239.       /// Audio codec capability
  240.       e_Audio,
  241.       /// Video codec capability
  242.       e_Video,
  243.       /// Arbitrary data capability
  244.       e_Data,
  245.       /// User Input capability
  246.       e_UserInput,
  247.       /// Count of main types
  248.       e_NumMainTypes
  249.     };
  250.  
  251.     /**Get the main type of the capability.
  252.  
  253.        This function is overridden by one of the three main sub-classes off
  254.        which real capabilities would be descendend.
  255.      */
  256.     virtual MainTypes GetMainType() const = 0;
  257.  
  258.     /**Get the sub-type of the capability. This is a code dependent on the
  259.        main type of the capability.
  260.      */
  261.     virtual unsigned  GetSubType()  const = 0;
  262.  
  263.     /**Get the name of the media data format this class represents.
  264.      */
  265.     virtual PString GetFormatName() const = 0;
  266.   //@}
  267.  
  268.   /**@name Operations */
  269.   //@{
  270.     /**Create an H323Capability descendant given a string name.
  271.        This uses the registration system to create the capability.
  272.       */
  273.     static H323Capability * Create(
  274.       H323EndPoint & ep,      /// EndPoint capability is created for.
  275.       const PString & name    /// Name of capability
  276.     );
  277.  
  278.     /**Get the default RTP session.
  279.        This function gets the default RTP session ID for the capability
  280.        type. For example audio capabilities return the value
  281.        RTP_Session::DefaultAudioSessionID etc.
  282.  
  283.        The default behaviour returns zero, indicating it is not an RTP
  284.        based capability.
  285.       */
  286.     virtual unsigned GetDefaultSessionID() const;
  287.  
  288.     /**Set the maximum size (in frames) of data that will be transmitted in a
  289.        single PDU.
  290.  
  291.        This will also be the desired number that will be sent by most codec
  292.        implemetations.
  293.  
  294.        The default behaviour does nothing.
  295.      */
  296.     virtual void SetTxFramesInPacket(
  297.       unsigned frames   /// Number of frames per packet
  298.     );
  299.  
  300.     /**Get the maximum size (in frames) of data that will be transmitted in a single PDU.
  301.  
  302.        The default behaviour returns the value 1.
  303.      */
  304.     virtual unsigned GetTxFramesInPacket() const;
  305.  
  306.     /**Get the maximum size (in frames) of data that can be received in a single PDU.
  307.  
  308.        The default behaviour returns the value 1.
  309.      */
  310.     virtual unsigned GetRxFramesInPacket() const;
  311.  
  312.     /**Create the channel instance, allocating resources as required.
  313.        This creates a logical channel object appropriate for the parameters
  314.        provided. Not if param is NULL, sessionID must be provided, otherwise
  315.        this is taken from the fields in param.
  316.      */
  317.     virtual H323Channel * CreateChannel(
  318.       H323Connection & connection,    /// Owner connection for channel
  319.       H323Channel::Directions dir,    /// Direction of channel
  320.       unsigned sessionID,             /// Session ID for RTP channel
  321.       const H245_H2250LogicalChannelParameters * param
  322.                                       /// Parameters for channel
  323.     ) const = 0;
  324.  
  325.     /**Create the codec instance, allocating resources as required.
  326.      */
  327.     virtual H323Codec * CreateCodec(
  328.       H323Codec::Direction direction  /// Direction in which this instance runs
  329.     ) const = 0;
  330.   //@}
  331.  
  332.   /**@name Protocol manipulation */
  333.   //@{
  334.     /**This function is called whenever and outgoing TerminalCapabilitySet
  335.        PDU is being constructed for the control channel. It allows the
  336.        capability to set the PDU fields from information in members specific
  337.        to the class.
  338.  
  339.        The default behaviour is pure.
  340.      */
  341.     virtual BOOL OnSendingPDU(
  342.       H245_Capability & pdu  /// PDU to set information on
  343.     ) const = 0;
  344.  
  345.     /**This function is called whenever and outgoing OpenLogicalChannel
  346.        PDU is being constructed for the control channel. It allows the
  347.        capability to set the PDU fields from information in members specific
  348.        to the class.
  349.  
  350.        The default behaviour is pure.
  351.      */
  352.     virtual BOOL OnSendingPDU(
  353.       H245_DataType & pdu  /// PDU to set information on
  354.     ) const = 0;
  355.  
  356.     /**This function is called whenever and outgoing RequestMode
  357.        PDU is being constructed for the control channel. It allows the
  358.        capability to set the PDU fields from information in members specific
  359.        to the class.
  360.  
  361.        The default behaviour is pure.
  362.      */
  363.     virtual BOOL OnSendingPDU(
  364.       H245_ModeElement & pdu  /// PDU to set information on
  365.     ) const = 0;
  366.  
  367.     /**This function is called whenever and incoming TerminalCapabilitySet
  368.        PDU is received on the control channel, and a new H323Capability
  369.        descendent was created. This completes reading fields from the PDU
  370.        into the classes members.
  371.  
  372.        If the function returns FALSE then the received PDU codec description
  373.        is not supported, so will be ignored.
  374.        
  375.          The default behaviour sets the capabilityDirection member variable
  376.          from the PDU and then returns TRUE. Note that this means it is very
  377.          important to call the ancestor function when overriding.
  378.      */
  379.     virtual BOOL OnReceivedPDU(
  380.       const H245_Capability & pdu /// PDU to get information from
  381.     );
  382.  
  383.     /**This function is called whenever and incoming OpenLogicalChannel
  384.        PDU has been used to construct the control channel. It allows the
  385.        capability to set from the PDU fields, information in members specific
  386.        to the class.
  387.  
  388.        The default behaviour is pure.
  389.      */
  390.     virtual BOOL OnReceivedPDU(
  391.       const H245_DataType & pdu,  /// PDU to get information from
  392.       BOOL receiver               /// Is receiver OLC
  393.     ) = 0;
  394.  
  395.     /**Compare the nonStandardData part of the capability, if applicable.
  396.       */
  397.     virtual BOOL IsNonStandardMatch(
  398.       const H245_NonStandardParameter & param  /// Non standard field in PDU received
  399.     ) const;
  400.  
  401.     /**Validate that the capability is usable given the connection.
  402.        This checks agains the negotiated protocol version number and remote
  403.        application to determine if this capability should be used in TCS or
  404.        OLC pdus.
  405.  
  406.        The default behaviour returns TRUE.
  407.       */
  408.     virtual BOOL IsUsable(
  409.       const H323Connection & connection
  410.     ) const;
  411.   //@}
  412.  
  413.   /**@name Member variable access */
  414.   //@{
  415.     enum CapabilityDirection {
  416.       e_Unknown,
  417.       e_Receive,
  418.       e_Transmit,
  419.       e_ReceiveAndTransmit,
  420.       e_NoDirection,
  421.       NumCapabilityDirections
  422.     };
  423.  
  424.     /**Get the direction for this capability.
  425.       */ 
  426.     CapabilityDirection GetCapabilityDirection() const { return capabilityDirection; }
  427.  
  428.     /**Set the direction for this capability.
  429.       */
  430.     void SetCapabilityDirection(
  431.       CapabilityDirection dir   /// New direction code
  432.     ) { capabilityDirection = dir; }
  433.  
  434.     /// Get unique capability number.
  435.     unsigned GetCapabilityNumber() const { return assignedCapabilityNumber; }
  436.  
  437.     /// Set unique capability number.
  438.     void SetCapabilityNumber(unsigned num) { assignedCapabilityNumber = num; }
  439.  
  440.     /// Get the payload type for the capaibility
  441.     RTP_DataFrame::PayloadTypes GetPayloadType() const { return rtpPayloadType; }
  442.   //@}
  443.  
  444. #if PTRACING
  445.     friend ostream & operator<<(ostream & o , MainTypes t);
  446.     friend ostream & operator<<(ostream & o , CapabilityDirection d);
  447. #endif
  448.  
  449.   protected:
  450.     unsigned assignedCapabilityNumber;  /// Unique ID assigned to capability
  451.     CapabilityDirection capabilityDirection;
  452.     RTP_DataFrame::PayloadTypes rtpPayloadType;
  453. };
  454.  
  455.  
  456.  
  457. /**This class describes the interface to a non-standard codec used to
  458.    transfer data via the logical channels opened and managed by the H323
  459.    control channel.
  460.  
  461.    It is expected that an application makes a descendent off
  462.    H323NonStandardAudioCapability or H323NonStandardVideoCapability which
  463.    multiply inherit from this class.
  464.  */
  465. class H323NonStandardCapabilityInfo
  466. {
  467.   public:
  468.     /**Create a new set of information about a non-standard codec.
  469.       */
  470.     H323NonStandardCapabilityInfo(
  471.       H323EndPoint & endpoint,        /// Endpoint to get t35 information
  472.       const BYTE * dataBlock,         /// Non-Standard data for codec type
  473.       PINDEX dataSize,                /// Size of dataBlock. If 0 and dataBlock != NULL use strlen(dataBlock)
  474.       PINDEX comparisonOffset = 0,    /// Offset into dataBlock to compare
  475.       PINDEX comparisonLength = P_MAX_INDEX  /// Length of bytes to compare
  476.     );
  477.  
  478.     /**Create a new set of information about a non-standard codec.
  479.       */
  480.     H323NonStandardCapabilityInfo(
  481.       const PString & oid,
  482.       const BYTE * dataBlock,         /// Non-Standard data for codec type
  483.       PINDEX dataSize,                /// Size of dataBlock. If 0 and dataBlock != NULL use strlen(dataBlock)
  484.       PINDEX comparisonOffset = 0,
  485.       PINDEX comparisonLength = P_MAX_INDEX
  486.     );
  487.  
  488.     /**Create a new set of information about a non-standard codec.
  489.       */
  490.     H323NonStandardCapabilityInfo(
  491.       BYTE country,                  /// t35 information
  492.       BYTE extension,                /// t35 information
  493.       WORD maufacturer,              /// t35 information
  494.       const BYTE * dataBlock,         /// Non-Standard data for codec type
  495.       PINDEX dataSize,                /// Size of dataBlock. If 0 and dataBlock != NULL use strlen(dataBlock)
  496.       PINDEX comparisonOffset = 0,    /// Offset into dataBlock to compare
  497.       PINDEX comparisonLength = P_MAX_INDEX  /// Length of bytes to compare
  498.     );
  499.  
  500.     /**Destroy the capability information
  501.      */
  502.     virtual ~H323NonStandardCapabilityInfo();
  503.  
  504.     /**This function gets the non-standard data field.
  505.  
  506.        The default behaviour sets data to fixedData.
  507.       */
  508.     virtual BOOL OnSendingPDU(
  509.       PBYTEArray & data  /// Data field in PDU to send
  510.     ) const;
  511.  
  512.     /**This function validates and uses the non-standard data field.
  513.  
  514.        The default behaviour returns TRUE if data is equal to fixedData.
  515.       */
  516.     virtual BOOL OnReceivedPDU(
  517.       const PBYTEArray & data  /// Data field in PDU received
  518.     );
  519.  
  520.     PObject::Comparison CompareParam(
  521.       const H245_NonStandardParameter & param
  522.     ) const;
  523.  
  524.   protected:
  525.     BOOL OnSendingNonStandardPDU(
  526.       PASN_Choice & pdu,
  527.       unsigned nonStandardTag
  528.     ) const;
  529.     BOOL OnReceivedNonStandardPDU(
  530.       const PASN_Choice & pdu,
  531.       unsigned nonStandardTag
  532.     );
  533.  
  534.     PObject::Comparison CompareInfo(
  535.       const H323NonStandardCapabilityInfo & obj
  536.     ) const;
  537.     PObject::Comparison CompareData(
  538.       const PBYTEArray & data  /// Data field in PDU received
  539.     ) const;
  540.  
  541.     PString    oid;
  542.     BYTE       t35CountryCode;
  543.     BYTE       t35Extension;
  544.     WORD       manufacturerCode;
  545.     PBYTEArray nonStandardData;
  546.     PINDEX     comparisonOffset;
  547.     PINDEX     comparisonLength;
  548. };
  549.  
  550.  
  551. /**This class describes the interface to a codec that has channels based on
  552.    the RTP protocol.
  553.  
  554.    An application may create a descendent off this class and override
  555.    functions as required for descibing the codec.
  556.  */
  557. class H323RealTimeCapability : public H323Capability
  558. {
  559.   PCLASSINFO(H323RealTimeCapability, H323Capability);
  560.  
  561.   public:
  562.   /**@name Operations */
  563.   //@{
  564.     /**Create the channel instance, allocating resources as required.
  565.      */
  566.     virtual H323Channel * CreateChannel(
  567.       H323Connection & connection,    /// Owner connection for channel
  568.       H323Channel::Directions dir,    /// Direction of channel
  569.       unsigned sessionID,             /// Session ID for RTP channel
  570.       const H245_H2250LogicalChannelParameters * param
  571.                                       /// Parameters for channel
  572.     ) const;
  573.   //@}
  574. };
  575.  
  576.  
  577. /**This class describes the interface to an audio codec used to transfer data
  578.    via the logical channels opened and managed by the H323 control channel.
  579.  
  580.    An application may create a descendent off this class and override
  581.    functions as required for descibing the codec.
  582.  */
  583. class H323AudioCapability : public H323RealTimeCapability
  584. {
  585.   PCLASSINFO(H323AudioCapability, H323RealTimeCapability);
  586.  
  587.   public:
  588.   /**@name Construction */
  589.   //@{
  590.     /**Create an audio based capability.
  591.       */
  592.     H323AudioCapability(
  593.       unsigned rxPacketSize, /// Maximum size of an audio packet in frames
  594.       unsigned txPacketSize  /// Desired transmit size of an audio packet frames
  595.     );
  596.   //@}
  597.  
  598.   /**@name Identification functions */
  599.   //@{
  600.     /**Get the main type of the capability.
  601.        Always returns e_Audio.
  602.      */
  603.     virtual MainTypes GetMainType() const;
  604.   //@}
  605.  
  606.   /**@name Operations */
  607.   //@{
  608.     /**Get the default RTP session.
  609.        This function gets the default RTP session ID for the capability
  610.        type. For example audio capabilities return the value
  611.        RTP_Session::DefaultAudioSessionID etc.
  612.  
  613.        The default behaviour returns zero, indicating it is not an RTP
  614.        based capability.
  615.       */
  616.     virtual unsigned GetDefaultSessionID() const;
  617.  
  618.     /**Set the maximum size (in frames) of data that will be transmitted in a
  619.        single PDU.
  620.  
  621.        This will also be the desired number that will be sent by most codec
  622.        implemetations.
  623.  
  624.        The default behaviour sets the txFramesInPacket variable.
  625.      */
  626.     virtual void SetTxFramesInPacket(
  627.       unsigned frames   /// Number of frames per packet
  628.     );
  629.  
  630.     /**Get the maximum size (in frames) of data that will be transmitted in a
  631.        single PDU.
  632.  
  633.        The default behaviour sends the txFramesInPacket variable.
  634.      */
  635.     virtual unsigned GetTxFramesInPacket() const;
  636.  
  637.     /**Get the maximum size (in frames) of data that can be received in a
  638.        single PDU.
  639.  
  640.        The default behaviour sends the rxFramesInPacket variable.
  641.      */
  642.     virtual unsigned GetRxFramesInPacket() const;
  643.   //@}
  644.  
  645.   /**@name Protocol manipulation */
  646.   //@{
  647.     /**This function is called whenever and outgoing TerminalCapabilitySet
  648.        PDU is being constructed for the control channel. It allows the
  649.        capability to set the PDU fields from information in members specific
  650.        to the class.
  651.  
  652.        The default behaviour calls the OnSendingPDU() function with a more
  653.        specific PDU type.
  654.      */
  655.     virtual BOOL OnSendingPDU(
  656.       H245_Capability & pdu  /// PDU to set information on
  657.     ) const;
  658.  
  659.     /**This function is called whenever and outgoing OpenLogicalChannel
  660.        PDU is being constructed for the control channel. It allows the
  661.        capability to set the PDU fields from information in members specific
  662.        to the class.
  663.  
  664.        The default behaviour calls the OnSendingPDU() function with a more
  665.        specific PDU type.
  666.      */
  667.     virtual BOOL OnSendingPDU(
  668.       H245_DataType & pdu  /// PDU to set information on
  669.     ) const;
  670.  
  671.     /**This function is called whenever and outgoing RequestMode
  672.        PDU is being constructed for the control channel. It allows the
  673.        capability to set the PDU fields from information in members specific
  674.        to the class.
  675.  
  676.        The default behaviour calls the OnSendingPDU() function with a more
  677.        specific PDU type.
  678.      */
  679.     virtual BOOL OnSendingPDU(
  680.       H245_ModeElement & pdu  /// PDU to set information on
  681.     ) const;
  682.  
  683.     /**This function is called whenever and outgoing TerminalCapabilitySet
  684.        or OpenLogicalChannel PDU is being constructed for the control channel.
  685.        It allows the capability to set the PDU fields from information in
  686.        members specific to the class.
  687.  
  688.        The default behaviour assumes the pdu is an integer number of frames
  689.        per packet.
  690.      */
  691.     virtual BOOL OnSendingPDU(
  692.       H245_AudioCapability & pdu,  /// PDU to set information on
  693.       unsigned packetSize          /// Packet size to use in capability
  694.     ) const;
  695.  
  696.     /**This function is called whenever and outgoing RequestMode
  697.        PDU is being constructed for the control channel. It allows the
  698.        capability to set the PDU fields from information in members specific
  699.        to the class.
  700.  
  701.        The default behaviour sets the PDUs tag according to the GetSubType()
  702.        function (translated to different enum).
  703.      */
  704.     virtual BOOL OnSendingPDU(
  705.       H245_AudioMode & pdu  /// PDU to set information on
  706.     ) const;
  707.  
  708.     /**This function is called whenever and incoming TerminalCapabilitySet
  709.        PDU is received on the control channel, and a new H323Capability
  710.        descendent was created. This completes reading fields from the PDU
  711.        into the classes members.
  712.  
  713.        If the function returns FALSE then the received PDU codec description
  714.        is not supported, so will be ignored.
  715.        
  716.        The default behaviour calls the OnReceivedPDU() that takes a
  717.        H245_AudioCapability and clamps the txFramesInPacket.
  718.      */
  719.     virtual BOOL OnReceivedPDU(
  720.       const H245_Capability & pdu  /// PDU to get information from
  721.     );
  722.  
  723.     /**This function is called whenever and incoming OpenLogicalChannel
  724.        PDU has been used to construct the control channel. It allows the
  725.        capability to set from the PDU fields, information in members specific
  726.        to the class.
  727.        
  728.        The default behaviour calls the OnReceivedPDU() that takes a
  729.        H245_AudioCapability and clamps the txFramesInPacket or
  730.        rxFramesInPacket.
  731.      */
  732.     virtual BOOL OnReceivedPDU(
  733.       const H245_DataType & pdu,  /// PDU to get information from
  734.       BOOL receiver               /// Is receiver OLC
  735.     );
  736.  
  737.     /**This function is called whenever and incoming TerminalCapabilitySet
  738.        or OpenLogicalChannel PDU has been used to construct the control
  739.        channel. It allows the capability to set from the PDU fields,
  740.        information in members specific to the class.
  741.  
  742.        The default behaviour assumes the pdu is an integer number of frames
  743.        per packet.
  744.      */
  745.     virtual BOOL OnReceivedPDU(
  746.       const H245_AudioCapability & pdu,  /// PDU to get information from
  747.       unsigned & packetSize              /// Packet size to use in capability
  748.     );
  749.   //@}
  750.  
  751.   protected:
  752.     unsigned rxFramesInPacket;
  753.     unsigned txFramesInPacket;
  754. };
  755.  
  756.  
  757. /**This class describes the interface to a non-standard audio codec used to
  758.    transfer data via the logical channels opened and managed by the H323
  759.    control channel.
  760.  
  761.    An application may create a descendent off this class and override
  762.    functions as required for descibing the codec.
  763.  */
  764. class H323NonStandardAudioCapability : public H323AudioCapability,
  765.                                        public H323NonStandardCapabilityInfo
  766. {
  767.   PCLASSINFO(H323NonStandardAudioCapability, H323AudioCapability);
  768.  
  769.   public:
  770.   /**@name Construction */
  771.   //@{
  772.     /**Create a new set of information about a non-standard codec.
  773.       */
  774.     H323NonStandardAudioCapability(
  775.       unsigned maxPacketSize,         /// Maximum size of an audio packet in frames
  776.       unsigned desiredPacketSize,     /// Desired transmit size of an audio packet in frames
  777.       H323EndPoint & endpoint,        /// Endpoint to get t35 information
  778.       const BYTE * dataBlock = NULL,  /// Non-Standard data for codec type
  779.       PINDEX dataSize = 0,            /// Size of dataBlock. If 0 and dataBlock != NULL use strlen(dataBlock)
  780.       PINDEX comparisonOffset = 0,    /// Offset into dataBlock to compare
  781.       PINDEX comparisonLength = P_MAX_INDEX  /// Length of bytes to compare
  782.      );
  783.  
  784.     /**Create a new set of information about a non-standard codec.
  785.       */
  786.     H323NonStandardAudioCapability(
  787.       unsigned maxPacketSize,         /// Maximum size of an audio packet in frames
  788.       unsigned desiredPacketSize,     /// Desired transmit size of an audio packet in frames
  789.       const PString & oid,            /// OID for indentification of codec
  790.       const BYTE * dataBlock = NULL,  /// Non-Standard data for codec type
  791.       PINDEX dataSize = 0,            /// Size of dataBlock. If 0 and dataBlock != NULL use strlen(dataBlock)
  792.       PINDEX comparisonOffset = 0,    /// Offset into dataBlock to compare
  793.       PINDEX comparisonLength = P_MAX_INDEX  /// Length of bytes to compare
  794.     );
  795.  
  796.     /**Create a new set of information about a non-standard codec.
  797.       */
  798.     H323NonStandardAudioCapability(
  799.       unsigned maxPacketSize,         /// Maximum size of an audio packet in frames
  800.       unsigned desiredPacketSize,     /// Desired transmit size of an audio packet in frames
  801.       BYTE country,                   /// t35 information
  802.       BYTE extension,                 /// t35 information
  803.       WORD maufacturer,               /// t35 information
  804.       const BYTE * dataBlock = NULL,  /// Non-Standard data for codec type
  805.       PINDEX dataSize = 0,            /// Size of dataBlock. If 0 and dataBlock != NULL use strlen(dataBlock)
  806.       PINDEX comparisonOffset = 0,    /// Offset into dataBlock to compare
  807.       PINDEX comparisonLength = P_MAX_INDEX  /// Length of bytes to compare
  808.     );
  809.   //@}
  810.  
  811.   /**@name Overrides from class PObject */
  812.   //@{
  813.     /**Compare two capability instances. This compares the main and sub-types
  814.        of the capability.
  815.      */
  816.     Comparison Compare(const PObject & obj) const;
  817.   //@}
  818.  
  819.   /**@name Identification functions */
  820.   //@{
  821.     /**Get the sub-type of the capability. This is a code dependent on the
  822.        main type of the capability.
  823.  
  824.        This returns H245_AudioCapability::e_nonStandard.
  825.      */
  826.     virtual unsigned GetSubType() const;
  827.   //@}
  828.  
  829.   /**@name Protocol manipulation */
  830.   //@{
  831.     /**This function is called whenever and outgoing TerminalCapabilitySet
  832.        or OpenLogicalChannel PDU is being constructed for the control channel.
  833.        It allows the capability to set the PDU fields from information in
  834.        members specific to the class.
  835.  
  836.        The default behaviour calls H323NonStandardCapabilityinfo::OnSendingPDU()
  837.        to handle the PDU.
  838.      */
  839.     virtual BOOL OnSendingPDU(
  840.       H245_AudioCapability & pdu,  /// PDU to set information on
  841.       unsigned packetSize          /// Packet size to use in capability
  842.     ) const;
  843.  
  844.     /**This function is called whenever and outgoing RequestMode
  845.        PDU is being constructed for the control channel. It allows the
  846.        capability to set the PDU fields from information in members specific
  847.        to the class.
  848.  
  849.        The default behaviour calls H323NonStandardCapabilityinfo::OnSendingPDU()
  850.        to handle the PDU.
  851.      */
  852.     virtual BOOL OnSendingPDU(
  853.       H245_AudioMode & pdu  /// PDU to set information on
  854.     ) const;
  855.  
  856.     /**This function is called whenever and incoming TerminalCapabilitySet
  857.        or OpenLogicalChannel PDU has been used to construct the control
  858.        channel. It allows the capability to set from the PDU fields,
  859.        information in members specific to the class.
  860.  
  861.        The default behaviour calls H323NonStandardCapabilityinfo::OnReceivedPDU()
  862.        to handle the provided PDU.
  863.      */
  864.     virtual BOOL OnReceivedPDU(
  865.       const H245_AudioCapability & pdu,  /// PDU to get information from
  866.       unsigned & packetSize              /// Packet size to use in capability
  867.     );
  868.  
  869.     /**Compare the nonStandardData part of the capability, if applicable.
  870.       */
  871.     virtual BOOL IsNonStandardMatch(
  872.       const H245_NonStandardParameter & param  /// Non standard field in PDU received
  873.     ) const;
  874.   //@}
  875. };
  876.  
  877.  
  878. /**This class describes the interface to a video codec used to transfer data
  879.    via the logical channels opened and managed by the H323 control channel.
  880.  
  881.    An application may create a descendent off this class and override
  882.    functions as required for descibing a codec.
  883.  */
  884. class H323VideoCapability : public H323RealTimeCapability
  885. {
  886.   PCLASSINFO(H323VideoCapability, H323RealTimeCapability);
  887.  
  888.   public:
  889.   /**@name Identification functions */
  890.   //@{
  891.     /**Get the main type of the capability.
  892.        Always returns e_Video.
  893.      */
  894.     virtual MainTypes GetMainType() const;
  895.   //@}
  896.  
  897.   /**@name Operations */
  898.   //@{
  899.     /**Get the default RTP session.
  900.        This function gets the default RTP session ID for the capability
  901.        type. For example audio capabilities return the value
  902.        RTP_Session::DefaultAudioSessionID etc.
  903.  
  904.        The default behaviour returns zero, indicating it is not an RTP
  905.        based capability.
  906.       */
  907.     virtual unsigned GetDefaultSessionID() const;
  908.   //@}
  909.  
  910.   /**@name Protocol manipulation */
  911.   //@{
  912.     /**This function is called whenever and outgoing TerminalCapabilitySet
  913.        PDU is being constructed for the control channel. It allows the
  914.        capability to set the PDU fields from information in members specific
  915.        to the class.
  916.  
  917.        The default behaviour calls the OnSendingPDU() function with a more
  918.        specific PDU type.
  919.      */
  920.     virtual BOOL OnSendingPDU(
  921.       H245_Capability & pdu  /// PDU to set information on
  922.     ) const;
  923.  
  924.     /**This function is called whenever and outgoing OpenLogicalChannel
  925.        PDU is being constructed for the control channel. It allows the
  926.        capability to set the PDU fields from information in members specific
  927.        to the class.
  928.  
  929.        The default behaviour calls the OnSendingPDU() function with a more
  930.        specific PDU type.
  931.      */
  932.     virtual BOOL OnSendingPDU(
  933.       H245_DataType & pdu  /// PDU to set information on
  934.     ) const;
  935.  
  936.     /**This function is called whenever and outgoing RequestMode
  937.        PDU is being constructed for the control channel. It allows the
  938.        capability to set the PDU fields from information in members specific
  939.        to the class.
  940.  
  941.        The default behaviour calls the OnSendingPDU() function with a more
  942.        specific PDU type.
  943.      */
  944.     virtual BOOL OnSendingPDU(
  945.       H245_ModeElement & pdu  /// PDU to set information on
  946.     ) const;
  947.  
  948.     /**This function is called whenever and outgoing TerminalCapabilitySet
  949.        or OpenLogicalChannel PDU is being constructed for the control channel.
  950.        It allows the capability to set the PDU fields from information in
  951.        members specific to the class.
  952.  
  953.        The default behaviour is pure.
  954.      */
  955.     virtual BOOL OnSendingPDU(
  956.       H245_VideoCapability & pdu  /// PDU to set information on
  957.     ) const = 0;
  958.  
  959.     /**This function is called whenever and outgoing RequestMode
  960.        PDU is being constructed for the control channel. It allows the
  961.        capability to set the PDU fields from information in members specific
  962.        to the class.
  963.  
  964.        The default behaviour sets the PDUs tag according to the GetSubType()
  965.        function (translated to different enum).
  966.      */
  967.     virtual BOOL OnSendingPDU(
  968.       H245_VideoMode & pdu  /// PDU to set information on
  969.     ) const = 0;
  970.  
  971.     /**This function is called whenever and incoming TerminalCapabilitySet
  972.        PDU is received on the control channel, and a new H323Capability
  973.        descendent was created. This completes reading fields from the PDU
  974.        into the classes members.
  975.  
  976.        If the function returns FALSE then the received PDU codec description
  977.        is not supported, so will be ignored. The default behaviour simply
  978.        returns TRUE.
  979.      */
  980.     virtual BOOL OnReceivedPDU(
  981.       const H245_Capability & pdu  /// PDU to get information from
  982.     );
  983.  
  984.     /**This function is called whenever and incoming OpenLogicalChannel
  985.        PDU has been used to construct the control channel. It allows the
  986.        capability to set from the PDU fields, information in members specific
  987.        to the class.
  988.  
  989.        The default behaviour is pure.
  990.      */
  991.     virtual BOOL OnReceivedPDU(
  992.       const H245_DataType & pdu,  /// PDU to get information from
  993.       BOOL receiver               /// Is receiver OLC
  994.     );
  995.  
  996.     /**This function is called whenever and incoming TerminalCapabilitySet
  997.        or OpenLogicalChannel PDU has been used to construct the control
  998.        channel. It allows the capability to set from the PDU fields,
  999.        information in members specific to the class.
  1000.  
  1001.        The default behaviour is pure.
  1002.      */
  1003.     virtual BOOL OnReceivedPDU(
  1004.       const H245_VideoCapability & pdu  /// PDU to set information on
  1005.     ) = 0;
  1006.   //@}
  1007. };
  1008.  
  1009.  
  1010. /**This class describes the interface to a non-standard video codec used to
  1011.    transfer data via the logical channels opened and managed by the H323
  1012.    control channel.
  1013.  
  1014.    An application may create a descendent off this class and override
  1015.    functions as required for descibing the codec.
  1016.  */
  1017. class H323NonStandardVideoCapability : public H323VideoCapability,
  1018.                                        public H323NonStandardCapabilityInfo
  1019. {
  1020.   PCLASSINFO(H323NonStandardVideoCapability, H323VideoCapability);
  1021.  
  1022.   public:
  1023.   /**@name Construction */
  1024.   //@{
  1025.     /**Create a new set of information about a non-standard codec.
  1026.       */
  1027.     H323NonStandardVideoCapability(
  1028.       H323EndPoint & endpoint,        /// Endpoint to get t35 information
  1029.       const BYTE * dataBlock = NULL,  /// Non-Standard data for codec type
  1030.       PINDEX dataSize = 0,            /// Size of dataBlock. If 0 and dataBlock != NULL use strlen(dataBlock)
  1031.       PINDEX comparisonOffset = 0,    /// Offset into dataBlock to compare
  1032.       PINDEX comparisonLength = P_MAX_INDEX  /// Length of bytes to compare
  1033.     );
  1034.  
  1035.     /**Create a new set of information about a non-standard codec.
  1036.       */
  1037.     H323NonStandardVideoCapability(
  1038.       const PString & oid,            /// OID for indentification of codec
  1039.       const BYTE * dataBlock = NULL,  /// Non-Standard data for codec type
  1040.       PINDEX dataSize = 0,            /// Size of dataBlock. If 0 and dataBlock != NULL use strlen(dataBlock)
  1041.       PINDEX comparisonOffset = 0,    /// Offset into dataBlock to compare
  1042.       PINDEX comparisonLength = P_MAX_INDEX  /// Length of bytes to compare
  1043.     );
  1044.  
  1045.     /**Create a new set of information about a non-standard codec.
  1046.       */
  1047.     H323NonStandardVideoCapability(
  1048.       BYTE country,                   /// t35 information
  1049.       BYTE extension,                 /// t35 information
  1050.       WORD maufacturer,               /// t35 information
  1051.       const BYTE * dataBlock = NULL,  /// Non-Standard data for codec type
  1052.       PINDEX dataSize = 0,            /// Size of dataBlock. If 0 and dataBlock != NULL use strlen(dataBlock)
  1053.       PINDEX comparisonOffset = 0,    /// Offset into dataBlock to compare
  1054.       PINDEX comparisonLength = P_MAX_INDEX  /// Length of bytes to compare
  1055.     );
  1056.   //@}
  1057.  
  1058.   /**@name Overrides from class PObject */
  1059.   //@{
  1060.     /**Compare two capability instances. This compares the main and sub-types
  1061.        of the capability.
  1062.      */
  1063.     Comparison Compare(const PObject & obj) const;
  1064.   //@}
  1065.  
  1066.   /**@name Identification functions */
  1067.   //@{
  1068.     /**Get the sub-type of the capability. This is a code dependent on the
  1069.        main type of the capability.
  1070.  
  1071.        This returns one of the four possible combinations of mode and speed
  1072.        using the enum values of the protocol ASN H245_AudioCapability class.
  1073.      */
  1074.     virtual unsigned GetSubType() const;
  1075.   //@}
  1076.  
  1077.   /**@name Protocol manipulation */
  1078.   //@{
  1079.     /**This function is called whenever and outgoing TerminalCapabilitySet
  1080.        or OpenLogicalChannel PDU is being constructed for the control channel.
  1081.        It allows the capability to set the PDU fields from information in
  1082.        members specific to the class.
  1083.  
  1084.        The default behaviour calls H323NonStandardCapabilityinfo::OnSendingPDU()
  1085.        to handle the PDU.
  1086.      */
  1087.     virtual BOOL OnSendingPDU(
  1088.       H245_VideoCapability & pdu  /// PDU to set information on
  1089.     ) const;
  1090.  
  1091.     /**This function is called whenever and outgoing RequestMode
  1092.        PDU is being constructed for the control channel. It allows the
  1093.        capability to set the PDU fields from information in members specific
  1094.        to the class.
  1095.  
  1096.        The default behaviour calls H323NonStandardCapabilityinfo::OnSendingPDU()
  1097.        to handle the PDU.
  1098.      */
  1099.     virtual BOOL OnSendingPDU(
  1100.       H245_VideoMode & pdu  /// PDU to set information on
  1101.     ) const;
  1102.  
  1103.     /**This function is called whenever and incoming TerminalCapabilitySet
  1104.        or OpenLogicalChannel PDU has been used to construct the control
  1105.        channel. It allows the capability to set from the PDU fields,
  1106.        information in members specific to the class.
  1107.  
  1108.        The default behaviour calls H323NonStandardCapabilityinfo::OnReceivedPDU()
  1109.        to handle the provided PDU.
  1110.      */
  1111.     virtual BOOL OnReceivedPDU(
  1112.       const H245_VideoCapability & pdu  /// PDU to set information on
  1113.     );
  1114.  
  1115.     /**Compare the nonStandardData part of the capability, if applicable.
  1116.       */
  1117.     virtual BOOL IsNonStandardMatch(
  1118.       const H245_NonStandardParameter & param  /// Non standard field in PDU received
  1119.     ) const;
  1120.   //@}
  1121. };
  1122.  
  1123.  
  1124. /**This class describes the interface to a data channel used to transfer data
  1125.    via the logical channels opened and managed by the H323 control channel.
  1126.  
  1127.    An application may create a descendent off this class and override
  1128.    functions as required for descibing a codec.
  1129.  */
  1130. class H323DataCapability : public H323Capability
  1131. {
  1132.   PCLASSINFO(H323DataCapability, H323Capability);
  1133.  
  1134.   public:
  1135.   /**@name Construction */
  1136.   //@{
  1137.     /**Create a new data capability.
  1138.       */
  1139.     H323DataCapability(
  1140.       unsigned maxBitRate = 0  /// Maximum bit rate for data in 100's b/s
  1141.     );
  1142.   //@}
  1143.  
  1144.   /**@name Identification functions */
  1145.   //@{
  1146.     /**Get the main type of the capability.
  1147.        Always returns e_Data.
  1148.      */
  1149.     virtual MainTypes GetMainType() const;
  1150.   //@}
  1151.  
  1152.   /**@name Operations */
  1153.   //@{
  1154.     /**Get the default RTP session.
  1155.        This function gets the default RTP session ID for the capability
  1156.        type. For example audio capabilities return the value
  1157.        RTP_Session::DefaultAudioSessionID etc.
  1158.  
  1159.        The default behaviour returns 3, indicating a data session.
  1160.       */
  1161.     virtual unsigned GetDefaultSessionID() const;
  1162.  
  1163.     /**Create the codec instance, allocating resources as required.
  1164.        As a data channel has no codec, this always returns NULL.
  1165.      */
  1166.     virtual H323Codec * CreateCodec(
  1167.       H323Codec::Direction direction  /// Direction in which this instance runs
  1168.     ) const;
  1169.   //@}
  1170.  
  1171.   /**@name Protocol manipulation */
  1172.   //@{
  1173.     /**This function is called whenever and outgoing TerminalCapabilitySet
  1174.        PDU is being constructed for the control channel. It allows the
  1175.        capability to set the PDU fields from information in members specific
  1176.        to the class.
  1177.  
  1178.        The default behaviour calls the OnSendingPDU() function with a more
  1179.        specific PDU type.
  1180.      */
  1181.     virtual BOOL OnSendingPDU(
  1182.       H245_Capability & pdu  /// PDU to set information on
  1183.     ) const;
  1184.  
  1185.     /**This function is called whenever and outgoing OpenLogicalChannel
  1186.        PDU is being constructed for the control channel. It allows the
  1187.        capability to set the PDU fields from information in members specific
  1188.        to the class.
  1189.  
  1190.        The default behaviour calls the OnSendingPDU() function with a more
  1191.        specific PDU type.
  1192.      */
  1193.     virtual BOOL OnSendingPDU(
  1194.       H245_DataType & pdu  /// PDU to set information on
  1195.     ) const;
  1196.  
  1197.     /**This function is called whenever and outgoing RequestMode
  1198.        PDU is being constructed for the control channel. It allows the
  1199.        capability to set the PDU fields from information in members specific
  1200.        to the class.
  1201.  
  1202.        The default behaviour calls the OnSendingPDU() function with a more
  1203.        specific PDU type.
  1204.      */
  1205.     virtual BOOL OnSendingPDU(
  1206.       H245_ModeElement & pdu  /// PDU to set information on
  1207.     ) const;
  1208.  
  1209.     /**This function is called whenever and outgoing TerminalCapabilitySet
  1210.        or OpenLogicalChannel PDU is being constructed for the control channel.
  1211.        It allows the capability to set the PDU fields from information in
  1212.        members specific to the class.
  1213.  
  1214.        The default behaviour is pure.
  1215.      */
  1216.     virtual BOOL OnSendingPDU(
  1217.       H245_DataApplicationCapability & pdu  /// PDU to set information on
  1218.     ) const = 0;
  1219.  
  1220.     /**This function is called whenever and outgoing RequestMode
  1221.        PDU is being constructed for the control channel. It allows the
  1222.        capability to set the PDU fields from information in members specific
  1223.        to the class.
  1224.  
  1225.        The default behaviour sets the PDUs tag according to the GetSubType()
  1226.        function (translated to different enum).
  1227.      */
  1228.     virtual BOOL OnSendingPDU(
  1229.       H245_DataMode & pdu  /// PDU to set information on
  1230.     ) const = 0;
  1231.  
  1232.     /**This function is called whenever and incoming TerminalCapabilitySet
  1233.        PDU is received on the control channel, and a new H323Capability
  1234.        descendent was created. This completes reading fields from the PDU
  1235.        into the classes members.
  1236.  
  1237.        If the function returns FALSE then the received PDU codec description
  1238.        is not supported, so will be ignored. The default behaviour simply
  1239.        returns TRUE.
  1240.      */
  1241.     virtual BOOL OnReceivedPDU(
  1242.       const H245_Capability & pdu  /// PDU to get information from
  1243.     );
  1244.  
  1245.     /**This function is called whenever and incoming OpenLogicalChannel
  1246.        PDU has been used to construct the control channel. It allows the
  1247.        capability to set from the PDU fields, information in members specific
  1248.        to the class.
  1249.  
  1250.        The default behaviour is pure.
  1251.      */
  1252.     virtual BOOL OnReceivedPDU(
  1253.       const H245_DataType & pdu,  /// PDU to get information from
  1254.       BOOL receiver               /// Is receiver OLC
  1255.     );
  1256.  
  1257.     /**This function is called whenever and incoming TerminalCapabilitySet
  1258.        or OpenLogicalChannel PDU has been used to construct the control
  1259.        channel. It allows the capability to set from the PDU fields,
  1260.        information in members specific to the class.
  1261.  
  1262.        The default behaviour is pure.
  1263.      */
  1264.     virtual BOOL OnReceivedPDU(
  1265.       const H245_DataApplicationCapability & pdu  /// PDU to set information on
  1266.     ) = 0;
  1267.   //@}
  1268.  
  1269.   protected:
  1270.     unsigned maxBitRate;
  1271. };
  1272.  
  1273.  
  1274. /**This class describes the interface to a non-standard data codec used to
  1275.    transfer data via the logical channels opened and managed by the H323
  1276.    control channel.
  1277.  
  1278.    An application may create a descendent off this class and override
  1279.    functions as required for descibing the codec.
  1280.  */
  1281. class H323NonStandardDataCapability : public H323DataCapability,
  1282.                                       public H323NonStandardCapabilityInfo
  1283. {
  1284.   PCLASSINFO(H323NonStandardDataCapability, H323DataCapability);
  1285.  
  1286.   public:
  1287.   /**@name Construction */
  1288.   //@{
  1289.     /**Create a new set of information about a non-standard codec.
  1290.       */
  1291.     H323NonStandardDataCapability(
  1292.       unsigned maxBitRate,            /// Maximum bit rate for data in 100's b/s
  1293.       H323EndPoint & endpoint,        /// Endpoint to get t35 information
  1294.       const BYTE * dataBlock = NULL,  /// Non-Standard data for codec type
  1295.       PINDEX dataSize = 0,            /// Size of dataBlock. If 0 and dataBlock != NULL use strlen(dataBlock)
  1296.       PINDEX comparisonOffset = 0,    /// Offset into dataBlock to compare
  1297.       PINDEX comparisonLength = P_MAX_INDEX  /// Length of bytes to compare
  1298.     );
  1299.  
  1300.     /**Create a new set of information about a non-standard codec.
  1301.       */
  1302.     H323NonStandardDataCapability(
  1303.       unsigned maxBitRate,            /// Maximum bit rate for data in 100's b/s
  1304.       const PString & oid,            /// OID for indentification of codec
  1305.       const BYTE * dataBlock = NULL,  /// Non-Standard data for codec type
  1306.       PINDEX dataSize = 0,            /// Size of dataBlock. If 0 and dataBlock != NULL use strlen(dataBlock)
  1307.       PINDEX comparisonOffset = 0,    /// Offset into dataBlock to compare
  1308.       PINDEX comparisonLength = P_MAX_INDEX  /// Length of bytes to compare
  1309.     );
  1310.  
  1311.     /**Create a new set of information about a non-standard codec.
  1312.       */
  1313.     H323NonStandardDataCapability(
  1314.       unsigned maxBitRate,            /// Maximum bit rate for data in 100's b/s
  1315.       BYTE country,                   /// t35 information
  1316.       BYTE extension,                 /// t35 information
  1317.       WORD maufacturer,               /// t35 information
  1318.       const BYTE * dataBlock = NULL,  /// Non-Standard data for codec type
  1319.       PINDEX dataSize = 0,            /// Size of dataBlock. If 0 and dataBlock != NULL use strlen(dataBlock)
  1320.       PINDEX comparisonOffset = 0,    /// Offset into dataBlock to compare
  1321.       PINDEX comparisonLength = P_MAX_INDEX  /// Length of bytes to compare
  1322.     );
  1323.   //@}
  1324.  
  1325.   /**@name Overrides from class PObject */
  1326.   //@{
  1327.     /**Compare two capability instances. This compares the main and sub-types
  1328.        of the capability.
  1329.      */
  1330.     Comparison Compare(const PObject & obj) const;
  1331.   //@}
  1332.  
  1333.   /**@name Identification functions */
  1334.   //@{
  1335.     /**Get the sub-type of the capability. This is a code dependent on the
  1336.        main type of the capability.
  1337.  
  1338.        This returns one of the four possible combinations of mode and speed
  1339.        using the enum values of the protocol ASN H245_AudioCapability class.
  1340.      */
  1341.     virtual unsigned GetSubType() const;
  1342.   //@}
  1343.  
  1344.   /**@name Protocol manipulation */
  1345.   //@{
  1346.     /**This function is called whenever and outgoing TerminalCapabilitySet
  1347.        or OpenLogicalChannel PDU is being constructed for the control channel.
  1348.        It allows the capability to set the PDU fields from information in
  1349.        members specific to the class.
  1350.  
  1351.        The default behaviour calls H323NonStandardCapabilityinfo::OnSendingPDU()
  1352.        to handle the PDU.
  1353.      */
  1354.     virtual BOOL OnSendingPDU(
  1355.       H245_DataApplicationCapability & pdu  /// PDU to set information on
  1356.     ) const;
  1357.  
  1358.     /**This function is called whenever and outgoing RequestMode
  1359.        PDU is being constructed for the control channel. It allows the
  1360.        capability to set the PDU fields from information in members specific
  1361.        to the class.
  1362.  
  1363.        The default behaviour calls H323NonStandardCapabilityinfo::OnSendingPDU()
  1364.        to handle the PDU.
  1365.      */
  1366.     virtual BOOL OnSendingPDU(
  1367.       H245_DataMode & pdu  /// PDU to set information on
  1368.     ) const;
  1369.  
  1370.     /**This function is called whenever and incoming TerminalCapabilitySet
  1371.        or OpenLogicalChannel PDU has been used to construct the control
  1372.        channel. It allows the capability to set from the PDU fields,
  1373.        information in members specific to the class.
  1374.  
  1375.        The default behaviour calls H323NonStandardCapabilityinfo::OnReceivedPDU()
  1376.        to handle the provided PDU.
  1377.      */
  1378.     virtual BOOL OnReceivedPDU(
  1379.       const H245_DataApplicationCapability & pdu  /// PDU to set information on
  1380.     );
  1381.  
  1382.     /**Compare the nonStandardData part of the capability, if applicable.
  1383.       */
  1384.     virtual BOOL IsNonStandardMatch(
  1385.       const H245_NonStandardParameter & param  /// Non standard field in PDU received
  1386.     ) const;
  1387.   //@}
  1388. };
  1389.  
  1390.  
  1391. ///////////////////////////////////////////////////////////////////////////////
  1392. // The simplest codec is the G.711 PCM codec.
  1393.  
  1394. /**This class describes the G.711 codec capability.
  1395.  */
  1396. class H323_G711Capability : public H323AudioCapability
  1397. {
  1398.   PCLASSINFO(H323_G711Capability, H323AudioCapability)
  1399.  
  1400.   public:
  1401.     /// Specific G.711 encoding algorithm.
  1402.     enum Mode {
  1403.       /// European standard
  1404.       ALaw,
  1405.       /// American standard
  1406.       muLaw
  1407.     };
  1408.     /// Specific G.711 encoding bit rates.
  1409.     enum Speed {
  1410.       /// European standard
  1411.       At64k,
  1412.       /// American standard
  1413.       At56k
  1414.     };
  1415.  
  1416.   /**@name Construction */
  1417.   //@{
  1418.     /**Create a new G.711 capability.
  1419.      */
  1420.     H323_G711Capability(
  1421.       Mode mode = muLaw,    /// Type of encoding.
  1422.       Speed speed = At64k   /// Encoding bit rate.
  1423.     );
  1424.   //@}
  1425.  
  1426.   /**@name Overrides from class PObject */
  1427.   //@{
  1428.     /**Create a copy of the object.
  1429.       */
  1430.     virtual PObject * Clone() const;
  1431.   //@}
  1432.  
  1433.   /**@name Identification functions */
  1434.   //@{
  1435.     /**Get the sub-type of the capability. This is a code dependent on the
  1436.        main type of the capability.
  1437.  
  1438.        This returns one of the four possible combinations of mode and speed
  1439.        using the enum values of the protocol ASN H245_AudioCapability class.
  1440.      */
  1441.     virtual unsigned GetSubType() const;
  1442.  
  1443.     /**Get the name of the media data format this class represents.
  1444.      */
  1445.     virtual PString GetFormatName() const;
  1446.   //@}
  1447.  
  1448.   /**@name Operations */
  1449.   //@{
  1450.     /**Create the codec instance, allocating resources as required.
  1451.      */
  1452.     virtual H323Codec * CreateCodec(
  1453.       H323Codec::Direction direction  /// Direction in which this instance runs
  1454.     ) const;
  1455.   //@}
  1456.  
  1457.   protected:
  1458.     Mode     mode;
  1459.     Speed    speed;
  1460. };
  1461.  
  1462.  
  1463. ///////////////////////////////////////////////////////////////////////////////
  1464.  
  1465. /**This class describes the UserInput psuedo-channel.
  1466.  */
  1467. class H323_UserInputCapability : public H323Capability
  1468. {
  1469.   PCLASSINFO(H323_UserInputCapability, H323Capability);
  1470.  
  1471.   public:
  1472.   /**@name Construction */
  1473.   //@{
  1474.     enum SubTypes {
  1475.       BasicString,
  1476.       IA5String,
  1477.       GeneralString,
  1478.       SignalToneH245,
  1479.       HookFlashH245,
  1480.       SignalToneRFC2833,
  1481.       NumSubTypes
  1482.     };
  1483.     static const char * const SubTypeNames[NumSubTypes];
  1484.  
  1485.     /**Create the capability for User Input.
  1486.        The subType parameter is a value from the enum
  1487.        H245_UserInputCapability::Choices.
  1488.       */
  1489.     H323_UserInputCapability(
  1490.       SubTypes subType
  1491.     );
  1492.   //@}
  1493.  
  1494.   /**@name Overrides from class PObject */
  1495.   //@{
  1496.     /**Create a copy of the object.
  1497.       */
  1498.     virtual PObject * Clone() const;
  1499.   //@}
  1500.  
  1501.   /**@name Identification functions */
  1502.   //@{
  1503.     /**Get the main type of the capability.
  1504.  
  1505.        This function is overridden by one of the three main sub-classes off
  1506.        which real capabilities would be descendend.
  1507.      */
  1508.     virtual MainTypes GetMainType() const;
  1509.  
  1510.     /**Get the sub-type of the capability. This is a code dependent on the
  1511.        main type of the capability.
  1512.      */
  1513.     virtual unsigned  GetSubType()  const;
  1514.  
  1515.     /**Get the name of the media data format this class represents.
  1516.      */
  1517.     virtual PString GetFormatName() const;
  1518.   //@}
  1519.  
  1520.   /**@name Operations */
  1521.   //@{
  1522.     /**Create the channel instance, allocating resources as required.
  1523.        This creates a logical channel object appropriate for the parameters
  1524.        provided. Not if param is NULL, sessionID must be provided, otherwise
  1525.        this is taken from the fields in param.
  1526.      */
  1527.     virtual H323Channel * CreateChannel(
  1528.       H323Connection & connection,    /// Owner connection for channel
  1529.       H323Channel::Directions dir,    /// Direction of channel
  1530.       unsigned sessionID,             /// Session ID for RTP channel
  1531.       const H245_H2250LogicalChannelParameters * param
  1532.                                       /// Parameters for channel
  1533.     ) const;
  1534.  
  1535.     /**Create the codec instance, allocating resources as required.
  1536.      */
  1537.     virtual H323Codec * CreateCodec(
  1538.       H323Codec::Direction direction  /// Direction in which this instance runs
  1539.     ) const;
  1540.   //@}
  1541.  
  1542.   /**@name Protocol manipulation */
  1543.   //@{
  1544.     /**This function is called whenever and outgoing TerminalCapabilitySet
  1545.        PDU is being constructed for the control channel. It allows the
  1546.        capability to set the PDU fields from information in members specific
  1547.        to the class.
  1548.  
  1549.        The default behaviour is pure.
  1550.      */
  1551.     virtual BOOL OnSendingPDU(
  1552.       H245_Capability & pdu  /// PDU to set information on
  1553.     ) const;
  1554.  
  1555.     /**This function is called whenever and outgoing OpenLogicalChannel
  1556.        PDU is being constructed for the control channel. It allows the
  1557.        capability to set the PDU fields from information in members specific
  1558.        to the class.
  1559.  
  1560.        The default behaviour is pure.
  1561.      */
  1562.     virtual BOOL OnSendingPDU(
  1563.       H245_DataType & pdu  /// PDU to set information on
  1564.     ) const;
  1565.  
  1566.     /**This function is called whenever and outgoing RequestMode
  1567.        PDU is being constructed for the control channel. It allows the
  1568.        capability to set the PDU fields from information in members specific
  1569.        to the class.
  1570.  
  1571.        The default behaviour calls the OnSendingPDU() function with a more
  1572.        specific PDU type.
  1573.      */
  1574.     virtual BOOL OnSendingPDU(
  1575.       H245_ModeElement & pdu  /// PDU to set information on
  1576.     ) const;
  1577.  
  1578.     /**This function is called whenever and incoming TerminalCapabilitySet
  1579.        PDU is received on the control channel, and a new H323Capability
  1580.        descendent was created. This completes reading fields from the PDU
  1581.        into the classes members.
  1582.  
  1583.        If the function returns FALSE then the received PDU codec description
  1584.        is not supported, so will be ignored. The default behaviour simply
  1585.        returns TRUE.
  1586.      */
  1587.     virtual BOOL OnReceivedPDU(
  1588.       const H245_Capability & pdu  /// PDU to get information from
  1589.     );
  1590.  
  1591.     /**This function is called whenever and incoming OpenLogicalChannel
  1592.        PDU has been used to construct the control channel. It allows the
  1593.        capability to set from the PDU fields, information in members specific
  1594.        to the class.
  1595.  
  1596.        The default behaviour is pure.
  1597.      */
  1598.     virtual BOOL OnReceivedPDU(
  1599.       const H245_DataType & pdu,  /// PDU to get information from
  1600.       BOOL receiver               /// Is receiver OLC
  1601.     );
  1602.  
  1603.     /**Validate that the capability is usable given the connection.
  1604.        This checks agains the negotiated protocol version number and remote
  1605.        application to determine if this capability should be used in TCS or
  1606.        OLC pdus.
  1607.  
  1608.        The default behaviour will check for early versions and return FALSE
  1609.        for RFC2833 mode.
  1610.       */
  1611.     virtual BOOL IsUsable(
  1612.       const H323Connection & connection
  1613.     ) const;
  1614.   //@}
  1615.  
  1616.     static void AddAllCapabilities(
  1617.       H323Capabilities & capabilities,        /// Table to add capabilities to
  1618.       PINDEX descriptorNum,   /// The member of the capabilityDescriptor to add
  1619.       PINDEX simultaneous     /// The member of the SimultaneousCapabilitySet to add
  1620.     );
  1621.  
  1622.   protected:
  1623.     SubTypes subType;
  1624. };
  1625.  
  1626.  
  1627.  
  1628. ///////////////////////////////////////////////////////////////////////////////
  1629.  
  1630. PLIST(H323CapabilitiesList, H323Capability);
  1631.  
  1632. PARRAY(H323CapabilitiesListArray, H323CapabilitiesList);
  1633.  
  1634. class H323SimultaneousCapabilities : public H323CapabilitiesListArray
  1635. {
  1636.   PCLASSINFO(H323SimultaneousCapabilities, H323CapabilitiesListArray);
  1637.   public:
  1638.     BOOL SetSize(PINDEX newSize);
  1639. };
  1640.  
  1641.  
  1642. PARRAY(H323CapabilitiesSetArray, H323SimultaneousCapabilities);
  1643.  
  1644.  
  1645. class H323CapabilitiesSet : public H323CapabilitiesSetArray
  1646. {
  1647.   PCLASSINFO(H323CapabilitiesSet, H323CapabilitiesSetArray);
  1648.   public:
  1649.     /// Set the new size of the table, internal use only.
  1650.     BOOL SetSize(PINDEX newSize);
  1651. };
  1652.  
  1653.  
  1654. /**This class contains all of the capabilities and their combinations.
  1655.   */
  1656. class H323Capabilities : public PObject
  1657. {
  1658.     PCLASSINFO(H323Capabilities, PObject);
  1659.   public:
  1660.   /**@name Construction */
  1661.   //@{
  1662.     /**Construct an empty capability set.
  1663.       */
  1664.     H323Capabilities();
  1665.  
  1666.     /**Construct a capability set from the H.245 PDU provided.
  1667.       */
  1668.     H323Capabilities(
  1669.       const H323Connection & connection,      /// Connection for capabilities
  1670.       const H245_TerminalCapabilitySet & pdu  /// PDU to convert to a capability set.
  1671.     );
  1672.  
  1673.     /**Construct a copy of a capability set.
  1674.        Note this will completely duplicate the set by making clones of every
  1675.        capability in the original set.
  1676.       */
  1677.     H323Capabilities(
  1678.       const H323Capabilities & original /// Original capabilities to duplicate
  1679.     );
  1680.  
  1681.     /**Assign a copy of a capability set.
  1682.        Note this will completely duplicate the set by making clones of every
  1683.        capability in the original set.
  1684.       */
  1685.     H323Capabilities & operator=(
  1686.       const H323Capabilities & original /// Original capabilities to duplicate
  1687.     );
  1688.   //@}
  1689.  
  1690.   /**@name Overrides from class PObject */
  1691.   //@{
  1692.     /**Print out the object to the stream, virtual version of << operator.
  1693.      */
  1694.     void PrintOn(
  1695.       ostream & strm    /// Stream to print out to.
  1696.     ) const;
  1697.   //@}
  1698.  
  1699.   /**@name Operations */
  1700.   //@{
  1701.     /**Get the number of capabilities in the set.
  1702.       */
  1703.     PINDEX GetSize() const { return table.GetSize(); }
  1704.  
  1705.     /**Get the capability at the specified index.
  1706.       */
  1707.     H323Capability & operator[](PINDEX i) const { return table[i]; }
  1708.  
  1709.     /**Set the capability descriptor lists. This is three tier set of
  1710.        codecs. The top most level is a list of particular capabilities. Each
  1711.        of these consists of a list of alternatives that can operate
  1712.        simultaneously. The lowest level is a list of codecs that cannot
  1713.        operate together. See H323 section 6.2.8.1 and H245 section 7.2 for
  1714.        details.
  1715.  
  1716.        If descriptorNum is P_MAX_INDEX, the the next available index in the
  1717.        array of descriptors is used. Similarly if simultaneous is P_MAX_INDEX
  1718.        the the next available SimultaneousCapabilitySet is used. The return
  1719.        value is the index used for the new entry. Note if both are P_MAX_INDEX
  1720.        then the return value is the descriptor index as the simultaneous index
  1721.        must be zero.
  1722.  
  1723.        Note that the capability specified here is automatically added to the
  1724.        capability table using the AddCapability() function. A specific
  1725.        instance of a capability is only ever added once, so multiple
  1726.        SetCapability() calls with the same H323Capability pointer will only
  1727.        add that capability once.
  1728.      */
  1729.     PINDEX SetCapability(
  1730.       PINDEX descriptorNum, /// The member of the capabilityDescriptor to add
  1731.       PINDEX simultaneous,  /// The member of the SimultaneousCapabilitySet to add
  1732.       H323Capability * cap  /// New capability specification
  1733.     );
  1734.  
  1735.     /**Add all matching capabilities to descriptor lists.
  1736.        All capabilities that match the specified name are added as in the other
  1737.        form of the SetCapability() function.
  1738.       */
  1739.     PINDEX AddAllCapabilities(
  1740.       H323EndPoint & ep,    /// The endpoint adding the capabilities.
  1741.       PINDEX descriptorNum, /// The member of the capabilityDescriptor to add
  1742.       PINDEX simultaneous,  /// The member of the SimultaneousCapabilitySet to add
  1743.       const PString & name  /// New capabilities name, if using "known" one.
  1744.     );
  1745.  
  1746.     /**Add a codec to the capabilities table. This will assure that the
  1747.        assignedCapabilityNumber field in the capability is unique for all
  1748.        capabilities installed on this set.
  1749.  
  1750.        If the specific instance of the capability is already in the table, it
  1751.        is not added again. Ther can be multiple instances of the same
  1752.        capability class however.
  1753.      */
  1754.     void Add(
  1755.       H323Capability * capability   /// New capability specification
  1756.     );
  1757.  
  1758.     /**Copy a codec to the capabilities table. This will make a clone of the
  1759.        capability and assure that the assignedCapabilityNumber field in the
  1760.        capability is unique for all capabilities installed on this set.
  1761.  
  1762.        Returns the copy that is put in the table.
  1763.      */
  1764.     H323Capability * Copy(
  1765.       const H323Capability & capability   /// New capability specification
  1766.     );
  1767.  
  1768.     /**Remove a capability from the table. Note that the the parameter must be
  1769.        the actual instance of the capability in the table. The instance is
  1770.        deleted when removed from the table.
  1771.       */
  1772.     void Remove(
  1773.       H323Capability * capability   /// Existing capability specification
  1774.     );
  1775.  
  1776.     /**Remove all capabilities matching the string. This uses FindCapability()
  1777.        to locate the first capability whose format name does a partial match
  1778.        for the argument.
  1779.       */
  1780.     void Remove(
  1781.       const PString & formatName   /// Format name to search for.
  1782.     );
  1783.  
  1784.     /**Remove all capabilities matching any of the strings provided. This
  1785.        simply calls Remove() for each string in the list.
  1786.       */
  1787.     void Remove(
  1788.       const PStringArray & formatNames  /// Array of format names to remove
  1789.     );
  1790.  
  1791.     /**Remove all of the capabilities.
  1792.       */
  1793.     void RemoveAll();
  1794.  
  1795.     /**Find the capability given the capability number. This number is
  1796.        guarenteed to be unique for a give capability table. Note that is may
  1797.        not be the same as the index into the table.
  1798.  
  1799.        Returns:
  1800.        NULL if no capability meeting the criteria was found
  1801.       */
  1802.     H323Capability * FindCapability(
  1803.       unsigned capabilityNumber
  1804.     ) const;
  1805.  
  1806.     /**Find the capability given the capability format name string. This does
  1807.        a partial match for the supplied argument. If the argument matches a
  1808.        substring of the actual capabilities name, then it is returned. For
  1809.        example "GSM" or "0610" will match "GSM 0610". Note case is not
  1810.        significant.
  1811.  
  1812.        The user should be carefull of using short strings such as "G"!
  1813.  
  1814.        The direction parameter can further refine the search for specific
  1815.        receive or transmit capabilities. The default value of e_Unknown will
  1816.        wildcard that field.
  1817.  
  1818.        Returns:
  1819.        NULL if no capability meeting the criteria was found
  1820.       */
  1821.     H323Capability * FindCapability(
  1822.       const PString & formatName, /// Wildcard format name to search for
  1823.       H323Capability::CapabilityDirection direction = H323Capability::e_Unknown
  1824.             /// Optional direction to include into search criteria
  1825.     ) const;
  1826.  
  1827.     /**Find the first capability in the table of the specified direction.
  1828.  
  1829.        Returns:
  1830.        NULL if no capability meeting the criteria was found
  1831.       */
  1832.     H323Capability * FindCapability(
  1833.       H323Capability::CapabilityDirection direction /// Direction to search for
  1834.     ) const;
  1835.  
  1836.     /**Find the capability given the capability. This does a value compare of
  1837.        the two capabilities. Usually this means the mainType and subType are
  1838.        the same.
  1839.  
  1840.        Returns:
  1841.        NULL if no capability meeting the criteria was found
  1842.       */
  1843.     H323Capability * FindCapability(
  1844.       const H323Capability & capability /// Capability to search for
  1845.     ) const;
  1846.  
  1847.     /**Find the capability given the H.245 capability PDU.
  1848.  
  1849.        Returns:
  1850.        NULL if no capability meeting the criteria was found
  1851.       */
  1852.     H323Capability * FindCapability(
  1853.       const H245_Capability & cap  /// H245 capability table entry
  1854.     ) const;
  1855.  
  1856.     /**Find the capability given the H.245 data type PDU.
  1857.  
  1858.        Returns:
  1859.        NULL if no capability meeting the criteria was found
  1860.       */
  1861.     H323Capability * FindCapability(
  1862.       const H245_DataType & dataType  /// H245 data type of codec
  1863.     ) const;
  1864.  
  1865.     /**Find the capability given the H.245 data type PDU.
  1866.  
  1867.        Returns:
  1868.        NULL if no capability meeting the criteria was found
  1869.       */
  1870.     H323Capability * FindCapability(
  1871.       const H245_ModeElement & modeElement  /// H245 data type of codec
  1872.     ) const;
  1873.  
  1874.     /**Find the capability given the sub-type info.
  1875.  
  1876.        Returns:
  1877.        NULL if no capability meeting the criteria was found
  1878.       */
  1879.     H323Capability * FindCapability(
  1880.       H323Capability::MainTypes mainType, /// Main type to find
  1881.       const PASN_Choice & subTypePDU,         /// Sub-type info
  1882.       unsigned nonStandardTag             /// NOn-standard tag ID for sub-type
  1883.     ) const;
  1884.  
  1885.     /**Find the capability given the type codecs.
  1886.  
  1887.        Returns:
  1888.        NULL if no capability meeting the criteria was found
  1889.       */
  1890.     H323Capability * FindCapability(
  1891.       H323Capability::MainTypes mainType, /// Main type to find
  1892.       unsigned subType = UINT_MAX         /// Sub-type to find (UINT_MAX=ignore)
  1893.     ) const;
  1894.  
  1895.     /**Build a H.245 PDU from the information in the capability set.
  1896.       */
  1897.     void BuildPDU(
  1898.       const H323Connection & connection,  /// Connection building PDU for
  1899.       H245_TerminalCapabilitySet & pdu    /// PDU to build
  1900.     ) const;
  1901.  
  1902.     /**Merge the capabilities into this set.
  1903.       */
  1904.     BOOL Merge(
  1905.       const H323Capabilities & newCaps
  1906.     );
  1907.  
  1908.     /**Change the order of capabilities in the table to the order specified.
  1909.        Note that this does not change the unique capability numbers assigned
  1910.        when the capability is first added to the set.
  1911.  
  1912.        The string matching rules are as for the FindCapability() function.
  1913.       */
  1914.     void Reorder(
  1915.       const PStringArray & preferenceOrder  /// New order
  1916.     );
  1917.  
  1918.     /**Test if the capability is allowed.
  1919.       */
  1920.     BOOL IsAllowed(
  1921.       const H323Capability & capability
  1922.     );
  1923.  
  1924.     /**Test if the capability is allowed.
  1925.       */
  1926.     BOOL IsAllowed(
  1927.       unsigned capabilityNumber
  1928.     );
  1929.  
  1930.     /**Test if the capabilities are an allowed combination.
  1931.       */
  1932.     BOOL IsAllowed(
  1933.       const H323Capability & capability1,
  1934.       const H323Capability & capability2
  1935.     );
  1936.  
  1937.     /**Test if the capabilities are an allowed combination.
  1938.       */
  1939.     BOOL IsAllowed(
  1940.       unsigned capabilityNumber1,
  1941.       unsigned capabilityNumber2
  1942.     );
  1943.   //@}
  1944.  
  1945.   protected:
  1946.     H323CapabilitiesList table;
  1947.     H323CapabilitiesSet  set;
  1948. };
  1949.  
  1950.  
  1951. ///////////////////////////////////////////////////////////////////////////////
  1952.  
  1953. /**Registration of a capability name.
  1954.    Exactly one static instance of this class is created so that the system can
  1955.    create the approriate H323Capability descendant given a string name.
  1956.   */
  1957. class H323CapabilityRegistration : public PCaselessString
  1958. {
  1959.     PCLASSINFO(H323CapabilityRegistration, PCaselessString);
  1960.   public:
  1961.     H323CapabilityRegistration(
  1962.       const char * name
  1963.     );
  1964.     virtual H323Capability * Create(H323EndPoint & ep) const = 0;
  1965.  
  1966.   protected:
  1967.     static PMutex & GetMutex();
  1968.     static H323CapabilityRegistration * registeredCapabilitiesListHead;
  1969.  
  1970.     H323CapabilityRegistration * link;
  1971.  
  1972.   friend class H323Capability;
  1973.   friend class H323Capabilities;
  1974.   friend class OpalDynaCodecDLL;
  1975. };
  1976.  
  1977.  
  1978.  
  1979.  
  1980. #define H323_REGISTER_CAPABILITY_FUNCTION(cls, name, epvar) \
  1981. class cls##_Registration : public H323CapabilityRegistration { \
  1982.   public: \
  1983.     cls##_Registration() : H323CapabilityRegistration(name) { } \
  1984.     H323Capability * Create(H323EndPoint & ep) const; \
  1985. } cls##_Registration_Instance; \
  1986. H323Capability * cls##_Registration::Create(H323EndPoint & epvar) const
  1987.  
  1988. #define H323_NO_EP_VAR
  1989.  
  1990. #define H323_REGISTER_CAPABILITY(cls, name) \
  1991.   H323_REGISTER_CAPABILITY_FUNCTION(cls, name, H323_NO_EP_VAR) \
  1992.   { return new cls; }
  1993.  
  1994. #define H323_REGISTER_CAPABILITY_EP(cls, name) \
  1995.   H323_REGISTER_CAPABILITY_FUNCTION(cls, name, ep) \
  1996.   { return new cls(ep); }
  1997.  
  1998.  
  1999. #define H323_STATIC_LOAD_REGISTER_CAPABILITY(cls) \
  2000.   class cls##_Registration; \
  2001.   extern cls##_Registration cls##_Registration_Instance; \
  2002.   static cls##_Registration * cls##_Registration_Static_Library_Loader = &cls##_Registration_Instance
  2003.  
  2004.  
  2005. #endif // __OPAL_H323CAPS_H
  2006.  
  2007.  
  2008. /////////////////////////////////////////////////////////////////////////////
  2009.