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