<?xml version="1.0" encoding="utf-8"?>
<!-- Copyright (c) 2007-2010 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 
"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: 
-->
<!DOCTYPE concept
  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="GUID-5857377F-B90D-5149-9485-5919C12B8F13" xml:lang="en"><title>How
to use a rule-based selector</title><prolog><metadata><keywords/></metadata></prolog><conbody>
<p>The following example demonstrates the use of the rule selector and the
inclusion of a selection rule to retrieve the characteristics of a symmetric
cipher object. </p>
<codeblock id="GUID-827D423E-4E63-563F-8D00-C3C906A3E20C" xml:space="preserve">#include &lt;ruleselector.h&gt;
#include &lt;cryptosymmetriccipherapi.h&gt;
#include &lt;cryptospistateapi.h&gt;
#include &lt;cryptospidef.h&gt;
#include &lt;keys.h&gt;

using namespace CryptoSpi;

// Create a CSelectionRules collection object which is used to store the rules
// that influence the choice of plug-in implementation selected

CSelectionRules* rules = CSelectionRules::NewL();
CleanupStack::PushL(rules);

// Add a selection rule selecting symmetric ciphers with a key length of 64 bytes
    
TInt ruleValue = 64;
            
// Create and initialise one or more crypto parameters 
// to store the contents of the rule value 
CCryptoParam* ruleValueParam = CCryptoIntParam::NewL(ruleValue,KMaximumKeyLengthTypeUid);

// Create a selection rule for each crypto parameter (CSelectionRuleContent
// takes ownership of the crypto parameter), by passing in the following parameters:
// *InterfaceScope        The Interface scope of which the rule should be applied
// *AlgorithmScope        The Algorithm scope of which the rule should be applied
// *CharacteristicValue   The parameter type and value of the rule
// *Operator              The operator of the rule
// *IsOptional            Whether this rule is optional (ETrue) or mandatory (EFalse)        
CSelectionRuleContent* rule = CSelectionRuleContent::NewL(KSymmetricCipherInterfaceUid,
                                                          KNoneUid,
                                                          ruleValueParam,
                                                          EOpEqual,
                                                          EFalse);

// Add the newly created selection rule to the CSelectionRules collection by calling
// the 'AddSelectionRuleL' method and passing in a pointer to the constructed rule.
// AddSelectionRuleL() checks that the type of the crypto parameters is correct and 
// leaves with KErrNotSupported if not. For instance, a creator name parameter must 
// be stored using a CCryptoDesC16Param. 
          
rules-&gt;AddSelectionRuleL(rule);
                                    
// Create an instance of the rule selector, passing in the selection rules 
// object previously instantiated
CRuleSelector* ruleSelector = CRuleSelector::NewL(rules);
    
// Ownership of the rule collection object is passed to the rule selector, therefore
// the CSelectionRules object needs to be popped off the cleanup stack before pushing on
// the rule selector
CleanupStack::Pop(rules);
CleanupStack::PushL(ruleSelector);
    
// The legacy selector is set within the framework by default. In order to set the rule
// selector, the 'SetSelector' method of CryptoSpiStateApi needs to be called, 
//passing a pointer to the initialized rule selector    
CCryptoSpiStateApi::SetSelector(ruleSelector);

// Create a new CryptoParams object to encapsulate the secret key string for the 
// Symmetric Cipher implementation 
CCryptoParams* keyParams = CCryptoParams::NewLC();

// Add the secret key to the CCryptoParams object by calling the AddL method, passing in 
// the key string and appropriate key parameter UID
keyParams-&gt;AddL(_L8("12345678"), KSymmetricKeyParameterUid);

// Create a CKey object by passing in an instance of TKeyProperty and the previously
// created CCryptoParams object containing the secret key
TKeyProperty keyProperty;        
CKey* key=CKey::NewL(keyProperty,*keyParams);
CleanupStack::PushL(key);

// Create and initialise a pointer for the Symmetric Cipher implementation object        
CSymmetricCipher* symmetricCipherImpl = NULL;
        
// If successful, the 'CreateSymmetricCipherL' method returns KErrNone and the framework
// creates an instance of the selected Symmetric Cipher implementation, as chosen by the
// rule selector. The CSymmetricCipher pointer is passed by reference and set to point to
// the new symmetric cipher object
TRAPD(err,CSymmetricCipherFactory::CreateSymmetricCipherL(symmetricCipherImpl,
                                                          KDesUid,
                                                          *key,
                                                          KCryptoModeEncryptUid,
                                                          KOperationModeNoneUid,
                                                          KPaddingModeNoneUid,
                                                          NULL));

// Having successfully constructed the symmetric cipher implementation object, it is
// possible to retrieve the plug-in characteristics associated with it
if (symmetricCipherImpl &amp;&amp; (err == KErrNone))
 {
 CleanupStack::PushL(symmetricCipherImpl);
 // Use cipher
 CleanupStack::PopAndDestroy(symmetricCipherImpl);
 }

CleanupStack::PopAndDestroy(2, keyParams);    //key, keyParams

// Unselect rule selector before destruction. This causes CryptoSPI to use the 
// legacy selector again. After calling SetSelector(), the caller 
// keeps ownership of the selector, so after calling UnsetSelector(), the 
// caller needs to delete the selector    
CCryptoSpiStateApi::UnsetSelector();
    
// Pop and destroy the rule selector
CleanupStack::PopAndDestroy(ruleSelector);
</codeblock>
</conbody></concept>