/*
 *
 *    Copyright (c) 2013-2017 Nest Labs, Inc.
 *    All rights reserved.
 *
 *    Licensed under the Apache License, Version 2.0 (the "License");
 *    you may not use this file except in compliance with the License.
 *    You may obtain a copy of the License at
 *
 *        http://www.apache.org/licenses/LICENSE-2.0
 *
 *    Unless required by applicable law or agreed to in writing, software
 *    distributed under the License is distributed on an "AS IS" BASIS,
 *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *    See the License for the specific language governing permissions and
 *    limitations under the License.
 */

/**                                                                           .
 *    @file
 *      This header file defines the <tt>nl::Inet::UDPEndPoint</tt>
 *      class, where the Nest Inet Layer encapsulates methods for
 *      interacting with UDP transport endpoints (SOCK_DGRAM sockets
 *      on Linux and BSD-derived systems) or LwIP UDP protocol
 *      control blocks, as the system is configured accordingly.
 */

#ifndef UDPENDPOINT_H
#define UDPENDPOINT_H

#include <InetLayer/EndPointBasis.h>
#include <InetLayer/IPAddress.h>

#include <SystemLayer/SystemPacketBuffer.h>

namespace nl {
namespace Inet {

class InetLayer;
class IPPacketInfo;

/**                                                                           .
 * @brief   Objects of this class represent UDP transport endpoints.
 *
 * @details
 *  Nest Inet Layer encapsulates methods for interacting with UDP transport
 *  endpoints (SOCK_DGRAM sockets on Linux and BSD-derived systems) or LwIP
 *  UDP protocol control blocks, as the system is configured accordingly.
 */
class NL_DLL_EXPORT UDPEndPoint : public EndPointBasis
{
    friend class InetLayer;

public:
    /**
     * @brief   Basic dynamic state of the underlying endpoint.
     *
     * @details
     *  Objects are initialized in the "ready" state, proceed to the "bound"
     *  state after binding to a local interface address, then proceed to the
     *  "listening" state when they have continuations registered for handling
     *  events for reception of UDP messages.
     *
     * @note
     *  The \c kBasisState_Closed state enumeration is mapped to \c kState_Ready for historical binary-compatibility reasons. The
     *  existing \c kState_Closed exists to identify separately the distinction between "not opened yet" and "previously opened now
     *  closed" that existed previously in the \c kState_Ready and \c kState_Closed states.
     */
    enum {
        kState_Ready        = kBasisState_Closed,   /**< Endpoint initialized, but not open. */
        kState_Bound        = 1,                    /**< Endpoint bound, but not listening. */
        kState_Listening    = 2,                    /**< Endpoint receiving datagrams. */
        kState_Closed       = 3                     /**< Endpoint closed, ready for release. */
    } mState;

    /**
     * @brief   Transmit option flags for the \c SendTo methods.
     */
    enum {
        /** Do not destructively queue the message directly. Queue a copy. */
        kSendFlag_RetainBuffer = 0x0040
    };

    /**
     * @brief   Bind the endpoint to an interface IP address.
     *
     * @param[in]   addrType    the protocol version of the IP address
     * @param[in]   addr        the IP address (must be an interface address)
     * @param[in]   port        the UDP port
     * @param[in]   intfId      an optional network interface indicator
     *
     * @retval  INET_NO_ERROR               success: endpoint bound to address
     * @retval  INET_ERROR_INCORRECT_STATE  endpoint has been bound previously
     * @retval  INET_NO_MEMORY              insufficient memory for endpoint
     *
     * @retval  INET_ERROR_UNKNOWN_INTERFACE
     *      On some platforms, the optionally specified interface is not
     *      present.
     *
     * @retval  INET_ERROR_WRONG_PROTOCOL_TYPE
     *      \c addrType does not match \c IPVer.
     *
     * @retval  INET_ERROR_WRONG_ADDRESS_TYPE
     *      \c addrType is \c kIPAddressType_Any, or the type of \c addr is not
     *      equal to \c addrType.
     *
     * @retval  other                   another system or platform error
     *
     *  already acquired.
     */
    INET_ERROR Bind(IPAddressType addrType, IPAddress addr, uint16_t port, InterfaceId intfId = INET_NULL_INTERFACEID);

    /**
     * @brief   Prepare the endpoint to receive UDP messages.
     *
     * @retval  INET_NO_ERROR   success: endpoint ready to receive messages.
     * @retval  INET_ERROR_INCORRECT_STATE  endpoint is already listening.
     *
     * @details
     *  If \c State is already \c kState_Listening, then no operation is
     *  performed, otherwise the \c State is set to \c kState_Listening and
     *  the endpoint is prepared to received UDP messages, according to the
     *  semantics of the platform.
     *
     *  On LwIP, this method must not be called with the LwIP stack lock
     *  already acquired
     */
    INET_ERROR Listen(void);

    /**
     *  A synonym for <tt>SendTo(addr, port, INET_NULL_INTERFACEID, msg,
     *  sendFlags)</tt>.
     */
    INET_ERROR SendTo(IPAddress addr, uint16_t port, Weave::System::PacketBuffer *msg, uint16_t sendFlags = 0);

    /**
     * @brief   Send a UDP message to the specified destination address.
     *
     * @param[in]   addr        the destination IP address
     * @param[in]   port        the destination UDP port
     * @param[in]   intfId      an optional network interface indicator
     * @param[in]   msg         the packet buffer containing the UDP message
     * @param[in]   sendFlags   optional transmit option flags
     *
     * @retval  INET_NO_ERROR       success: \msg is queued for transmit.
     * @retval  INET_ERROR_NOT_IMPLEMENTED  system implementation not complete.
     *
     * @retval  INET_ERROR_WRONG_ADDRESS_TYPE
     *      the destination address and the bound interface address do not
     *      have matching protocol versions or address type.
     *
     * @retval  INET_ERROR_MESSAGE_TOO_LONG
     *      \c msg does not contain the whole UDP message.
     *
     * @retval  INET_ERROR_OUTBOUND_MESSAGE_TRUNCATED
     *      On some platforms, only a truncated portion of \c msg was queued
     *      for transmit.
     *
     * @retval  other                   another system or platform error
     *
     * @details
     *      If possible, then this method sends the UDP message \c msg to the
     *      destination \c addr (with \c intfId used as the scope
     *      identifier for IPv6 link-local destinations) and \c port with the
     *      transmit option flags encoded in \c sendFlags.
     *
     *      Where <tt>(sendFlags & kSendFlag_RetainBuffer) != 0</tt>, calls
     *      <tt>Weave::System::PacketBuffer::Free</tt> on behalf of the caller, otherwise this
     *      method deep-copies \c msg into a fresh object, and queues that for
     *      transmission, leaving the original \c msg available after return.
     */
    INET_ERROR SendTo(IPAddress addr, uint16_t port, InterfaceId intfId, Weave::System::PacketBuffer *msg, uint16_t sendFlags = 0);

    /**
     * Get the bound interface on this endpoint.
     *
     * @return InterfaceId   The bound interface id.
     */
    InterfaceId GetBoundInterface(void);

    /**
     * @brief   Bind the endpoint to a network interface.
     *
     * @param[in]   addrType    the protocol version of the IP address
     * @param[in]   intf        indicator of the network interface.
     *
     * @retval  INET_NO_ERROR               success: endpoint bound to address
     * @retval  INET_NO_MEMORY              insufficient memory for endpoint
     * @retval  INET_ERROR_NOT_IMPLEMENTED  system implementation not complete.
     *
     * @retval  INET_ERROR_UNKNOWN_INTERFACE
     *      On some platforms, the interface is not present.
     *
     * @retval  other                   another system or platform error
     *
     * @details
     *  Binds the endpoint to the specified network interface IP address.
     *
     *  On LwIP, this method must not be called with the LwIP stack lock
     *  already acquired.
     */
    INET_ERROR BindInterface(IPAddressType addrType, InterfaceId intf);

    /**
     * @brief   Close the endpoint.
     *
     * @details
     *  If <tt>mState != kState_Closed</tt>, then closes the endpoint, removing
     *  it from the set of endpoints eligible for communication events.
     *
     *  On LwIP systems, this method must not be called with the LwIP stack
     *  lock already acquired.
     */
    void Close(void);

    /**
     * @brief   Close the endpoint and recycle its memory.
     *
     * @details
     *  Invokes the \c Close method, then invokes the
     *  <tt>InetLayerBasis::Release</tt> method to return the object to its
     *  memory pool.
     *
     *  On LwIP systems, this method must not be called with the LwIP stack
     *  lock already acquired.
     */
    void Free(void);

    /**
     * @brief   Type of message text reception event handling function.
     *
     * @param[in]   endPoint    The UDP endpoint associated with the event.
     * @param[in]   msg         The message text received.
     * @param[in]   pktInfo     The ancillary packet information.
     *
     * @details
     *  Provide a function of this type to the \c OnMessageReceived delegate
     *  member to process message text reception events on \c endPoint where
     *  \c msg is the message text and \c pktInfo is the ancillary packet
     *  information for it.
     */
    typedef void (*OnMessageReceivedFunct)(UDPEndPoint *endPoint, Weave::System::PacketBuffer *msg, const IPPacketInfo *pktInfo);

    /** The endpoint's message reception event handling function delegate. */
    OnMessageReceivedFunct OnMessageReceived;

    /**
     * @brief   Type of reception error event handling function.
     *
     * @param[in]   endPoint    The raw endpoint associated with the event.
     * @param[in]   err         The reason for the error.
     * @param[in]   pktInfo     The ancillary packet information.
     *
     * @details
     *  Provide a function of this type to the \c OnReceiveError delegate
     *  member to process reception acceptance error events on \c endPoint. The
     *  \c err argument provides specific detail about the type of the error,
     *  and \c pktInfo is the ancillary packet information associated with the
     *  reception event.
     */
    typedef void (*OnReceiveErrorFunct)(UDPEndPoint *endPoint, INET_ERROR err, const IPPacketInfo *pktInfo);

    /** The endpoint's receive error event handling function delegate. */
    OnReceiveErrorFunct OnReceiveError;

private:
    UDPEndPoint(void);                                  // not defined
    UDPEndPoint(const UDPEndPoint&);                    // not defined
    ~UDPEndPoint(void);                                 // not defined

    static Weave::System::ObjectPool<UDPEndPoint, INET_CONFIG_NUM_UDP_ENDPOINTS> sPool;

    void Init(InetLayer *inetLayer);

#if WEAVE_SYSTEM_CONFIG_USE_LWIP
    void HandleDataReceived(Weave::System::PacketBuffer *msg);
    INET_ERROR GetPCB(IPAddressType addrType4);
    static IPPacketInfo *GetPacketInfo(Weave::System::PacketBuffer *buf);
#if LWIP_VERSION_MAJOR > 1
    static void LwIPReceiveUDPMessage(void *arg, struct udp_pcb *pcb, struct pbuf *p, const ip_addr_t *addr, u16_t port);
#else // LWIP_VERSION_MAJOR <= 1
    static void LwIPReceiveUDPMessage(void *arg, struct udp_pcb *pcb, struct pbuf *p, ip_addr_t *addr, u16_t port);
#endif // LWIP_VERSION_MAJOR <= 1
#endif // WEAVE_SYSTEM_CONFIG_USE_LWIP

#if WEAVE_SYSTEM_CONFIG_USE_SOCKETS
    uint16_t mBoundPort;
    InterfaceId mBoundIntfId;

    INET_ERROR GetSocket(IPAddressType addrType);
    SocketEvents PrepareIO(void);
    void HandlePendingIO(void);
#endif // WEAVE_SYSTEM_CONFIG_USE_SOCKETS
};

} // namespace Inet
} // namespace nl

#endif // !defined(UDPENDPOINT_H)