<?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/<app_SID>/</filepath>. <i><app_SID></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>