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


-- | A pure Haskell, asyncronous DNS client library
--   
--   A pure Haskell, asyncronous DNS client library
@package network-dns
@version 0.1.2


-- | Contains DNS types which users of the DNS library may need to use.
--   Private types are mostly kept in Network.DNS.Common
module Network.DNS.Types

-- | Types of DNS resources. RFC 1035, 3.2.2.
data DNSType
A :: DNSType
NS :: DNSType
CNAME :: DNSType
SOA :: DNSType
PTR :: DNSType
MX :: DNSType
TXT :: DNSType
AAAA :: DNSType

-- | This is for internal error handling and should never be used or seen
--   outside Network.DNS
UnknownDNSType :: DNSType

-- | Error codes. RFC 1035, 4.1.1.
data ResponseCode
NoError :: ResponseCode

-- | The name server was unable to interpret the query
FormatError :: ResponseCode

-- | The name server was unable to process this query due to a problem with
--   the name server
ServerError :: ResponseCode

-- | Meaningful only for responses from an authoritative name server, this
--   code signifies that the domain name referenced in the query does not
--   exist
NXDomain :: ResponseCode

-- | The name server does not support the requested kind of query.
NotImplemented :: ResponseCode

-- | The name server refuses to perform the specified operation for policy
--   reasons. For example, a name server may not wish to provide the
--   information to the particular requester, or a name server may not wish
--   to perform a particular operation (e.g., zone transfer) for particular
--   data.
AccessDenied :: ResponseCode

-- | Resource record types. There store the actual data in the DNS
--   database. There's one for each DNSType
data RR
RRCNAME :: [String] -> RR

-- | a list of preferences and hostnames
RRMX :: [(Int, [String])] -> RR
RRNS :: [String] -> RR
RRPTR :: [String] -> RR
RRSOA :: [String] -> [String] -> Word32 -> Word32 -> Word32 -> Word32 -> Word32 -> RR
soaName :: RR -> [String]
soaRname :: RR -> [String]
soaSerial :: RR -> Word32
soaRefresh :: RR -> Word32
soaRetry :: RR -> Word32
soaExpire :: RR -> Word32
soaMinTTL :: RR -> Word32
RRTXT :: ByteString -> RR
RRA :: [HostAddress] -> RR
RRAAAA :: [HostAddress6] -> RR

-- | Given an RR, this tells you the resource type of it
rrToType :: RR -> DNSType
instance Show RR
instance Show ResponseCode
instance Eq ResponseCode
instance Enum ResponseCode
instance Bounded ResponseCode
instance Show DNSType
instance Eq DNSType
instance Ord DNSType
instance Enum DNSType


-- | A DNS resolver. This code acts like the resolver library from libc,
--   except that it can work asynchronously, and can return much more
--   information.
--   
--   At the moment, the interface is very much undecided but currently
--   looks like this:
--   
--   <pre>
--   import qualified Network.DNS.Client as DNS
--   
--   DNS.resolve DNS.A "somedomain.com"
--   Right [(2008-02-01 00:27:14.861098 UTC, DNS.RRA [2466498203])]
--   </pre>
--   
--   The first element of the tuple is the time when the information
--   expires. The second depends on the record type requested (A, in this
--   case) and A records contain IP address, so that's a HostAddress in
--   there.
--   
--   This module parses <tt><i>etc</i>resolv.conf</tt> for it's
--   configuration. It needs a recursive server to do the hard work. If
--   you're lacking a recursive server, you can setup dnscache (from
--   djbdns) locally and point at that.
module Network.DNS.Client

-- | Lookup some information from DNS
resolve :: DNSType -> String -> IO (Either DNSError [(UTCTime, RR)])

-- | This is the same as resolve, below, put you get the answer
--   asynchronously. Blocking the thread which makes the callback in this
--   case is bad - it'll block the DNS network reading thread.
resolveAsync :: DNSType -> String -> (Either DNSError [(UTCTime, RR)] -> IO ()) -> IO ()

-- | This is the type of errors from the library. Either it's one of the
--   first two errors (which are generated from within this code), or it's
--   an error directly from the DNS server.
data DNSError

-- | the DNS server didn't answer
Timeout :: DNSError

-- | this is returned when the DNS server returned a valid answer, but the
--   answer didn't include the information we were looking for. Firstly,
--   this isn't a recursive resolver, so if you point it at a non-recursive
--   server you'll get this for nearly every query as the server will just
--   be telling us the location of the roots.
--   
--   This can also occur when you ask for a resource which doesn't exist -
--   like a AAAA record from www.google.com
AnswerNotIncluded :: DNSError

-- | errors from the DNS server
DNSError :: ResponseCode -> DNSError
instance Show DNSError
instance Eq DNSError
instance Random Word16