<?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. For more information, see <b>Symbian^3 Tools Guide &gt; Building</b>.</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>