Merged revisions 56569 via svnmerge from
[asterisk/asterisk.git] / doc / enum.txt
index 7341875..3d3d03b 100644 (file)
@@ -1,5 +1,5 @@
-README.enum
-
+Enum support in the ENUMLOOKUP dialplan function
+------------------------------------------------
 2005-09-06 
 jtodd@loligo.com
 
@@ -26,10 +26,10 @@ 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.
 
-Function: ENUMLOOKUP(<number>[,pointer_type[,options[,zone_suffix]]])
+Function: ENUMLOOKUP(number[|Method-type[|options[|record#[|zone-suffix]]]])
 
-  Performs an ENUM tree lookup on the specified number, method type,
-  and (optionally) ordinal offset, and returns one of four different values:
+  Performs an ENUM tree lookup on the specified number, method type, and
+  ordinal record offset, and returns one of four different values:
 
    1) post-parsed NAPTR of one method (URI) type
    2) count of elements of one method (URI) type
@@ -58,14 +58,15 @@ options = optional specifiers.
     (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.
+
+record# = 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"
  
-zone_suffix = allows customization of the ENUM zone. If no zone_suffix is 
-    given the default zones are taken from enum.conf
+zone_suffix = allows customization of the ENUM zone. Default is e164.arpa.
 
 
 EXAMPLE USES:
@@ -92,46 +93,46 @@ simpler NAPTRs will work just as well.
 
 Example 1: Simplest case, using first SIP return (use all defaults
 except for domain name)
-exten => 100,1,Set(foo=${ENUMLOOKUP(+13015611020,,,loligo.com)})
+exten => 100,1,Set(foo=${ENUMLOOKUP(+13015611020,,,,loligo.com)})
   returns: ${foo}="2203@sip.fox-den.com"
 
 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)
-exten => 100,1,Set(foo=${ENUMLOOKUP(+13015611020,tel,,loligo.com)})
+exten => 100,1,Set(foo=${ENUMLOOKUP(+13015611020,tel,,,loligo.com)})
   returns: ${foo}="+12125551212"
 
 Example 3: How many "sip" pointer type entries are there for this number?
-exten => 100,1,Set(foo=${ENUMLOOKUP(+13015611020,sip,c,loligo.com)})
+exten => 100,1,Set(foo=${ENUMLOOKUP(+13015611020,sip,c,,loligo.com)})
   returns: ${foo}=3
 
 Example 4: For all the "tel" pointer type entries, what is the second
 one in the list? (after sorting by preference)
-exten => 100,1,Set(foo=${ENUMLOOKUP(+13015611020,tel,2,loligo.com)})
+exten => 100,1,Set(foo=${ENUMLOOKUP(+13015611020,tel,,2,loligo.com)})
   returns: ${foo}="+14155551212"
 
 Example 5: How many NAPTRs (tel, sip, mailto, etc.) are in the list for this number?
-exten => 100,1,Set(foo=${ENUMLOOKUP(+13015611020,ALL,c,loligo.com)})
+exten => 100,1,Set(foo=${ENUMLOOKUP(+13015611020,ALL,c,,loligo.com)})
   returns: ${foo}=6
 
 Example 6: Give back the second full URI in the sorted list of all NAPTR URIs:
-exten => 100,1,Set(foo=${ENUMLOOKUP(+13015611020,ALL,2,loligo.com)})
+exten => 100,1,Set(foo=${ENUMLOOKUP(+13015611020,ALL,,2,loligo.com)})
   returns: ${foo}="tel:+14155551212"  [note the "tel:" prefix in the string]
 
-Example 7: Look up first SIP entry for the number in the default zone(s) from enum.conf 
+Example 7: Look up first SIP entry for the number in the e164.arpa zone (all defaults)
 exten => 100,1,Set(foo=${ENUMLOOKUP(+437203001721)})
   returns: ${foo}="enum-test@sip.nemox.net"  [note: this result is
   subject to change as it is "live" DNS and not under my control]
 
 
 Example 8: Look up the ISN mapping in freenum.org alpha test zone
-exten => 100,1,Set(foo=${ENUMLOOKUP(1234*256,,,freenum.org)})
+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]
 
 Example 9: Give back the first SIP pointer for a number in the
 enum.yoydynelabs.com zone (invalid lookup)
-exten => 100,1,Set(foo=${ENUMLOOKUP(1234567890,sip,1,enum.yoyodynelabs.com)})
+exten => 100,1,Set(foo=${ENUMLOOKUP(1234567890,sip,,1,enum.yoyodynelabs.com)})
   returns: ${foo}=""
 
 
@@ -196,12 +197,13 @@ Usage notes and subtle features:
   a result of your query, the function will RANDOMLY select a single
   NAPTR from those equal results.
 
-  g) If a zone is given explicitely the function ignores the settings 
-  in enum.conf as the search zone name is now specified within the function, 
-  and the H323  driver can be chosen by the user via the dialplan. 
+  g) Currently, the function ignores the settings in enum.conf as the
+  search zone name is now specified within the function, and the H323
+  driver can be chosen by the user via the dialplan.  There were no
+  other values in this file, and so it becomes deprecated.
 
   h) The function will digest and return NAPTRs which use older
-  (depricated) style, reversed method strings such as "sip+E2U"
+  (deprecated) style, reversed method strings such as "sip+E2U"
   instead of the more modern "E2U+sip"
 
   i) There is no provision for multi-part methods at this time.  If
@@ -225,8 +227,7 @@ Usage notes and subtle features:
 ==EXAMPLES==
 
 All examples below except where noted use "e164.arpa" as the
-referenced domain, which is the default domain name for ENUMLOOKUP if
-'search => e164.arpa' is set in enum.conf.
+referenced domain, which is the default domain name for ENUMLOOKUP.
 All numbers are assumed to not have a leading "+" as dialed by the
 inbound channel, so that character is added where necessary during
 ENUMLOOKUP function calls.
@@ -240,7 +241,7 @@ ENUMLOOKUP function calls.
 ;  NAPTR(s). 
 ;
 exten => _011.,1,Set(enumresult=${ENUMLOOKUP(+${EXTEN:3})})
-exten => _011.,n,Dial(SIP/${enumlookup})
+exten => _011.,n,Dial(SIP/${enumresult})
 exten => _011.,n,Dial(Zap/g1/${EXTEN})
 ; 
 ; end example 1
@@ -255,7 +256,7 @@ exten => _011.,n,Dial(Zap/g1/${EXTEN})
 exten => _011.,1,Set(sipcount=${ENUMLOOKUP(${EXTEN:3},sip,c)}|counter=0)
 exten => _011.,n,While($["${counter}"<"${sipcount}"])
 exten => _011.,n,Set(counter=$[${counter}+1])
-exten => _011.,n,Dial(SIP/${ENUMLOOKUP(+${EXTEN:3},sip,${counter})})
+exten => _011.,n,Dial(SIP/${ENUMLOOKUP(+${EXTEN:3},sip,,${counter})})
 exten => _011.,n,EndWhile
 exten => _011.,n,Dial(Zap/g1/${EXTEN})
 ;
@@ -271,32 +272,32 @@ exten => _011.,n,Dial(Zap/g1/${EXTEN})
 ;
 ; Start first with e164.arpa zone...
 ;
-exten => _X.,1,Set(sipcount=${ENUMLOOKUP(+${EXTEN},sip,c,e164.arpa)}|counter=0)
+exten => _X.,1,Set(sipcount=${ENUMLOOKUP(+${EXTEN},sip,c)}|counter=0)
 exten => _X.,2,GotoIf($["${counter}"<"${sipcount}"]?3:6)
 exten => _X.,3,Set(counter=$[${counter}+1])
-exten => _X.,4,Dial(SIP/${ENUMLOOKUP(+${EXTEN},sip,${counter},e164.arpa)})
+exten => _X.,4,Dial(SIP/${ENUMLOOKUP(+${EXTEN},sip,,${counter})})
 exten => _X.,5,GotoIf($["${counter}"<"${sipcount}"]?3:6)
 ;
-exten => _X.,6,Set(iaxcount=${ENUMLOOKUP(+${EXTEN},iax2,c,e164.arpa)}|counter=0)
+exten => _X.,6,Set(iaxcount=${ENUMLOOKUP(+${EXTEN},iax2,c)}|counter=0)
 exten => _X.,7,GotoIf($["${counter}"<"${iaxcount}"]?8:11)
 exten => _X.,8,Set(counter=$[${counter}+1])
-exten => _X.,9,Dial(IAX2/${ENUMLOOKUP(+${EXTEN},iax2,${counter},e164.arpa)})
+exten => _X.,9,Dial(IAX2/${ENUMLOOKUP(+${EXTEN},iax2,,${counter})})
 exten => _X.,10,GotoIf($["${counter}"<"${iaxcount}"]?8:11)
 ;
 exten => _X.,11,NoOp("No valid entries in e164.arpa for ${EXTEN} - checking in e164.org")
 ;
 ; ...then also try e164.org, and look for SIP and IAX NAPTRs...
 ;
-exten => _X.,12,Set(sipcount=${ENUMLOOKUP(+${EXTEN},sip,c,e164.org)}|counter=0)
+exten => _X.,12,Set(sipcount=${ENUMLOOKUP(+${EXTEN},sip,c,,e164.org)}|counter=0)
 exten => _X.,13,GotoIf($["${counter}"<"${sipcount}"]?14:17)
 exten => _X.,14,Set(counter=$[${counter}+1])
-exten => _X.,15,Dial(SIP/${ENUMLOOKUP(+${EXTEN},sip,${counter},e164.org)})
+exten => _X.,15,Dial(SIP/${ENUMLOOKUP(+${EXTEN},sip,,${counter},e164.org)})
 exten => _X.,16,GotoIf($["${counter}"<"${sipcount}"]?14:17)
 ;
-exten => _X.,17,Set(iaxcount=${ENUMLOOKUP(+${EXTEN},iax2,c,e164.org)}|counter=0)
+exten => _X.,17,Set(iaxcount=${ENUMLOOKUP(+${EXTEN},iax2,c,,e164.org)}|counter=0)
 exten => _X.,18,GotoIf($["${counter}"<"${iaxcount}"]?19:22)
 exten => _X.,19,Set(counter=$[${counter}+1])
-exten => _X.,20,Dial(IAX2/${ENUMLOOKUP(+${EXTEN},iax2,${counter},e164.org)})
+exten => _X.,20,Dial(IAX2/${ENUMLOOKUP(+${EXTEN},iax2,,${counter},e164.org)})
 exten => _X.,21,GotoIf($["${counter}"<"${iaxcount}"]?19:22)
 ;
 ; ...then send out PRI.
@@ -305,26 +306,3 @@ exten => _X.,22,NoOp("No valid entries in e164.org for ${EXTEN} - sending out vi
 exten => _X.,23,Dial(Zap/g1/${EXTEN})
 ;
 ; end example 3
-
-;
-;
-; An alternative to example 3 would be setting the search zones in enum.conf like
-; search => e164.arpa
-; search => e164.org
-;
-; Start start matching the default zones from configuration:
-exten => _X.,1,Set(sipcount=${ENUMLOOKUP(+${EXTEN},sip,c)}|counter=0)
-exten => _X.,2,GotoIf($["${counter}"<"${sipcount}"]?3:6)
-exten => _X.,3,Set(counter=$[${counter}+1])
-exten => _X.,4,Dial(SIP/${ENUMLOOKUP(+${EXTEN},sip,${counter})})
-exten => _X.,5,GotoIf($["${counter}"<"${sipcount}"]?3:6)
-;
-exten => _X.,6,Set(iaxcount=${ENUMLOOKUP(+${EXTEN},iax2,c)}|counter=0)
-exten => _X.,7,GotoIf($["${counter}"<"${iaxcount}"]?8:11)
-exten => _X.,8,Set(counter=$[${counter}+1])
-exten => _X.,9,Dial(IAX2/${ENUMLOOKUP(+${EXTEN},iax2,${counter})})
-exten => _X.,10,GotoIf($["${counter}"<"${iaxcount}"]?8:11)
-;
-exten => _X.,11,NoOp("No valid entries in default zones from enum.conf for ${EXTEN}")
-;
-