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


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

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

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

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

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

-- | Query <tt>TXT</tt> records (see <a>RFC 1035, section 3.3.14</a>).
--   
--   <pre>
--   &gt;&gt;&gt; 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/"])]
--   </pre>
queryTXT :: Name -> IO [(TTL, [CharStr])]

-- | Send a query via <tt>res_query(3)</tt> and decode its response into a
--   <a>Msg</a>
--   
--   Throws <a>DnsException</a> in case of encoding or decoding errors. May
--   throw other IO exceptions in case of network errors.
--   
--   <h3>Example</h3>
--   
--   <pre>
--   &gt;&gt;&gt; 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 ""}]
--         })
--   </pre>
query :: IsLabels n => Class -> n -> TypeSym -> IO (Msg n)

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

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

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

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

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

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

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

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

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

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

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

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

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

-- | <tt>&lt;character-string&gt;</tt> as per <a>RFC 1035, section 3.3</a>.
--   
--   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.
--   <tt>127.0.0.1</tt> is represented as <tt>(IPv4 0x7f000001)</tt>.
data IPv4
IPv4 :: !Word32 -> IPv4

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

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

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

-- | The <a>Class</a> constant for <tt>IN</tt> (Internet)
classIN :: Class

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

-- | Symbolic DNS record type
data TypeSym

-- | <a>RFC 1035</a>
TypeA :: TypeSym

-- | <a>RFC 3596</a>
TypeAAAA :: TypeSym

-- | <a>RFC 1183</a>
TypeAFSDB :: TypeSym

-- | <a>RFC 1035</a> (query)
TypeANY :: TypeSym

-- | <a>RFC 6844</a>
TypeCAA :: TypeSym

-- | <a>RFC 1035</a>
TypeCNAME :: TypeSym

-- | <a>RFC 4034</a>
TypeDNSKEY :: TypeSym

-- | <a>RFC 4034</a>
TypeDS :: TypeSym

-- | <a>RFC 1035</a>
TypeHINFO :: TypeSym

-- | <a>RFC 1035</a>
TypeMX :: TypeSym

-- | <a>RFC 2915</a>
TypeNAPTR :: TypeSym

-- | <a>RFC 1035</a>
TypeNS :: TypeSym

-- | <a>RFC 4034</a>
TypeNSEC :: TypeSym

-- | <a>RFC 5155</a>
TypeNSEC3 :: TypeSym

-- | <a>RFC 5155</a>
TypeNSEC3PARAM :: TypeSym

-- | <a>RFC 6891</a> (meta)
TypeOPT :: TypeSym

-- | <a>RFC 1035</a>
TypePTR :: TypeSym

-- | <a>RFC 4034</a>
TypeRRSIG :: TypeSym

-- | <a>RFC 1035</a>
TypeSOA :: TypeSym

-- | <a>RFC 4408</a>
TypeSPF :: TypeSym

-- | <a>RFC 2782</a>
TypeSRV :: TypeSym

-- | <a>RFC 4255</a>
TypeSSHFP :: TypeSym

-- | <a>RFC 1035</a>
TypeTXT :: TypeSym

-- | <a>RFC 7553</a>
TypeURI :: TypeSym

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

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

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

-- | DNS message header section as per <a>RFC 1035, section 4.1.1</a>
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 <a>RFC 1035, section 4.1.1</a>
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 <a>RFC 1035, section 4.1.2</a>
data MsgQuestion l
MsgQuestion :: !l -> !Type -> !Class -> MsgQuestion l

-- | DNS resource record section as per <a>RFC 1035, section 4.1.3</a>
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 <a>MsgRR</a> and <a>TypeSym</a>)
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 <a>RData</a> object
rdType :: RData l -> Either Type TypeSym

-- | <tt>SRV</tt> Record data as per <a>RFC 2782</a>
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.Show.Show Network.DNS.DnsException
instance GHC.Exception.Type.Exception Network.DNS.DnsException
