--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-C75726D3-E815-503D-8267-26DA27AD4787.dita	Fri Jun 11 12:39:03 2010 +0100
@@ -0,0 +1,122 @@
+<?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-C75726D3-E815-503D-8267-26DA27AD4787" xml:lang="en"><title>Big integers</title><prolog><metadata><keywords/></metadata></prolog><conbody>
+<ul>
+<li id="GUID-44E43C1D-81C0-566D-AD44-65046947046D"><p> <xref href="GUID-C75726D3-E815-503D-8267-26DA27AD4787.dita#GUID-C75726D3-E815-503D-8267-26DA27AD4787/GUID-E105FD3A-2600-504A-842E-E75ABFB6FD31">What does the big integer library do?</xref>  </p> </li>
+<li id="GUID-F28BE30D-0E28-57A0-8302-BBA5BEF9DA2E"><p> <xref href="GUID-C75726D3-E815-503D-8267-26DA27AD4787.dita#GUID-C75726D3-E815-503D-8267-26DA27AD4787/GUID-324AFDAC-314C-5CC5-B322-E908AA6F53C3">How do I use the big integer library?</xref>  </p> </li>
+<li id="GUID-FEC8841D-52D9-5232-9E56-1E59E2A36DE2"><p> <xref href="GUID-C75726D3-E815-503D-8267-26DA27AD4787.dita#GUID-C75726D3-E815-503D-8267-26DA27AD4787/GUID-268F2081-4385-5D43-8ADA-4F17BAA4B0BC">Base classes and their derived classes</xref>  </p> <ul>
+<li id="GUID-3EEF522F-49CE-5131-BD57-501582746773"><p> <xref href="GUID-C75726D3-E815-503D-8267-26DA27AD4787.dita#GUID-C75726D3-E815-503D-8267-26DA27AD4787/GUID-FE43C9B9-7F50-5311-A2AF-7BA9785A68BC">RInteger class</xref>  </p> </li>
+</ul> </li>
+</ul>
+<section id="GUID-E105FD3A-2600-504A-842E-E75ABFB6FD31"><title>What does the
+big integer library do?</title><p>Some types of cryptography require the handling
+of finite arbitrary length integers. This big integer library attempts to
+provide support for that requirement. </p><p>It is capable of representing
+both negative and positive integers with an absolute value of less than 2^(2<sup>37</sup>). </p> </section>
+<section id="GUID-324AFDAC-314C-5CC5-B322-E908AA6F53C3"><title>How do I use
+the big integer library?</title> <p>There are four categories of exposed APIs: </p> <ol id="GUID-93981CBD-4B6D-5E95-BD02-44492535C517">
+<li id="GUID-3374E318-C0C5-5E7D-92D4-0F541F0F6B61"><p>Creation of new integers
+given some other representation (descriptor, TUint, etc). <xref href="GUID-8C8CA735-6B76-3204-AFBF-F95496EDCD91.dita#GUID-8C8CA735-6B76-3204-AFBF-F95496EDCD91/GUID-B5E4DBDC-2C7D-30BD-A3D3-8ADE6265CFD2"><apiname>RInteger::NewL()</apiname></xref>  </p> </li>
+<li id="GUID-808268B2-FF70-522B-92BD-5B5EA67DA61B"><p>Creation of new integers
+given some criteria (range, bitcount, prime). <xref href="GUID-8C8CA735-6B76-3204-AFBF-F95496EDCD91.dita#GUID-8C8CA735-6B76-3204-AFBF-F95496EDCD91/GUID-3F59160C-AE87-32A1-8138-C28F977C7607"><apiname>RInteger::NewRandomL()</apiname></xref>, <xref href="GUID-8C8CA735-6B76-3204-AFBF-F95496EDCD91.dita#GUID-8C8CA735-6B76-3204-AFBF-F95496EDCD91/GUID-612D2DC1-69D5-3AAE-83AE-6DA5D9983072"><apiname>RInteger::NewPrimeL()</apiname></xref> </p> </li>
+<li id="GUID-3F7FD594-479E-5631-87DE-95D0AC843A0C"><p>Exporting of previously
+created integers to descriptors. <xref href="GUID-E3D3C429-EA8C-34C1-9D1D-9062BC3D4F16.dita#GUID-E3D3C429-EA8C-34C1-9D1D-9062BC3D4F16/GUID-2E9955F7-9219-37B0-84EA-62A3F3327EE8"><apiname>TInteger::BufferLC()</apiname></xref>  </p> </li>
+<li id="GUID-7D5C5166-15D1-5219-B085-E5D5513E50CE"><p>Querying attributes
+about the size of a previously created integer. <xref href="GUID-E3D3C429-EA8C-34C1-9D1D-9062BC3D4F16.dita#GUID-E3D3C429-EA8C-34C1-9D1D-9062BC3D4F16/GUID-F990DD4D-0886-3BF6-B9EE-D48E086D8C78"><apiname>TInteger::BitCount()</apiname></xref>, <xref href="GUID-E3D3C429-EA8C-34C1-9D1D-9062BC3D4F16.dita#GUID-E3D3C429-EA8C-34C1-9D1D-9062BC3D4F16/GUID-11AB504D-2919-3F39-A0B6-EA79B498074B"><apiname>TInteger::ByteCount()</apiname></xref>, <xref href="GUID-E3D3C429-EA8C-34C1-9D1D-9062BC3D4F16.dita#GUID-E3D3C429-EA8C-34C1-9D1D-9062BC3D4F16/GUID-99874A2D-37D5-3A05-8275-351E29972FA8"><apiname>TInteger::WordCount()</apiname></xref>. </p> </li>
+</ol> <p>The following code demonstrates how to create an <xref href="GUID-8C8CA735-6B76-3204-AFBF-F95496EDCD91.dita"><apiname>RInteger</apiname></xref> from
+a bit string representation of a big integer. </p> <codeblock id="GUID-A496A62E-0912-5241-871B-073270AA72E0" xml:space="preserve">
+//This creates an RInteger from the following binary hexadecimal (base 16)
+//descriptor.  Note that the number is written overall in big endian (most
+//significant digit is first, least significant digit (ones digit) is last).  
+//P.S. The hexadecimal binary descriptor below is the base 16 representation
+//of the base 10 number 123456789012345678901234567890.
+RInteger integer = RInteger::NewL(_L8("18EE90FF6C373E0EE4E3F0AD2")); 
+CleanupStack::PushL(integer);
+
+//This next line converts the number stored by an RInteger into a binary, big
+//endian, hexadecimal descriptor.
+HBufC8* descriptor = integer.BufferLC();
+CleanupStack::Pop(descriptor);
+CleanupStack::PopAndDestroy(integer);
+//descriptor is the same as the original _L8 input value now.
+</codeblock> <p>For more information on integers, including important memory
+management information and additional creation overloads, see <xref href="GUID-8C8CA735-6B76-3204-AFBF-F95496EDCD91.dita"><apiname>RInteger</apiname></xref> in
+the Cryptography API Reference material. </p> </section>
+<section id="GUID-268F2081-4385-5D43-8ADA-4F17BAA4B0BC"><title>Base classes
+and their derived classes</title> <p>The diagram below shows the main classes
+used in bigint and which are implemented in <filepath>cryptography.dll</filepath>.
+The color of the boxes indicates the type of Symbian class, that is, <codeph>M</codeph>, <codeph>C</codeph>, <codeph>R</codeph> or <codeph>T</codeph> class. For detailed information on each component see the Cryptography API
+Reference material. </p> <fig id="GUID-45174FC0-A4B0-572E-801F-EC6CD5A96127">
+<title>The inheritance diagram above shows the <codeph>TInteger</codeph> and <codeph>RInteger</codeph> classes.</title>
+<image href="GUID-598140D3-6C92-5D8E-B204-C7197C6E404D_d0e384680_href.png" placement="inline"/>
+</fig> <p id="GUID-FE43C9B9-7F50-5311-A2AF-7BA9785A68BC"><b>RInteger class</b> </p><p> <xref href="GUID-8C8CA735-6B76-3204-AFBF-F95496EDCD91.dita"><apiname>RInteger</apiname></xref> is
+a <codeph>TInteger</codeph> derived class allowing the construction of variable
+length big integers. </p><p>This class follows standard <codeph>R</codeph> class
+rules. As a quick refresher, the following rules apply to <xref href="GUID-8C8CA735-6B76-3204-AFBF-F95496EDCD91.dita"><apiname>RInteger</apiname></xref> s: </p><ul>
+<li id="GUID-07C1504B-0A75-5FAF-BCFC-11E0C6977DD4"><p>You can construct an
+empty <xref href="GUID-8C8CA735-6B76-3204-AFBF-F95496EDCD91.dita"><apiname>RInteger</apiname></xref>. </p> <codeblock id="GUID-1A9CA02D-E0AA-508D-A870-4572FF3FD4A4" xml:space="preserve">
+RInteger integer;
+</codeblock> <p>This is a constructed, but uninitialized integer. It does
+not own memory and no operations can be performed on it. It is useful, mostly,
+to assign the result of another integer operation to. <codeph>Push</codeph> ing
+and then <codeph>PopAndDestroy</codeph> ing an empty <xref href="GUID-8C8CA735-6B76-3204-AFBF-F95496EDCD91.dita"><apiname>RInteger</apiname></xref> works,
+although it's not needed. </p> </li>
+<li id="GUID-CB62909E-910A-5C29-81E1-6DFD17081B6D"><p> <xref href="GUID-8C8CA735-6B76-3204-AFBF-F95496EDCD91.dita"><apiname>RInteger</apiname></xref> s
+can be bitwised copied (the default assignment operator and copy constructor
+are valid), but you need to be careful you don't lose your original memory
+in the process. You should only use the assignment operator on a newly declared
+integer. To set an <xref href="GUID-8C8CA735-6B76-3204-AFBF-F95496EDCD91.dita"><apiname>RInteger</apiname></xref> to another value without losing
+memory see <codeph>TInteger::Set()</codeph>. </p> <codeblock id="GUID-ECCE21CF-BCD0-57D3-AF54-766B32939D2C" xml:space="preserve">
+RInteger a = anotherInteger; // OK -- you now have two integers that point to the same memory
+RInteger b = RInteger::NewL(aDesc); // OK 
+b = a; // NOT OK, b's original memory has been lost
+</codeblock> </li>
+<li id="GUID-D6F49AA0-5C91-5054-A59A-C01757D53AD9"><p>You own any <xref href="GUID-8C8CA735-6B76-3204-AFBF-F95496EDCD91.dita"><apiname>RInteger</apiname></xref> returned
+by value from a <codeph>TInteger</codeph> function. </p> <codeblock id="GUID-D03786AD-EF19-59B6-B8A9-F91020D14754" xml:space="preserve">
+RInteger integer = a.MinusL(b); // We now own integer
+CleanupStack::PushL(integer); 
+</codeblock> </li>
+<li id="GUID-076C4F7F-8EC7-5E5E-833C-DD3E32996DCE"><p>You must call <codeph>Close()</codeph> on
+all <xref href="GUID-8C8CA735-6B76-3204-AFBF-F95496EDCD91.dita"><apiname>RInteger</apiname></xref> s that own memory before they go out of scope.
+(The cleanup stack can do this for you as well, see further bullet points
+below). </p> <codeblock id="GUID-B018E759-4201-53D2-AA08-04B6F6ABAD04" xml:space="preserve">
+void foo(void)
+    {
+    RInteger integer = a.TimesL(TInteger::Two);
+    //&lt; all sorts of non-leaving code here &gt;
+    integer.Close();
+    }
+</codeblock> </li>
+<li id="GUID-0C2577CE-0336-553F-8D7C-9F731BECDDC5"><p> <xref href="GUID-8C8CA735-6B76-3204-AFBF-F95496EDCD91.dita"><apiname>RInteger</apiname></xref> has
+a operator <codeph>TCleanupItem()</codeph> cast function that allows you to
+call <codeph>CleanupStack::PushL(RInteger&amp;)</codeph>. Use this in preference
+to <codeph>CleanupClosePushL(RInteger&amp;)</codeph>, which although it does
+the same thing, generates more code. </p> <codeblock id="GUID-EFAD6082-D6BB-56C5-91AA-E94C2EAF419B" xml:space="preserve">
+RInteger integer = a.ModularExponentiateL(b, p);
+CleanupStack::PushL(integer);
+//&lt; all sorts of leaving code here &gt;
+CleanupStack::PopAndDestroy(&amp;integer);
+</codeblock> </li>
+<li id="GUID-6FF78282-6B29-5094-8D6B-C2D0FCDFC9E7"><p>Be careful calling <xref href="GUID-E3D3C429-EA8C-34C1-9D1D-9062BC3D4F16.dita#GUID-E3D3C429-EA8C-34C1-9D1D-9062BC3D4F16/GUID-F2E2C416-D2F2-31C1-942B-256F74A4075C"><apiname>TInteger::Set()</apiname></xref>.
+After calling this, two <xref href="GUID-8C8CA735-6B76-3204-AFBF-F95496EDCD91.dita"><apiname>RInteger</apiname></xref> s have a pointer to the
+same heap-based integer. Calling <codeph>Close()</codeph> on one, either explicitly
+or through the cleanup stack, leaves a dangling pointer to the other. You
+probably want to use code similar to the following: </p> <codeblock id="GUID-7A7EE1D4-8931-5A43-8470-2C7C3E9E83F2" xml:space="preserve">
+RInteger first = RInteger::NewL(298728);
+CleanupStack::PushL(first);
+//&lt; all sorts of leaving code here &gt;
+RInteger second.Set(first);
+CleanupStack::Pop(first);
+CleanupStack::PushL(second);
+</codeblock> </li>
+</ul> </section>
+</conbody></concept>
\ No newline at end of file