/* Network-Integrated Multimedia Middleware (NMM)
 * http://www.motama.com/nmm.html
 *
 * Copyright (C) 2006-2007
 * Motama GmbH, Saarbruecken, Germany
 * http://www.motama.com
 *
 * This file is part of NMM. 
 * 
 * NMM is free software; you can redistribute it and/or modify it    
 * under the terms of the GNU General Public License as published by 
 * the Free Software Foundation; only version 2 of the License.      
 * 
 * NMM is distributed in the hope that it will be useful, but WITHOUT 
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY 
 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public 
 * License for more details.  
 * 
 * You should have received a copy of the GNU General Public License 
 * along with NMM; if not, write to the Free Software Foundation,    
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 */

module NMM {

  /** Interface for setting and getting IP options.
   *
   * This interface provides several methods for controlling socket
   * options which relate to the IP protocol in general. For
   * controlling options of specific sub-protocols, use the sub
   * classes of this interface.
   *
   * @see ITCPControl, IUDPControl, IRTPControl
   */
  interface IIPControl  {

    /** Set the size of the receive buffer.
     *
     * This method sets the size of the internal receive buffer of the socket.
     * This is the maximum amount of data that is queued at the socket after it is received
     * and before it is read.
     *
     * If new data is received, and there is not enough space in the buffer,
     * this data will be lost or delayed, depending on the used protocol.
     *
     * This option corresponds to the SO_RCVBUF socket option on Linux.
     *
     * @param buffer_size Size of the receive buffer in bytes.
     */
    void setRecvBufferSize(in nmm_int32 buffer_size);
    
    /** Get the size of the receive buffer.
     *
     * This method gets the size of the internal receive buffer of the socket.
     * This is the maximum amount of data that is queued at the socket after it is received
     * and before it is read.
     *
     * If new data is received, and there is not enough space in the buffer,
     * this data will be lost or delayed, depending on the used protocol.
     *
     * This option corresponds to the SO_RCVBUF socket option on Linux.
     *
     * @return Size of the receive buffer in bytes.
     */
    nmm_int32 getRecvBufferSize()  const;
    
    /** Set the size of the send buffer.
     *
     * This method sets the size of the internal send buffer of the socket.
     * This is the maximum amount of data that is queued at the socket after it was written
     * and before it is sent.
     *
     * If data is written to the socket, and there is not enough space in the buffer,
     * the write operation will block.
     *
     * This option corresponds to the SO_SNDBUF socket option on Linux.
     *
     * @param buffer_size Size of the send buffer in bytes.
     */ 
    void setSendBufferSize(in nmm_int32 buffer_size) instream;
    
    /** Get the size of the send buffer.
     *
     * This method gets the size of the internal send buffer of the socket.
     * This is the maximum amount of data that is queued at the socket after it was written
     * and before it is sent.
     *
     * If data is written to the socket, and there is not enough space in the buffer,
     * the write operation will block.
     *
     * This option corresponds to the SO_SNDBUF socket option on Linux.
     *
     * @return Size of the send buffer in bytes.
     */ 
    nmm_int32 getSendBufferSize() const;
    
    /** This method sets the priority of the data.
     *
     * This option corresponds to the SO_PRIORITY socket option on Linux.
     * It sets the priority of the data and the type-of-service (ToS) field for outgoing IP packets.
     *
     * @deprecated This method is obsolete and should not be used for setting the ToS field
     * @note Not implemented on some platforms
     *
     * @param priority The priority
     */
    void setPriority(in nmm_int32 priority);

    /** This method gets the priority of the data.
     *
     * This option corresponds to the SO_PRIORITY socket option on Linux.
     * It sets the priority of the data and the type-of-service (ToS) field for outgoing IP packets.
     *
     * @deprecated This method is obsolete and should not be used for setting the ToS field
     * @note Not implemented on some platforms
     *
     * @return The priority
     */
    nmm_int32 getPriority() const;

    /** Set the quality-of-service (QoS) tag for instream messages.
     * This method sets the quality-of-service (QoS) tag for instream messages.
     * The default value is STREAMING_DATA.
     *
     * @param qos_tag Quality-of-service (QoS) tag
     */
    void setInstreamBufferPriority(in Sock::QOS_TAG qos_tag);

    /** Set the quality-of-service (QoS) tag for instream events.
     * This method sets the quality-of-service (QoS) tag for instream events.
     * The default value is INBAND_DATA.
     *
     * @param qos_tag Quality-of-service (QoS) tag
     */
    void setInstreamEventPriority(in Sock::QOS_TAG qos_tag);

    /** Set the quality-of-service (QoS) tag for out-of-band events.
     * This method sets the quality-of-service (QoS) tag for out-of-band events.
     * The default value is RMI_DATA.
     *
     * @param qos_tag Quality-of-service (QoS) tag
     */
    void setOutOfBandEventPriority(in Sock::QOS_TAG qos_tag);

    /** Get the quality-of-service (QoS) tag for instream messages.
     * This method gets the quality-of-service (QoS) tag for instream messages.
     * The default value is STREAMING_DATA.
     *
     * @return Quality-of-service (QoS) tag
     */
    Sock::QOS_TAG getInstreamBufferPriority();

    /** Get the quality-of-service (QoS) tag for instream events.
     * This method gets the quality-of-service (QoS) tag for instream events.
     * The default value is INBAND_DATA.
     *
     * @return Quality-of-service (QoS) tag
     */
    Sock::QOS_TAG getInstreamEventPriority();

    /** Get the quality-of-service (QoS) tag for out-of-band events.
     * This method gets the quality-of-service (QoS) tag for out-of-band events.
     * The default value is RMI_DATA.
     *
     * @return Quality-of-service (QoS) tag
     */
    Sock::QOS_TAG getOutOfBandEventPriority();

  };
}
