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


-- | icmp echo requests
--   
--   This library provides functions that have similar behavior as the unix
--   command-line utility ping. In particular, both emit ICMP echo requests
--   and wait for responses. This library uses a haskell implementation of
--   ICMP rather than invoking `/bin/ping`. This avoids the costly process
--   of starting a child process. Additionally, there are greater
--   opportunities for reusing sockets. The cost of this is that the user
--   must ensure that one of these is true:
--   
--   <ul>
--   <li>The kernel parameter `net.ipv4.ping_group_range` has been
--   configured to allow pings to all IP addresses. (preferred
--   solution)</li>
--   <li>The process is running with the the <a>CAP_NET_RAW</a>
--   capability.</li>
--   <li>The process is running as root. (worst solution)</li>
--   </ul>
@package ping
@version 0.1.0.2

module Network.Icmp.Ping

-- | Ping an IPv4 address. Blocks until a response is received.
host :: Int -> IPv4 -> IO (Either IcmpException (Maybe Word64))

-- | Ping a set of hosts simultaneously. Performs one ping for each host
--   and reports the elapsed nanoseconds for the response. If a key is
--   missing from the resulting map, it indicates that a response was not
--   received from that host.
hosts :: Int -> Set IPv4 -> IO (Either IcmpException (Map IPv4 Word64))

-- | Ping a range of hosts simultaneously.
range :: Int -> IPv4Range -> IO (Either IcmpException (Map IPv4 Word64))

-- | Ping a group of hosts simultaneously. Performs a configurable number
--   of pings for each host and reports the elapsed nanoseconds for each
--   response. If the array of durations is smaller than the total number
--   of pings, it indicates that some ICMP requests for that host were lost
--   or corrupted.
--   
--   The function also accepts an cutoff for unresponsive hosts. If a host
--   does not respond to the initial number of pings equal to the cutoff,
--   this function does not attempt further pings to the host. Consider the
--   case in which this function performs 20 pings per host with a 5e6
--   microsecond timeout. Without the unresponsive cutoff, a single
--   nonresponsive host would cause this function to always run for 100
--   seconds. However, with the cutoff set to 3, this function would stop
--   trying pinging the host after there was no response to any of the
--   first 3 pings. However if there were a response to any of the first 3
--   pings, then all 20 pings would continue to be sent. This does not
--   necessarily guarantee that this function would run for less than 100
--   seconds. A host might respond to the initial ping and then go offline.
--   Or a host might take just under 5 seconds to respond to each ping.
--   However, both of these situations are uncommon. What is much more
--   common is that someone includes a bad IP address in the list of hosts,
--   and a low cutoff can considerably reduce the amount of time wasted on
--   such pings. To prevent the cutoff behavior, set it to the number of
--   pings per host.
multihosts :: Int -> Int -> Int -> Int -> Set IPv4 -> IO (Either IcmpException (Map IPv4 (PrimArray Word64)))

-- | Send multiple pings to each host in a range of hosts simultaneously.
multirange :: Int -> Int -> Int -> Int -> IPv4Range -> IO (Either IcmpException (Map IPv4 (PrimArray Word64)))
data IcmpException

-- | Could not create the socket
IcmpExceptionSocket :: !CInt -> IcmpException

-- | Unable to send when the event manager indicated that the socket was
--   ready for writes.
IcmpExceptionSend :: !CInt -> IcmpException

-- | Unable to send the entirity on an ICMP request. The field is the
--   number of bytes actually sent.
IcmpExceptionSendBytes :: !CSize -> IcmpException

-- | Unable to receive when the event manager indicated that the socket was
--   ready for reads.
IcmpExceptionReceive :: !CInt -> IcmpException

-- | Could not close the socket.
IcmpExceptionClose :: !CInt -> IcmpException