VCardConfig.java revision 36ba003879c5583609af3afcec8df22f51d94cd3
1/* 2 * Copyright (C) 2009 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16package com.android.vcard; 17 18import android.telephony.PhoneNumberUtils; 19import android.util.Log; 20 21import java.util.HashMap; 22import java.util.HashSet; 23import java.util.Map; 24import java.util.Set; 25 26/** 27 * The class representing VCard related configurations. Useful static methods are not in this class 28 * but in VCardUtils. 29 */ 30public class VCardConfig { 31 private static final String LOG_TAG = "VCardConfig"; 32 33 /* package */ static final int LOG_LEVEL_NONE = 0; 34 /* package */ static final int LOG_LEVEL_PERFORMANCE_MEASUREMENT = 0x1; 35 /* package */ static final int LOG_LEVEL_SHOW_WARNING = 0x2; 36 /* package */ static final int LOG_LEVEL_VERBOSE = 37 LOG_LEVEL_PERFORMANCE_MEASUREMENT | LOG_LEVEL_SHOW_WARNING; 38 39 /* package */ static final int LOG_LEVEL = LOG_LEVEL_NONE; 40 41 /** 42 * <p> 43 * The charset used during import. 44 * </p> 45 * <p> 46 * We cannot determine which charset should be used to interpret lines in vCard, 47 * while Java requires us to specify it when InputStream is used. 48 * We need to rely on the mechanism due to some performance reason. 49 * </p> 50 * <p> 51 * In order to avoid "misinterpretation" of charset and lose any data in vCard, 52 * "ISO-8859-1" is first used for reading the stream. 53 * When a charset is specified in a property (with "CHARSET=..." parameter), 54 * the string is decoded to raw bytes and encoded into the specific charset, 55 * </p> 56 * <p> 57 * Unicode specification there's a one to one mapping between each byte in ISO-8859-1 58 * and a codepoint, and Java specification requires runtime must have the charset. 59 * Thus, ISO-8859-1 is one effective mapping for intermediate mapping. 60 * </p> 61 */ 62 public static final String DEFAULT_INTERMEDIATE_CHARSET = "ISO-8859-1"; 63 64 /** 65 * The charset used when there's no information affbout what charset should be used to 66 * encode the binary given from vCard. 67 */ 68 public static final String DEFAULT_IMPORT_CHARSET = "UTF-8"; 69 public static final String DEFAULT_EXPORT_CHARSET = "UTF-8"; 70 71 /** 72 * Do not use statically like "version == VERSION_V21" 73 */ 74 public static final int VERSION_21 = 0; 75 public static final int VERSION_30 = 1; 76 public static final int VERSION_40 = 2; 77 public static final int VERSION_MASK = 3; 78 79 public static final int NAME_ORDER_DEFAULT = 0; 80 public static final int NAME_ORDER_EUROPE = 0x4; 81 public static final int NAME_ORDER_JAPANESE = 0x8; 82 private static final int NAME_ORDER_MASK = 0xC; 83 84 // 0x10 is reserved for safety 85 86 /** 87 * <p> 88 * The flag indicating the vCard composer will add some "X-" properties used only in Android 89 * when the formal vCard specification does not have appropriate fields for that data. 90 * </p> 91 * <p> 92 * For example, Android accepts nickname information while vCard 2.1 does not. 93 * When this flag is on, vCard composer emits alternative "X-" property (like "X-NICKNAME") 94 * instead of just dropping it. 95 * </p> 96 * <p> 97 * vCard parser code automatically parses the field emitted even when this flag is off. 98 * </p> 99 */ 100 private static final int FLAG_USE_ANDROID_PROPERTY = 0x80000000; 101 102 /** 103 * <p> 104 * The flag indicating the vCard composer will add some "X-" properties seen in the 105 * vCard data emitted by the other softwares/devices when the formal vCard specification 106 * does not have appropriate field(s) for that data. 107 * </p> 108 * <p> 109 * One example is X-PHONETIC-FIRST-NAME/X-PHONETIC-MIDDLE-NAME/X-PHONETIC-LAST-NAME, which are 110 * for phonetic name (how the name is pronounced), seen in the vCard emitted by some other 111 * non-Android devices/softwares. We chose to enable the vCard composer to use those 112 * defact properties since they are also useful for Android devices. 113 * </p> 114 * <p> 115 * Note for developers: only "X-" properties should be added with this flag. vCard 2.1/3.0 116 * allows any kind of "X-" properties but does not allow non-"X-" properties (except IANA tokens 117 * in vCard 3.0). Some external parsers may get confused with non-valid, non-"X-" properties. 118 * </p> 119 */ 120 private static final int FLAG_USE_DEFACT_PROPERTY = 0x40000000; 121 122 /** 123 * <p> 124 * The flag indicating some specific dialect seen in vCard of DoCoMo (one of Japanese 125 * mobile careers) should be used. This flag does not include any other information like 126 * that "the vCard is for Japanese". So it is "possible" that "the vCard should have DoCoMo's 127 * dialect but the name order should be European", but it is not recommended. 128 * </p> 129 */ 130 private static final int FLAG_DOCOMO = 0x20000000; 131 132 /** 133 * <p> 134 * The flag indicating the vCard composer does "NOT" use Quoted-Printable toward "primary" 135 * properties even though it is required by vCard 2.1 (QP is prohibited in vCard 3.0). 136 * </p> 137 * <p> 138 * We actually cannot define what is the "primary" property. Note that this is NOT defined 139 * in vCard specification either. Also be aware that it is NOT related to "primary" notion 140 * used in {@link android.provider.ContactsContract}. 141 * This notion is just for vCard composition in Android. 142 * </p> 143 * <p> 144 * We added this Android-specific notion since some (incomplete) vCard exporters for vCard 2.1 145 * do NOT use Quoted-Printable encoding toward some properties related names like "N", "FN", etc. 146 * even when their values contain non-ascii or/and CR/LF, while they use the encoding in the 147 * other properties like "ADR", "ORG", etc. 148 * <p> 149 * We are afraid of the case where some vCard importer also forget handling QP presuming QP is 150 * not used in such fields. 151 * </p> 152 * <p> 153 * This flag is useful when some target importer you are going to focus on does not accept 154 * such properties with Quoted-Printable encoding. 155 * </p> 156 * <p> 157 * Again, we should not use this flag at all for complying vCard 2.1 spec. 158 * </p> 159 * <p> 160 * In vCard 3.0, Quoted-Printable is explicitly "prohibitted", so we don't need to care this 161 * kind of problem (hopefully). 162 * </p> 163 * @hide 164 */ 165 public static final int FLAG_REFRAIN_QP_TO_NAME_PROPERTIES = 0x10000000; 166 167 /** 168 * <p> 169 * The flag indicating that phonetic name related fields must be converted to 170 * appropriate form. Note that "appropriate" is not defined in any vCard specification. 171 * This is Android-specific. 172 * </p> 173 * <p> 174 * One typical (and currently sole) example where we need this flag is the time when 175 * we need to emit Japanese phonetic names into vCard entries. The property values 176 * should be encoded into half-width katakana when the target importer is Japanese mobile 177 * phones', which are probably not able to parse full-width hiragana/katakana for 178 * historical reasons, while the vCard importers embedded to softwares for PC should be 179 * able to parse them as we expect. 180 * </p> 181 */ 182 public static final int FLAG_CONVERT_PHONETIC_NAME_STRINGS = 0x08000000; 183 184 /** 185 * <p> 186 * The flag indicating the vCard composer "for 2.1" emits "TYPE=" string toward TYPE params 187 * every time possible. The default behavior does not emit it and is valid in the spec. 188 * In vCrad 3.0, this flag is unnecessary, since "TYPE=" is MUST in vCard 3.0 specification. 189 * </p> 190 * <p> 191 * Detail: 192 * How more than one TYPE fields are expressed is different between vCard 2.1 and vCard 3.0. 193 * </p> 194 * <p> 195 * e.g. 196 * </p> 197 * <ol> 198 * <li>Probably valid in both vCard 2.1 and vCard 3.0: "ADR;TYPE=DOM;TYPE=HOME:..."</li> 199 * <li>Valid in vCard 2.1 but not in vCard 3.0: "ADR;DOM;HOME:..."</li> 200 * <li>Valid in vCard 3.0 but not in vCard 2.1: "ADR;TYPE=DOM,HOME:..."</li> 201 * </ol> 202 * <p> 203 * If you are targeting to the importer which cannot accept TYPE params without "TYPE=" 204 * strings (which should be rare though), please use this flag. 205 * </p> 206 * <p> 207 * Example usage: 208 * <pre class="prettyprint">int type = (VCARD_TYPE_V21_GENERIC | FLAG_APPEND_TYPE_PARAM);</pre> 209 * </p> 210 */ 211 public static final int FLAG_APPEND_TYPE_PARAM = 0x04000000; 212 213 /** 214 * <p> 215 * The flag indicating the vCard composer does touch nothing toward phone number Strings 216 * but leave it as is. 217 * </p> 218 * <p> 219 * The vCard specifications mention nothing toward phone numbers, while some devices 220 * do (wrongly, but with innevitable reasons). 221 * For example, there's a possibility Japanese mobile phones are expected to have 222 * just numbers, hypens, plus, etc. but not usual alphabets, while US mobile phones 223 * should get such characters. To make exported vCard simple for external parsers, 224 * we have used {@link PhoneNumberUtils#formatNumber(String)} during export, and 225 * removed unnecessary characters inside the number (e.g. "111-222-3333 (Miami)" 226 * becomes "111-222-3333"). 227 * Unfortunate side effect of that use was some control characters used in the other 228 * areas may be badly affected by the formatting. 229 * </p> 230 * <p> 231 * This flag disables that formatting, affecting both importer and exporter. 232 * If the user is aware of some side effects due to the implicit formatting, use this flag. 233 * </p> 234 */ 235 public static final int FLAG_REFRAIN_PHONE_NUMBER_FORMATTING = 0x02000000; 236 237 /** 238 * <p> 239 * For importer only. Ignored in exporter. 240 * </p> 241 * <p> 242 * The flag indicating the parser should handle a nested vCard, in which vCard clause starts 243 * in another vCard clause. Here's a typical example. 244 * </p> 245 * <pre class="prettyprint">BEGIN:VCARD 246 * BEGIN:VCARD 247 * VERSION:2.1 248 * ... 249 * END:VCARD 250 * END:VCARD</pre> 251 * <p> 252 * The vCard 2.1 specification allows the nest, but also let parsers ignore nested entries, 253 * while some mobile devices emit nested ones as primary data to be imported. 254 * </p> 255 * <p> 256 * This flag forces a vCard parser to torelate such a nest and understand its content. 257 * </p> 258 */ 259 public static final int FLAG_TORELATE_NEST = 0x01000000; 260 261 //// The followings are VCard types available from importer/exporter. //// 262 263 /** 264 * <p> 265 * The type indicating nothing. Used by {@link VCardSourceDetector} when it 266 * was not able to guess the exact vCard type. 267 * </p> 268 */ 269 public static final int VCARD_TYPE_UNKNOWN = 0; 270 271 /** 272 * <p> 273 * Generic vCard format with the vCard 2.1. When composing a vCard entry, 274 * the US convension will be used toward formatting some values. 275 * </p> 276 * <p> 277 * e.g. The order of the display name would be "Prefix Given Middle Family Suffix", 278 * while it should be "Prefix Family Middle Given Suffix" in Japan for example. 279 * </p> 280 * <p> 281 * Uses UTF-8 for the charset as a charset for exporting. Note that old vCard importer 282 * outside Android cannot accept it since vCard 2.1 specifically does not allow 283 * that charset, while we need to use it to support various languages around the world. 284 * </p> 285 * <p> 286 * If you want to use alternative charset, you should notify the charset to the other 287 * compontent to be used. 288 * </p> 289 */ 290 public static final int VCARD_TYPE_V21_GENERIC = 291 (VERSION_21 | NAME_ORDER_DEFAULT | FLAG_USE_DEFACT_PROPERTY | FLAG_USE_ANDROID_PROPERTY); 292 293 /* package */ static String VCARD_TYPE_V21_GENERIC_STR = "v21_generic"; 294 295 /** 296 * <p> 297 * General vCard format with the version 3.0. Uses UTF-8 for the charset. 298 * </p> 299 * <p> 300 * Not fully ready yet. Use with caution when you use this. 301 * </p> 302 */ 303 public static final int VCARD_TYPE_V30_GENERIC = 304 (VERSION_30 | NAME_ORDER_DEFAULT | FLAG_USE_DEFACT_PROPERTY | FLAG_USE_ANDROID_PROPERTY); 305 306 /* package */ static final String VCARD_TYPE_V30_GENERIC_STR = "v30_generic"; 307 308 /** 309 * General vCard format with the version 4.0. 310 * @hide vCard 4.0 is not published yet. 311 */ 312 public static final int VCARD_TYPE_V40_GENERIC = 313 (VERSION_40 | NAME_ORDER_DEFAULT | FLAG_USE_DEFACT_PROPERTY | FLAG_USE_ANDROID_PROPERTY); 314 315 /* package */ static final String VCARD_TYPE_V40_GENERIC_STR = "v40_generic"; 316 317 /** 318 * <p> 319 * General vCard format for the vCard 2.1 with some Europe convension. Uses Utf-8. 320 * Currently, only name order is considered ("Prefix Middle Given Family Suffix") 321 * </p> 322 */ 323 public static final int VCARD_TYPE_V21_EUROPE = 324 (VERSION_21 | NAME_ORDER_EUROPE | FLAG_USE_DEFACT_PROPERTY | FLAG_USE_ANDROID_PROPERTY); 325 326 /* package */ static final String VCARD_TYPE_V21_EUROPE_STR = "v21_europe"; 327 328 /** 329 * <p> 330 * General vCard format with the version 3.0 with some Europe convension. Uses UTF-8. 331 * </p> 332 * <p> 333 * Not ready yet. Use with caution when you use this. 334 * </p> 335 */ 336 public static final int VCARD_TYPE_V30_EUROPE = 337 (VERSION_30 | NAME_ORDER_EUROPE | FLAG_USE_DEFACT_PROPERTY | FLAG_USE_ANDROID_PROPERTY); 338 339 /* package */ static final String VCARD_TYPE_V30_EUROPE_STR = "v30_europe"; 340 341 /** 342 * <p> 343 * The vCard 2.1 format for miscellaneous Japanese devices, using UTF-8 as default charset. 344 * </p> 345 * <p> 346 * Not ready yet. Use with caution when you use this. 347 * </p> 348 */ 349 public static final int VCARD_TYPE_V21_JAPANESE = 350 (VERSION_21 | NAME_ORDER_JAPANESE | FLAG_USE_DEFACT_PROPERTY | FLAG_USE_ANDROID_PROPERTY); 351 352 /* package */ static final String VCARD_TYPE_V21_JAPANESE_STR = "v21_japanese_utf8"; 353 354 /** 355 * <p> 356 * The vCard 3.0 format for miscellaneous Japanese devices, using UTF-8 as default charset. 357 * </p> 358 * <p> 359 * Not ready yet. Use with caution when you use this. 360 * </p> 361 */ 362 public static final int VCARD_TYPE_V30_JAPANESE = 363 (VERSION_30 | NAME_ORDER_JAPANESE | FLAG_USE_DEFACT_PROPERTY | FLAG_USE_ANDROID_PROPERTY); 364 365 /* package */ static final String VCARD_TYPE_V30_JAPANESE_STR = "v30_japanese_utf8"; 366 367 /** 368 * <p> 369 * The vCard 2.1 based format which (partially) considers the convention in Japanese 370 * mobile phones, where phonetic names are translated to half-width katakana if 371 * possible, etc. It would be better to use Shift_JIS as a charset for maximum 372 * compatibility. 373 * </p> 374 * @hide Should not be available world wide. 375 */ 376 public static final int VCARD_TYPE_V21_JAPANESE_MOBILE = 377 (VERSION_21 | NAME_ORDER_JAPANESE | 378 FLAG_CONVERT_PHONETIC_NAME_STRINGS | FLAG_REFRAIN_QP_TO_NAME_PROPERTIES); 379 380 /* package */ static final String VCARD_TYPE_V21_JAPANESE_MOBILE_STR = "v21_japanese_mobile"; 381 382 /** 383 * <p> 384 * The vCard format used in DoCoMo, which is one of Japanese mobile phone careers. 385 * </p> 386 * <p> 387 * Base version is vCard 2.1, but the data has several DoCoMo-specific convensions. 388 * No Android-specific property nor defact property is included. The "Primary" properties 389 * are NOT encoded to Quoted-Printable. 390 * </p> 391 * @hide Should not be available world wide. 392 */ 393 public static final int VCARD_TYPE_DOCOMO = 394 (VCARD_TYPE_V21_JAPANESE_MOBILE | FLAG_DOCOMO); 395 396 /* package */ static final String VCARD_TYPE_DOCOMO_STR = "docomo"; 397 398 public static int VCARD_TYPE_DEFAULT = VCARD_TYPE_V21_GENERIC; 399 400 private static final Map<String, Integer> sVCardTypeMap; 401 private static final Set<Integer> sJapaneseMobileTypeSet; 402 403 static { 404 sVCardTypeMap = new HashMap<String, Integer>(); 405 sVCardTypeMap.put(VCARD_TYPE_V21_GENERIC_STR, VCARD_TYPE_V21_GENERIC); 406 sVCardTypeMap.put(VCARD_TYPE_V30_GENERIC_STR, VCARD_TYPE_V30_GENERIC); 407 sVCardTypeMap.put(VCARD_TYPE_V21_EUROPE_STR, VCARD_TYPE_V21_EUROPE); 408 sVCardTypeMap.put(VCARD_TYPE_V30_EUROPE_STR, VCARD_TYPE_V30_EUROPE); 409 sVCardTypeMap.put(VCARD_TYPE_V21_JAPANESE_STR, VCARD_TYPE_V21_JAPANESE); 410 sVCardTypeMap.put(VCARD_TYPE_V30_JAPANESE_STR, VCARD_TYPE_V30_JAPANESE); 411 sVCardTypeMap.put(VCARD_TYPE_V21_JAPANESE_MOBILE_STR, VCARD_TYPE_V21_JAPANESE_MOBILE); 412 sVCardTypeMap.put(VCARD_TYPE_DOCOMO_STR, VCARD_TYPE_DOCOMO); 413 414 sJapaneseMobileTypeSet = new HashSet<Integer>(); 415 sJapaneseMobileTypeSet.add(VCARD_TYPE_V21_JAPANESE); 416 sJapaneseMobileTypeSet.add(VCARD_TYPE_V30_JAPANESE); 417 sJapaneseMobileTypeSet.add(VCARD_TYPE_V21_JAPANESE_MOBILE); 418 sJapaneseMobileTypeSet.add(VCARD_TYPE_DOCOMO); 419 } 420 421 public static int getVCardTypeFromString(final String vcardTypeString) { 422 final String loweredKey = vcardTypeString.toLowerCase(); 423 if (sVCardTypeMap.containsKey(loweredKey)) { 424 return sVCardTypeMap.get(loweredKey); 425 } else if ("default".equalsIgnoreCase(vcardTypeString)) { 426 return VCARD_TYPE_DEFAULT; 427 } else { 428 Log.e(LOG_TAG, "Unknown vCard type String: \"" + vcardTypeString + "\""); 429 return VCARD_TYPE_DEFAULT; 430 } 431 } 432 433 public static boolean isVersion21(final int vcardType) { 434 return (vcardType & VERSION_MASK) == VERSION_21; 435 } 436 437 public static boolean isVersion30(final int vcardType) { 438 return (vcardType & VERSION_MASK) == VERSION_30; 439 } 440 441 public static boolean isVersion40(final int vcardType) { 442 return (vcardType & VERSION_MASK) == VERSION_40; 443 } 444 445 public static boolean shouldUseQuotedPrintable(final int vcardType) { 446 return !isVersion30(vcardType); 447 } 448 449 public static int getNameOrderType(final int vcardType) { 450 return vcardType & NAME_ORDER_MASK; 451 } 452 453 public static boolean usesAndroidSpecificProperty(final int vcardType) { 454 return ((vcardType & FLAG_USE_ANDROID_PROPERTY) != 0); 455 } 456 457 public static boolean usesDefactProperty(final int vcardType) { 458 return ((vcardType & FLAG_USE_DEFACT_PROPERTY) != 0); 459 } 460 461 public static boolean showPerformanceLog() { 462 return (VCardConfig.LOG_LEVEL & VCardConfig.LOG_LEVEL_PERFORMANCE_MEASUREMENT) != 0; 463 } 464 465 public static boolean shouldRefrainQPToNameProperties(final int vcardType) { 466 return (!shouldUseQuotedPrintable(vcardType) || 467 ((vcardType & FLAG_REFRAIN_QP_TO_NAME_PROPERTIES) != 0)); 468 } 469 470 public static boolean appendTypeParamName(final int vcardType) { 471 return (isVersion30(vcardType) || ((vcardType & FLAG_APPEND_TYPE_PARAM) != 0)); 472 } 473 474 /** 475 * @return true if the device is Japanese and some Japanese convension is 476 * applied to creating "formatted" something like FORMATTED_ADDRESS. 477 */ 478 public static boolean isJapaneseDevice(final int vcardType) { 479 // TODO: Some mask will be required so that this method wrongly interpret 480 // Japanese"-like" vCard type. 481 // e.g. VCARD_TYPE_V21_JAPANESE_SJIS | FLAG_APPEND_TYPE_PARAMS 482 return sJapaneseMobileTypeSet.contains(vcardType); 483 } 484 485 /* package */ static boolean refrainPhoneNumberFormatting(final int vcardType) { 486 return ((vcardType & FLAG_REFRAIN_PHONE_NUMBER_FORMATTING) != 0); 487 } 488 489 public static boolean needsToConvertPhoneticString(final int vcardType) { 490 return ((vcardType & FLAG_CONVERT_PHONETIC_NAME_STRINGS) != 0); 491 } 492 493 public static boolean onlyOneNoteFieldIsAvailable(final int vcardType) { 494 return vcardType == VCARD_TYPE_DOCOMO; 495 } 496 497 public static boolean isDoCoMo(final int vcardType) { 498 return ((vcardType & FLAG_DOCOMO) != 0); 499 } 500 501 private VCardConfig() { 502 } 503}