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

-- | Domain Name Service (DNS) lookup via the libresolv standard library routines
--   
--   This package implements an API for accessing the Domain Name
--   Service (DNS) resolver service via the standard libresolv
--   system library (whose API is often available directly via the standard
--   libc C library) on Unix systems.
--   
--   This package also includes support for decoding message record types
--   as defined in the following RFCs:
--   
--   
--   
- RFC 1035: Domain Names - Implementation And
--   Specification
--   
- RFC 1183: New DNS RR Definitions
--   
- RFC 2782: A DNS RR for specifying the location of services
--   (DNS SRV)
--   
- RFC 2915: The Naming Authority Pointer (NAPTR) DNS Resource
--   Record
--   
- RFC 3596: DNS Extensions to Support IP Version 6
--   
- RFC 4034: Resource Records for the DNS Security
--   Extensions
--   
- RFC 4255: Using DNS to Securely Publish Secure Shell (SSH)
--   Key Fingerprints
--   
- RFC 4408: Sender Policy Framework (SPF) for Authorizing Use
--   of Domains in E-Mail, Version 1
--   
- RFC 5155: DNS Security (DNSSEC) Hashed Authenticated Denial
--   of Existence
--   
- RFC 6844: DNS Certification Authority Authorization (CAA)
--   Resource Record
--   
- RFC 6891: Extension Mechanisms for DNS (EDNS(0))
--   
- RFC 7553: The Uniform Resource Identifier (URI) DNS
--   Resource Record
--   
--   
--   For Windows, the package windns provides a compatible subset of
--   this package's API.
@package resolv
@version 0.2.0.3

-- | This module implements an API for accessing the Domain Name Service
--   (DNS) resolver service via the standard libresolv system
--   library on Unix systems.
module Network.DNS

-- | Query A record (see RFC 1035, section 3.4.1).
--   
--   This query returns only exact matches (modulo foldCaseName).
--   E.g. in case of CNAME responses even if the answer section
--   would contain A records for the hostnames pointed to by the
--   CNAME. You can use query if you need more control.
--   
--   
--   >>> queryA (Name "www.google.com")
--   [(TTL 72,IPv4 0xd83acde4)]
--   
queryA :: Name -> IO [(TTL, IPv4)]

-- | Query AAAA records (see RFC 3596).
--   
--   This query returns only exact matches (modulo foldCaseName).
--   E.g. in case of CNAME responses even if the answer section
--   would contain A records for the hostnames pointed to by the
--   CNAME. You can use query if you need more control.
--   
--   
--   >>> queryAAAA (Name "www.google.com")
--   [(TTL 299,IPv6 0x2a0014504001081e 0x2004)]
--   
queryAAAA :: Name -> IO [(TTL, IPv6)]

-- | Query CNAME records (see RFC 1035, section 3.3.1).
--   
--   
--   >>> queryCNAME (Name "hackage.haskell.org")
--   [(TTL 299,Name "j.global-ssl.fastly.net.")]
--   
queryCNAME :: Name -> IO [(TTL, Name)]

-- | Query PTR records (see RFC 1035, section 3.3.12).
--   
--   
--   >>> queryPTR (Name "4.4.8.8.in-addr.arpa.")
--   [(TTL 14390,Name "dns.google.")]
--   
--   
--   See also arpaIPv6 and arpaIPv4 for converting
--   IPv6 and IPv4 values to the respective .arpa."
--   domain name for reverse lookups.
queryPTR :: Name -> IO [(TTL, Name)]

-- | Query SRV records (see RFC 2782).
--   
--   
--   >>> querySRV (Name "_imap._tcp.gmail.com")
--   [(TTL 21599,SRV {srvPriority = 0, srvWeight = 0, srvPort = 0, srvTarget = Name "."})]
--   
querySRV :: Name -> IO [(TTL, SRV Name)]

-- | Query TXT records (see RFC 1035, section 3.3.14).
--   
--   
--   >>> queryTXT (Name "_mirrors.hackage.haskell.org")
--   [(TTL 299,["0.urlbase=http://hackage.fpcomplete.com/",
--              "1.urlbase=http://objects-us-west-1.dream.io/hackage-mirror/"])]
--   
queryTXT :: Name -> IO [(TTL, [CharStr])]

-- | Send a query via res_query(3) and decode its response into a
--   Msg
--   
--   Throws DnsException in case of resolving or encoding/decoding
--   errors. May throw other IO exceptions in case of network errors.
--   
--   
Example
--   
--   
--   >>> query classIN (Name "_mirrors.hackage.haskell.org") TypeTXT
--   Just (Msg{msgHeader = MsgHeader{mhId    = 56694,
--                                   mhFlags = MsgHeaderFlags{mhQR = IsResponse, mhOpcode = 0, mhAA = False,
--                                                            mhTC = False, mhRD = True, mhRA = True, mhZ = False,
--                                                            mhAD = False, mhCD = False, mhRCode = 0},
--                                   mhQDCount = 1, mhANCount = 1, mhNSCount = 0, mhARCount = 1},
--             msgQD = [MsgQuestion (Name "_mirrors.hackage.haskell.org.") (Type 16) (Class 1)],
--             msgAN = [MsgRR{rrName  = Name "_mirrors.hackage.haskell.org.",
--                            rrClass = Class 1, rrTTL = TTL 299,
--                            rrData  = RDataTXT ["0.urlbase=http://hackage.fpcomplete.com/",
--                                                "1.urlbase=http://objects-us-west-1.dream.io/hackage-mirror/"]}],
--             msgNS = [],
--             msgAR = [MsgRR{rrName = Name ".", rrClass = Class 512, rrTTL = TTL 32768, rrData = RDataOPT ""}]
--         })
--   
query :: IsLabels n => Class -> n -> TypeSym -> IO (Msg n)

-- | Exception thrown in case of errors while resolving or
--   encoding/decoding into a Msg.
data DnsException
DnsEncodeException :: DnsException
DnsDecodeException :: DnsException

-- | No such domain (authoritative)
DnsHostNotFound :: DnsException

-- | No record for requested type
DnsNoData :: DnsException

-- | Non recoverable errors, REFUSED, NOTIMP
DnsNoRecovery :: DnsException

-- | No such domain (non-authoritative) or SERVERFAIL
DnsTryAgain :: DnsException

-- | Whether the reentrant DNS resolver C API (e.g. res_nquery(3),
--   res_nsend(3)) is being used.
--   
--   If this this False, then as a fall-back
--   res_query(3)/res_send(3) are used, protected by a
--   global mutex.
resIsReentrant :: Bool

-- | Send a query via res_query(3), the return value is the raw
--   binary response message.
--   
--   You can use decodeMessage to decode the response message.
queryRaw :: Class -> Name -> Type -> IO ByteString

-- | Send a raw preformatted query via res_send(3).
sendRaw :: ByteString -> IO ByteString

-- | Use res_mkquery(3) to construct a DNS query message.
mkQueryRaw :: Class -> Name -> Type -> IO ByteString

-- | Decode a raw DNS message (query or response)
--   
--   Returns Nothing on decoding failures.
decodeMessage :: IsLabels n => ByteString -> Maybe (Msg n)

-- | Construct a raw DNS message (query or response)
--   
--   May return Nothing in input parameters are detected to be
--   invalid.
encodeMessage :: IsLabels n => Msg n -> Maybe ByteString

-- | Construct a DNS query Msg in the style of mkQueryRaw
mkQueryMsg :: IsLabels n => Class -> n -> Type -> Msg n

-- | A DNS Label
--   
--   Must be non-empty and at most 63 octets.
type Label = ByteString

-- | A domain-name as per RFC 1035, section 3.3
--   expressed as list of Labels.
--   
--   See also Name
data Labels
(:.:) :: !Label -> !Labels -> Labels
Root :: Labels
infixr 5 :.:

-- | Types that represent domain-name as per RFC 1035,
--   section 3.3 and can be converted to and from Labels.
class IsLabels s
toLabels :: IsLabels s => s -> Maybe Labels
fromLabels :: IsLabels s => Labels -> s

-- | <domain-name> as per RFC 1035, section 3.3.
--   
--   A domain-name represented as a series of labels separated by dots.
--   
--   See also Labels for list-based representation.
--   
--   NOTE: The Labels type is able to properly represent
--   domain names whose components contain dots which the Name
--   representation cannot.
newtype Name
Name :: ByteString -> Name

-- | Normalise Name
--   
--   This function case folds Names as described in in RFC 4343,
--   section 3 by subtracting 0x20 from all octets in the
--   inclusive range [0x61..0x7A] (i.e. mapping
--   [a..z] to
--   [A..Z]).
--   
--   This operation is idempotent.
caseFoldName :: Name -> Name

-- | <character-string> as per RFC 1035, section 3.3.
--   
--   A sequence of up to 255 octets
--   
--   The limit of 255 octets is caused by the encoding which uses by a
--   prefixed octet denoting the length.
newtype CharStr
CharStr :: ByteString -> CharStr

-- | An IPv4 address
--   
--   The IP address is represented in network order, i.e.
--   127.0.0.1 is represented as (IPv4 0x7f000001).
data IPv4
IPv4 :: !Word32 -> IPv4

-- | Convert IPv4 address to in-addr.arpa. Name (see
--   RFC 1035, section 3.5).
--   
--   
--   >>> arpaIPv4 (IPv4 0x8080404)
--   Name "4.4.8.8.in-addr.arpa."
--   
arpaIPv4 :: IPv4 -> Name

-- | An IPv6 address
--   
--   The IP address is represented in network order, i.e.
--   2606:2800:220:1:248:1893:25c8:1946 is represented as
--   (IPv6 0x2606280002200001 0x248189325c81946).
data IPv6
IPv6 :: !Word64 -> !Word64 -> IPv6

-- | Convert IPv4 address to ip6.arpa. Name (see
--   RFC 3596, section 2.5).
--   
--   
--   >>> arpaIPv6 (IPv6 0x2001486048600000 0x8844)
--   Name "4.4.8.8.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.6.8.4.0.6.8.4.1.0.0.2.ip6.arpa."
--   
arpaIPv6 :: IPv6 -> Name

-- | Cache time-to-live expressed in seconds
newtype TTL
TTL :: Int32 -> TTL

-- | DNS CLASS code as per RFC 1035, section 3.2.4
--   
--   The most commonly used value is classIN.
newtype Class
Class :: Word16 -> Class

-- | The Class constant for IN (Internet)
classIN :: Class

-- | Raw DNS record type code
--   
--   See also TypeSym
newtype Type
Type :: Word16 -> Type

-- | Symbolic DNS record type
data TypeSym

-- | RFC 1035
TypeA :: TypeSym

-- | RFC 3596
TypeAAAA :: TypeSym

-- | RFC 1183
TypeAFSDB :: TypeSym

-- | RFC 1035 (query)
TypeANY :: TypeSym

-- | RFC 6844
TypeCAA :: TypeSym

-- | RFC 1035
TypeCNAME :: TypeSym

-- | RFC 4034
TypeDNSKEY :: TypeSym

-- | RFC 4034
TypeDS :: TypeSym

-- | RFC 1035
TypeHINFO :: TypeSym

-- | RFC 1035
TypeMX :: TypeSym

-- | RFC 2915
TypeNAPTR :: TypeSym

-- | RFC 1035
TypeNS :: TypeSym

-- | RFC 4034
TypeNSEC :: TypeSym

-- | RFC 5155
TypeNSEC3 :: TypeSym

-- | RFC 5155
TypeNSEC3PARAM :: TypeSym

-- | RFC 6891 (meta)
TypeOPT :: TypeSym

-- | RFC 1035
TypePTR :: TypeSym

-- | RFC 4034
TypeRRSIG :: TypeSym

-- | RFC 1035
TypeSOA :: TypeSym

-- | RFC 4408
TypeSPF :: TypeSym

-- | RFC 2782
TypeSRV :: TypeSym

-- | RFC 4255
TypeSSHFP :: TypeSym

-- | RFC 1035
TypeTXT :: TypeSym

-- | RFC 7553
TypeURI :: TypeSym

-- | Convert symbolic TypeSym to numeric Type code
typeFromSym :: TypeSym -> Type

-- | Convert Type code to symbolic TypeSym
typeToSym :: Type -> Maybe TypeSym

-- | Represents a DNS message as per RFC 1035
data Msg l
Msg :: !MsgHeader -> [MsgQuestion l] -> [MsgRR l] -> [MsgRR l] -> [MsgRR l] -> Msg l
[msgHeader] :: Msg l -> !MsgHeader
[msgQD] :: Msg l -> [MsgQuestion l]
[msgAN] :: Msg l -> [MsgRR l]
[msgNS] :: Msg l -> [MsgRR l]
[msgAR] :: Msg l -> [MsgRR l]

-- | DNS message header section as per RFC 1035, section 4.1.1
data MsgHeader
MsgHeader :: !Word16 -> !MsgHeaderFlags -> !Word16 -> !Word16 -> !Word16 -> !Word16 -> MsgHeader
[mhId] :: MsgHeader -> !Word16
[mhFlags] :: MsgHeader -> !MsgHeaderFlags
[mhQDCount] :: MsgHeader -> !Word16
[mhANCount] :: MsgHeader -> !Word16
[mhNSCount] :: MsgHeader -> !Word16
[mhARCount] :: MsgHeader -> !Word16

-- | DNS message header flags as per RFC 1035, section 4.1.1
data MsgHeaderFlags
MsgHeaderFlags :: !QR -> !Word8 -> !Bool -> !Bool -> !Bool -> !Bool -> !Bool -> !Bool -> !Bool -> !Word8 -> MsgHeaderFlags
[mhQR] :: MsgHeaderFlags -> !QR
[mhOpcode] :: MsgHeaderFlags -> !Word8
[mhAA] :: MsgHeaderFlags -> !Bool
[mhTC] :: MsgHeaderFlags -> !Bool
[mhRD] :: MsgHeaderFlags -> !Bool
[mhRA] :: MsgHeaderFlags -> !Bool
[mhZ] :: MsgHeaderFlags -> !Bool
[mhAD] :: MsgHeaderFlags -> !Bool
[mhCD] :: MsgHeaderFlags -> !Bool
[mhRCode] :: MsgHeaderFlags -> !Word8

-- | Encodes whether message is a query or a response
data QR
IsQuery :: QR
IsResponse :: QR

-- | DNS message header section as per RFC 1035, section 4.1.2
data MsgQuestion l
MsgQuestion :: !l -> !Type -> !Class -> MsgQuestion l

-- | DNS resource record section as per RFC 1035, section 4.1.3
data MsgRR l
MsgRR :: !l -> !Class -> !TTL -> !RData l -> MsgRR l
[rrName] :: MsgRR l -> !l
[rrClass] :: MsgRR l -> !Class
[rrTTL] :: MsgRR l -> !TTL
[rrData] :: MsgRR l -> !RData l

-- | DNS resource record data (see also MsgRR and TypeSym)
data RData l
RDataA :: !IPv4 -> RData l
RDataAAAA :: !IPv6 -> RData l
RDataCNAME :: !l -> RData l
RDataPTR :: !l -> RData l
RDataHINFO :: !CharStr -> !CharStr -> RData l
RDataNS :: !l -> RData l
RDataMX :: !Word16 -> !l -> RData l
RDataTXT :: ![CharStr] -> RData l
RDataSPF :: ![CharStr] -> RData l
RDataSOA :: !l -> !l -> !Word32 -> !Word32 -> !Word32 -> !Word32 -> !Word32 -> RData l
RDataSRV :: !SRV l -> RData l
RDataAFSDB :: !Word16 -> !l -> RData l
RDataNAPTR :: !Word16 -> !Word16 -> !CharStr -> !CharStr -> !CharStr -> !l -> RData l
RDataURI :: !Word16 -> !Word16 -> !ByteString -> RData l
RDataRRSIG :: !Word16 -> !Word8 -> !Word8 -> !Word32 -> !Word32 -> !Word32 -> !Word16 -> !l -> !ByteString -> RData l
RDataDNSKEY :: !Word16 -> !Word8 -> !Word8 -> !ByteString -> RData l
RDataDS :: !Word16 -> !Word8 -> !Word8 -> !ByteString -> RData l
RDataNSEC :: !l -> !Set Type -> RData l
RDataSSHFP :: !Word8 -> !Word8 -> !ByteString -> RData l
RDataNSEC3PARAM :: !Word8 -> !Word8 -> !Word16 -> !CharStr -> RData l
RDataNSEC3 :: !Word8 -> !Word8 -> !Word16 -> !CharStr -> !CharStr -> !Set Type -> RData l
RDataCAA :: !Word8 -> !CharStr -> !ByteString -> RData l
RDataOPT :: !ByteString -> RData l

-- | Unknown/undecoded resource record type
RData :: !Type -> !ByteString -> RData l

-- | Extract the resource record type of a RData object
rdType :: RData l -> Either Type TypeSym

-- | SRV Record data as per RFC 2782
data SRV l
SRV :: !Word16 -> !Word16 -> !Word16 -> !l -> SRV l
[srvPriority] :: SRV l -> !Word16
[srvWeight] :: SRV l -> !Word16
[srvPort] :: SRV l -> !Word16
[srvTarget] :: SRV l -> !l
instance GHC.Classes.Eq Network.DNS.DnsException
instance GHC.Internal.Exception.Type.Exception Network.DNS.DnsException
instance GHC.Internal.Show.Show Network.DNS.DnsException
