Contributed Logic / file comparison
comparison: opensips/modules/enum/README
opensips/modules/enum/README
- changeset 12
- a3ac912f2857
- child 13
- b63f281afe6b
equal
deleted
inserted
replaced
| -1:000000000000 | 0:e3310cc35ff0 |
|---|---|
| 1 Enum Module | |
| 2 | |
| 3 Juha Heinanen | |
| 4 | |
| 5 <jh@song.fi> | |
| 6 | |
| 7 Otmar Lendl | |
| 8 | |
| 9 <lendl@nic.at> | |
| 10 | |
| 11 Copyright © 2002, 2003 Juha Heinanen | |
| 12 Revision History | |
| 13 Revision $Revision: 5906 $ $Date: 2009-07-21 10:45:05 +0300 | |
| 14 (Tue, 21 Jul 2009) $ | |
| 15 __________________________________________________________ | |
| 16 | |
| 17 Table of Contents | |
| 18 | |
| 19 1. Admin Guide | |
| 20 | |
| 21 1.1. Overview | |
| 22 1.2. Dependencies | |
| 23 1.3. Exported Parameters | |
| 24 | |
| 25 1.3.1. domain_suffix (string) | |
| 26 1.3.2. tel_uri_params (string) | |
| 27 1.3.3. i_enum_suffix (string) | |
| 28 1.3.4. branchlabel (string) | |
| 29 1.3.5. bl_algorithm (string) | |
| 30 | |
| 31 1.4. Exported Functions | |
| 32 | |
| 33 1.4.1. enum_query(["suffix"[,"service"]]) | |
| 34 1.4.2. enum_pv_query("pvar"[,"suffix"[,"service"]]) | |
| 35 1.4.3. i_enum_query(["suffix"[,"service"]]) | |
| 36 1.4.4. is_from_user_enum() | |
| 37 | |
| 38 List of Examples | |
| 39 | |
| 40 1.1. Setting domain_suffix module parameter | |
| 41 1.2. Setting tel_uri_params module parameter | |
| 42 1.3. Setting i_enum_suffix module parameter | |
| 43 1.4. Setting brachlabel module parameter | |
| 44 1.5. Zone file example | |
| 45 1.6. Zone file example | |
| 46 1.7. Setting the bl_algorithm module parameter | |
| 47 1.8. enum_query usage | |
| 48 1.9. enum_pv_query usage | |
| 49 1.10. is_from_user_enum usage | |
| 50 | |
| 51 Chapter 1. Admin Guide | |
| 52 | |
| 53 1.1. Overview | |
| 54 | |
| 55 Enum module implements [i_]enum_query functions that make an | |
| 56 enum query based on the user part of the current Request-URI. | |
| 57 These functions assume that the user part consists of an | |
| 58 international phone number of the form +decimal-digits, where | |
| 59 the number of digits is at least 2 and at most 15. Out of this | |
| 60 number enum_query forms a domain name, where the digits are in | |
| 61 reverse order and separated by dots followed by domain suffix | |
| 62 that by default is "e164.arpa.". For example, if the user part | |
| 63 is +35831234567, the domain name will be | |
| 64 "7.6.5.4.3.2.1.3.8.5.3.e164.arpa.". i_enum_query operates in a | |
| 65 similar fashion. The only difference is that it adds a label | |
| 66 (default "i") to branch off from the default, user-ENUM tree to | |
| 67 an infrastructure ENUM tree. | |
| 68 | |
| 69 After forming the domain name, enum_query queries DNS for its | |
| 70 NAPTR records. From the possible response enum_query chooses | |
| 71 those records, whose flags field has string value "u", and | |
| 72 whose services field has string value "e2u+[service:]sip" or | |
| 73 "e2u+type[:subtype][+type[:subtype]...]" (case is ignored in | |
| 74 both cases), and whose regexp field is of the form | |
| 75 !pattern!replacement!. | |
| 76 | |
| 77 Then enum_query sorts the chosen NAPTR records based on their | |
| 78 <order, preference>. After sorting, enum_query replaces the | |
| 79 current Request URI by applying regexp of the most preferred | |
| 80 NAPTR record its user part and appends to the request new | |
| 81 branches by applying regexp of each remaining NAPTR record to | |
| 82 the user part of the current Request URI. If a new URI is a tel | |
| 83 URI, enum_query appends to it as tel URI parameters the value | |
| 84 of tel_uri_params module parameter. Finally, enum_query | |
| 85 associates a q value with each new URI based on the <order, | |
| 86 preference> of the corresponding NAPTR record. | |
| 87 | |
| 88 When using enum_query without any parameters, it searches for | |
| 89 NAPTRs with service type "e2u+sip" in the default enum tree. | |
| 90 When using enum_query with a single parameter, this parameter | |
| 91 will be used as enum tree. When using enum_query with two | |
| 92 parameters, the functionality depends on the first letter in | |
| 93 the second parameter. When the first letter is not a '+' sign, | |
| 94 the second parameter will be used to search for NAPTRs with | |
| 95 service type "e2u+parameter:sip". When the second parameter | |
| 96 starts with a '+' sign, the ENUM lookup also supports compound | |
| 97 NAPTRs (e.g. "e2u+voice:sip+video:sip") and searching for | |
| 98 multiple service types within one lookup. Multiple service | |
| 99 types must be separeted by a '+' sign. | |
| 100 | |
| 101 Most of the time you want to route based on the RURI. On rare | |
| 102 occasions you may wish to route based on something else. The | |
| 103 function enum_pv_query mimics the behavior of the enum_query | |
| 104 function except the E.164 number in its pseudo variable | |
| 105 argument is used for the enum lookup instead of the user part | |
| 106 of the RURI. Obviously the user part of the RURI is still used | |
| 107 in the NAPTR regexp. | |
| 108 | |
| 109 Enum query returns 1 if the current Request URI was replaced | |
| 110 and -1 if not. | |
| 111 | |
| 112 Enum module also implements is_from_user_enum function. This | |
| 113 function does an enum lookup on the from user and returns true | |
| 114 if found, false otherwise. | |
| 115 | |
| 116 1.2. Dependencies | |
| 117 | |
| 118 The module depends on the following modules (in the other words | |
| 119 the listed modules must be loaded before this module): | |
| 120 * No dependencies. | |
| 121 | |
| 122 1.3. Exported Parameters | |
| 123 | |
| 124 1.3.1. domain_suffix (string) | |
| 125 | |
| 126 The domain suffix to be added to the domain name obtained from | |
| 127 the digits of an E164 number. Can be overridden by a parameter | |
| 128 to enum_query. | |
| 129 | |
| 130 Default value is "e164.arpa." | |
| 131 | |
| 132 Example 1.1. Setting domain_suffix module parameter | |
| 133 modparam("enum", "domain_suffix", "e1234.arpa.") | |
| 134 | |
| 135 1.3.2. tel_uri_params (string) | |
| 136 | |
| 137 A string whose contents is appended to each new tel URI in the | |
| 138 request as tel URI parameters. | |
| 139 | |
| 140 Note | |
| 141 | |
| 142 Currently OpenSIPS does not support tel URIs. This means that | |
| 143 at present tel_uri_params is appended as URI parameters to | |
| 144 every URI. | |
| 145 | |
| 146 Default value is "" | |
| 147 | |
| 148 Example 1.2. Setting tel_uri_params module parameter | |
| 149 modparam("enum", "tel_uri_params", ";npdi") | |
| 150 | |
| 151 1.3.3. i_enum_suffix (string) | |
| 152 | |
| 153 The domain suffix to be used for i_enum_query() lookups. Can be | |
| 154 overridden by a parameter to i_enum_query. | |
| 155 | |
| 156 Default value is "e164.arpa." | |
| 157 | |
| 158 Example 1.3. Setting i_enum_suffix module parameter | |
| 159 modparam("enum", "i_enum_suffix", "e1234.arpa.") | |
| 160 | |
| 161 1.3.4. branchlabel (string) | |
| 162 | |
| 163 This parameter determines which label i_enum_query() will use | |
| 164 to branch off to the infrastructure ENUM tree. | |
| 165 | |
| 166 Default value is ""i"" | |
| 167 | |
| 168 Example 1.4. Setting brachlabel module parameter | |
| 169 modparam("enum", "branchlabel", "i") | |
| 170 | |
| 171 1.3.5. bl_algorithm (string) | |
| 172 | |
| 173 This parameter determines which algorithm i_enum_query() will | |
| 174 use to select the position in the DNS tree where the | |
| 175 infrastructure tree branches off the user ENUM tree. | |
| 176 | |
| 177 If set to "cc", i_enum_query() will always inserts the label at | |
| 178 the country-code level. Examples: i.1.e164.arpa, | |
| 179 i.3.4.e164.arpa, i.2.5.3.e164.arpa | |
| 180 | |
| 181 If set to "txt", i_enum_query() will look for a TXT record at | |
| 182 [branchlabel].[reverse-country-code].[i_enum_suffix] to | |
| 183 indicate after how many digits the label should in inserted. | |
| 184 | |
| 185 Example 1.5. Zone file example | |
| 186 i.1.e164.arpa. IN TXT "4" | |
| 187 9.9.9.8.7.6.5.i.4.3.2.1.e164.arpa. IN NAPTR "NAPTR content for +1 234 5 | |
| 188 678 999" | |
| 189 | |
| 190 If set to "ebl", i_enum_query() will look for an EBL (ENUM | |
| 191 Branch Label) record at | |
| 192 [branchlabel].[reverse-country-code].[i_enum_suffix]. See | |
| 193 http://www.ietf.org/internet-drafts/draft-lendl-enum-branch-loc | |
| 194 ation-record-00.txt for a description of that record and the | |
| 195 meaning of the fields. The RR type for the EBL has not been | |
| 196 allocated yet. This version of the code uses 65300. See | |
| 197 resolve.h. | |
| 198 | |
| 199 Example 1.6. Zone file example | |
| 200 i.1.e164.arpa. TYPE65300 \# 14 ( | |
| 201 04 ; position | |
| 202 01 69 ; separator | |
| 203 04 65 31 36 34 04 61 72 70 61 00 ; e164.ar | |
| 204 pa | |
| 205 ; ) | |
| 206 9.9.9.8.7.6.5.i.4.3.2.1.e164.arpa. IN NAPTR "NAPTR content for +1 234 5 | |
| 207 678 999" | |
| 208 | |
| 209 Default value is "cc" | |
| 210 | |
| 211 Example 1.7. Setting the bl_algorithm module parameter | |
| 212 modparam("enum", "bl_algorithm", "txt") | |
| 213 | |
| 214 1.4. Exported Functions | |
| 215 | |
| 216 1.4.1. enum_query(["suffix"[,"service"]]) | |
| 217 | |
| 218 The function performs an enum query and rewrites the | |
| 219 Request-URI with the result of the query. See Section 1.1, | |
| 220 "Overview" for more information. | |
| 221 | |
| 222 Meaning of the parameters is as follows: | |
| 223 * suffix - Suffix to be appended to the domain name. | |
| 224 * service - Service string to be used in the service field. | |
| 225 | |
| 226 This function can be used from REQUEST_ROUTE. | |
| 227 | |
| 228 Example 1.8. enum_query usage | |
| 229 ... | |
| 230 # search for "e2u+sip" in freenum.org | |
| 231 enum_query("freenum.org."); | |
| 232 ... | |
| 233 # search for "e2u+sip" in default tree (configured as parameter) | |
| 234 enum_query(); | |
| 235 ... | |
| 236 # search for "e2u+voice:sip" in e164.arpa | |
| 237 enum_query("e164.arpa.","voice"); | |
| 238 ... | |
| 239 # search for service type "sip" or "voice:sip" or "video:sip" | |
| 240 # note the '+' sign in front of the second parameter | |
| 241 enum_query("e164.arpa.","+sip+voice:sip+video:sip"); | |
| 242 ... | |
| 243 # quering for service sip and voice:sip | |
| 244 enum_query("e164.arpa."); | |
| 245 enum_query("e164.arpa.","voice"); | |
| 246 # or use instead | |
| 247 enum_query("e164.arpa.","+sip+voice:sip"); | |
| 248 ... | |
| 249 | |
| 250 1.4.2. enum_pv_query("pvar"[,"suffix"[,"service"]]) | |
| 251 | |
| 252 The function performs an enum query on E.164 number stored in | |
| 253 its pseudo variable argument and rewrites the Request-URI with | |
| 254 the result of the query. See Section 1.1, "Overview" for more | |
| 255 information. | |
| 256 | |
| 257 Meaning of the parameters is as follows: | |
| 258 * pvar - Pseudo variable that holds an E.164 number on which | |
| 259 enum query is performed. | |
| 260 * suffix - Suffix to be appended to the domain name. | |
| 261 * service - Service string to be used in the service field. | |
| 262 | |
| 263 This function can be used from REQUEST_ROUTE. | |
| 264 | |
| 265 Example 1.9. enum_pv_query usage | |
| 266 ... | |
| 267 # search for "e2u+sip" in freenum.org | |
| 268 enum_pv_query("$avp(i:100)", "freenum.org."); | |
| 269 ... | |
| 270 # search for "e2u+sip" in default tree (configured as parameter) | |
| 271 enum_pv_query("$fU"); | |
| 272 ... | |
| 273 # search for "e2u+voice:sip" in e164.arpa | |
| 274 enum_pv_query("$avp(i:100)","e164.arpa.","voice"); | |
| 275 ... | |
| 276 # search for service type "sip" or "voice:sip" or "video:sip" | |
| 277 # note the '+' sign in front of the second parameter | |
| 278 enum_pv_query("$fU","e164.arpa.","+sip+voice:sip+video:sip"); | |
| 279 ... | |
| 280 # quering for service sip and voice:sip | |
| 281 enum_pv_query("$avp(i:100)","e164.arpa."); | |
| 282 enum_pv_query("$avp(i:100)","e164.arpa.","voice"); | |
| 283 # or use instead | |
| 284 enum_pv_query("$avp(i:100)","e164.arpa.","+sip+voice:sip"); | |
| 285 ... | |
| 286 | |
| 287 1.4.3. i_enum_query(["suffix"[,"service"]]) | |
| 288 | |
| 289 The function performs an enum query and rewrites the | |
| 290 Request-URI with the result of the query. This the | |
| 291 Infrastructure-ENUM version of enum_query(). The only | |
| 292 difference to enum_query() is in the calculation of the FQDN | |
| 293 where NAPTR records are looked for. | |
| 294 | |
| 295 See | |
| 296 ftp://ftp.rfc-editor.org/in-notes/internet-drafts/draft-haberle | |
| 297 r-carrier-enum-01.txt for the rationale behind this function. | |
| 298 | |
| 299 1.4.4. is_from_user_enum() | |
| 300 | |
| 301 Checks if the user part of from URI is found in an enum lookup. | |
| 302 Returns 1 if yes and -1 if not. | |
| 303 | |
| 304 This function can be used from REQUEST_ROUTE. | |
| 305 | |
| 306 Example 1.10. is_from_user_enum usage | |
| 307 ... | |
| 308 if (is_from_user_enum()) { | |
| 309 .... | |
| 310 }; | |
| 311 ... |
