update enum documentation to reflect recent changes to the ENUMLOOKUP function (issue #6513)

git-svn-id: http://svn.digium.com/svn/asterisk/trunk@14053 f38db490-d61c-443f-a65b-d21fe96a405b

1 files changed, 20 insertions, 18 deletions

diff --git a/doc/enum.txt b/doc/enum.txt
index 59fbd5d7b..ea09111f1 100644
--- a/doc/enum.txt
+++ b/doc/enum.txt
@@ -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,6 +58,8 @@ 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
@@ -91,30 +93,30 @@ 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 e164.arpa zone (all defaults)
@@ -124,13 +126,13 @@ exten => 100,1,Set(foo=${ENUMLOOKUP(+437203001721)})
 
 
 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}=""
 
 
@@ -254,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})
 ;
@@ -273,29 +275,29 @@ exten => _011.,n,Dial(Zap/g1/${EXTEN})
 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.,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.,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.