/*

* Copyright (c) 2006 Nokia Corporation and/or its subsidiary(-ies).

* All rights reserved.

* This component and the accompanying materials are made available

* under the terms of "Eclipse Public License v1.0"

* which accompanies this distribution, and is available

* at the URL "http://www.eclipse.org/legal/epl-v10.html".

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description:   MNcdParser interface

*

*/

#ifndef NcdPARSER_H

#define NcdPARSER_H

#include <e32base.h>

class MNcdParserObserverBundle;

class MNcdProtocolDefaultObserver;

class CNcdSubParser;

/**

 * Parser interface.

 */

class MNcdParser 

    {

public:

    /**

     * Destructor

     */

    virtual ~MNcdParser() {}

    /**

     * Retrieves the observer bundle. The caller must set some 

     * observers prior to beginning the operation, or BeginL()-methods will fail.

     */

    virtual MNcdParserObserverBundle& Observers() const = 0;

    /**

     * Retrieves the default observer. All events not handled or handled by 

     * the client should be passed to the default observer.

     * It will further handle the events and free the memory.

     */

    virtual MNcdProtocolDefaultObserver& DefaultObserver() const = 0;

    /**

     * Sets the origin of data for this parser. This is passed to some

     * observers, as session observer.

     */

    virtual void SetOriginL( const TDesC& aOrigin ) = 0;

    /** 

     * Begin parsing in asynchronous manner. 

     * After this, data may fed to the parser.

     */

    virtual void BeginAsyncL() = 0;

    /**

     * Begin parsing in asynchronous manner using the given parser

     *

     * @param aSubParser Parser. If NULL, normal top level parser is used. Ownership is transferred.

     * @note Ownership is always transferred so aSubParser must NOT be deleted

     * by the calling code even if this method leaves

     */

    virtual void BeginAsyncL( CNcdSubParser* aSubParser ) = 0;

    /** 

     * Begin parsing in synchronous manner.

     * After this, data may fed to the parser.

     */

    virtual void BeginSyncL( ) = 0;

    /**

     * Begin parsing in asynchronous manner using the given parser

     *

     * @param aSubParser Parser. If NULL, normal top level parser is used. Ownership is transferred.

     * @note Ownership is always transferred so aSubParser must NOT be deleted

     * by the calling code even if this method leaves

     */

    virtual void BeginSyncL( CNcdSubParser* aSubParser ) = 0;

    /**

     * Parse some data.

     * @param aData UTF8 format XML data

     */

    virtual void ParseL( const TDesC8& aUTF8Data ) = 0;

    /**

     * Parse some data.

     * @param aData 16-bit unicode format XML data

     */

    virtual void ParseL( const TDesC16& aData ) = 0;

    /**

     * End parsing. 

     * This method must be called when all the data has been fed to the parser.

     * In synchronous mode, a callback will be immediately issued.

     * In asynchronous mode, a callback will be issued after all data

     * in the buffers has been processed.

     */

    virtual void EndL() = 0;

    /**

     * Cancel ongoing asynchronous parsing process.

     * A callback will not be issued.

     */

    virtual void CancelParsing() = 0;

    };

#endif