1 /*

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

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

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

     6 * which accompanies this distribution, and is available

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

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:   Device lock handling related classes

    15 *

    16 */

    17 

    18 

    19 

    20 

    21 #ifndef C_VPNDEVLOCKHANDLER_H

    22 #define C_VPNDEVLOCKHANDLER_H

    23 

    24 #include <e32base.h>

    25 #include <TerminalControl3rdPartyAPI.h>

    26 #include <TerminalControl.h>

    27 

    28 class CVpnTcStub;

    29 

    30 /**

    31  * Process:

    32  * 1. Instantiate devlock policy handler

    33  * 2. Make sure devlock is available and VPN can use it

    34  *    If TerminalControlUsableL() leaves, device lock can't be used.

    35  * 3. (do other required stuff, e.g. pkcs12 deciphering and

    36  *    policy installation)

    37  * 4. Set the desired terminal control device lock policy by

    38  *    calling SetTerminalControlPolicyL(). TInt parameter

    39  *    dictates what kind of a policy will be set.

    40  *    If there are mutual attributes which exist in both

    41  *    current TC dev lock settings and in the intended

    42  *    VPN-imported settings, always use the stricter

    43  *    value for the attribute (i.e. if VPN wants to set devlock

    44  *    timeout to 50 and current policy has a timeout 20, stick

    45  *    with the current policy).

    46  */

    47 

    48 /**

    49  * CVpnDevLockAttribute class defines a single devicelock related

    50  * attribute and its value. E.g. "ETimeout" with value "30" (minutes).

    51  *

    52  * ID range comes from TerminalControl3rdPartyAPI.h.

    53  *

    54  */

    55 class CVpnDevLockAttribute : public CBase 

    56     {

    57 public:

    58     /**

    59      * Instantiate a single attribute, with given ID and value

    60      *

    61      * @param aId The ID of the attribute, from TerminalControl3rdPartyAPI

    62      *        defined range

    63      * @param aVal The string value of the attribute. New memory will be allocated

    64      *        locally for the value.

    65      *

    66      * @return CVpnDevLockAttribute* the instantiated object.

    67      *

    68      * @leave Leaves if OOM

    69      */

    70     static CVpnDevLockAttribute* NewL(const TInt aId, const TDesC8& aVal);

    71 

    72     /**

    73      * Instantiate a single attribute, with given ID and value

    74      *

    75      * @param aId The ID of the attribute, from TerminalControl3rdPartyAPI

    76      *        defined range

    77      * @param aVal The TInt value of the attribute. It will be converted to a HBufC8

    78      *        internally, and new memory will be allocated locally for the new string.

    79      *

    80      * @return CVpnDevLockAttribute* the instantiated object.

    81      *

    82      * @leave Leaves if OOM

    83      */

    84     static CVpnDevLockAttribute* NewL(const TInt aId, const TInt aVal);

    85 

    86     /**

    87      * Instantiate a single attribute, with given ID and value.

    88      * The instantiated object will remain in CleanupStack.

    89      *

    90      * @return CVpnDevLockAttribute* the instantiated object.

    91      *

    92      * @leave Leaves if OOM

    93      */

    94     static CVpnDevLockAttribute* NewLC(const TInt aId, const TDesC8& aVal);

    95 

    96     /**

    97      * Destructor deletes the attribute's locally controlled resources.

    98      *

    99      */

   100     ~CVpnDevLockAttribute();

   101 

   102 private:

   103     CVpnDevLockAttribute();

   104 

   105 protected:

   106     /**

   107      * Instantiate a single attribute, with given ID and value

   108      *

   109      * @param aId The ID of the attribute, from TerminalControl3rdPartyAPI

   110      *        defined range

   111      * @param aVal The string value of the attribute. New memory will be 

   112      *        allocated locally for the new string.

   113      *

   114      * @leave Leaves if OOM

   115      */

   116     void ConstructL(const TInt aId, const TDesC8& aVal);

   117 

   118     /**

   119      * Instantiate a single attribute, with given ID and value

   120      *

   121      * @param aId The ID of the attribute, from TerminalControl3rdPartyAPI

   122      *        defined range

   123      * @param aVal The TInt value of the attribute. It will be converted to a HBufC8

   124      *        internally, and new memory will be allocated locally for the new string.

   125      *

   126      * @leave Leaves if OOM

   127      */

   128     void ConstructL(const TInt aId, const TInt aVal);

   129 

   130 public:

   131 

   132     /**

   133      * Returns the TPtrC8 to the attribute value

   134      * 

   135      * @return KNullDesC8 if no attrib value set, the value otherwise

   136      */

   137     TPtrC8    AttributeValue() const;

   138 

   139     /**

   140      * Returns the ID of the attribute. IDs are defined in 

   141      *

   142      * @return TInt ID of the attribute

   143      *

   144      */

   145     TInt      AttributeId() const;

   146     

   147     /**

   148      * Returns the attribute value converted to TInt

   149      *

   150      * @param aVal The TInt version of the parameter

   151      *

   152      * @leave Leaves if the value is not convertible to TInt

   153      */

   154     void      AttributeValueAsIntL(TInt& aVal) const;

   155 

   156 private:

   157     TInt        iAttributeId;

   158     HBufC8*     iAttributeVal;

   159     };

   160 

   161 /**

   162  * CVpnDevLockPolicy is a container class for device lock related

   163  * attributes. Attributes are stored as CVpnDevLockAttribute

   164  * objects in the private member variable iPolicyArray.

   165  *

   166  * Attributes can be accessed using public accessors.

   167  *

   168  */

   169 class CVpnDevLockPolicy : public CBase 

   170     {

   171 public:

   172     /**

   173      * Instantiates a new policy with a set of related attributes.

   174      * Policy levels are defined in SUB SUB 415-467. Currently,

   175      * policy levels 0..3 are supported.

   176      *

   177      * @return CVpnDevLockPolicy* the instantiated object.

   178      *

   179      * @leave Leaves if OOM, or if the requested policy level

   180      *        is not supported.

   181      */

   182     static CVpnDevLockPolicy* NewL(const TInt aPolLevel);

   183 

   184     /**

   185      * Instantiates a new policy with a set of related attributes.

   186      * Policy levels are defined in SUB SUB 415-467. Currently,

   187      * policy levels 0..3 are supported. The instantiated object

   188      * will remain in CleanupStack.

   189      *

   190      * @return CVpnDevLockPolicy* the instantiated object.

   191      *

   192      * @leave Leaves if OOM, or if the requested policy level

   193      *        is not supported.

   194      */

   195     static CVpnDevLockPolicy* NewLC(const TInt aPolLevel);

   196 

   197     /**

   198      * Instantiates a new "empty" policy. The instantiated object

   199      * will remain in CleanupStack.

   200      *

   201      * @return CVpnDevLockPolicy* the instantiated object.

   202      *

   203      * @leave Leaves if OOM.

   204      */

   205     static CVpnDevLockPolicy* NewLC();

   206 

   207     /**

   208      * Destructor cleans up the locally allocated/controlled resources

   209      */

   210     ~CVpnDevLockPolicy();

   211 

   212 private:

   213     CVpnDevLockPolicy();

   214 

   215 protected:

   216     void ConstructL(const TInt aPolLevel);

   217     void ConstructL();

   218 

   219 public:

   220 

   221     /**

   222      * Returns the attribute count for the policy.

   223      *

   224      * @return TInt Total count of all defined 

   225      * attributes in the container

   226      */

   227     TInt                    AttributeCount();

   228 

   229     /**

   230      * Returns the Policy attribute at the given attribute array 

   231      * index, if one exists.

   232      *

   233      * @param aIdx The index of the attribute requested. Must be

   234      *        between 0 and AttributeCount() - 1, inclusively

   235      *

   236      * @return The requested attribute or NULL if one didn't exist

   237      *

   238      */

   239     CVpnDevLockAttribute*   GetPolicyAttributeAt(const TInt aIdx);

   240 

   241     /**

   242      * Add an individual attribute for policy.

   243      *

   244      * @param aAttrib Attribute ID from device lock attribute range

   245      * @param aVal The value to assign. Internally converted to a string.

   246      *

   247      * @leave Leaves if there is not enough memory; may leave,

   248      * if the attribute id is out of range.

   249      * 

   250      */

   251     void    SetPolicyAttributeL(const TInt aAttrib, const TInt aVal);

   252 

   253     /**

   254      * Add an individual attribute for policy

   255      *

   256      * @param aAttrib Attribute ID from device lock attribute range

   257      * @param aVal The value to assign.

   258      *

   259      * @leave Leaves if there is not enough memory; may leave,

   260      * if the attribute id is out of range.

   261      * 

   262      */

   263     void    SetPolicyAttributeL(const TInt aAttrib, const TDesC8& aVal);

   264 

   265 private:

   266 

   267     /**

   268      * Sets pre-defined attribute values to the policy according to

   269      * policy level.

   270      *

   271      * @param aPolLevel The requested policy level. Valid values

   272      *        range is 0..3.

   273      *

   274      * @leave Leaves if there is not enough memory to allocate

   275      *        the attribute strings, or if the requested

   276      *        policy level is not supported (KErrNotSupported)

   277      */

   278     void SetPolicyLevelL(const TInt aPolLevel);

   279 

   280 private:

   281     CArrayFixFlat<CVpnDevLockAttribute*>*   iPolicyArray;

   282     };

   283 

   284 /**

   285  * The main class for device lock operations.

   286  */

   287 class CVpnDevLockHandler : public CBase 

   288     {

   289 public:

   290     

   291     static CVpnDevLockHandler* NewL();

   292     static CVpnDevLockHandler* NewLC();

   293     

   294     /**

   295      * Standard destructor

   296      *

   297      */

   298     ~CVpnDevLockHandler();

   299 

   300 protected:

   301     void ConstructL();

   302 

   303 private:

   304     CVpnDevLockHandler();

   305 

   306 public:

   307 

   308     /**

   309      * Checks whether VPN has access to terminal control device lock

   310      *

   311      * @leave Leaves when OOM. Leaves if VPN can't access device

   312      *        lock settings properly

   313      */

   314     void    TerminalControlSupportsVpnL();

   315 

   316     /**

   317      * Sets the terminal control's device lock policy to desired level.

   318      * If there are some existing device lock attributes that are 

   319      * "stricter" than the new ones proposed by the policy level, 

   320      * those will be left intact. Otherwise, the new requested

   321      * values will be applied.

   322      *

   323      */

   324     void SetTerminalControlPolicyL(const TInt aPolLevel);

   325 

   326 private:

   327 

   328     /**

   329      * Checks whether there is a need to override the old existing

   330      * device lock parameter value. Returns ETrue iff the new

   331      * suggested value must be applied.

   332      *

   333      * @param aNew The suggested new attribute

   334      *

   335      * @ret TBool ETrue, if the old setting was more lenient than the

   336      *            new one, and therefore needs to be overridden.

   337      *

   338      * @leave Leaves when OOM

   339      */

   340     TBool   OverrideExistingL(const CVpnDevLockAttribute& aNew);

   341 

   342     /**

   343      * Obtains from the device the current setting for the given 

   344      * attribute.

   345      *

   346      * @param aAttribId The ID of the attribute for which the value is 

   347      *        to be fetched.

   348      *

   349      * @return A HBufC8* string containing the requested attribute

   350      *         value. Memory control of the object passes to the 

   351      *         caller.

   352      *

   353      * @leave Leaves if OOM or if the device doesn't support

   354      *        the given attribute.

   355      */

   356     HBufC8*     GetDevAttribValueL(const TInt aAttribId);

   357     

   358     /**

   359      * Sets the device's attribute (indicated by parameter's attribute id)

   360      * to the value contained by the parameter.

   361      *

   362      * @param aNew A CVpnDevLockAttribute object containing the desired 

   363      *        new settings

   364      *

   365      * @leave Leaves if OOM or if the device doesn't support

   366      *        the given attribute.

   367      */

   368     void        SetDevAttributeL(const CVpnDevLockAttribute& aNew);

   369 

   370     /**

   371      * Dynamically load the device lock library (if it's available)

   372      *

   373      * @return KErrNone if the library was found and is usable

   374      * @return KErrNotFound if lib wasn't found or is not usable.

   375      */

   376     void        LoadTCLibraryL();

   377 

   378 private:

   379 

   380     RLibrary                        iTcLib;

   381 

   382     TBool                           iDevLockAvailable;

   383     

   384     CVpnTcStub*                     iTcStub;

   385     };

   386 

   387 #endif // C_VPNPOLICYINSTALLER_H

   388