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


-- | High-level network sockets
--   
--   High-level abstraction for network sockets
@package sockets
@version 0.1.0.0

module Socket.Datagram.IPv4.Undestined

-- | A connectionless datagram socket that may communicate with many
--   different endpoints on a datagram-by-datagram basis.
newtype Socket
Socket :: Fd -> Socket

-- | An endpoint for an IPv4 socket, connection, or listener. Everything is
--   in host byte order, and the user is not responisble for performing any
--   conversions.
data Endpoint
Endpoint :: !IPv4 -> !Word16 -> Endpoint
[$sel:address:Endpoint] :: Endpoint -> !IPv4
[$sel:port:Endpoint] :: Endpoint -> !Word16

-- | Open a socket and run the supplied callback on it. This closes the
--   socket when the callback finishes or when an exception is thrown. Do
--   not return the socket from the callback. This leads to undefined
--   behavior. If the address <tt>0.0.0.0</tt> is used, the socket receives
--   on all network interfaces. If the port 0 is used, an unused port is
--   chosen by the operating system. The callback provides the chosen port
--   (or if the user specified a non-zero port, the chosen port will be
--   that value).
withSocket :: Endpoint -> (Socket -> Word16 -> IO a) -> IO (Either SocketException a)

-- | Send a slice of a bytearray to the specified endpoint.
send :: Socket -> Endpoint -> ByteArray -> Int -> Int -> IO (Either SocketException ())

-- | Receive a datagram into a freshly allocated bytearray.
receive :: Socket -> Int -> IO (Either SocketException (Endpoint, ByteArray))

-- | Receive a datagram into a mutable byte array, ignoring information
--   about the remote endpoint. Returns the actual number of bytes present
--   in the datagram. Precondition: <tt>buffer_length - offset &gt;=
--   max_datagram_length</tt>.
receiveMutableByteArraySlice_ :: Socket -> MutableByteArray RealWorld -> Int -> Int -> IO (Either SocketException Int)

-- | Represents any unexpected behaviors that a function working on a
--   socket, connection, or listener can exhibit.
data SocketException
SocketException :: Context -> Reason -> SocketException
[$sel:context:SocketException] :: SocketException -> Context
[$sel:reason:SocketException] :: SocketException -> Reason

-- | The function that behaved unexpectedly.
data Context
Accept :: Context
Bind :: Context
Close :: Context
Connect :: Context
GetName :: Context
Listen :: Context
Open :: Context
Option :: Context
Receive :: Context
Send :: Context
Shutdown :: Context

-- | A description of the unexpected behavior.
data Reason

-- | The datagram did not fit in the buffer. This can happen while sending
--   or receiving. Fields: buffer size, datagram size.
MessageTruncated :: !Int -> !Int -> Reason

-- | The socket address was not the expected size. This exception indicates
--   a bug in this library or (less likely) in the operating system.
SocketAddressSize :: Reason

-- | The socket address had an unexpected family. This exception indicates
--   a bug in this library or (less likely) in the operating system.
SocketAddressFamily :: Reason

-- | The option value was not the expected size. This exception indicates a
--   bug in this library or (less likely) in the operating system.
OptionValueSize :: Reason

-- | The user requested a negative number of bytes in a call to a receive
--   function.
NegativeBytesRequested :: Reason

-- | The remote end sent more data when it was expected to send a shutdown.
RemoteNotShutdown :: Reason

-- | The remote end has shutdown its side of the full-duplex connection.
--   This can happen <tt>receive</tt> is called on a stream socket. This is
--   not necessarily a bad thing. Many protocols use shutdown to indicate
--   that no more data is available. These protocols can be contrasted with
--   protocols that send a length representing a number of expected bytes.
RemoteShutdown :: Reason

-- | Any error code from the operating system that this library does not
--   expect or recognize. Consult your operating system manual for details
--   about the error code.
ErrorCode :: !CInt -> Reason
instance GHC.Classes.Ord Socket.Datagram.IPv4.Undestined.Socket
instance GHC.Classes.Eq Socket.Datagram.IPv4.Undestined.Socket

module Socket.Stream.IPv4

-- | A socket that listens for incomming connections.
data Listener

-- | A connection-oriented stream socket.
data Connection

-- | An endpoint for an IPv4 socket, connection, or listener. Everything is
--   in host byte order, and the user is not responisble for performing any
--   conversions.
data Endpoint
Endpoint :: !IPv4 -> !Word16 -> Endpoint
[$sel:address:Endpoint] :: Endpoint -> !IPv4
[$sel:port:Endpoint] :: Endpoint -> !Word16
withListener :: Endpoint -> (Listener -> Word16 -> IO a) -> IO (Either SocketException a)

-- | Accept a connection on the listener and run the supplied callback on
--   it. This closes the connection when the callback finishes or if an
--   exception is thrown. Since this function blocks the thread until the
--   callback finishes, it is only suitable for stream socket clients that
--   handle one connection at a time. The variant
--   <a>forkAcceptedUnmasked</a> is preferrable for servers that need to
--   handle connections concurrently (most use cases).
withAccepted :: Listener -> (Connection -> Endpoint -> IO a) -> IO (Either SocketException a)

-- | Establish a connection to a server.
withConnection :: Endpoint -> (Connection -> IO a) -> IO (Either SocketException a)

-- | Accept a connection on the listener and run the supplied callback in a
--   new thread. Prefer <a>forkAcceptedUnmasked</a> unless the masking
--   state needs to be preserved for the callback. Such a situation seems
--   unlikely to the author.
forkAccepted :: Listener -> (Either SocketException a -> IO ()) -> (Connection -> Endpoint -> IO a) -> IO (Either SocketException ThreadId)

-- | Accept a connection on the listener and run the supplied callback in a
--   new thread. The masking state is set to <tt>Unmasked</tt> when running
--   the callback.
forkAcceptedUnmasked :: Listener -> (Either SocketException a -> IO ()) -> (Connection -> Endpoint -> IO a) -> IO (Either SocketException ThreadId)
sendByteArray :: Connection -> ByteArray -> IO (Either SocketException ())
sendByteArraySlice :: Connection -> ByteArray -> Int -> Int -> IO (Either SocketException ())
sendMutableByteArray :: Connection -> MutableByteArray RealWorld -> IO (Either SocketException ())
sendMutableByteArraySlice :: Connection -> MutableByteArray RealWorld -> Int -> Int -> IO (Either SocketException ())

-- | Receive exactly the given number of bytes. If the remote application
--   shuts down its end of the connection before sending the required
--   number of bytes, this returns <tt><a>Left</a> (<a>SocketException</a>
--   <a>Receive</a> <a>RemoteShutdown</a>)</tt>.
receiveByteArray :: Connection -> Int -> IO (Either SocketException ByteArray)

-- | Receive up to the given number of bytes. If the remote application
--   shuts down its end of the connection instead of sending any bytes,
--   this returns <tt><a>Left</a> (<a>SocketException</a> <a>Receive</a>
--   <a>RemoteShutdown</a>)</tt>.
receiveBoundedByteArray :: Connection -> Int -> IO (Either SocketException ByteArray)

-- | Receive a number of bytes exactly equal to the size of the mutable
--   byte array. If the remote application shuts down its end of the
--   connection before sending the required number of bytes, this returns
--   <tt><a>Left</a> (<a>SocketException</a> <a>Receive</a>
--   <a>RemoteShutdown</a>)</tt>.
receiveMutableByteArray :: Connection -> MutableByteArray RealWorld -> IO (Either SocketException ())

-- | Represents any unexpected behaviors that a function working on a
--   socket, connection, or listener can exhibit.
data SocketException
SocketException :: Context -> Reason -> SocketException
[$sel:context:SocketException] :: SocketException -> Context
[$sel:reason:SocketException] :: SocketException -> Reason

-- | The function that behaved unexpectedly.
data Context
Accept :: Context
Bind :: Context
Close :: Context
Connect :: Context
GetName :: Context
Listen :: Context
Open :: Context
Option :: Context
Receive :: Context
Send :: Context
Shutdown :: Context

-- | A description of the unexpected behavior.
data Reason

-- | The datagram did not fit in the buffer. This can happen while sending
--   or receiving. Fields: buffer size, datagram size.
MessageTruncated :: !Int -> !Int -> Reason

-- | The socket address was not the expected size. This exception indicates
--   a bug in this library or (less likely) in the operating system.
SocketAddressSize :: Reason

-- | The socket address had an unexpected family. This exception indicates
--   a bug in this library or (less likely) in the operating system.
SocketAddressFamily :: Reason

-- | The option value was not the expected size. This exception indicates a
--   bug in this library or (less likely) in the operating system.
OptionValueSize :: Reason

-- | The user requested a negative number of bytes in a call to a receive
--   function.
NegativeBytesRequested :: Reason

-- | The remote end sent more data when it was expected to send a shutdown.
RemoteNotShutdown :: Reason

-- | The remote end has shutdown its side of the full-duplex connection.
--   This can happen <tt>receive</tt> is called on a stream socket. This is
--   not necessarily a bad thing. Many protocols use shutdown to indicate
--   that no more data is available. These protocols can be contrasted with
--   protocols that send a length representing a number of expected bytes.
RemoteShutdown :: Reason

-- | Any error code from the operating system that this library does not
--   expect or recognize. Consult your operating system manual for details
--   about the error code.
ErrorCode :: !CInt -> Reason