| /* |
| * Copyright (C) 2009 The Android Open Source Project |
| * |
| * Licensed under the Apache License, Version 2.0 (the "License"); |
| * you may not use this file except in compliance with the License. |
| * You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| package android.pim.vcard; |
| |
| import android.pim.vcard.exception.VCardException; |
| |
| import java.io.IOException; |
| import java.io.InputStream; |
| |
| public abstract class VCardParser { |
| public static final int PARSER_MODE_DEFAULT = 0; |
| /** |
| * The parser should ignore "AGENT" properties and nested vCard structure. |
| */ |
| public static final int PARSER_MODE_SCAN = 1; |
| |
| protected final int mParserMode; |
| protected boolean mCanceled; |
| |
| public VCardParser() { |
| mParserMode = PARSER_MODE_DEFAULT; |
| } |
| |
| public VCardParser(int parserMode) { |
| mParserMode = parserMode; |
| } |
| |
| /** |
| * Parses the given stream and send the VCard data into VCardBuilderBase object. |
| * |
| * Note that vCard 2.1 specification allows "CHARSET" parameter, and some career sets |
| * local encoding to it. For example, Japanese phone career uses Shift_JIS, which is |
| * formally allowed in VCard 2.1, but not recommended in VCard 3.0. In VCard 2.1, |
| * In some exreme case, some VCard may have different charsets in one VCard (though |
| * we do not see any device which emits such kind of malicious data) |
| * |
| * In order to avoid "misunderstanding" charset as much as possible, this method |
| * use "ISO-8859-1" for reading the stream. When charset is specified in some property |
| * (with "CHARSET=..." parameter), the string is decoded to raw bytes and encoded to |
| * the charset. This method assumes that "ISO-8859-1" has 1 to 1 mapping in all 8bit |
| * characters, which is not completely sure. In some cases, this "decoding-encoding" |
| * scheme may fail. To avoid the case, |
| * |
| * We recommend you to use VCardSourceDetector and detect which kind of source the |
| * VCard comes from and explicitly specify a charset using the result. |
| * |
| * @param is The source to parse. |
| * @param builder The VCardBuilderBase object which used to construct data. If you want to |
| * include multiple VCardBuilderBase objects in this field, consider using |
| * {#link VCardBuilderCollection} class. |
| * @return Returns true for success. Otherwise returns false. |
| * @throws IOException, VCardException |
| */ |
| public abstract boolean parse(InputStream is, VCardBuilder builder) |
| throws IOException, VCardException; |
| |
| /** |
| * The method variants which accept charset. |
| * |
| * RFC 2426 "recommends" (not forces) to use UTF-8, so it may be OK to use |
| * UTF-8 as an encoding when parsing vCard 3.0. But note that some Japanese |
| * phone uses Shift_JIS as a charset (e.g. W61SH), and another uses |
| * "CHARSET=SHIFT_JIS", which is explicitly prohibited in vCard 3.0 specification |
| * (e.g. W53K). |
| * |
| * @param is The source to parse. |
| * @param charset Charset to be used. |
| * @param builder The VCardBuilderBase object. |
| * @return Returns true when successful. Otherwise returns false. |
| * @throws IOException, VCardException |
| */ |
| public abstract boolean parse(InputStream is, String charset, VCardBuilder builder) |
| throws IOException, VCardException; |
| |
| /** |
| * The method variants which tells this object the operation is already canceled. |
| * XXX: Is this really necessary? |
| * @hide |
| */ |
| public abstract void parse(InputStream is, String charset, |
| VCardBuilder builder, boolean canceled) |
| throws IOException, VCardException; |
| |
| /** |
| * Cancel parsing. |
| * Actual cancel is done after the end of the current one vcard entry parsing. |
| */ |
| public void cancel() { |
| mCanceled = true; |
| } |
| } |