1 <?xml version="1.0" encoding="utf-8"?>

     2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

     3 <!-- This component and the accompanying materials are made available under the terms of the License 

     4 "Eclipse Public License v1.0" which accompanies this distribution, 

     5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

     6 <!-- Initial Contributors:

     7     Nokia Corporation - initial contribution.

     8 Contributors: 

     9 -->

    10 <!DOCTYPE concept

    11   PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

    12 <concept id="GUID-57BBF5C1-C08D-59FA-8F10-F180A82306A4" xml:lang="en"><title> STS

    13 Client</title><prolog><metadata><keywords/></metadata></prolog><conbody>

    14 <p>The STS provides APIs to start a file system transaction, record various

    15 file system operation as part of a transaction, and commit or roll back the

    16 transaction. </p>

    17 <section id="GUID-5380BCC6-7850-42D5-93AF-086125888658"><title>STS Client library details</title> <p>The STS client is implemented

    18 in <filepath>stsclient.dll</filepath>. </p> <table id="GUID-48F0AABE-0127-5F98-A297-2925B57CD551">

    19 <tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/>

    20 <thead>

    21 <row>

    22 <entry>DLL</entry>

    23 <entry>LIB</entry>

    24 <entry>Short description</entry>

    25 </row>

    26 </thead>

    27 <tbody>

    28 <row>

    29 <entry><p> <filepath>stsclient.dll</filepath>  </p> </entry>

    30 <entry><p> <filepath>stsclient.lib</filepath>  </p> </entry>

    31 <entry><p>An STS client application can access the services provided by the

    32 STS by linking against <filepath>stsclient.lib</filepath>. </p> </entry>

    33 </row>

    34 </tbody>

    35 </tgroup>

    36 </table> </section>

    37 <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">

    38 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

    39 <thead>

    40 <row>

    41 <entry>API</entry>

    42 <entry>Description</entry>

    43 </row>

    44 </thead>

    45 <tbody>

    46 <row>

    47 <entry><p> <xref href="GUID-8ACAC5C6-1EDD-3EEB-995B-53833BEACF25.dita"><apiname>RStsSession</apiname></xref>  </p> </entry>

    48 <entry><p>This class provides a synchronous interface to the STS server. </p> </entry>

    49 </row>

    50 </tbody>

    51 </tgroup>

    52 </table> </section>

    53 <section id="GUID-378E940D-FE89-4337-919B-8691F035B53E"><title>Description</title> <p>The STS can record every file system

    54 operation such as adding, removing, or updating a file. An STS client, such

    55 as a software installer, requires that all of its file system operations are

    56 performed, or that none of them are to ensure that the integrity of the file

    57 system is not compromised. An STS client instructs STS to group file system

    58 operations as a single transaction which must be either committed fully or,

    59 in the event of failure, rolled back to leave the file system unchanged. </p> <p>The

    60 STS client instructs the STS to commit a transaction once all of the operations

    61 have been performed. </p> <p><b>Creating a transaction</b> </p> <p>A transaction

    62 can include file system operations such as adding, removing or updating a

    63 temporary file. An STS client must do the following to create a new transaction: </p> <ul>

    64 <li id="GUID-422FC9DD-9AE3-5872-81EC-0D50B6F67A87"><p>Open a new STS session. </p> </li>

    65 <li id="GUID-3927483B-57B9-58B9-B1AF-F29943DD574C"><p>Create a new transaction

    66 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

    67 new transaction ID. </p> </li>

    68 </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

    69 a transaction</b> </p> <p>Multiple clients can share a single transaction.

    70 If an STS client wants to use an existing transaction, it must do the following: </p> <ul>

    71 <li id="GUID-B2180EAA-E4A7-5F83-A533-01C1F5AE9804"><p>Open a new a session

    72 to the STS. </p> </li>

    73 <li id="GUID-2EC132C4-EA74-52F6-A446-5E23BBAFCFD5"><p>Supply the transaction

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

    75 </ul> <p><b>Registering a file</b> </p> <p>You must create a transaction before

    76 registering a file with the server. </p> <p>Register a file with the STS server

    77 to inform the server about the addition of a new file to the file system. </p> <ul>

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

    79 inform STS about addition of a new file. STS does not perform any action on

    80 the file. The client must create/add the file to the file system and close

    81 it properly after calling this function. </p> </li>

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

    83 registering a temporary file. </p> </li>

    84 </ul> <p><b>Creating a file</b> </p> <p>Create a file with specified file

    85 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

    86 creates an empty file and passes the file handle to the client. </p> <p>Create

    87 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>.

    88 STS removes temporary files automatically on both commit and rollback. </p> <p><b>Overwriting

    89 a file</b> </p> <p>Overwrite a specified file in the file system with an empty

    90 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

    91 the new file is added to the file system, and on rollback the original file

    92 is restored. </p> <p> <b>Note</b>: This function is recommended only when

    93 your client generates the content for the new file. </p> <p><b>Removing a

    94 file</b> </p> <p>Remove a file with specified file name from the file system

    95 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

    96 it from the file system, otherwise it returns an error. </p> <p>On commit

    97 the specified file is permanently deleted from the file system, on rollback

    98 it is restored. </p> <p><b>Committing operation</b> </p> <p>Commit the transaction

    99 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

   100 to the STS server automatically. </p> <p> <b>Note</b>: After a transaction

   101 is committed the STS server cannot restore any file system operation performed

   102 during the transaction. </p> <p><b>Reverting or rolling back operation</b> </p> <p>Rollback

   103 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

   104 reverts all of the file system operations in the transaction and closes the

   105 session to the STS server. </p> <p> <b>Note</b>: Only file system operations

   106 performed using RStsSession functions are included in the transaction. </p> <p><b>Closing

   107 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

   108 rolls back the current transaction. </p> <p><b>Example</b> </p> <p>Symbian

   109 provides an example reference installer which shows typical usage of STS.

   110 For more information, see the example code under <codeph>security/usif/examples/installer/</codeph>. </p> </section>

   111 <section id="GUID-50689CB2-2CF3-4D72-8C3C-A2E32781A5A0"><title>Related Information</title><ul>

   112 <li><xref href="GUID-2B902EA0-F954-5474-9A79-7C1AB208A3D4.dita">STS Overview </xref></li>

   113 </ul></section>

   114 </conbody></concept>