--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-310A8A9C-98E7-59EE-9376-8E572580190F.dita	Wed Mar 31 11:11:55 2010 +0100
@@ -0,0 +1,174 @@
+<?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-310A8A9C-98E7-59EE-9376-8E572580190F" xml:lang="en"><title>File
+services in Symbian platform</title><shortdesc>This topic describes the common concepts of file systems and files
+used by Symbian platform.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
+<p>Like other software systems, Symbian platform can store data so that it
+is kept when a handset is powered down. </p>
+<p>On PCs, a file is kept on magnetic disk or optical media such as CD or
+DVD. On older generations of personal organisers, a file was often kept in
+RAM, needing a permanent power supply, and a backup battery to guarantee this.
+On the most recent telephone handsets, files are normally stored in flash
+memory, either NOR flash or NAND flash, and also on removable devices such
+as MultiMediaCard (MMC), Secure Digital card (SD card), Memory Stick or Compact
+flash (CF). </p>
+<p>There are more sophisticated services for persisting data such as streams,
+stores, central repository etc. that applications can use, but they all rely,
+either directly or indirectly, on the commonly understood idea of the file. </p>
+<p>The ROM on a typical handset is located in non-volatile flash memory, allowing
+it to be upgraded by the handset manufacturer after initial production. The
+location for user data is almost always flash memory (NAND or NOR), on the
+grounds of cost, although rotating media devices capable of holding large
+amounts of data are likely in future handsets. </p>
+<ul>
+<li id="GUID-798E9ED1-24DF-5990-9D1E-CD043B94B722"><p> <xref href="GUID-310A8A9C-98E7-59EE-9376-8E572580190F.dita#GUID-310A8A9C-98E7-59EE-9376-8E572580190F/GUID-DD8C4BFB-9816-5EA5-A9F2-5146C64BBC9C">Basic concepts</xref>  </p> </li>
+<li id="GUID-BBB6D4C2-4AE6-55CD-BC65-416BCF705F31"><p> <xref href="GUID-310A8A9C-98E7-59EE-9376-8E572580190F.dita#GUID-310A8A9C-98E7-59EE-9376-8E572580190F/GUID-62387DD0-D8E4-5426-8432-B14696291AF8">Accessing file services</xref>  </p> </li>
+<li id="GUID-B6AEF9DA-60D3-5728-9C46-59EE5C98346C"><p> <xref href="GUID-310A8A9C-98E7-59EE-9376-8E572580190F.dita#GUID-310A8A9C-98E7-59EE-9376-8E572580190F/GUID-9FF4525A-EBFD-5E9F-BD86-C6B75E5C35EF">Security issues</xref>  </p> </li>
+<li id="GUID-ACF583E3-3FAA-52FE-9A07-8172A4BBBCC9"><p> <xref href="GUID-310A8A9C-98E7-59EE-9376-8E572580190F.dita#GUID-310A8A9C-98E7-59EE-9376-8E572580190F/GUID-849F5D6E-7911-55F8-839A-019D1BF16726">File systems and mounting a drive</xref>  </p> </li>
+</ul>
+<section id="GUID-DD8C4BFB-9816-5EA5-A9F2-5146C64BBC9C"><title>Basic concepts</title> <p>Symbian
+platform uses a number of file concepts that are common to most operating
+systems, for example, drives and directories. </p> <p><b>Drives</b> </p> <p>Symbian
+platform uses the concept of the <i>drive</i>. This idea is similar to that
+in other operating systems, i.e. it corresponds to a logical device. A media
+device such as a MultiMediaCard can be logically split into partitions, and
+each partition is treated as a separate drive. Symbian platform adopts a DOS-like
+convention where each drive is identified by a single letter. This means that
+there can be up to 26 drives on a handset, identified by the letters <filepath>A:</filepath> through
+to <filepath>Z:</filepath>. In practice, there are far fewer than this, and
+the number depends on the individual manufacturer's handset </p> <p>Internally,
+Symbian platform uses the idea of a drive number instead of a letter, and
+some legacy API items take a drive number as input, or return a drive number
+as output. However, there are functions that can translate drive numbers to
+and from drive letters: <xref href="GUID-E263C747-946F-35AA-9F1D-41833BD350FC.dita#GUID-E263C747-946F-35AA-9F1D-41833BD350FC/GUID-A0F50C51-A4F0-33C1-BBD4-757DEC4B7F2E"><apiname>RFs::DriveToChar()</apiname></xref> and <xref href="GUID-E263C747-946F-35AA-9F1D-41833BD350FC.dita#GUID-E263C747-946F-35AA-9F1D-41833BD350FC/GUID-D545B868-0549-37A9-AACE-288E7C9CE8C3"><apiname>RFs::CharToDrive()</apiname></xref>. </p> <p>The
+main ROM on a handset is always identified as the <filepath>Z:</filepath> drive.
+Other drives may be in use: sixteen of the drives <filepath>C:</filepath> to <filepath>R:</filepath> are
+usually reserved as local drives, i.e. for media devices located within the
+handset. A common convention is to adopt <filepath>C:</filepath> as the main
+user data drive. and to designate <filepath>D:</filepath> or <filepath>E:</filepath> as
+drives for removable media. <i>Be aware</i>, however, that this is a convention
+that some handset manufacturers may not follow, so you are always advised
+to check the full SDK that applies to a specific handset for guidance. Indeed,
+as a matter of principle, you should always use the <xref href="GUID-629AB2C9-BEDD-5166-8B09-F8DFF7527C03.dita">system
+drive</xref> for user data. </p> <p><b>Volume</b> </p> <p>The concept of the volume applies to removable media. As users insert
+and remove individual devices, so different volumes are said to be mounted
+and demounted. For media types that can be split into partitions, each partition
+corresponds to a separate volume. </p> <p><b>File
+names and directory structures</b> </p> <p>Files have names, and Symbian platform
+uses a hierarchical directory structure in which to organize them; this is
+similar to schemes adopted by other operating systems. For example: </p> <codeblock id="GUID-C4330879-E93B-5939-A810-8D4A1E5B14DB" xml:space="preserve">C:\AAA\BBB\CCC\DDD.EXT</codeblock> <p>There
+are four main parts to the structure: </p> <ul>
+<li id="GUID-39D18587-8793-511F-B3CC-8CFA6D129F80"><p>the <i>drive</i>; this
+is always at the top of the hierarchy, and is represented by a drive letter
+and a colon. </p> </li>
+<li id="GUID-8F5F5EB0-721F-5C5B-90B6-08E2CB92BA98"><p>the <i>path</i>; this
+is a list of names, each name representing a level in the hierarchy. Each
+directory name is separated by a back slash character, and the last directory
+name is always terminated by a back slash character. </p> </li>
+<li id="GUID-BD848A50-9BEA-5E08-ACDB-92EDB9C5CA86"><p>the <i>filename</i>;
+this is everything after the final backslash, and before the dot if there
+is a file extension. Symbian platform supports long file filenames. </p> </li>
+<li id="GUID-07E1D5CB-9D9B-5141-AD7B-76F839AA2FC0"><p>the <i>extension</i>,
+everything after the final dot. There is no restriction on the length of the
+extension; limits on length apply to the whole structure, not to any single
+part of it. </p> </li>
+</ul> <p>You will find that the whole structure is sometimes referred to as
+the full file name or the full path name. The maximum length of a full file
+name is limited to 256 characters. Symbian platform does not use the extension
+to identify the software or application that can access the data. Instead,
+files have UIDs embedded within them, and the mapping of files to applications
+is done through these UIDs. See <xref href="GUID-3AFA877F-41DE-5343-8BC2-C0FB894A062C.dita">Application
+registration information</xref>. </p> <p>The case of full path names is always
+preserved, but operations on names are case insensitive. This means that two
+files that have the same name but differ only in case are considered to refer
+to the same file. </p> <p>Full file names are normally manipulated programmatically.
+Extracting drive names, filenames, file extensions, and changing the names
+of a directory structure are typical activities. Symbian platform provides
+you with the <xref href="GUID-E79A3B03-F8CB-37DB-A2A8-1C6C4E4D739A.dita"><apiname>TParse</apiname></xref>, <xref href="GUID-A6268E58-68EC-3041-93FD-5368CD230947.dita"><apiname>TParsePtr</apiname></xref>, and <xref href="GUID-C65BCDAB-0476-3EAC-9BFC-37243AE43FE9.dita"><apiname>TParsePtrC</apiname></xref> classes
+to help you do this manipulation. </p> <p>See <xref href="GUID-ECF9E432-EA93-5284-B0E6-A1211289CBD8.dita">parsing
+paths and filenames</xref> . </p> </section>
+<section id="GUID-62387DD0-D8E4-5426-8432-B14696291AF8"><title>Accessing file
+services</title> <p>On Symbian platform, file services are a common resource.
+Like other common or shared resources on Symbian platform, file services are
+handled by a server - the file server. Applications and other software that
+require access to files, directories and drives are clients of the file server,
+and send file-related requests using the <xref href="GUID-198DCED1-F429-5C95-A51D-53AE416687E8.dita">file
+server client-side API</xref>. </p> <p>The file server is multithreaded, which
+allows each logical drive to be accessed concurrently. More than one request
+can be issued for the same drive, but these requests are handled sequentially.
+For example, a request to read or write data to a MultiMediaCard can be handled
+at the same time as a request to read or write data to the main user drive. </p> <p>The
+file server has a main thread that initially handles all requests. Short requests,
+such as those that require access to the ROM drive, and those that do not
+require access to any media, run in the file server. </p> <p>The services
+provided by the file server can be divided into two types: </p> <ul>
+<li id="GUID-12F7606D-835D-5948-B0F0-EBACC5F6E569"><p>those that give you
+access to individual files, directories and drives using the <xref href="GUID-BE0804F6-4375-3C8A-8C83-968F510466E0.dita"><apiname>RFile</apiname></xref>, <xref href="GUID-12AE154F-7741-38C0-ADFE-9784FCF5E516.dita"><apiname>RDir</apiname></xref> and <xref href="GUID-9D7E765B-6872-3EB9-9D5B-1503FA466EC1.dita"><apiname>RFormat</apiname></xref> classes. </p> <p>See also <xref href="GUID-30B2AF3F-E120-5D47-AAA2-529555625B55.dita">How to
+use sessions, files, and directories</xref>. </p> </li>
+<li id="GUID-9E40CF33-C35E-52CE-80B9-8A019F34F305"><p>those that allow you
+to do higher level longer running operations such as moving, copying and deleting
+files, using the <xref href="GUID-82CEC14F-1479-3922-846A-9FCDB6465EF7.dita"><apiname>CFileMan</apiname></xref> class, scanning directory trees
+using the <xref href="GUID-C657AF2D-1183-3CD2-ACAF-3B0B00FC91BB.dita"><apiname>CDirScan</apiname></xref> class, and tracking the progress of
+these operations using the <xref href="GUID-E608485F-B3E3-3310-A80E-169D8B9D2234.dita"><apiname>MFileManObserver</apiname></xref> class. </p> <p>See
+also <xref href="GUID-ACF6C0A2-87ED-55B3-B22A-9B331D9940AC.dita">File management
+and searching</xref>  </p> </li>
+</ul> <p>Like most other servers, the client API allows you to make file requests
+synchronously or asynchronously. </p> <p>See also <xref href="GUID-6047DB3F-DC92-51DF-9EEB-00E79E890B54.dita">client-server</xref>. </p> </section>
+<section id="GUID-9FF4525A-EBFD-5E9F-BD86-C6B75E5C35EF"><title>Security issues</title> <p>Security
+considerations restrict the parts of a handset's directory structure that
+an application is allowed to access. The concept is referred to as <i>data
+caging</i>. </p> <p>There are a number of principles involved: </p> <ul>
+<li id="GUID-21674EE5-40A3-5F71-9973-C089FD838585"><p>The fundamental principle
+is the separation of executable code from data. Executable code can only reside
+in the <filepath>/sys/bin/</filepath> directory. Executables cannot be loaded
+from any location other than <filepath>/sys/bin/</filepath>. Unless an application
+has the appropriate system capabilities, the <filepath>/sys/</filepath> directory
+is not visible to that application. System capabilities are a discrete set
+of 'permissions' that give access to various sensitive system services, and
+which can only be granted to applications, if justified, through the <xref href="https://www.symbiansigned.com/app/page" scope="external">Symbian Signed</xref> scheme. </p> </li>
+<li id="GUID-4A1854CE-25CB-5630-A27C-73931D937567"><p>Applications have their
+own private directory, under which they are free to create further directory
+structures and files, and to write to those files. This is the directory structure <filepath>/private/&lt;app_SID&gt;/</filepath>. <i>&lt;app_SID&gt;</i> is known as a secure identifier and, in general, is used when verifying
+an executable's rights of access to system resources. Here, it is used to
+form the path name for the executable's private directory. The secure identifier
+is a UID which is allocated to a developer through the <xref href="https://www.symbiansigned.com/app/page" scope="external">Symbian Signed</xref> scheme, and is guaranteed to be unique
+within the handset on which the application is installed. The UID is coded
+into the <filepath>mmp</filepath> file(s) that define the application's source
+files, link requirements, and general characteristics. </p> <p>Other applications
+have no right of access to an application's private directory. </p> </li>
+<li id="GUID-2814D086-A660-5294-9952-E6D66243B652"><p>There is a directory <filepath>/resource/</filepath> to
+which all applications have read access, but no write access. The purpose
+of this directory is to conatin common read-only files. </p> </li>
+<li id="GUID-FC6EE81A-59FA-5AC5-8EC4-3034597F8829"><p>All other directories
+are accessible for both reading and writing. This allows the use of standard
+file system hierarchies that may be available on removable media. </p> </li>
+<li id="GUID-95121831-873B-5E79-B07C-410858FC9779"><p>The above principles
+apply regardless of the drive. </p> </li>
+</ul> <p>It is possible to pass an open file to another process, or between
+a client and server, so that the target can access the file without knowing
+the full path name. The only information that is passed to the target is the
+filename and extension. </p> </section>
+<section id="GUID-849F5D6E-7911-55F8-839A-019D1BF16726"><title>File systems
+and mounting a drive</title> <p>The varying characteristics of media types
+can mean that different media types require different formats. A common format
+is VFAT, and typically, this is used for removable media to maintain compatibility
+with other systems. This also means that long file names are supported. </p> <p>In
+Symbian platform, format schemes are implemented by what are called file systems;
+they are constructed as plugins to the file server. This means that the file
+server itself is independent of the format scheme, and also means that a phone
+manufacturer is free to add new file systems to a handset. The ROM is an exception
+- it has its own file system built into the main file server code. </p> <p>A
+file system must be associated with a drive before the drive can be used.
+This is known as mounting the drive, and is typically done at system boot
+time. </p> <p>In practice, an application does not need to concern itself
+with the format scheme. </p> </section>
+</conbody></concept>
\ No newline at end of file