/* 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_SOCKDGRAM_HPP
#define NMM_SOCKDGRAM_HPP NMM_SOCKDGRAM_HPP

#include "nmm/nmm_prefix.hpp"

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

#include "visibility.hpp"

namespace NMM {

  /** Connectionless network socket.
   *
   * This class provide methods to transport data between a pair of
   * datagram sockets.
   */
  class DLLEXPORT SockDGram : public Sock {
  public:
    /** @name Constructor & Destructor
     */
    //@{
    /** Create a new connectionless socket.
     *
     * This constructor creates a %SockDGram for a certain protocol
     * and request a socket for it.
     *
     * @param owner @c true, if this socket should be responsible for the created socket
     */
    SockDGram(bool owner = true);

    /** Create a %SockDGram for an already existing socket.
     *
     * @param socket Socket to assign to this SockDGram
     * @param owner If true, this socket is responsible for the socket
     */
    SockDGram(SocketHandle socket, bool owner);

    /** Virtual Destructor.
     *
     * Releases the socket if SockDGram is owner of it.
     */
    virtual ~SockDGram();
    //@}
    
    /** @name Addresses
     */
    //@{
    /** Set address of peer socket.
     *
     * This method should only be called by a SockConnector or
     * SockAcceptor. Changes the address where UDP datagrams are sent
     * to and should be received from.
     *
     * @param addr Pointer to peer address
     */
    void setPeerAddress(const INetAddr& addr);
    
    /** Get 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 { return __peer_addr; } 
    
    /** 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 Sock 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. This implementation does nothing and is
     * only needed for completeness of the interface.
     */
    virtual void close();
    //@}
    
    /** @name Transmission Methods
     */
    //@{
    /** Receives data from the peer socket.
     *
     * If the datagram does not come from the current peer address, a
     * %TransmissionException is thrown.
     *
     * @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&);
    
    /** Send data to the peer socket.
     *
     * The datagram is sent to the current peer address.
     *
     * @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&);
    
  private:
    SocketHandle __socket;          ///< Stores the datagram socket
    bool __own_socket;              ///< If true, this object is responsible for the socket
    INetAddr __peer_addr;           ///< Stores the peer address to send to and receive from
  };

}

#include "nmm/nmm_suffix.hpp"

#endif
