--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/PDK/Source/GUID-57BBF5C1-C08D-59FA-8F10-F180A82306A4.dita	Fri Jul 16 17:23:46 2010 +0100
@@ -0,0 +1,114 @@
+<?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-57BBF5C1-C08D-59FA-8F10-F180A82306A4" xml:lang="en"><title> STS
+Client</title><prolog><metadata><keywords/></metadata></prolog><conbody>
+<p>The STS provides APIs to start a file system transaction, record various
+file system operation as part of a transaction, and commit or roll back the
+transaction. </p>
+<section id="GUID-5380BCC6-7850-42D5-93AF-086125888658"><title>STS Client library details</title> <p>The STS client is implemented
+in <filepath>stsclient.dll</filepath>. </p> <table id="GUID-48F0AABE-0127-5F98-A297-2925B57CD551">
+<tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/>
+<thead>
+<row>
+<entry>DLL</entry>
+<entry>LIB</entry>
+<entry>Short description</entry>
+</row>
+</thead>
+<tbody>
+<row>
+<entry><p> <filepath>stsclient.dll</filepath>  </p> </entry>
+<entry><p> <filepath>stsclient.lib</filepath>  </p> </entry>
+<entry><p>An STS client application can access the services provided by the
+STS by linking against <filepath>stsclient.lib</filepath>. </p> </entry>
+</row>
+</tbody>
+</tgroup>
+</table> </section>
+<section id="GUID-3ABA3351-20B8-42B7-84FD-1DBE9045D393"><title>APIs</title> <p>The key class of the STS client is as follows: </p> <table id="GUID-3528B2AF-5499-52C5-A69C-391C03DBD6E2">
+<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
+<thead>
+<row>
+<entry>API</entry>
+<entry>Description</entry>
+</row>
+</thead>
+<tbody>
+<row>
+<entry><p> <xref href="GUID-8ACAC5C6-1EDD-3EEB-995B-53833BEACF25.dita"><apiname>RStsSession</apiname></xref>  </p> </entry>
+<entry><p>This class provides a synchronous interface to the STS server. </p> </entry>
+</row>
+</tbody>
+</tgroup>
+</table> </section>
+<section id="GUID-378E940D-FE89-4337-919B-8691F035B53E"><title>Description</title> <p>The STS can record every file system
+operation such as adding, removing, or updating a file. An STS client, such
+as a software installer, requires that all of its file system operations are
+performed, or that none of them are to ensure that the integrity of the file
+system is not compromised. An STS client instructs STS to group file system
+operations as a single transaction which must be either committed fully or,
+in the event of failure, rolled back to leave the file system unchanged. </p> <p>The
+STS client instructs the STS to commit a transaction once all of the operations
+have been performed. </p> <p><b>Creating a transaction</b> </p> <p>A transaction
+can include file system operations such as adding, removing or updating a
+temporary file. An STS client must do the following to create a new transaction: </p> <ul>
+<li id="GUID-422FC9DD-9AE3-5872-81EC-0D50B6F67A87"><p>Open a new STS session. </p> </li>
+<li id="GUID-3927483B-57B9-58B9-B1AF-F29943DD574C"><p>Create a new transaction
+using <xref href="GUID-8ACAC5C6-1EDD-3EEB-995B-53833BEACF25.dita#GUID-8ACAC5C6-1EDD-3EEB-995B-53833BEACF25/GUID-53899D0C-3FA8-353E-8A6B-1E4492375251"><apiname>RStsSession::CreateTransactionL()</apiname></xref>. This creates a
+new transaction ID. </p> </li>
+</ul> <p> <b>Note</b>: Each STS session can have only one transaction. If <xref href="GUID-F53B786C-301D-34D4-B3CC-D814896DDCC5.dita"><apiname>CreateTransactionL</apiname></xref> or <xref href="GUID-9777AB74-5C7A-3547-A7A1-A2F60EF259AB.dita"><apiname>OpenTransactionL</apiname></xref> is invoked more than once in an STS session, STS returns an error. </p> <p><b>Opening
+a transaction</b> </p> <p>Multiple clients can share a single transaction.
+If an STS client wants to use an existing transaction, it must do the following: </p> <ul>
+<li id="GUID-B2180EAA-E4A7-5F83-A533-01C1F5AE9804"><p>Open a new a session
+to the STS. </p> </li>
+<li id="GUID-2EC132C4-EA74-52F6-A446-5E23BBAFCFD5"><p>Supply the transaction
+ID of the existing transaction to <xref href="GUID-8ACAC5C6-1EDD-3EEB-995B-53833BEACF25.dita#GUID-8ACAC5C6-1EDD-3EEB-995B-53833BEACF25/GUID-28E986DA-A2E4-3345-8639-C4F367FE5CC3"><apiname>RStsSession::OpenTransactionL()</apiname></xref>. </p> </li>
+</ul> <p><b>Registering a file</b> </p> <p>You must create a transaction before
+registering a file with the server. </p> <p>Register a file with the STS server
+to inform the server about the addition of a new file to the file system. </p> <ul>
+<li id="GUID-35EAD7D7-530F-5559-971E-D50A38F44815"><p>Use <xref href="GUID-8ACAC5C6-1EDD-3EEB-995B-53833BEACF25.dita#GUID-8ACAC5C6-1EDD-3EEB-995B-53833BEACF25/GUID-E6B456F0-81A8-3940-9824-EC15C14F20D3"><apiname>RStsSession::RegisterNewL</apiname></xref> to
+inform STS about addition of a new file. STS does not perform any action on
+the file. The client must create/add the file to the file system and close
+it properly after calling this function. </p> </li>
+<li id="GUID-E5117E6D-8680-59A1-81B1-59DF8E631CBD"><p>Use <xref href="GUID-8ACAC5C6-1EDD-3EEB-995B-53833BEACF25.dita#GUID-8ACAC5C6-1EDD-3EEB-995B-53833BEACF25/GUID-D26C70A2-A36A-3DD6-9690-ABCA6EBB399B"><apiname>RStsSession::RegisterTemporaryL</apiname></xref> for
+registering a temporary file. </p> </li>
+</ul> <p><b>Creating a file</b> </p> <p>Create a file with specified file
+name using <xref href="GUID-8ACAC5C6-1EDD-3EEB-995B-53833BEACF25.dita#GUID-8ACAC5C6-1EDD-3EEB-995B-53833BEACF25/GUID-DEB1036D-7B1F-3798-9522-8BEA5E83A7F7"><apiname>RStsSession::CreateNewL()</apiname></xref>. </p> <p>The STS server
+creates an empty file and passes the file handle to the client. </p> <p>Create
+a temporary file using <xref href="GUID-8ACAC5C6-1EDD-3EEB-995B-53833BEACF25.dita#GUID-8ACAC5C6-1EDD-3EEB-995B-53833BEACF25/GUID-3BEAFA0F-7C31-3C34-B2E3-0D48FD58365B"><apiname>RStsSession::CreateTemporaryL()</apiname></xref>.
+STS removes temporary files automatically on both commit and rollback. </p> <p><b>Overwriting
+a file</b> </p> <p>Overwrite a specified file in the file system with an empty
+file using <xref href="GUID-8ACAC5C6-1EDD-3EEB-995B-53833BEACF25.dita#GUID-8ACAC5C6-1EDD-3EEB-995B-53833BEACF25/GUID-7295D60F-9FE4-3CDA-986E-DD7E900E78EA"><apiname>RStsSession::OverwriteL()</apiname></xref>. </p> <p>On commit
+the new file is added to the file system, and on rollback the original file
+is restored. </p> <p> <b>Note</b>: This function is recommended only when
+your client generates the content for the new file. </p> <p><b>Removing a
+file</b> </p> <p>Remove a file with specified file name from the file system
+using <xref href="GUID-8ACAC5C6-1EDD-3EEB-995B-53833BEACF25.dita#GUID-8ACAC5C6-1EDD-3EEB-995B-53833BEACF25/GUID-C8799D1E-DD7A-3299-813B-1F8552251FC5"><apiname>RStsSession::RemoveL()</apiname></xref>. If the file exists STS removes
+it from the file system, otherwise it returns an error. </p> <p>On commit
+the specified file is permanently deleted from the file system, on rollback
+it is restored. </p> <p><b>Committing operation</b> </p> <p>Commit the transaction
+using <xref href="GUID-8ACAC5C6-1EDD-3EEB-995B-53833BEACF25.dita#GUID-8ACAC5C6-1EDD-3EEB-995B-53833BEACF25/GUID-9230F07E-37D1-3F49-AD21-401F1DF3F993"><apiname>RStsSession::CommitL</apiname></xref>. This function closes the session
+to the STS server automatically. </p> <p> <b>Note</b>: After a transaction
+is committed the STS server cannot restore any file system operation performed
+during the transaction. </p> <p><b>Reverting or rolling back operation</b> </p> <p>Rollback
+a transaction using <xref href="GUID-8ACAC5C6-1EDD-3EEB-995B-53833BEACF25.dita#GUID-8ACAC5C6-1EDD-3EEB-995B-53833BEACF25/GUID-648E46E1-411E-36BF-A47D-9F105E0D0647"><apiname>RStsSession::RollBackL()</apiname></xref>. This function
+reverts all of the file system operations in the transaction and closes the
+session to the STS server. </p> <p> <b>Note</b>: Only file system operations
+performed using RStsSession functions are included in the transaction. </p> <p><b>Closing
+a session</b> </p> <p>A session to the STS is valid until the client calls <xref href="GUID-D7D5B755-456D-3774-ACF9-E4ABC07E5C40.dita"><apiname>CommitL()</apiname></xref> or <xref href="GUID-C6169B55-8E5A-3113-B323-A22EC167C743.dita"><apiname>RollBackL()</apiname></xref> or <xref href="GUID-01D2AF56-21E1-3FF3-BF86-0C356A1658EF.dita"><apiname>Close()</apiname></xref> functions. The <xref href="GUID-01D2AF56-21E1-3FF3-BF86-0C356A1658EF.dita"><apiname>Close()</apiname></xref> function automatically
+rolls back the current transaction. </p> <p><b>Example</b> </p> <p>Symbian
+provides an example reference installer which shows typical usage of STS.
+For more information, see the example code under <codeph>security/usif/examples/installer/</codeph>. </p> </section>
+<section id="GUID-50689CB2-2CF3-4D72-8C3C-A2E32781A5A0"><title>Related Information</title><ul>
+<li><xref href="GUID-2B902EA0-F954-5474-9A79-7C1AB208A3D4.dita">STS Overview </xref></li>
+</ul></section>
+</conbody></concept>
\ No newline at end of file