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