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 */ 16 package com.android.vcard; 17 18 import 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 */ 40 public interface VCardInterpreter { 41 /** 42 * Called when vCard interpretation started. 43 */ start()44 void start(); 45 46 /** 47 * Called when vCard interpretation finished. 48 */ end()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 */ startEntry()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 */ endEntry()63 void endEntry(); 64 65 /** 66 * Called when reading one property started. 67 */ startProperty()68 void startProperty(); 69 70 /** 71 * Called when reading one property ended. 72 */ endProperty()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 */ propertyGroup(String group)79 void propertyGroup(String group); 80 81 /** 82 * @param name A property name like "N", "FN", "ADR", etc. 83 */ propertyName(String name)84 void propertyName(String name); 85 86 /** 87 * @param type A parameter name like "ENCODING", "CHARSET", etc. 88 */ propertyParamType(String type)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 */ propertyParamValue(String value)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 */ propertyValues(List<String> values)101 void propertyValues(List<String> values); 102 } 103