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 android.pim.vcard; 17 18import android.pim.vcard.exception.VCardException; 19 20import java.io.IOException; 21import java.io.InputStream; 22 23public abstract class VCardParser { 24 protected final int mParseType; 25 protected boolean mCanceled; 26 27 public VCardParser() { 28 this(VCardConfig.PARSE_TYPE_UNKNOWN); 29 } 30 31 public VCardParser(int parseType) { 32 mParseType = parseType; 33 } 34 35 /** 36 * <P> 37 * Parses the given stream and send the VCard data into VCardBuilderBase object. 38 * </P. 39 * <P> 40 * Note that vCard 2.1 specification allows "CHARSET" parameter, and some career sets 41 * local encoding to it. For example, Japanese phone career uses Shift_JIS, which is 42 * formally allowed in VCard 2.1, but not recommended in VCard 3.0. In VCard 2.1, 43 * In some exreme case, some VCard may have different charsets in one VCard (though 44 * we do not see any device which emits such kind of malicious data) 45 * </P> 46 * <P> 47 * In order to avoid "misunderstanding" charset as much as possible, this method 48 * use "ISO-8859-1" for reading the stream. When charset is specified in some property 49 * (with "CHARSET=..." parameter), the string is decoded to raw bytes and encoded to 50 * the charset. This method assumes that "ISO-8859-1" has 1 to 1 mapping in all 8bit 51 * characters, which is not completely sure. In some cases, this "decoding-encoding" 52 * scheme may fail. To avoid the case, 53 * </P> 54 * <P> 55 * We recommend you to use {@link VCardSourceDetector} and detect which kind of source the 56 * VCard comes from and explicitly specify a charset using the result. 57 * </P> 58 * 59 * @param is The source to parse. 60 * @param interepreter A {@link VCardInterpreter} object which used to construct data. 61 * @return Returns true for success. Otherwise returns false. 62 * @throws IOException, VCardException 63 */ 64 public abstract boolean parse(InputStream is, VCardInterpreter interepreter) 65 throws IOException, VCardException; 66 67 /** 68 * <P> 69 * The method variants which accept charset. 70 * </P> 71 * <P> 72 * RFC 2426 "recommends" (not forces) to use UTF-8, so it may be OK to use 73 * UTF-8 as an encoding when parsing vCard 3.0. But note that some Japanese 74 * phone uses Shift_JIS as a charset (e.g. W61SH), and another uses 75 * "CHARSET=SHIFT_JIS", which is explicitly prohibited in vCard 3.0 specification (e.g. W53K). 76 * </P> 77 * 78 * @param is The source to parse. 79 * @param charset Charset to be used. 80 * @param builder The VCardBuilderBase object. 81 * @return Returns true when successful. Otherwise returns false. 82 * @throws IOException, VCardException 83 */ 84 public abstract boolean parse(InputStream is, String charset, VCardInterpreter builder) 85 throws IOException, VCardException; 86 87 /** 88 * The method variants which tells this object the operation is already canceled. 89 */ 90 public abstract void parse(InputStream is, String charset, 91 VCardInterpreter builder, boolean canceled) 92 throws IOException, VCardException; 93 94 /** 95 * Cancel parsing. 96 * Actual cancel is done after the end of the current one vcard entry parsing. 97 */ 98 public void cancel() { 99 mCanceled = true; 100 } 101} 102