/*
* 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 the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
* which accompanies this distribution, and is available
* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
*
* Initial Contributors:
* Nokia Corporation - initial contribution.
*
* Contributors:
*
* Description:        This abstract class defines consumer policy interface.
*
*/








#ifndef M_SEN_CONSUMER_POLICY_H
#define M_SEN_CONSUMER_POLICY_H

//  INCLUDES
#include <e32base.h> // for CActive
#include <badesca.h>
#include <SenDomFragment.h>

// FORWARD DECLARATIONS
class CSenIdentityProviderIdArray8;

// CLASS DECLARATION

/**
*  This abstract class defines consumer policy interface.
*  The consumer policy sets the conditions in which some service provider 
*  is capable to operate in. It is defining context, through which these
*  (possibly remote) services may be contacted and used.
*  The actual properties may include transport layer settings, like 
*  predefined Internet Access Point (IAP) ID. In addition, consumer policy
*  may declare, that certain service should only be contacted using certain
*  identity provider (in ID-WSF). This can be achieved by mapping certain 
*  list of IDP IDs to a consumer policy. 
*  A consumer policy is effective only for a single session, and thus it
*  applies to one service connection only. This means, that this policy
*  information is "private", and not shared between different WSC applications
*  using WSF, event though they might be using the same (remote) service at the
*  same time. Consumer policy properties are not serialized in any WSF
*  database, but resides in memory only.
*
*   Example structure of ConsumerPolicy XML fragment:
*
*   <ConsumerPolicy>
*       <Transport>
*           <IapId>
*               2
*           </IapId>
*       </Transport>
*       <IdentityProviderIDs strict="false">
*           <IdentityProviderID>
*             urn:first.example.idp.com
*           </IdentityProviderID>
*           <IdentityProviderID>
*             urn:second.example.idp.com
*           </IdentityProviderID>
*       </IdentityProviderIDs>
*   </ConsumerPolicy>
*
*  @lib SenServDesc.lib
*  @since Series60 3.0
*/
class MSenConsumerPolicy
    {
    public: // New functions
        
        /**
        * Setter for Internet Access Point (IAP) ID existing in CommDB.
        * @since Series60 3.0
        * @param aIapId IAP ID
        */ 
        virtual void SetConsumerIapIdL(TUint32 aIapId) = 0;

        /**
        * Getter for IAP ID.
        * @since Series60 3.0
        * @param aCurrentIapId  will contain the current 
        *                       Internet Access Point ID
        * @return
        *  - KErrNone if <IapId> element is found and has valid content
        *  - KErrNotFound if no <IapId> element has been found or it has
        *       no content
        *  - TLex error codes, if <IapId> element has non-numeric value,
        *    which cannot be resolved
        */ 
        virtual TInt ConsumerIapId(TUint32& aCurrentIapId) = 0;

        /**
        * Setter for consumer identity provider IDs. Overrides current values 
        * with the given values from the array. If an ID does not exist, it
        * will be added. 
        * @since Series60 3.0
        * @param aList  list of identity provider IDs.
        */ 
        virtual void SetConsumerIdentityProviderIdsL(
                                        CSenIdentityProviderIdArray8& aList) = 0;

        /**
        * Adds a new Identity provider ID value at the end of the current list
        * values. 
        * @since Series60 3.0
        * @param aProviderId unique ProviderID as UTF-8 descriptor
        * @return   KErrAlreadyExists, if a duplicate is tried to add
        *           KErrArgument if a zero-length descriptor is tried to add
        *           (aProviderId.Length() == 0)
        */
        virtual TInt AddConsumerIdentityProviderIdL(const TDesC8& aProviderId) = 0;

        /**
        * Rebuilds the consumer policy of this service pattern from the given
        * consumer policy.
        * @since Series60 3.0
        * @param aTemplate  the consumer policy to rebuild from.
        * @return KErrNone or other system-wide Symbian error codes.
        */
        virtual TInt RebuildFromConsumerPolicy(MSenConsumerPolicy& aTemplate) = 0;

        /**
        * Getter for Identity provider IDs.
        * @since Series60 3.0
        * @return a list of IDP arrays if such value(s) have been set
        *         or an empty array if no IDP:s have been specified.
        */ 
        virtual const CSenIdentityProviderIdArray8& 
                                            ConsumerIdentityProviderIds8L() = 0;

        /**
        * Checks if the policy of this service pattern accepts given policy.
        * @since Series60 3.0
        * @param aPolicyPattern the consumer policy to check.
        * @return ETrue if accepts, EFalse if not
        */
        virtual TBool AcceptsConsumerPolicy(MSenConsumerPolicy& aPolicyPattern) = 0;        
    };

#endif //M_SEN_CONSUMER_POLICY_H

// End of File