--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-5857377F-B90D-5149-9485-5919C12B8F13.dita Fri Jun 11 12:39:03 2010 +0100
@@ -0,0 +1,124 @@
+<?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 <ruleselector.h>
+#include <cryptosymmetriccipherapi.h>
+#include <cryptospistateapi.h>
+#include <cryptospidef.h>
+#include <keys.h>
+
+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->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->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 && (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>
\ No newline at end of file