-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | UDP library
--   
--   Best current practice library for UDP clients and servers.
@package network-udp
@version 0.0.0


-- | Best current practice library for UDP clients and servers.
--   
--   <ul>
--   <li>Efficient receiving function without memory copy</li>
--   <li>Proper buffer size</li>
--   <li>Type-safe APIs</li>
--   <li>TCP-like APIs (creating a UDP connection from a listing socket) in
--   the server side</li>
--   <li>Auto migration (network interface selection) in the client
--   side</li>
--   </ul>
--   
--   The <a>recv</a> family in <a>Network.Socket.ByteString</a> uses
--   <tt>createAndTrim</tt> internaly. So, one buffer is allocated before
--   corresponding system calls are called. Then another buffer is
--   allocated according to the input size and the input is copied.
--   Receiving functions provided by this library uses <tt>createUptoN</tt>
--   to avoid the memory copy.
--   
--   Recent application protocols are designed to avoid IP fragmentation.
--   So, the UDP payload size is never over 1,500. This library uses 2,048
--   for the buffer size. This size ensures no global locking when
--   allocating <a>ByteString</a> (i.e. a buffer).
--   
--   To know the background of TCP-like API in the server side, see:
--   
--   <ul>
--   
--   <li><a>https://kazu-yamamoto.hatenablog.jp/entry/2022/02/25/153122</a></li>
--   </ul>
--   
--   To know the background of auto migration in the client side, see:
--   
--   <ul>
--   
--   <li><a>https://kazu-yamamoto.hatenablog.jp/entry/2021/06/29/134930</a></li>
--   
--   <li><a>https://www.iij.ad.jp/en/dev/iir/pdf/iir_vol52_focus2_EN.pdf</a>
--   (Sec 3.9)</li>
--   </ul>
module Network.UDP

-- | A UDP socket which are used with <a>recv</a> and <a>send</a>.
data UDPSocket
UDPSocket :: Socket -> SockAddr -> Bool -> UDPSocket
[udpSocket] :: UDPSocket -> Socket

-- | Used for a unconnected socket naturally. Used for a connected sockdet
--   for checking
[peerSockAddr] :: UDPSocket -> SockAddr
[connected] :: UDPSocket -> Bool

-- | Creating a unconnected UDP socket.
clientSocket :: HostName -> ServiceName -> Bool -> IO UDPSocket

-- | Receiving data with a UDP socket. If the socket is connected, recv()
--   is called. Otherwise, recvfrom() is called.
recv :: UDPSocket -> IO ByteString

-- | Receiving data in a buffer with a UDP socket. If the socket is
--   connected, recv() is called. Otherwise, recvfrom() is called.
recvBuf :: UDPSocket -> Ptr Word8 -> Int -> IO Int

-- | Sending data with a UDP socket. If the socket is connected, send() is
--   called. Otherwise, sento() is called.
send :: UDPSocket -> ByteString -> IO ()

-- | Sending data in a buffer with a UDP socket. If the socket is
--   connected, send() is called. Otherwise, sento() is called.
sendBuf :: UDPSocket -> Ptr Word8 -> Int -> IO ()

-- | A listening socket for UDP which can be used for <a>recvFrom</a> and
--   <a>sendTo</a>. Optionally, a connected UDP socket can be created with
--   <a>accept</a> as an emulation of TCP.
data ListenSocket
ListenSocket :: Socket -> SockAddr -> Bool -> ListenSocket
[listenSocket] :: ListenSocket -> Socket
[mySockAddr] :: ListenSocket -> SockAddr

-- | <a>True</a> for wildcard. <a>False</a> for interface-specific.
[wildcard] :: ListenSocket -> Bool

-- | Creating a listening UDP socket.
serverSocket :: (IP, PortNumber) -> IO ListenSocket

-- | A client socket address from the server point of view.
data ClientSockAddr
ClientSockAddr :: SockAddr -> [Cmsg] -> ClientSockAddr

-- | Receiving data with a listening UDP socket. For a wildcard socket,
--   recvmsg() is called. For an interface specific socket, recvfrom() is
--   called.
recvFrom :: ListenSocket -> IO (ByteString, ClientSockAddr)

-- | Sending data with a listening UDP socket. For a wildcard socket,
--   sendmsg() is called. For an interface specific socket, sento() is
--   called.
sendTo :: ListenSocket -> ByteString -> ClientSockAddr -> IO ()

-- | Creating a connected UDP socket like TCP's accept().
accept :: ListenSocket -> ClientSockAddr -> IO UDPSocket

-- | Closing a socket.
stop :: ListenSocket -> IO ()

-- | Closing a socket.
close :: UDPSocket -> IO ()

-- | Emulation of NAT rebiding in the client side. This is mainly used for
--   test purposes.
natRebinding :: UDPSocket -> IO UDPSocket
instance GHC.Show.Show Network.UDP.ListenSocket
instance GHC.Classes.Eq Network.UDP.ListenSocket
instance GHC.Show.Show Network.UDP.UDPSocket
instance GHC.Classes.Eq Network.UDP.UDPSocket
instance GHC.Show.Show Network.UDP.ClientSockAddr
instance GHC.Classes.Eq Network.UDP.ClientSockAddr
