enum.tex

asterisk 是一个很有知名度开源软件

\section{The ENUMLOOKUP dialplan function}

The ENUMLOOKUP function is more complex than it first may appear, and
this guide is to give a general overview and set of examples that may
be well-suited for the advanced user to evaluate in their
consideration of ENUM or ENUM-like lookup strategies.  This document
assumes a familiarity with ENUM (RFC3761) or ENUM-like methods, as
well as familiarity with NAPTR DNS records (RFC2915, RFC3401-3404).
For an overview of NAPTR records, and the use of NAPTRs in the ENUM
global phone-number-to-DNS mapping scheme, please see
\url{http://www.voip-info.org/tiki-index.php?page=ENUM} for more detail.

Using ENUM within Asterisk can be simple or complex, depending on how
many failover methods and redundancy procedures you wish to utilize.
Implementation of ENUM paths is supposedly defined by the person
creating the NAPTR records, but the local administrator may choose to
ignore certain NAPTR response methods (URI types) or prefer some over
others, which is in contradiction to the RFC.  The ENUMLOOKUP method
simply provides administrators a method for determining NAPTR results
in either the globally unique ENUM (e164.arpa) DNS tree, or in other
ENUM-like DNS trees which are not globally unique.  The methods to
actually create channels ("dial") results given by the ENUMLOOKUP
function is then up to the administrator to implement in a way that
best suits their environment.

\begin{verbatim}
Function: ENUMLOOKUP(number[,Method-type[,options[,record#[,zone-suffix]]]])
\end{verbatim}

  Performs an ENUM tree lookup on the specified number, method type, and
  ordinal record offset, and returns one of four different values:

\begin{enumerate}
   \item post-parsed NAPTR of one method (URI) type
   \item count of elements of one method (URI) type
   \item count of all method types
   \item full URI of method at a particular point in the list of all possible methods
\end{enumerate}

\subsection{Arguments}

\begin{itemize}
  \item number
  \begin{itemize}
    \item telephone number or search string.  Only numeric values
    within this string are parsed; all other digits are ignored for
    search, but are re-written during NAPTR regexp expansion.
  \end{itemize}

  \item service\_type
  \begin{itemize}
     \item tel, sip, h323, iax2, mailto, ...[any other string],
     ALL. Default type is "sip".
     Special name of "ALL" will create a list of method types across
     all NAPTR records for the search number, and then put the results
     in an ordinal list starting with 1. The position <number>
     specified will then be returned, starting with 1 as the first
     record (lowest value) in the list.  The service types are not
     hardcoded in Asterisk except for the default (sip) if no other
     service type specified; any method type string (IANA-approved or
     not) may be used except for the string "ALL".
  \end{itemize}

  \item options
  \begin{itemize}
    \item c
    \begin{itemize}
      \item count. Returns the number of records of this type are returned
    (regardless of order or priority.)  If "ALL" is the specified
    service\_type, then a count of all methods will be returned for the
    DNS record.
    \end{itemize}
  \end{itemize}

  \item record\#
  \begin{itemize}
    \item which record to present if multiple answers are returned
    <integer> = The record in priority/order sequence based on the
    total count of records passed back by the query. If a service\_type
    is specified, all entries of that type will be sorted into an
    ordinal list starting with 1 (by order first, then priority).
    The default of <options> is "1"
  \end{itemize}

  \item zone\_suffix
  \begin{itemize}
    \item allows customization of the ENUM zone. Default is e164.arpa.
  \end{itemize}
\end{itemize}

\subsection{Examples}

Let's use this ENUM list as an example (note that these examples exist
in the DNS, and will hopefully remain in place as example
destinations, but they may change or become invalid over time.  The
end result URIs are not guaranteed to actually work, since some of
these hostnames or SIP proxies are imaginary.  Of course, the tel:
replies go to directory assistance for New York City and San
Francisco...)  Also note that the complex SIP NAPTR at weight 30 will
strip off the leading "+" from the dialed string if it exists.  This
is probably a better NAPTR than hard-coding the number into the NAPTR,
and it is included as a more complex regexp example, though other
simpler NAPTRs will work just as well.

\begin{verbatim}
0.2.0.1.1.6.5.1.0.3.1.loligo.com. 3600 IN NAPTR 10 100 "u"
     "E2U+tel" "!^\\[phone]$!tel:[phone]!" .
0.2.0.1.1.6.5.1.0.3.1.loligo.com. 3600 IN NAPTR 21 100 "u"
     "E2U+tel" "!^\\[phone]$!tel:[phone]!" .
0.2.0.1.1.6.5.1.0.3.1.loligo.com. 3600 IN NAPTR 25 100 "u"
     "E2U+sip" "!^\\[phone]$!sip:[e-mail]!" .
0.2.0.1.1.6.5.1.0.3.1.loligo.com. 3600 IN NAPTR 26 100 "u"
     "E2U+sip" "!^\\[phone]$!sip:[e-mail]!" .
0.2.0.1.1.6.5.1.0.3.1.loligo.com. 3600 IN NAPTR 30 100 "u"
     "E2U+sip" "!^\\+*([^\\*]*)!sip:\\[e-mail]!" .
0.2.0.1.1.6.5.1.0.3.1.loligo.com. 3600 IN NAPTR 55 100 "u"
     "E2U+mailto" "!^\\[phone]$!mailto:[e-mail]!" .
\end{verbatim}

Example 1: Simplest case, using first SIP return (use all defaults
except for domain name)
\begin{verbatim}
exten => 100,1,Set(foo=${ENUMLOOKUP([phone],,,,loligo.com)})
  returns: ${foo}="[e-mail]"
\end{verbatim}

Example 2: What is the first "tel" pointer type for this number?
(after sorting by order/preference; default of "1" is assumed in
options field)
\begin{verbatim}
exten => 100,1,Set(foo=${ENUMLOOKUP([phone],tel,,,loligo.com)})
  returns: ${foo}="[phone]"
\end{verbatim}

Example 3: How many "sip" pointer type entries are there for this number?
\begin{verbatim}
exten => 100,1,Set(foo=${ENUMLOOKUP([phone],sip,c,,loligo.com)})
  returns: ${foo}=3
\end{verbatim}

Example 4: For all the "tel" pointer type entries, what is the second
one in the list? (after sorting by preference)
\begin{verbatim}
exten => 100,1,Set(foo=${ENUMLOOKUP([phone],tel,,2,loligo.com)})
  returns: ${foo}="[phone]"
\end{verbatim}

Example 5: How many NAPTRs (tel, sip, mailto, etc.) are in the list for this number?
\begin{verbatim}
exten => 100,1,Set(foo=${ENUMLOOKUP([phone],ALL,c,,loligo.com)})
  returns: ${foo}=6
\end{verbatim}

Example 6: Give back the second full URI in the sorted list of all NAPTR URIs:
\begin{verbatim}
exten => 100,1,Set(foo=${ENUMLOOKUP([phone],ALL,,2,loligo.com)})
  returns: ${foo}="tel:[phone]"  [note the "tel:" prefix in the string]
\end{verbatim}

Example 7: Look up first SIP entry for the number in the e164.arpa zone (all defaults)
\begin{verbatim}
exten => 100,1,Set(foo=${ENUMLOOKUP([phone])})
  returns: ${foo}="[e-mail]"  [note: this result is
  subject to change as it is "live" DNS and not under my control]
\end{verbatim}

Example 8: Look up the ISN mapping in freenum.org alpha test zone
\begin{verbatim}
exten => 100,1,Set(foo=${ENUMLOOKUP(1234*256,,,,freenum.org)})
  returns: ${foo}="1234@204.91.156.10"  [note: this result is subject
  to change as it is "live" DNS]
\end{verbatim}

Example 9: Give back the first SIP pointer for a number in the
\begin{verbatim}
enum.yoydynelabs.com zone (invalid lookup)
exten => 100,1,Set(foo=${ENUMLOOKUP(1234567890,sip,,1,enum.yoyodynelabs.com)})
  returns: ${foo}=""