/*

 * Copyright (c) 2002-2005 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:  Extends the ussd functionality.

 *

 */

#ifndef __CUSSDEXTENSIONINTERFACE_H__

#define __CUSSDEXTENSIONINTERFACE_H__

// INCLUDES

#include<ecom\ecom.h>

#include<etelmm.h>

#include<ussdinterfaceconstants.hrh>

// FORWARD DECLARATIONS

// CONSTANTS

const TUid KUssdExtensionInterfaceUid =

    {

    KUssdExtensionInterfaceUidValue

    };

// CLASS DECLARATION

/**

 *  Base class for Ussd Extension Plugin.

 *

 *  This API allows customizing the USSD sending feature of the S60 Telephony 

 *  applications at runtime.

 *

 *  The API defines two roles:

 *  1) Validates the USSD string while sending. if it is unauthorized 

 *  in the context shall terminate the request.

 *  2) Validates the USSD string while receiving, the extension will get the first chance to consume the reply if needed

 *

 *

 *  Note:

 *  The customizer needs only one plug-in implementation for a variant, and so supports only rom-only plug-in.

 */

class CUssdExtensionInterface : public CBase

    {

public:

    // Constructors and destructor

    /**

     * NewL

     * Wraps ECom object instantitation. Will return the

     * default interface implementation, which matches to

     * given aOperationName.

     */

    static CUssdExtensionInterface* NewL();

    /**

     * NewL

     * Wraps ECom object instantitation. Will search for

     * interface implementation, which matches to given

     * aOperationName.

     * @param aOperationName name of requested implementation.

     * Implementations advertise their "name" as specified

     * in their resource file field

     * IMPLEMENTATION_INFO::default_data.

     */

    static CUssdExtensionInterface* NewL(const TDesC8& aMatch);

public:

    // API to be implemented by ECOM plug-in

    /**

     * Validate/Authenticate the Ussd string Before Sending from

     * the USSD Send handler

     * When Ussd Extention plugin return true, then ussd manager will continue sending of the ussd

     * Otherwise the transaction will be terminated with KErrAccessDenined 

     *

     * @param aMessageData  

     * @param aMessageAttributes .

     */

    virtual TBool

            ValidateUssdMsgSending(

                    const TDesC8& aMessageData,

                    const RMobileUssdMessaging::TMobileUssdAttributesV1& aMsgAttribute) = 0;

    /**

     * Validate/Authenticate the Ussd response received by the 

     * USSD receive handler

     *

     * @param aMessageData  

     * @return true implies that the ussd response is valid for the extension.

     * otherwise pass it to the observer. .

     */

    virtual TBool ValidateUssdResponse(const TDesC8& aMessage) = 0;

    /**

     * if ValidateUssdResponse returns true, then the extension plugin is waiting for the response 

     * so invoke the interface to deligate to the plugin.

     * Example:

     * ...

     *  TBool isValidForExtension = iUssdExtnInterface->ValidateUssdResponse(aMsgData);

     *  TInt errfromextension = KErrNone;

     *  if (isValidForExtension)

     *     {

     *     TRAPD(err, iUssdExtnInterface->ProcessReceivedUssdL(iDecodedMessage, errfromextension));

     *     ...

     *     

     * @param aMessageData  

     * @return error code

     * @leave On typical leave level problems. 

     */

    virtual void

            ProcessReceivedUssdL(const TDesC& aMessageData, TInt aError) = 0;

    /**

     * Notify the any network error to the extension, so that it can handle the internal states if required

     * @param aError 

     */

    virtual void NotifyNWError(TInt aError)=0;

public:

    /**

     * ~CUssdExtensionInterface

     *

     * Cleans up resources, specifically notify ECOM server that this

     * instance is being deleted.

     */

    virtual ~CUssdExtensionInterface();

private:

    TUid iDtor_ID_Key; // Identification on cleanup

    };

#include "CUssdExtensionInterface.inl"    

#endif // __CUSSDEXTENSIONINTERFACE_H__