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 java.util.List;
19
20/**
21 * <P>
22 * The interface which should be implemented by the classes which have to analyze each
23 * vCard entry minutely.
24 * </P>
25 * <P>
26 * Here, there are several terms specific to vCard (and this library).
27 * </P>
28 * <P>
29 * The term "entry" is one vCard representation in the input, which should start with "BEGIN:VCARD"
30 * and end with "END:VCARD".
31 * </P>
32 * <P>
33 * The term "property" is one line in vCard entry, which consists of "group", "property name",
34 * "parameter(param) names and values", and "property values".
35 * </P>
36 * <P>
37 * e.g. group1.propName;paramName1=paramValue1;paramName2=paramValue2;propertyValue1;propertyValue2...
38 * </P>
39 */
40public interface VCardInterpreter {
41    /**
42     * Called when vCard interpretation started.
43     */
44    void onVCardStarted();
45
46    /**
47     * Called when vCard interpretation finished.
48     */
49    void onVCardEnded();
50
51    /**
52     * Called when parsing one vCard entry started.
53     * More specifically, this method is called when "BEGIN:VCARD" is read.
54     *
55     * This may be called before {@link #onEntryEnded()} is called, as vCard 2.1 accepts nested
56     * vCard.
57     *
58     * <code>
59     * BEGIN:VCARD
60     * BEGIN:VCARD
61     * VERSION:2.1
62     * N:test;;;;
63     * END:VCARD
64     * END:VCARD
65     * </code>
66     */
67    void onEntryStarted();
68
69    /**
70     * Called when parsing one vCard entry ended.
71     * More specifically, this method is called when "END:VCARD" is read.
72     */
73    void onEntryEnded();
74
75    /**
76     * Called when a property is created.
77     */
78    void onPropertyCreated(VCardProperty property);
79}
80