Doc/libmacdnr.tex

   1
   2 \section{Built-in Module \sectcode{macdnr}}
   3 \bimodindex{macdnr}
   4
   5 This module provides an interface to the Macintosh Domain Name
   6 Resolver.  It is usually used in conjunction with the \var{mactcp}
   7 module, to map hostnames to IP-addresses.  It may not be available in
   8 all Mac Python versions.
   9
  10 The \code{macdnr} module defines the following functions:
  11
  12 \renewcommand{\indexsubitem}{(in module macdnr)}
  13
  14 \begin{funcdesc}{Open}{\optional{filename}}
  15 Open the domain name resolver extension.  If \var{filename} is given it
  16 should be the pathname of the extension, otherwise a default is
  17 used.  Normally, this call is not needed since the other calls will
  18 open the extension automatically.
  19 \end{funcdesc}
  20
  21 \begin{funcdesc}{Close}{}
  22 Close the resolver extension.  Again, not needed for normal use.
  23 \end{funcdesc}
  24
  25 \begin{funcdesc}{StrToAddr}{hostname}
  26 Look up the IP address for \var{hostname}.  This call returns a dnr
  27 result object of the ``address'' variation.
  28 \end{funcdesc}
  29
  30 \begin{funcdesc}{AddrToName}{addr}
  31 Do a reverse lookup on the 32-bit integer IP-address
  32 \var{addr}.  Returns a dnr result object of the ``address'' variation.
  33 \end{funcdesc}
  34
  35 \begin{funcdesc}{AddrToStr}{addr}
  36 Convert the 32-bit integer IP-address \var{addr} to a dotted-decimal
  37 string.  Returns the string.
  38 \end{funcdesc}
  39
  40 \begin{funcdesc}{HInfo}{hostname}
  41 Query the nameservers for a \code{HInfo} record for host
  42 \var{hostname}.  These records contain hardware and software
  43 information about the machine in question (if they are available in
  44 the first place).  Returns a dnr result object of the ``hinfo''
  45 variety.
  46 \end{funcdesc}
  47
  48 \begin{funcdesc}{MXInfo}{domain}
  49 Query the nameservers for a mail exchanger for \var{domain}.  This is
  50 the hostname of a host willing to accept SMTP mail for the given
  51 domain.  Returns a dnr result object of the ``mx'' variety.
  52 \end{funcdesc}
  53
  54 \subsection{dnr result object}
  55
  56 Since the DNR calls all execute asynchronously you do not get the
  57 results back immediately.  Instead, you get a dnr result object.  You
  58 can check this object to see whether the query is complete, and access
  59 its attributes to obtain the information when it is.
  60
  61 Alternatively, you can also reference the result attributes directly,
  62 this will result in an implicit wait for the query to complete.
  63
  64 The \var{rtnCode} and \var{cname} attributes are always available, the
  65 others depend on the type of query (address, hinfo or mx).
  66
  67 \renewcommand{\indexsubitem}{(dnr result object method)}
  68
  69 % Add args, as in {arg1\, arg2 \optional{\, arg3}}
  70 \begin{funcdesc}{wait}{}
  71 Wait for the query to complete.
  72 \end{funcdesc}
  73
  74 % Add args, as in {arg1\, arg2 \optional{\, arg3}}
  75 \begin{funcdesc}{isdone}{}
  76 Return 1 if the query is complete.
  77 \end{funcdesc}
  78
  79 \renewcommand{\indexsubitem}{(dnr result object attribute)}
  80
  81 \begin{datadesc}{rtnCode}
  82 The error code returned by the query.
  83 \end{datadesc}
  84
  85 \begin{datadesc}{cname}
  86 The canonical name of the host that was queried.
  87 \end{datadesc}
  88
  89 \begin{datadesc}{ip0}
  90 \dataline{ip1}
  91 \dataline{ip2}
  92 \dataline{ip3}
  93 At most four integer IP addresses for this host.  Unused entries are
  94 zero.  Valid only for address queries.
  95 \end{datadesc}
  96
  97 \begin{datadesc}{cpuType}
  98 \dataline{osType}
  99 Textual strings giving the machine type an OS name.  Valid for hinfo
 100 queries.
 101 \end{datadesc}
 102
 103 \begin{datadesc}{exchange}
 104 The name of a mail-exchanger host.  Valid for mx queries.
 105 \end{datadesc}
 106
 107 \begin{datadesc}{preference}
 108 The preference of this mx record.  Not too useful, since the Macintosh
 109 will only return a single mx record.  Mx queries only.
 110 \end{datadesc}
 111
 112 The simplest way to use the module to convert names to dotted-decimal
 113 strings, without worrying about idle time, etc:
 114 \begin{verbatim}
 115 >>> def gethostname(name):
 116 ...     import macdnr
 117 ...     dnrr = macdnr.StrToAddr(name)
 118 ...     return macdnr.AddrToStr(dnrr.ip0)
 119 \end{verbatim}