/*
 * Copyright (C) 2009 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package android.pim.vcard;

import android.pim.vcard.exception.VCardException;

import java.io.IOException;
import java.io.InputStream;

public abstract class VCardParser {

    protected boolean mCanceled;
    
    /**
     * Parses the given stream and send the VCard data into VCardBuilderBase object.
     * 
     * Note that vCard 2.1 specification allows "CHARSET" parameter, and some career sets
     * local encoding to it. For example, Japanese phone career uses Shift_JIS, which is
     * formally allowed in VCard 2.1, but not recommended in VCard 3.0. In VCard 2.1,
     * In some exreme case, some VCard may have different charsets in one VCard (though
     * we do not see any device which emits such kind of malicious data)
     * 
     * In order to avoid "misunderstanding" charset as much as possible, this method
     * use "ISO-8859-1" for reading the stream. When charset is specified in some property
     * (with "CHARSET=..." attribute), the string is decoded to raw bytes and encoded to
     * the charset. This method assumes that "ISO-8859-1" has 1 to 1 mapping in all 8bit
     * characters, which is not completely sure. In some cases, this "decoding-encoding"
     * scheme may fail. To avoid the case,
     * 
     * We recommend you to use VCardSourceDetector and detect which kind of source the
     * VCard comes from and explicitly specify a charset using the result.
     *       
     * @param is The source to parse.
     * @param builder The VCardBuilderBase object which used to construct data. If you want to
     * include multiple VCardBuilderBase objects in this field, consider using
     * {#link VCardBuilderCollection} class.
     * @return Returns true for success. Otherwise returns false.
     * @throws IOException, VCardException
     */
    public abstract boolean parse(InputStream is, VCardBuilder builder)
            throws IOException, VCardException;
    
    /**
     * The method variants which accept charset.
     * 
     * RFC 2426 "recommends" (not forces) to use UTF-8, so it may be OK to use
     * UTF-8 as an encoding when parsing vCard 3.0. But note that some Japanese
     * phone uses Shift_JIS as a charset (e.g. W61SH), and another uses
     * "CHARSET=SHIFT_JIS", which is explicitly prohibited in vCard 3.0 specification
     * (e.g. W53K).
     *  
     * @param is The source to parse.
     * @param charset Charset to be used.
     * @param builder The VCardBuilderBase object.
     * @return Returns true when successful. Otherwise returns false.
     * @throws IOException, VCardException
     */
    public abstract boolean parse(InputStream is, String charset, VCardBuilder builder)
            throws IOException, VCardException;
    
    /**
     * The method variants which tells this object the operation is already canceled.
     * XXX: Is this really necessary?
     * @hide 
     */
    public abstract void parse(InputStream is, String charset,
            VCardBuilder builder, boolean canceled)
        throws IOException, VCardException;
    
    /**
     * Cancel parsing.
     * Actual cancel is done after the end of the current one vcard entry parsing.
     */
    public void cancel() {
        mCanceled = true;
    }
}
