blob: fabe3e160236378744614ed8ca304452b4cdf52b [file] [log] [blame]
Guido van Rossum470be141995-03-17 16:07:09 +00001\section{Built-in Module \sectcode{macdnr}}
Guido van Rossume47da0a1997-07-17 16:34:52 +00002\label{module-macdnr}
Jack Jansenf16d5fa1995-03-02 14:41:55 +00003\bimodindex{macdnr}
4
5This module provides an interface to the Macintosh Domain Name
Guido van Rossum96628a91995-04-10 11:34:00 +00006Resolver. It is usually used in conjunction with the \var{mactcp}
7module, to map hostnames to IP-addresses. It may not be available in
8all Mac Python versions.
Jack Jansenf16d5fa1995-03-02 14:41:55 +00009
10The \code{macdnr} module defines the following functions:
11
Fred Drake19479911998-02-13 06:58:54 +000012\setindexsubitem{(in module macdnr)}
Jack Jansenf16d5fa1995-03-02 14:41:55 +000013
14\begin{funcdesc}{Open}{\optional{filename}}
Guido van Rossum96628a91995-04-10 11:34:00 +000015Open the domain name resolver extension. If \var{filename} is given it
Jack Jansenf16d5fa1995-03-02 14:41:55 +000016should be the pathname of the extension, otherwise a default is
Guido van Rossum96628a91995-04-10 11:34:00 +000017used. Normally, this call is not needed since the other calls will
Jack Jansenf16d5fa1995-03-02 14:41:55 +000018open the extension automatically.
19\end{funcdesc}
20
21\begin{funcdesc}{Close}{}
Guido van Rossum96628a91995-04-10 11:34:00 +000022Close the resolver extension. Again, not needed for normal use.
Jack Jansenf16d5fa1995-03-02 14:41:55 +000023\end{funcdesc}
24
25\begin{funcdesc}{StrToAddr}{hostname}
Guido van Rossum96628a91995-04-10 11:34:00 +000026Look up the IP address for \var{hostname}. This call returns a dnr
Jack Jansenf16d5fa1995-03-02 14:41:55 +000027result object of the ``address'' variation.
28\end{funcdesc}
29
30\begin{funcdesc}{AddrToName}{addr}
31Do a reverse lookup on the 32-bit integer IP-address
Guido van Rossum96628a91995-04-10 11:34:00 +000032\var{addr}. Returns a dnr result object of the ``address'' variation.
Jack Jansenf16d5fa1995-03-02 14:41:55 +000033\end{funcdesc}
34
35\begin{funcdesc}{AddrToStr}{addr}
36Convert the 32-bit integer IP-address \var{addr} to a dotted-decimal
Guido van Rossum96628a91995-04-10 11:34:00 +000037string. Returns the string.
Jack Jansenf16d5fa1995-03-02 14:41:55 +000038\end{funcdesc}
39
40\begin{funcdesc}{HInfo}{hostname}
41Query the nameservers for a \code{HInfo} record for host
Guido van Rossum96628a91995-04-10 11:34:00 +000042\var{hostname}. These records contain hardware and software
Jack Jansenf16d5fa1995-03-02 14:41:55 +000043information about the machine in question (if they are available in
Guido van Rossum96628a91995-04-10 11:34:00 +000044the first place). Returns a dnr result object of the ``hinfo''
Jack Jansenf16d5fa1995-03-02 14:41:55 +000045variety.
46\end{funcdesc}
47
48\begin{funcdesc}{MXInfo}{domain}
Guido van Rossum96628a91995-04-10 11:34:00 +000049Query the nameservers for a mail exchanger for \var{domain}. This is
Jack Jansenf16d5fa1995-03-02 14:41:55 +000050the hostname of a host willing to accept SMTP mail for the given
Guido van Rossum96628a91995-04-10 11:34:00 +000051domain. Returns a dnr result object of the ``mx'' variety.
Jack Jansenf16d5fa1995-03-02 14:41:55 +000052\end{funcdesc}
53
54\subsection{dnr result object}
55
56Since the DNR calls all execute asynchronously you do not get the
Guido van Rossum96628a91995-04-10 11:34:00 +000057results back immediately. Instead, you get a dnr result object. You
Jack Jansenf16d5fa1995-03-02 14:41:55 +000058can check this object to see whether the query is complete, and access
59its attributes to obtain the information when it is.
60
61Alternatively, you can also reference the result attributes directly,
62this will result in an implicit wait for the query to complete.
63
64The \var{rtnCode} and \var{cname} attributes are always available, the
65others depend on the type of query (address, hinfo or mx).
66
Fred Drake19479911998-02-13 06:58:54 +000067\setindexsubitem{(dnr result object method)}
Jack Jansenf16d5fa1995-03-02 14:41:55 +000068
69% Add args, as in {arg1\, arg2 \optional{\, arg3}}
70\begin{funcdesc}{wait}{}
71Wait for the query to complete.
72\end{funcdesc}
73
74% Add args, as in {arg1\, arg2 \optional{\, arg3}}
75\begin{funcdesc}{isdone}{}
76Return 1 if the query is complete.
77\end{funcdesc}
78
Fred Drake19479911998-02-13 06:58:54 +000079\setindexsubitem{(dnr result object attribute)}
Guido van Rossum470be141995-03-17 16:07:09 +000080
Jack Jansenf16d5fa1995-03-02 14:41:55 +000081\begin{datadesc}{rtnCode}
82The error code returned by the query.
83\end{datadesc}
84
85\begin{datadesc}{cname}
86The 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}
Guido van Rossum96628a91995-04-10 11:34:00 +000093At most four integer IP addresses for this host. Unused entries are
94zero. Valid only for address queries.
Jack Jansenf16d5fa1995-03-02 14:41:55 +000095\end{datadesc}
96
97\begin{datadesc}{cpuType}
98\dataline{osType}
Guido van Rossum96628a91995-04-10 11:34:00 +000099Textual strings giving the machine type an OS name. Valid for hinfo
Jack Jansenf16d5fa1995-03-02 14:41:55 +0000100queries.
101\end{datadesc}
102
103\begin{datadesc}{exchange}
Guido van Rossum96628a91995-04-10 11:34:00 +0000104The name of a mail-exchanger host. Valid for mx queries.
Jack Jansenf16d5fa1995-03-02 14:41:55 +0000105\end{datadesc}
106
107\begin{datadesc}{preference}
Guido van Rossum96628a91995-04-10 11:34:00 +0000108The preference of this mx record. Not too useful, since the Macintosh
109will only return a single mx record. Mx queries only.
Jack Jansenf16d5fa1995-03-02 14:41:55 +0000110\end{datadesc}
111
112The simplest way to use the module to convert names to dotted-decimal
113strings, without worrying about idle time, etc:
Fred Drake19479911998-02-13 06:58:54 +0000114\begin{verbatim}
Jack Jansenf16d5fa1995-03-02 14:41:55 +0000115>>> def gethostname(name):
116... import macdnr
117... dnrr = macdnr.StrToAddr(name)
118... return macdnr.AddrToStr(dnrr.ip0)
Fred Drake19479911998-02-13 06:58:54 +0000119\end{verbatim}