vpnui/vpnpolins/inc/vpndevlockhandler.h
author Dremov Kirill (Nokia-D-MSW/Tampere) <kirill.dremov@nokia.com>
Thu, 17 Dec 2009 09:14:51 +0200
changeset 0 33413c0669b9
permissions -rw-r--r--
Revision: 200949 Kit: 200951

/*
* Copyright (c) 2007 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:   Device lock handling related classes
*
*/




#ifndef C_VPNDEVLOCKHANDLER_H
#define C_VPNDEVLOCKHANDLER_H

#include <e32base.h>
#include <TerminalControl3rdPartyAPI.h>
#include <TerminalControl.h>

class CVpnTcStub;

/**
 * Process:
 * 1. Instantiate devlock policy handler
 * 2. Make sure devlock is available and VPN can use it
 *    If TerminalControlUsableL() leaves, device lock can't be used.
 * 3. (do other required stuff, e.g. pkcs12 deciphering and
 *    policy installation)
 * 4. Set the desired terminal control device lock policy by
 *    calling SetTerminalControlPolicyL(). TInt parameter
 *    dictates what kind of a policy will be set.
 *    If there are mutual attributes which exist in both
 *    current TC dev lock settings and in the intended
 *    VPN-imported settings, always use the stricter
 *    value for the attribute (i.e. if VPN wants to set devlock
 *    timeout to 50 and current policy has a timeout 20, stick
 *    with the current policy).
 */

/**
 * CVpnDevLockAttribute class defines a single devicelock related
 * attribute and its value. E.g. "ETimeout" with value "30" (minutes).
 *
 * ID range comes from TerminalControl3rdPartyAPI.h.
 *
 */
class CVpnDevLockAttribute : public CBase 
    {
public:
    /**
     * Instantiate a single attribute, with given ID and value
     *
     * @param aId The ID of the attribute, from TerminalControl3rdPartyAPI
     *        defined range
     * @param aVal The string value of the attribute. New memory will be allocated
     *        locally for the value.
     *
     * @return CVpnDevLockAttribute* the instantiated object.
     *
     * @leave Leaves if OOM
     */
    static CVpnDevLockAttribute* NewL(const TInt aId, const TDesC8& aVal);

    /**
     * Instantiate a single attribute, with given ID and value
     *
     * @param aId The ID of the attribute, from TerminalControl3rdPartyAPI
     *        defined range
     * @param aVal The TInt value of the attribute. It will be converted to a HBufC8
     *        internally, and new memory will be allocated locally for the new string.
     *
     * @return CVpnDevLockAttribute* the instantiated object.
     *
     * @leave Leaves if OOM
     */
    static CVpnDevLockAttribute* NewL(const TInt aId, const TInt aVal);

    /**
     * Instantiate a single attribute, with given ID and value.
     * The instantiated object will remain in CleanupStack.
     *
     * @return CVpnDevLockAttribute* the instantiated object.
     *
     * @leave Leaves if OOM
     */
    static CVpnDevLockAttribute* NewLC(const TInt aId, const TDesC8& aVal);

    /**
     * Destructor deletes the attribute's locally controlled resources.
     *
     */
    ~CVpnDevLockAttribute();

private:
    CVpnDevLockAttribute();

protected:
    /**
     * Instantiate a single attribute, with given ID and value
     *
     * @param aId The ID of the attribute, from TerminalControl3rdPartyAPI
     *        defined range
     * @param aVal The string value of the attribute. New memory will be 
     *        allocated locally for the new string.
     *
     * @leave Leaves if OOM
     */
    void ConstructL(const TInt aId, const TDesC8& aVal);

    /**
     * Instantiate a single attribute, with given ID and value
     *
     * @param aId The ID of the attribute, from TerminalControl3rdPartyAPI
     *        defined range
     * @param aVal The TInt value of the attribute. It will be converted to a HBufC8
     *        internally, and new memory will be allocated locally for the new string.
     *
     * @leave Leaves if OOM
     */
    void ConstructL(const TInt aId, const TInt aVal);

public:

    /**
     * Returns the TPtrC8 to the attribute value
     * 
     * @return KNullDesC8 if no attrib value set, the value otherwise
     */
    TPtrC8    AttributeValue() const;

    /**
     * Returns the ID of the attribute. IDs are defined in 
     *
     * @return TInt ID of the attribute
     *
     */
    TInt      AttributeId() const;
    
    /**
     * Returns the attribute value converted to TInt
     *
     * @param aVal The TInt version of the parameter
     *
     * @leave Leaves if the value is not convertible to TInt
     */
    void      AttributeValueAsIntL(TInt& aVal) const;

private:
    TInt        iAttributeId;
    HBufC8*     iAttributeVal;
    };

/**
 * CVpnDevLockPolicy is a container class for device lock related
 * attributes. Attributes are stored as CVpnDevLockAttribute
 * objects in the private member variable iPolicyArray.
 *
 * Attributes can be accessed using public accessors.
 *
 */
class CVpnDevLockPolicy : public CBase 
    {
public:
    /**
     * Instantiates a new policy with a set of related attributes.
     * Policy levels are defined in SUB SUB 415-467. Currently,
     * policy levels 0..3 are supported.
     *
     * @return CVpnDevLockPolicy* the instantiated object.
     *
     * @leave Leaves if OOM, or if the requested policy level
     *        is not supported.
     */
    static CVpnDevLockPolicy* NewL(const TInt aPolLevel);

    /**
     * Instantiates a new policy with a set of related attributes.
     * Policy levels are defined in SUB SUB 415-467. Currently,
     * policy levels 0..3 are supported. The instantiated object
     * will remain in CleanupStack.
     *
     * @return CVpnDevLockPolicy* the instantiated object.
     *
     * @leave Leaves if OOM, or if the requested policy level
     *        is not supported.
     */
    static CVpnDevLockPolicy* NewLC(const TInt aPolLevel);

    /**
     * Instantiates a new "empty" policy. The instantiated object
     * will remain in CleanupStack.
     *
     * @return CVpnDevLockPolicy* the instantiated object.
     *
     * @leave Leaves if OOM.
     */
    static CVpnDevLockPolicy* NewLC();

    /**
     * Destructor cleans up the locally allocated/controlled resources
     */
    ~CVpnDevLockPolicy();

private:
    CVpnDevLockPolicy();

protected:
    void ConstructL(const TInt aPolLevel);
    void ConstructL();

public:

    /**
     * Returns the attribute count for the policy.
     *
     * @return TInt Total count of all defined 
     * attributes in the container
     */
    TInt                    AttributeCount();

    /**
     * Returns the Policy attribute at the given attribute array 
     * index, if one exists.
     *
     * @param aIdx The index of the attribute requested. Must be
     *        between 0 and AttributeCount() - 1, inclusively
     *
     * @return The requested attribute or NULL if one didn't exist
     *
     */
    CVpnDevLockAttribute*   GetPolicyAttributeAt(const TInt aIdx);

    /**
     * Add an individual attribute for policy.
     *
     * @param aAttrib Attribute ID from device lock attribute range
     * @param aVal The value to assign. Internally converted to a string.
     *
     * @leave Leaves if there is not enough memory; may leave,
     * if the attribute id is out of range.
     * 
     */
    void    SetPolicyAttributeL(const TInt aAttrib, const TInt aVal);

    /**
     * Add an individual attribute for policy
     *
     * @param aAttrib Attribute ID from device lock attribute range
     * @param aVal The value to assign.
     *
     * @leave Leaves if there is not enough memory; may leave,
     * if the attribute id is out of range.
     * 
     */
    void    SetPolicyAttributeL(const TInt aAttrib, const TDesC8& aVal);

private:

    /**
     * Sets pre-defined attribute values to the policy according to
     * policy level.
     *
     * @param aPolLevel The requested policy level. Valid values
     *        range is 0..3.
     *
     * @leave Leaves if there is not enough memory to allocate
     *        the attribute strings, or if the requested
     *        policy level is not supported (KErrNotSupported)
     */
    void SetPolicyLevelL(const TInt aPolLevel);

private:
    CArrayFixFlat<CVpnDevLockAttribute*>*   iPolicyArray;
    };

/**
 * The main class for device lock operations.
 */
class CVpnDevLockHandler : public CBase 
    {
public:
    
    static CVpnDevLockHandler* NewL();
    static CVpnDevLockHandler* NewLC();
    
    /**
     * Standard destructor
     *
     */
    ~CVpnDevLockHandler();

protected:
    void ConstructL();

private:
    CVpnDevLockHandler();

public:

    /**
     * Checks whether VPN has access to terminal control device lock
     *
     * @leave Leaves when OOM. Leaves if VPN can't access device
     *        lock settings properly
     */
    void    TerminalControlSupportsVpnL();

    /**
     * Sets the terminal control's device lock policy to desired level.
     * If there are some existing device lock attributes that are 
     * "stricter" than the new ones proposed by the policy level, 
     * those will be left intact. Otherwise, the new requested
     * values will be applied.
     *
     */
    void SetTerminalControlPolicyL(const TInt aPolLevel);

private:

    /**
     * Checks whether there is a need to override the old existing
     * device lock parameter value. Returns ETrue iff the new
     * suggested value must be applied.
     *
     * @param aNew The suggested new attribute
     *
     * @ret TBool ETrue, if the old setting was more lenient than the
     *            new one, and therefore needs to be overridden.
     *
     * @leave Leaves when OOM
     */
    TBool   OverrideExistingL(const CVpnDevLockAttribute& aNew);

    /**
     * Obtains from the device the current setting for the given 
     * attribute.
     *
     * @param aAttribId The ID of the attribute for which the value is 
     *        to be fetched.
     *
     * @return A HBufC8* string containing the requested attribute
     *         value. Memory control of the object passes to the 
     *         caller.
     *
     * @leave Leaves if OOM or if the device doesn't support
     *        the given attribute.
     */
    HBufC8*     GetDevAttribValueL(const TInt aAttribId);
    
    /**
     * Sets the device's attribute (indicated by parameter's attribute id)
     * to the value contained by the parameter.
     *
     * @param aNew A CVpnDevLockAttribute object containing the desired 
     *        new settings
     *
     * @leave Leaves if OOM or if the device doesn't support
     *        the given attribute.
     */
    void        SetDevAttributeL(const CVpnDevLockAttribute& aNew);

    /**
     * Dynamically load the device lock library (if it's available)
     *
     * @return KErrNone if the library was found and is usable
     * @return KErrNotFound if lib wasn't found or is not usable.
     */
    void        LoadTCLibraryL();

private:

    RLibrary                        iTcLib;

    TBool                           iDevLockAvailable;
    
    CVpnTcStub*                     iTcStub;
    };

#endif // C_VPNPOLICYINSTALLER_H