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

#include "nmm/nmm_prefix.hpp"

#include "Sock.hpp"
#include "INetAddr.hpp"

#include "visibility.hpp"

namespace NMM {

  /** Connection-oriented network socket.
   *
   * This class provides methods to transport data over a network
   * connection.
   */
  class DLLEXPORT SockStream : public Sock {
  public:
    /** @name Constructor & Destructor
     */
    //@{
    /** Create a new %SockStream.
     *
     * This constructor creates a %SockStream for a certain protocol
     * and request a socket for it.
     *
     * @param owner @c true, if this socket should be responsible for the created socket
     */
    SockStream(bool owner = true);
    
    /** Create SockStream for an already existing socket.
     *
     * This constructor uses an already existing socket.
     *
     * @param socket Socket to assign to this SockStream
     * @param owner If @c true, this socket is responsible for the socket
     */
    SockStream(SocketHandle socket, bool owner);

    /** Virtual destructor.
     *
     * Releases the socket if SockStream is owner of it.
     */
    virtual ~SockStream();
    //@}
    
    /** @name Addresses
     */
    //@{
    /** Set address of peer.
     *
     * This method should only be called by a SockConnector or
     * SockAcceptor.
     *
     * @param addr Pointer to peer address
     */
    void setPeerAddress(const INetAddr& addr);
    
    /** Returns the peer address of a socket.
     *
     * This method gets the correct peer address only if the socket is
     * connected.
     *
     * @return Peer address of this socket
     */
    const INetAddr& getPeerAddress() const;
    
    /** Returns the local address of the socket.
     *
     * @return Local address of this socket
     */
    INetAddr getLocalAddress() const;
    //@}
    
    /** @name Socket Handling
     */
    //@{
    /** Assigns a new socket.
     *
     * The old socket is closed if this %SockStream is owner of it.
     *
     * @param socket The new socket
     * @param owner Specify if Sock is responsible for the new socket
     */
    void setSocket(SocketHandle socket, bool owner = false);
    
    /** returns the current socket.
     * @return current socket
     */
    inline SocketHandle getSocket()  const    { return __socket; }
    
    /** This method closes a connection.
     *
     * In this case no difference is made if the SockStream is owner
     * of the socket or not.
     */
    virtual void close();
    //@}
    
    /** @name Transmission Methods
     */
    //@{
    /** Receives data from a connection.
     *
     * @param buffer Buffer where the received data should be stored
     * @param len Maximum number of bytes to receive
     * @return Actual number of bytes received
     * @exception TransmissionException if the transmission fails or a socket error occurs
     */
    size_t recv(void* buffer, size_t len)
      throw(const TransmissionException&);
    
    /** Sends data over a connection.
     *
     * @param buffer Buffer containing the data to be sent
     * @param len Maximum number of bytes to send
     * @return Actual number of bytes sent
     * @exception TransmissionException if the transmission fails or a socket error occurs
     */
    size_t send(const void* buffer, size_t len)
      throw(const TransmissionException&);
    
    /** Read data from the socket, treating it like a stream.
     * This method reads data until len bytes have been read or the connection has been closed.
     *
     * @param buffer Buffer where the read data should be stored
     * @param len Maximum number of bytes to read
     * @param max_packet_size Maximum size of a single packet, 0 to use protocol default
     * @exception TransmissionException if the transmission fails or a socket error occurs
     * @exception ConnectionClosed if the connection was closed before len bytes have been read
     */
    void readStream(char* buffer, size_t len,  size_t max_packet_size = 0)
      throw(const TransmissionException&, const ConnectionClosed&);
    
    /** Write data from the socket, treating it like a stream.
     * This method tries to write exactly len bytes of data.
     *
     * @param buffer Buffer containing the data to be written
     * @param length Maximum number of bytes to write
     * @param max_packet_size Maximum size of a single packet, 0 to use protocol default
     * @exception TransmissionException if the transmission fails or a socket error occurs
     * @exception ConnectionClosed if the connection was closed before len bytes have been written
     */
    void writeStream(const char* buffer, size_t length, size_t max_packet_size = 0)
      throw (const TransmissionException&, const ConnectionClosed&);
    //@}
    
    /** @name Socket Options
     */
    //@{
    /** This method turns the Nagle algorithm on or off. This means
     * that packets are always sent as soon as possible and no
     * unnecessary delays are introduced, at the cost of more packets
     * in the network. Expects an integer boolean flag.
     *
     * @param value true disables the Nagle algorithm, false turns it on
     */
    void enableNoDelay(const bool& value);

    /** Returns true if the Nagle algorithm is enabled, otherwise false
     *
     * @return true if the Nagle algorithm is enabled, otherwise false
     */
    bool isDelayEnabled() const;

    /** Set or receive the maximum segment size for outgoing TCP
     * packets. If this option is set before connection establishment,
     * it also changes the MSS value announced to the other end in the
     * initial packet. Values greater than the interface MTU are
     * ignored and have no effect.
     * 
     * @param value sets the maximum segement size for outgoung TCP packets. 
     */
    void setMaxSegment(const int& value);

    /** This method returns the current segment size.
     *
     * @return current segments size
     */
    int  getMaxSegment() const;

    /** This method enanbles/disables partial frames. If enabled don't
     * send out partial frames.  All queued partial frames are sent
     * when the option is cleared again.  This is useful for
     * prepending headers before calling sendfile(2), or for
     * throughput optimization. This option cannot be combined with
     * TCP_NODELAY.
     * 
     * @param value specifies if partial frames should be enabled or not. 
     */
    void enablePartialFrames(const bool& value);

    /** This method returns true if partial frames are enabled,
     * otherwise false.
     *
     * \return true if partial frames are enabled,
     * otherwise false
     */
    bool isPartialFramesEnabled();

    /** This method returns the count of unread data.
     *  
     * @return count of unread data.
     */
    int  getUnreadQueueCount() const;

    /** This method returns the count of unsend data.
     *  
     * @return count of unsend data.
     */
    int  getUnsendQueueCount() const;

    /** This method returns true if all data are send.
     *  
     * @return true if all urgent packets are send.
     */
    bool allUrgentDataSend()   const;

    /** This method enables/disables keep connections alive
     * 
     * @param value true enables keep alive connections, false disable keep alive
     */
    void enableKeepAlive(const bool& value);

    /** This method returns true if a connection is keeped alive,
     * otherwise false.
     * 
     * @return true if keep alive is enabled, otherwise false
     */
    bool getKeepAlive() const;
    //@}
    
  private:
    SocketHandle __socket;                ///< Stores the socket which is used for transmission
    bool         __own_socket;            ///< If true, the SockStream uses automatic memory management
    INetAddr     __peer_addr;             ///< Peer address, set by the SockConnector
  };

}

#include "nmm/nmm_suffix.hpp"

#endif
