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


-- | Fast, memory-efficient, low-level networking
--   
--   Fast, memory-efficient, low-level socket functions that use
--   <a>Data.ByteString</a>s instead of <a>String</a>s.
@package network-bytestring
@version 0.1.3


-- | This module provides access to the BSD <i>socket</i> interface. This
--   module is generally more efficient than the <a>String</a> based
--   network functions in <tt>Network.Socket</tt>. For detailed
--   documentation, consult your favorite POSIX socket reference. All
--   functions communicate failures by converting the error number to
--   <tt>System.IO.IOError</tt>.
--   
--   This module is made to be imported with <tt>Network.Socket</tt> like
--   so:
--   
--   <pre>
--   import Network.Socket hiding (send, sendTo, recv, recvFrom)
--   import Network.Socket.ByteString
--   </pre>
module Network.Socket.ByteString

-- | Send data to the socket. The socket must be connected to a remote
--   socket. Returns the number of bytes sent. Applications are responsible
--   for ensuring that all data has been sent.
send :: Socket -> ByteString -> IO Int

-- | Send data to the socket. The socket must be connected to a remote
--   socket. Unlike <a>send</a>, this function continues to send data until
--   either all data has been sent or an error occurs. On error, an
--   exception is raised, and there is no way to determine how much data,
--   if any, was successfully sent.
sendAll :: Socket -> ByteString -> IO ()

-- | Send data to the socket. The recipient can be specified explicitly, so
--   the socket need not be in a connected state. Returns the number of
--   bytes sent. Applications are responsible for ensuring that all data
--   has been sent.
sendTo :: Socket -> ByteString -> SockAddr -> IO Int

-- | Send data to the socket. The recipient can be specified explicitly, so
--   the socket need not be in a connected state. Unlike <a>sendTo</a>,
--   this function continues to send data until either all data has been
--   sent or an error occurs. On error, an exception is raised, and there
--   is no way to determine how much data, if any, was successfully sent.
sendAllTo :: Socket -> ByteString -> SockAddr -> IO ()

-- | Send data to the socket. The socket must be in a connected state. The
--   data is sent as if the parts have been concatenated. This function
--   continues to send data until either all data has been sent or an error
--   occurs. On error, an exception is raised, and there is no way to
--   determine how much data, if any, was successfully sent.
sendMany :: Socket -> [ByteString] -> IO ()

-- | Send data to the socket. The recipient can be specified explicitly, so
--   the socket need not be in a connected state. The data is sent as if
--   the parts have been concatenated. This function continues to send data
--   until either all data has been sent or an error occurs. On error, an
--   exception is raised, and there is no way to determine how much data,
--   if any, was successfully sent.
sendManyTo :: Socket -> [ByteString] -> SockAddr -> IO ()

-- | Receive data from the socket. The socket must be in a connected state.
--   This function may return fewer bytes than specified. If the message is
--   longer than the specified length, it may be discarded depending on the
--   type of socket. This function may block until a message arrives.
--   
--   Considering hardware and network realities, the maximum number of
--   bytes to receive should be a small power of 2, e.g., 4096.
--   
--   For TCP sockets, a zero length return value means the peer has closed
--   its half side of the connection.
recv :: Socket -> Int -> IO ByteString

-- | Receive data from the socket. The socket need not be in a connected
--   state. Returns <tt>(bytes, address)</tt> where <tt>bytes</tt> is a
--   <a>ByteString</a> representing the data received and <tt>address</tt>
--   is a <a>SockAddr</a> representing the address of the sending socket.
recvFrom :: Socket -> Int -> IO (ByteString, SockAddr)


-- | This module provides access to the BSD <i>socket</i> interface. This
--   module is generally more efficient than the <a>String</a> based
--   network functions in <tt>Network.Socket</tt>. For detailed
--   documentation, consult your favorite POSIX socket reference. All
--   functions communicate failures by converting the error number to
--   <tt>System.IO.IOError</tt>.
--   
--   This module is made to be imported with <tt>Network.Socket</tt> like
--   so:
--   
--   <pre>
--   import Network.Socket hiding (send, sendTo, recv, recvFrom)
--   import Network.Socket.ByteString.Lazy
--   import Prelude hiding (getContents)
--   </pre>
module Network.Socket.ByteString.Lazy

-- | Send data to the socket. The socket must be in a connected state.
--   Returns the number of bytes sent. Applications are responsible for
--   ensuring that all data has been sent.
--   
--   Because a lazily generated <a>ByteString</a> may be arbitrarily long,
--   this function caps the amount it will attempt to send at 4MB. This
--   number is large (so it should not penalize performance on fast
--   networks), but not outrageously so (to avoid demanding lazily computed
--   data unnecessarily early). Before being sent, the lazy
--   <a>ByteString</a> will be converted to a list of strict
--   <a>ByteString</a>s with <a>toChunks</a>; at most 1024 chunks will be
--   sent. <i>Unix only</i>.
send :: Socket -> ByteString -> IO Int64

-- | Send data to the socket. The socket must be in a connected state. This
--   function continues to send data until either all data has been sent or
--   an error occurs. If there is an error, an exception is raised, and
--   there is no way to determine how much data was sent. <i>Unix only</i>.
sendAll :: Socket -> ByteString -> IO ()

-- | Receive data from the socket. The socket must be in a connected state.
--   Data is received on demand, in chunks; each chunk will be sized to
--   reflect the amount of data received by individual <a>recv</a> calls.
--   
--   All remaining data from the socket is consumed. When there is no more
--   data to be received, the receiving side of the socket is shut down. If
--   there is an error and an exception is thrown, the socket is not shut
--   down.
getContents :: Socket -> IO ByteString

-- | Receive data from the socket. The socket must be in a connected state.
--   This function may return fewer bytes than specified. If the received
--   data is longer than the specified length, it may be discarded
--   depending on the type of socket. This function may block until a
--   message arrives.
--   
--   If there is no more data to be received, returns an empty
--   <a>ByteString</a>.
recv :: Socket -> Int64 -> IO ByteString