<?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>