VCardParser.java revision c955c8b0da0c9fcbad0ddcae76641358c27e72cd 
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 com.android.vcard.exception.VCardException;
19
20import java.io.IOException;
21import java.io.InputStream;
22
23public interface VCardParser {
24    /**
25     * <p>
26     * Parses the given stream and send the vCard data into VCardBuilderBase object.
27     * </p>.
28     * <p>
29     * Note that vCard 2.1 specification allows "CHARSET" parameter, and some career sets
30     * local encoding to it. For example, Japanese phone career uses Shift_JIS, which is
31     * formally allowed in vCard 2.1, but not allowed in vCard 3.0. In vCard 2.1,
32     * In some exreme case, it is allowed for vCard to have different charsets in one vCard.
33     * </p>
34     * <p>
35     * We recommend you use {@link VCardSourceDetector} and detect which kind of source the
36     * vCard comes from and explicitly specify a charset using the result.
37     * </p>
38     *
39     * @param is The source to parse.
40     * @param interepreter A {@link VCardInterpreter} object which used to construct data.
41     * @throws IOException, VCardException
42     */
43    public void parse(InputStream is, VCardInterpreter interepreter)
44            throws IOException, VCardException;
45
46    /**
47     * <p>
48     * Cancel parsing vCard. Useful when you want to stop the parse in the other threads.
49     * </p>
50     * <p>
51     * Actual cancel is done after parsing the current vcard.
52     * </p>
53     */
54    public void cancel();
55}
56