VCardInterpreter.java revision 4199c54c527330ac01699b176e7bca186a3aa3a4 
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 start();
45
46    /**
47     * Called when vCard interpretation finished.
48     */
49    void end();
50
51    /**
52     * Called when parsing one vCard entry started.
53     * More specifically, this method is called when "BEGIN:VCARD" is read.
54     */
55    void startEntry();
56
57    /**
58     * Called when parsing one vCard entry ended.
59     * More specifically, this method is called when "END:VCARD" is read.
60     * Note that {@link #startEntry()} may be called since
61     * vCard (especially 2.1) allows nested vCard.
62     */
63    void endEntry();
64
65    /**
66     * Called when reading one property started.
67     */
68    void startProperty();
69
70    /**
71     * Called when reading one property ended.
72     */
73    void endProperty();
74
75    /**
76     * @param group A group name. This method may be called more than once or may not be
77     * called at all, depending on how many gruoups are appended to the property.
78     */
79    void propertyGroup(String group);
80
81    /**
82     * @param name A property name like "N", "FN", "ADR", etc.
83     */
84    void propertyName(String name);
85
86    /**
87     * @param type A parameter name like "ENCODING", "CHARSET", etc.
88     */
89    void propertyParamType(String type);
90
91    /**
92     * @param value A parameter value. This method may be called without
93     * {@link #propertyParamType(String)} being called (when the vCard is vCard 2.1).
94     */
95    void propertyParamValue(String value);
96
97    /**
98     * @param values List of property values. The size of values would be 1 unless
99     * coressponding property name is "N", "ADR", or "ORG".
100     */
101    void propertyValues(List<String> values);
102}
103