Home | History | Annotate | Download | only in vcard 
      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 android.pim.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      */
     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